docs: Phase 2 实施计划（platform.db/认证/配置版本试金石/数据视图统计，12 任务）

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-13 07:35:22 +08:00
parent 9ad02a778f
commit fe9e767689
1 changed files with 286 additions and 0 deletions
@@ -0,0 +1,286 @@
+# Phase 2：平台层（platform.db/认证/配置版本/试金石/统计）实施计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 在 Phase 1 的多租户引擎之上建平台层：platform.db（租户/站点/域名/配置版本/账号）、超管+租户管理员认证、配置保存-校验-版本-回滚-试金石 API、数据视图与统计 API；Registry 数据源抽象（文件源保测试、DB 源上生产）。
+
+**Architecture:** 平台层拥有独立的 platform.db（单库，WAL）；`TenantSource` 协议隔开"租户数据从哪来"——`FileTenantSource`（seed_profiles，测试与出厂档案）与 `DbTenantSource`（platform.db，生产）；admin API 挂 `/api/platform/*`（Host 中间件豁免，认证鉴权守护）；配置保存 = 整份快照新版本（校验管线前置）→ registry 热加载。
+
+**Tech Stack:** 同 Phase 1（FastAPI/SQLAlchemy async/aiosqlite/pytest）；认证零新依赖（hashlib.scrypt + 内存 token）。
+
+**参照 spec:** §5（配置模型/存储/校验试金石）、§7.2-7.3（认证/页面后端）、§7.6（统计）。Phase 1 遗产：CLAUDE.md 清理单 12 项（本计划顺势处理 #1/#2/#3）、conftest 跨循环纪律、build_app/app_client/TenantTestClient 夹具。
+
+**关键既有资产（不要重建）：** `app/platform/registry.py`（TenantRegistry/resolve_site/reload/dispose_all）、`wall_schema.compile_wall`（校验已含键 allowlist/占位符白名单/flags）、`PromptProvider`、`config.py` 的 ProcessSettings（ADMIN_PASSWORD 保留即为本阶段超管引导）、`seed_profiles/`（出厂档案=创建租户的模板源）。
+
+---
+
+### Task 1: platform.db 模型与引导
+
+**Files:**
+- Create: `app/platform/db.py`、`tests/test_platform_db.py`
+- Modify: `app/main.py`（lifespan 初始化 platform engine + bootstrap）
+
+- [ ] **Step 1: 失败测试**
+
+```python
+# tests/test_platform_db.py 核心
+async def test_bootstrap_creates_superuser_once(tmp_path):
+    engine = make_platform_engine(tmp_path / "platform.db")
+    await ensure_platform_schema(engine)
+    await bootstrap_superuser(engine, username="admin", password="s3cret!")
+    await bootstrap_superuser(engine, username="admin", password="other")   # 幂等：不重复建/不改密
+    users = await list_admin_users(engine)
+    assert len(users) == 1 and users[0].username == "admin"
+    assert verify_password("s3cret!", users[0]) and not verify_password("other", users[0])
+
+async def test_platform_db_wal(tmp_path):
+    engine = make_platform_engine(tmp_path / "platform.db")
+    await ensure_platform_schema(engine)
+    # PRAGMA journal_mode == wal（照抄 test_registry 的查法）
+```
+
+- [ ] **Step 2: 实现 `app/platform/db.py`**
+
+```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 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)
+class AdminUser(id, tenant_id FK NULL=超管, username UNIQUE, password_hash, salt,
+                must_change_password BOOL, status, created_at)
+class PlatformSetting(key PK, value)
+
+def make_platform_engine(db_path) -> AsyncEngine:   # WAL + pool 2，照抄 make_tenant_engine 纪律
+async def ensure_platform_schema(engine): ...
+async def bootstrap_superuser(engine, username, password): ...   # 空表才建；must_change_password=True
+# hash: hashlib.scrypt(password, salt=salt, n=2**14, r=8, p=1)；verify 常量时间比较(hmac.compare_digest)
+```
+
+- [ ] **Step 3: main.py 装配**：lifespan 建 platform engine（`Path(__file__).parents[1]/"platform.db"`，.gitignore 已覆盖）挂 `app.state.platform_engine`；bootstrap 超管（env `ADMIN_USERNAME` 默认 admin / `ADMIN_PASSWORD` 默认 admin123，`must_change_password=True`）；退出 dispose。测试缝：`app.state.platform_engine` 预置则沿用（照抄 registry 缝模式）。
+
+- [ ] **Step 4: 全量回归 + 提交** `feat: platform.db 模型与超管引导（WAL/scrypt/幂等bootstrap）`
+
+### Task 2: 认证（登录/令牌/限流/改密）
+
+**Files:**
+- Create: `app/platform/auth.py`、`app/platform/routes/__init__.py`、`app/platform/routes/auth_routes.py`、`tests/test_auth.py`
+
+- [ ] **Step 1: 失败测试**（核心 8 项）
+
+```python
+def test_login_ok_returns_token(app_client):        # admin + 正确密码 → {"token", "role":"super", "must_change_password":true}
+def test_login_bad_password_401(app_client)
+def test_login_lockout_after_5_fails(app_client):   # 第 6 次 429/423，15 分钟窗（测试里可注入窗长）
+def test_token_expiry(app_client, freezer_or_short_ttl)   # 过期 token → 401
+def test_protected_requires_auth(app_client):       # 无 Authorization → 401
+def test_change_password_flow(app_client):          # 旧密改新密成功；旧密失效；must_change 清零
+def test_tenant_admin_role_scoped(app_client):      # 租户管理员 token 访问超管端点 → 403
+def test_logout_invalidates_token(app_client)
+```
+
+- [ ] **Step 2: 实现**
+- `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 语义）
+- 密码永不明文进日志；token 走 Authorization 头（无 Cookie，免 CSRF——spec §7.2）
+
+- [ ] **Step 3: 全量回归 + 提交** `feat: 平台认证（scrypt/内存token 8h/登录限流/改密/角色依赖）`
+
+### Task 3: 中间件豁免与 admin 挂载骨架
+
+**Files:**
+- Modify: `app/platform/host_middleware.py`（豁免 `/api/platform/`）、`app/main.py`（挂 auth_routes）
+- Test: `tests/test_admin_mounting.py`
+
+- [ ] **Step 1: 失败测试**
+
+```python
+def test_platform_api_bypasses_tenant_resolution(app_client):
+    # 未知 Host 下 POST /api/platform/auth/login 可达（不被中间件 404）
+def test_platform_prefix_not_open(app_client):
+    # 无 token 访问 /api/platform/tenants → 401（豁免≠放行，认证守护）
+def test_prefix_match_precise(app_client):
+    # /api/platform-evil/ 仍走租户解析（未知 Host → 404）——豁免必须 startswith("/api/platform/") 精确
+```
+
+- [ ] **Step 2: 实现**：中间件豁免规则 `path == "/health" or path.startswith("/api/platform/")`；顺序守护测试补一条（豁免后租户中间件仍最外层）。**全量回归确认既有 463 零破坏**。
+- [ ] **Step 3: 提交** `feat: /api/platform 豁免租户解析（认证守护）+ admin 路由挂载`
+
+### Task 4: TenantSource 抽象与 DB 源
+
+**Files:**
+- Create: `app/platform/tenant_source.py`、`tests/test_db_tenant_source.py`
+- Modify: `app/platform/registry.py`（构造收 source；`load_from_dir` 变 File 便捷构造【既有调用零破坏】）、`app/engine/services/ai_service.py`（PromptProvider 加 `from_config(md: dict)` 类方法）
+
+- [ ] **Step 1: 失败测试**
+
+```python
+async def test_db_source_loads_tenant(platform_db_with_tenant):   # 夹具：建租户+站点+域名+版本1 config_json
+    src = DbTenantSource(platform_engine)
+    loaded = await src.load_all()
+    rt_cfg = loaded[0]                      # slug/status/sites(含域名)/snapshot(含 wall+prompts)
+    assert rt_cfg.snapshot["push"]["prefix"] == "ai-kefu-jc"        # 快照组直读
+    assert "system" in rt_cfg.snapshot["prompts"]
+async def test_db_source_no_version_raises(...)                     # 有租户无版本 → 显性错误
+async def test_file_source_unchanged(...)                           # FileTenantSource 行为与旧 load_from_dir 一致（既有 test_registry 全绿即证）
+async def test_registry_reload_via_db_source(...)                   # DB 改版本 → registry_reload → 新配置生效
+```
+
+- [ ] **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` 键）
+- 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 更新）
+
+- [ ] **Step 3: 全量回归（463+新增）+ 提交** `feat: TenantSource 抽象——File源(测试/档案)与DB源(生产)，registry 数据源可切换`
+
+### Task 5: 租户管理 API（超管）
+
+**Files:**
+- Create: `app/platform/routes/tenant_routes.py`、`tests/test_tenant_admin_api.py`
+
+- [ ] **Step 1: 失败测试**（核心 6 项）
+
+```python
+def test_create_tenant_from_profile(super_client, file_source_app):
+    # POST /api/platform/tenants {name, slug:"demo", profile:"jiancai", admin_username, admin_password}
+    # → 201；platform.db 有 tenant+main 站点+版本1（config 内容=seed 档案）；租户管理员可登录
+def test_create_blank_tenant(...)              # profile=blank → 出厂默认配置
+def test_slug_immutable(...)                   # PATCH 改 slug → 400
+def test_add_domain_and_resolve(...)           # 加域名 demo.example.com → registry reload → resolve_site 命中（File/DB 源均可，测试用注入）
+def test_disable_tenant_releases(...)          # 停用 → resolve 抛 TenantDisabledError；engine 已 dispose
+def test_tenant_admin_cannot_create_tenant(...)  # 403
+```
+
+- [ ] **Step 2: 实现**（全部 require_super，除标注）
+- `POST /api/platform/tenants`：profile ∈ {auto, jiancai, blank}——auto/jiancai 读 seed_profiles/<slug>/ 合并出首版快照（tenant.json 的 config + wall.json + prompts/*.md 嵌入）；blank = 出厂默认；slug 校验（^[a-z0-9-]+$、不可变、与现有租户不撞）；同时建租户管理员账号
+- `POST /api/platform/tenants/{slug}/sites`（站点 CRUD：建站/停用）；`POST .../sites/{site}/domains`、`DELETE .../domains/{domain}`
+- `PATCH /api/platform/tenants/{slug}`（name/status；status≠active 触发 registry 释放）
+- 写操作后 `registry_reload(slug)`；域名表变更后重建域名索引（reload 内已做）
+- GET 列表/详情（含版本号、域名、管理员账号概要）
+
+- [ ] **Step 3: 提交** `feat: 租户管理API（创建向导消费出厂档案/域名/停用/slug不可变）`
+
+### Task 6: 配置 API——校验管线/版本/回滚/试金石
+
+**Files:**
+- Create: `app/platform/config_validation.py`、`app/platform/routes/config_routes.py`、`tests/test_config_api.py`、`tests/test_touchstone.py`
+- Modify: `app/engine/services/ai_service.py`（无改则不动）
+
+- [ ] **Step 1: 失败测试**
+
+```python
+def test_put_group_bumps_version_and_hot_reloads(super_client, db_source_app):
+    # PUT /api/platform/tenants/{slug}/config/brand {"color":"#ff0000"} → 200 {version:2}
+    # → registry resolve → brand.color 已变；GET config 返回新值+version
+def test_put_wall_bad_regex_400_with_field(super_client, ...):
+    # price_patterns 含 "([unclosed" → 400，错误信息含字段路径与 regex 字样；版本不涨
+def test_prompts_size_cap(...)                # company_facts > 50KB → 400
+def test_prefix_uniqueness_across_tenants(...)  # 把 auto 的 push.prefix 改成 ai-kefu-jc → 400（spec E1）
+def test_rollback_restores(super_client, ...):
+    # 版本列表 → rollback v1 → 生效值回到 v1；产生新版本（历史不可变）
+def test_touchstone_verdicts(super_client, ...):
+    # POST /api/platform/tenants/{slug}/wall/test {"sentences":["The total is €500...","预算5000美元","DN800 specs?"]}
+    # → 逐句 {action: blocked|pass|replaced, replacement?}——不落库不 bump 版本
+def test_tenant_admin_scoped_config(...)      # jiancai 管理员能改自己、403 改 auto（租户全开，spec §3）
+```
+
+- [ ] **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 纯函数给判定）
+- 鉴权：超管任意租户；租户管理员限自己（require_tenant）
+
+- [ ] **Step 3: 提交** `feat: 配置API（分组校验管线/整份版本/回滚/试金石端点/前缀唯一）`
+
+### Task 7: 头像上传与解析链
+
+**Files:**
+- Create: `app/platform/routes/upload_routes.py`、`tests/test_avatar_upload.py`
+- Modify: `app/engine/routes/public.py`（avatar 解析链：uploads → seed assets → static）
+
+- [ ] **Step 1: 失败测试**
+
+```python
+def test_upload_and_serve(super_client, app_client):
+    # POST /api/platform/tenants/{slug}/brand/avatar (multipart png ≤2MB) → 200 {avatar:"<uuid>.png"}
+    # → GET /api/public/avatar（该租户 Host）返回新图字节；config 版本+1
+def test_reject_bad_type_and_oversize(...)     # .txt → 400；3MB → 413
+def test_traversal_safe(...)                   # 文件名服务端 uuid 重命名；../ 不生效（解析链已有防线，测试钉住 uploads 段）
+```
+
+- [ ] **Step 2: 实现**：存 `data/uploads/<slug>/<uuid>.<ext>`（gitignore 已含 data/uploads/）；类型白名单 png/jpg/jpeg/webp（魔数校验优先于扩展名）；≤2MB；brand.avatar=文件名（经配置版本管线 Task 6——bump+reload）；public.py avatar 解析链变：`data/uploads/<slug>/<name>` → `seed_profiles/<slug>/assets/<name>` → `static/kefu-small.png`
+- [ ] **Step 3: 提交** `feat: 头像上传（uuid重命名/魔数校验/2MB）与三级解析链`
+
+### Task 8: 数据视图 API（会话/消息/推送日志）
+
+**Files:**
+- Create: `app/platform/routes/data_routes.py`、`tests/test_data_views.py`
+
+- [ ] **Step 1: 失败测试**
+
+```python
+def test_conversations_list_with_filters(super_client, seeded_app)
+def test_conversation_detail_with_messages(super_client, ...)
+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 3: 提交** `feat: 数据视图API（会话/详情/推送日志/租户scope强制）`
+
+### Task 9: 统计 API
+
+**Files:**
+- Create: `app/platform/routes/stats_routes.py`、`app/platform/stats.py`、`tests/test_stats.py`
+
+- [ ] **Step 1: 失败测试**（小夹具造数→精确数断言）
+
+```python
+def test_cards_and_funnel(...):      # 会话5→留资3→评估完成2→推送成功1
+def test_daily_trend(...)            # 两天的会话数按日分组
+def test_distributions(...)          # intent 三级占比 / source / site / country top
+def test_push_health(...)            # success/failed/skipped/duplicated 计数
+def test_cross_tenant_super_view(...)  # 超管无 tenant 参数=全部租户合并；有=单租户
+```
+
+- [ ] **Step 2: 实现**：`stats.py` 纯查询函数（输入 runtime/session，输出指标 dict）；路由 `GET /api/platform/stats`（超管，可 ?tenant=）与 `GET /api/platform/tenants/{slug}/stats`（require_tenant）；**逐库查询应用层合并，禁 ATTACH**（spec §7.6）；日期边界用本地时区（容器 TZ=Asia/Shanghai 部署期生效，代码用 naive local 约定并注释）
+- [ ] **Step 3: 提交** `feat: 统计API（卡片/漏斗/趋势/分布/推送健康，逐库聚合）`
+
+### Task 10: 清理单顺势收拢（#1/#2/#3）
+
+**Files:**
+- Create: `app/platform/config_views.py`、`tests/test_config_views.py`
+- Modify: 各 services 的 resolver import 改从 config_views（**re-export 保旧 import 路径不断**——或全量替换+旧名删；选全量替换，测试锚定）、`app/engine/services/conn_limiter.py` 与 `rate_limit.py` 的 0 语义注释与行为、`tests/conftest.py`（FakeAI 收敛）
+
+- [ ] **Step 1: 失败测试**：config_views 单入口（一次 import 拿全 resolve_*）；ws_conn_limit=0 与 rate_limit_per_hour=0 的语义统一测试（0=回退出厂默认，写进校验与文档）
+- [ ] **Step 2: 实现**：`config_views.py` 聚合 resolve_email/push/ai/contact_flags/context_seed_map/name_to_region_extras（函数体从各服务搬入，服务层 import 之）；0 语义统一（limiter 的 0 值回退默认）；conftest 加 `FakeAI` 公共类（三份拷贝收敛，旧测试改 import）
+- [ ] **Step 3: 全量回归 + 提交** `refactor: config_views 单入口 + 0语义统一 + FakeAI 收敛（清理单#1#2#3）`
+
+### Task 11: 生产装配切换与 bootstrap 脚本
+
+**Files:**
+- Create: `scripts/bootstrap_platform.py`、`tests/test_bootstrap_script.py`
+- Modify: `app/main.py`（TENANT_SOURCE 切换）
+
+- [ ] **Step 1: 失败测试**：bootstrap 脚本幂等导入两租户（跑两遍第二遍零变化）；db 源 boot 冒烟（bootstrap → DbTenantSource → registry resolve 两租户 → brand/墙/前缀就位）
+- [ ] **Step 2: 实现**：脚本（init schema → bootstrap 超管 → 逐 seed 档案导入租户[已存在 slug 跳过]）；main.py：env `TENANT_SOURCE`（db|file，**默认 db**；conftest 预置 file registry 的测试缝已有，不受影响——conftest 显式构造 File 源 app，不依赖 env 默认）
+- [ ] **Step 3: 提交** `feat: 生产装配切换DbTenantSource + bootstrap脚本（超管/两租户幂等导入）`
+
+### Task 12: Phase 2 收尾
+
+- [ ] **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 5: 提交** `chore: Phase 2 收尾——平台层完成`
+
+---
+
+## 显式不做（Phase 2 范围外）
+
+art-design-pro SPA 全部页面（Phase 3）；嵌入代码复制块的前端展示（Phase 3，API 已含 brand）；Dockerfile/部署/存量数据导入（Phase 4）；/health 分级健康（Phase 4 批次，清理单在案）；推送失败告警（二期）。
+
+## 执行注意（继承 Phase 1 血泪）
+
+conftest 跨循环三坑（async_db NullPool / TestClient portal / 禁 asyncio.run 直开租户 session_factory）继续遵守；所有测试路径 `Path(__file__)` 锚定；`PYTHONUTF8=1`；每任务提交带 Co-Authored-By。