docs: Phase 2 计划评审修复（挂载挪Task2/Site补brand_overlay列/reload upsert语义/重置出厂+平台设置CRUD归位）
Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
浅念
@@ -44,7 +44,8 @@ async def test_platform_db_wal(tmp_path):
|
||||
```python
|
||||
# 模型（PlatformBase 独立 MetaData，与租户库 Base 无关）
|
||||
class Tenant(id, slug UNIQUE, name, status, created_at)
|
||||
class Site(id, tenant_id FK, slug, name, status) # UNIQUE(tenant_id, slug)
|
||||
class Site(id, tenant_id FK, slug, name, status, brand_overlay JSON NULL) # UNIQUE(tenant_id, slug)
|
||||
# brand_overlay = 站点门面覆盖层（spec §5.2；DbTenantSource 映射进站点 brand 合并链）
|
||||
class SiteDomain(id, domain UNIQUE, site_id FK)
|
||||
class TenantConfigVersion(id, tenant_id FK, version, config_json TEXT, updated_by, comment, created_at)
|
||||
# 当前生效 = MAX(version)；UNIQUE(tenant_id, version)
|
||||
@@ -66,6 +67,7 @@ async def bootstrap_superuser(engine, username, password): ... # 空表才建
|
||||
|
||||
**Files:**
|
||||
- Create: `app/platform/auth.py`、`app/platform/routes/__init__.py`、`app/platform/routes/auth_routes.py`、`tests/test_auth.py`
|
||||
- Modify: `app/main.py`（挂 auth_routes——**本任务就挂**，jiancai Host 下 /api/platform/auth/login 可经中间件直达路由，TDD 循环才能闭环；Task 3 只管豁免与守护）
|
||||
|
||||
- [ ] **Step 1: 失败测试**（核心 8 项）
|
||||
|
||||
@@ -84,14 +86,16 @@ def test_logout_invalidates_token(app_client)
|
||||
- `auth.py`：`hash_password/verify_password`（Task 1 已有则上移共用）；`TokenStore`（内存 dict：token(secrets.token_urlsafe 32B)→{user_id, role, tenant_slug, expires_at}；TTL 默认 8h；prune 过期；logout 删）；`LoginLimiter`（(username, ip) 键滑动窗 5 次/15 分钟，照抄 rate_limit 风格）
|
||||
- `auth_routes.py`：`POST /api/platform/auth/login`（限流→验密→发 token）；`POST /api/platform/auth/logout`；`POST /api/platform/auth/change-password`（验旧密，must_change 清零）
|
||||
- 依赖项：`get_current_user(request) -> UserContext`（Authorization: Bearer 解析→TokenStore 查验→role/tenant）；`require_super`/`require_tenant(slug)` 两个依赖工厂（403 语义）
|
||||
- **must_change_password 强制语义**：UserContext 带该标志；除 `/auth/change-password` 外的所有 `/api/platform/*` 受保护端点在标志为真时返回 409（超管引导密码不得只当摆设）
|
||||
- 密码永不明文进日志；token 走 Authorization 头（无 Cookie，免 CSRF——spec §7.2）
|
||||
- 偏差注记：spec §7.2 写 bcrypt/argon2，本实现用 **hashlib.scrypt**（stdlib 零新依赖，抗 GPU 性能同级）——记录为有意取舍
|
||||
|
||||
- [ ] **Step 3: 全量回归 + 提交** `feat: 平台认证（scrypt/内存token 8h/登录限流/改密/角色依赖）`
|
||||
|
||||
### Task 3: 中间件豁免与 admin 挂载骨架
|
||||
|
||||
**Files:**
|
||||
- Modify: `app/platform/host_middleware.py`（豁免 `/api/platform/`）、`app/main.py`（挂 auth_routes）
|
||||
- Modify: `app/platform/host_middleware.py`（豁免 `/api/platform/`）
|
||||
- Test: `tests/test_admin_mounting.py`
|
||||
|
||||
- [ ] **Step 1: 失败测试**
|
||||
@@ -129,7 +133,8 @@ async def test_registry_reload_via_db_source(...) # DB 改版
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 实现**
|
||||
- `tenant_source.py`：`LoadedTenant` dataclass（slug/name/status/sites raw/snapshot dict）；`TenantSource` Protocol（`load_all() / reload(slug)`）；`FileTenantSource(seed_dir)`（把 registry 现有 `_load_tenant` 逻辑搬入，**行为逐字等价**）；`DbTenantSource(engine)`（JOIN tenants/sites/domains + 当前版本 config_json；prompts 嵌在 config_json 的 `prompts` 键）
|
||||
- `tenant_source.py`：`LoadedTenant` dataclass（slug/name/status/sites raw/snapshot dict）；`TenantSource` Protocol（`load_all() / reload(slug)`）；`FileTenantSource(seed_dir)`（把 registry 现有 `_load_tenant` 逻辑搬入，**行为逐字等价**）；`DbTenantSource(engine)`（JOIN tenants/sites/domains——**sites.brand_overlay 进站点覆盖层**——+ 当前版本 config_json；prompts 嵌在 config_json 的 `prompts` 键）
|
||||
- **registry_reload 补 upsert 语义**：现行实现在 slug 未加载时抛 UnknownTenantError——改为"source 已知但未加载 → 载入并插入"（Task 5 创建租户后 reload 依赖此语义）；补测试：新租户（未 resolve 过）创建后直接 reload 不炸且可 resolve
|
||||
- registry：`__init__(source)`；`load_from_dir(seed_dir, data_dir)` = `TenantRegistry(FileTenantSource(seed_dir), data_dir)` 便捷函数（**既有 conftest/test 调用零改动**）；reload 走 source
|
||||
- `PromptProvider.from_config(md: dict)`（四件套字符串构造；`from_dir` 改为读文件后委托它）；DbTenantSource 路径的 TenantRuntime.prompts 用 from_config（seed_dir 字段对 DB 源为 None——avatar 解析链 Task 7 更新）
|
||||
|
||||
@@ -187,8 +192,9 @@ def test_tenant_admin_scoped_config(...) # jiancai 管理员能改自己、
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 实现校验管线 `config_validation.py`**
|
||||
- `validate_group(group, payload, context) -> list[str]`（错误清单）：类型检查（engine 组 int/bool；brand 字符串列表）、wall → `compile_wall`（复用全部既有校验）、prompts 大小上限（company_facts ≤50KB、其余 ≤100KB）、email notify_emails 格式、push/ai 数值范围、`context.other_prefixes` 查重
|
||||
- `config_routes.py`：`GET /api/platform/tenants/{slug}/config`（当前 merged+version）；`PUT .../config/{group}`（校验→整份快照写 MAX(version)+1【updated_by=当前用户, comment 可选】→ registry_reload）；`GET .../config/versions`（列表：版本/时间/作者/备注）；`POST .../config/rollback` `{version}`（复制为新版本）；`POST .../wall/test`（试金石：compile 请求体里的 wall【或当前+覆盖】→ 逐句调 boundary_filter 纯函数给判定）
|
||||
- `validate_group(group, payload, context) -> list[str]`（错误清单）：类型检查（engine 组 int/bool；brand 字符串/字符串列表；contact 开关与 template_languages、misc 映射也纳入类型校验）、wall → `compile_wall`（复用全部既有校验）、prompts 大小上限（company_facts ≤50KB、其余 ≤100KB）、email notify_emails 格式、push/ai 数值范围、`context.other_prefixes` 查重
|
||||
- `config_routes.py`：`GET /api/platform/tenants/{slug}/config`（当前 merged+version）；`PUT .../config/{group}`（校验→整份快照写 MAX(version)+1【updated_by=当前用户, comment 可选】→ registry_reload）；`POST .../config/{group}/reset`（**重置出厂**：拷出厂档案该组为新版本——auto/jiancai 档案取 seed_profiles，blank/无档案租户取 DEFAULT_CONFIG 组；spec §5.4）；`GET .../config/versions`（列表：版本/时间/作者/备注）；`POST .../config/rollback` `{version}`（复制为新版本）；`POST .../wall/test`（试金石：compile 请求体里的 wall【或当前+覆盖】→ 逐句调 boundary_filter 纯函数给判定）
|
||||
- **平台设置 CRUD**（spec §7.3 平台配置页后端）：`GET/PUT /api/platform/settings`（仅超管；PlatformSetting 表读写——集团默认 AI 凭据/默认 SMTP；**resolver 回退链接入 platform_settings 归 Phase 3**——本阶段先落存储与接口）
|
||||
- 鉴权：超管任意租户；租户管理员限自己（require_tenant）
|
||||
|
||||
- [ ] **Step 3: 提交** `feat: 配置API（分组校验管线/整份版本/回滚/试金石端点/前缀唯一）`
|
||||
@@ -226,7 +232,7 @@ def test_push_logs_payload_lazy(...) # 列表不含 request_payload
|
||||
def test_tenant_scope_isolation(...) # jiancai 管理员 GET auto 的会话 → 403；自己的 → 200
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 实现**（查询逻辑从 jc 原 admin.py 的查询语义移植，跑在 `runtime.session_factory()` 上；分页 page/page_size 上限；筛选：intent/site/日期区间；IP 归国沿用 ip_service）
|
||||
- [ ] **Step 2: 实现**（查询逻辑从 jc 原 admin.py 移植查询语义——源文件在 `D:\refactor\ai-kefu-jc\app\api\routes\admin.py`，实施时可读；跑在 `runtime.session_factory()` 上；分页 page/page_size 上限；筛选：intent/site/日期区间；IP 归国沿用 ip_service）
|
||||
- [ ] **Step 3: 提交** `feat: 数据视图API（会话/详情/推送日志/租户scope强制）`
|
||||
|
||||
### Task 9: 统计 API
|
||||
@@ -272,14 +278,14 @@ def test_cross_tenant_super_view(...) # 超管无 tenant 参数=全部租户合
|
||||
- [ ] **Step 1: 全量回归（根+tests/ 双跑）**
|
||||
- [ ] **Step 2: 零同步 IO 审计复查**（grep requests/urllib/time.sleep/open 于 app/——新增代码延续纪律；scrypt 在登录路径是 CPU 非阻塞 ~100ms 可接受，注释声明）
|
||||
- [ ] **Step 3: 安全自查**：token 不进日志、密码不进日志、platform.db 进 gitignore 复核、登录限流在豁免路径上仍生效、上传目录不可执行
|
||||
- [ ] **Step 4: CLAUDE.md/README 更新**（Phase 2 完成状态、Phase 3 清理单刷新、bootstrap 用法、admin API 速览）
|
||||
- [ ] **Step 4: CLAUDE.md/README 更新**（Phase 2 完成状态、Phase 3 清理单刷新、bootstrap 用法、admin API 速览、基线数字刷新 463→当前）
|
||||
- [ ] **Step 5: 提交** `chore: Phase 2 收尾——平台层完成`
|
||||
|
||||
---
|
||||
|
||||
## 显式不做（Phase 2 范围外）
|
||||
|
||||
art-design-pro SPA 全部页面（Phase 3）；嵌入代码复制块的前端展示（Phase 3，API 已含 brand）；Dockerfile/部署/存量数据导入（Phase 4）；/health 分级健康（Phase 4 批次，清理单在案）；推送失败告警（二期）。
|
||||
art-design-pro SPA 全部页面（Phase 3）；嵌入代码复制块的前端展示（Phase 3，API 已含 brand）；**resolver 回退链接入 platform_settings**（Phase 3 平台配置页联动；本阶段 PlatformSetting 表与 CRUD 已落）；Dockerfile/部署/存量数据导入（Phase 4）；/health 分级健康（Phase 4 批次，清理单在案）；推送失败告警（二期）。
|
||||
|
||||
## 执行注意（继承 Phase 1 血泪）
|
||||
|
||||
|
||||
Reference in New Issue
Block a user