chore: Phase 3 收尾——平台设置页+全页冒烟+文档

Task 9（Phase 3 最后任务）：
- 平台设置页实装（settings/platform）：推荐键表单（ai.* 三键 /
  smtp.* 四键，键名为前端约定——PlatformSetting 是自由 KV 表）+
  存储总览表格；保存 = 逐键 PUT 只提交脏键（与 config 组整组替换
  不同）；密钥键哨兵交互与凭据页同款（已设置占位 / 清除 / 恢复
  保持 / 端口 1-65535 校验）；页头注记 resolver 回退链未接线、
  现阶段仅存储。
- api/settings.ts：fetchPlatformSettings / putPlatformSetting 实装
  （GET items 列表 / PUT 单键 upsert 形态钉在 docstring）。
- vitest +14（model 10 + api 4）：掩码判定后端镜像、归一/脏检测/
  提交值/校验/展示全覆盖；前端基线 139 → 153。
- 全页面浏览器冒烟通过（登录→强制改密→仪表盘双视角→租户管理→
  会话与线索→配置中心全组→统计分析→平台设置→退出→租户管理员
  视角菜单收敛）。
- CLAUDE.md：新增 Phase 3 完成状态段（基线 595/153、本地起法、
  admin 能力一览、前端约定）；Phase 3 清理单结项 7/11/12（掩码
  哨兵 / 站点权限 / push enabled 显式化）；Phase 4 清理单增补四项
  （components.dts 行尾漂移 / 推送探测 env 回退真址 / 生产反代
  /api/public / VITE_TENANT_PREVIEW_HOST 单域名）。README 现状
  刷新至 Phase 3。

Co-Authored-By: Claude Code <noreply@anthropic.com>

CLAUDE.md

@@ -86,10 +86,10 @@
 8. **400（预检撞车）vs 409（竞态 IntegrityError）并存**——API 冻结前统一。
 9. **limiter 全量清扫**（token/登录限流的内存键永不回访，长跑进程缓慢累积；收口 = 定期清扫）。
 10. **lead_push_service 的 settings re-export 锚**（app.engine.config 的 settings 在 lead_push_service 顶部 re-export，22 处测试 monkeypatch 依赖此锚——改动前先迁测试）。
-11. **密钥掩码未实现**——GET config/settings 返回明文 api_key/smtp 密码；Phase 3 前端对接前必须定掩码哨兵方案（GET 吐 `__SET__` + PUT 收哨兵保留旧值）（出处：终审审查 I-2）。
-12. **站点管理权限现为仅超管**（spec §7.3 写租户管理员同左）——Phase 3 对接时决策放开或改 spec（出处：终审审查 M-2）。
+11. ~~密钥掩码未实现~~（Phase 3 收口，commit 0c25287：GET config/settings 四处响应密钥值掩码为哨兵 `__SET__`，PUT 收哨兵保留库值；前端 `admin/src/api/mask.ts` secretToSubmit/secretPlaceholder 同款契约）。
+12. ~~站点管理权限现为仅超管~~（Phase 3 收口，commit 0c25287：放开租户管理员同权，与 spec §7.3 原文一致）。
 
-**Phase 3 清理单**（Phase 1/2 审查挂账滚动合并；~~删除线~~ 项已在 Phase 2 完成）：
+**Phase 3 清理单**（Phase 1/2 审查挂账滚动合并；~~删除线~~ 项已结，结项时点见各条注记；未结项滚入 Phase 4 清理单增补）：
 
 1. ~~FakeAI 三份拷贝收敛进 conftest~~（Task 10 完成：conftest.py 单一定义，tests/ 零拷贝）。
 2. ~~rate_limit 与 ws_conn_limit 的 0 语义统一 + 配置类型校验~~（Task 10 完成）。
@@ -97,19 +97,41 @@
 4. ~~avatar 从 seed_profiles 迁 uploads 卷~~（Task 7 完成：上传 + 三级解析链）。
 5. **AIService.from_runtime 类方法**——组装正典化（出处：引擎改造审查）。
 6. **boundary_filter 视图常量退役**——admin 重写后旧测试迁移时（出处：引擎改造审查）。
-7. **push enabled 布尔空槽语义**——admin 配置显式化时解决（出处：push 审查）。
+7. ~~push enabled 布尔空槽语义~~（Phase 3 收口：凭据页显式布尔开关 ElSwitch，normalize `enabled === true` 空槽归 false，提交永为显式布尔）。
 8. **contact.template_languages 运行期接线**——后台批次（出处：配置 schema 审查）。
 9. **话术含引号/换行的转义**——编辑器批次（`_format_deflection_pool` docstring 有注）。
 10. **产品决策项**：国名纠正 e164 变化时是否补发更正邮件（上游行为更优）；REST/WS 服务端 IP 口径是否统一（出处：上游吸收审查）。
 11. **/health 分级健康**——Phase 4 部署批次（进程存活之外按依赖分级上报；出处：终审审查 M-3）。
 12. **PromptProvider.from_dir 的 FileNotFoundError 带路径上下文**——提示词目录缺失时异常信息含实际路径（出处：终审审查 M-4）。
 
-## Phase 3 计划编写注意
+## Phase 3 完成状态（2026-10-13 收尾核对）
 
-- conftest 三坑纪律延续：`async_db` 夹具用 NullPool；TestClient 必须走 portal 桥接事件循环；禁止 `asyncio.run` 直开租户 session_factory（三个坑都在 tests/conftest.py 有既成解法，照抄勿发明）。
-- `build_app` / `app_client` / `TenantTestClient` 夹具已就绪，新测试优先复用而非自建 app 实例；**平台层测试用 `db_source_app` / `super_client` 夹具**（conftest.py：DB 源装配 + 超管登录态客户端，Phase 2 全部平台路由测试的既成姿势）。
-- 引擎侧读配置一律经 **config_views 单入口**（app/platform/config_views.py：resolve_email/push/ai_settings、resolve_contact_flags、context_seed_map、name_to_region_extras）——新消费点不再自写 resolver。
-- 统计前端照 **stats.py docstring 的指标口径表**展示（会话数不要求有消息、线索=三选一非空、推送成功率分母口径、北京日界趋势等，歧义处已定死）。
+**测试基线：后端 pytest 595 passed / 前端 vitest 153 passed**（Phase 3 起步 139，Task 9 平台设置页 +14；两端数字均已实跑核对，后端唯一 warning 仍为 starlette TestClient 弃用提示，无害）。`pnpm build`（vue-tsc --noEmit && vite build）零错误。后续回归以此为准。
+
+**交付形态**：`admin/` 子目录的 Vue3 + TS + Vite + Element Plus SPA（art-design-pro 模板，pnpm 管理），与后端同仓。本地起法：
+
+- 后端：`PYTHONUTF8=1 .venv/Scripts/python -m uvicorn app.main:app --port 8018 --workers 1`（不变）。
+- 前端：`cd admin && pnpm install && pnpm dev`（默认 3006，被占自动顺延）；Vite 代理 `/api` → 8018，`/api/public` 与 `/static` 走 Host 改写代理（`VITE_TENANT_PREVIEW_HOST`，见 admin/.env.development 注释）。`pnpm test` 跑 vitest；`pnpm build` 出 dist。
+- 登录：超管 / 租户管理员同一登录页（滑块验证为纯前端交互校验）；must_change_password 由后端 409 门强制，前端跳 `#/auth/force-change-password`。
+
+**admin 能力一览**（Phase 2 平台 API 的全量对接；菜单按角色过滤，后端 require_super / _tenant_guard 兜底）：
+
+- 认证流：登录 / 强制改密 / 退出；pinia + 内存 token，401 统一跳登录，改密 409 契约锁定。
+- 仪表盘：平台总览 + 租户卡片墙（超管）/ 我的指标（租户管理员），时间窗切换。
+- 租户管理（仅超管）：列表 / 创建向导（消费出厂档案）/ 详情编辑 / 站点与域名子资源 / 停用复启。
+- 会话与线索：列表（筛选 / 分页 / 租户切换）/ 详情消息流 / 推送日志 / 删除。
+- 配置中心：品牌（表单 / 本地简化预览 / 嵌入代码 / 头像上传）、提示词四件套与结构化词表、试金石面板、凭据（邮件 / 推送 / AI 表单 + SMTP 测试 + 推送探测）、版本历史（两版对比 / 回滚 / 组级重置出厂）。
+- 统计分析：卡片 / 转化漏斗 / 按日趋势 / 意向·来源·站点·国家分布（ECharts）/ 推送健康表；时间与租户筛选（口径同 stats.py docstring 口径表）。
+- 平台设置（仅超管）：自由 KV 表的推荐键表单（ai.* / smtp.*，键名是前端约定）+ 存储总览表格；保存 = 逐键 PUT（只提交脏键）。**当前仅存储与展示——resolver 的平台默认回退链未接线（页头注记），引擎不读取这些值**；密钥键掩码哨兵交互与凭据页同款（清除 / 恢复保持）。
+
+**前端实现约定**（后续维护须知）：
+
+- 视图逻辑沉淀在各 `views/**/model.ts` 纯函数（掩码判定 / 归一 / 脏检测 / 提交值构造 / 校验），vitest 直接覆盖；.vue 只做装配。auto-import 生效（ref/reactive/ElMessage 等无需手写 import）。
+- 密钥键判定前端镜像后端 `_SETTING_SECRET_MARKERS` 子串匹配（'monkey' 含 'key' 也命中——与后端一致是契约，不"修正"）。
+- PUT config 整组替换语义：前端封装读-改-写（GET 全组 → 改 → PUT）；平台设置不同，为逐键 upsert。
+- `components.d.ts` 构建漂移：`pnpm build`/dev 会重写入库的 dts（仅行尾差异）——`git diff --ignore-cr-at-eol` 为空即 `git checkout --` 还原入库版（超集原则，勿提交行尾噪音）。
+
+**滚动纪律**（自 Phase 3 计划注意延续）：conftest 三坑（NullPool / portal 桥接 / 禁 asyncio.run）、平台层测试用 `db_source_app` / `super_client` 夹具、引擎读配置走 config_views 单入口、统计展示照 stats.py 口径表——均照抄勿发明。
 
 ## Phase 4 部署记档（提前锚定，部署批次展开成 docs/deploy-production.md）
 
@@ -118,10 +140,16 @@
 - **TENANT_SOURCE=db 默认**（生产装配形态）；`file` 为冷备/本地调试回退。
 - **admin 域名反代区分**：`/api/platform/*` 前缀豁免租户 Host 解析——平台后台 API 可与租户聊天域名同源反代（按路径分流）或独立域名，两形态皆可；租户聊天面（`/`、`/static`、WS、`/api/public`、`/api/chat*`）仍严格按 Host 解析租户，未知 Host 404。
 - **ADMIN_PASSWORD 默认值警示**（终审 I-4）：lifespan 启动检测到 ADMIN_PASSWORD 仍是出厂默认（admin123）时打 WARNING 日志——生产部署必须设 ADMIN_PASSWORD 环境变量换掉，且超管首登立即改密（must_change_password 门强制）。
+- **Phase 4 清理单增补**（Phase 3 冒烟沉淀；Phase 3 清理单未结项 5/6/8/9/10 一并滚入）：
+  1. `components.d.ts` 构建行尾漂移（长期收口 = 生成物出库或 EOL 规范钩子，现阶段靠手工还原）。
+  2. 推送探测 env 回退真址：租户 push URL 空槽时 `resolve_push_settings` 回退 env `PUSH_API_URL`（默认即真 UniService 生产址）——后台点「探测」会对真实服务发空批量 POST（`{"messages": []}`，按契约文档应为无操作，但属真实出站）。收口 = 部署设 stub 域或探测端点拒绝 env 回退 URL。
+  3. 生产反代需规划 admin 域的头像/品牌公开端点：`/api/public/*` 按租户 Host 解析，admin 域直挂必 404——开发期靠 Vite Host 改写代理，生产要么同源反代改 Host（单租户形态）要么前端改用租户域名绝对 URL。
+  4. `VITE_TENANT_PREVIEW_HOST` 单一预览域名：开发代理只指向一个租户 Host，切换租户时头像等公开资源预览不准（.env.development 已注记）。
 
 ## 文档索引
 
 - 设计文档（spec）：`docs/superpowers/specs/2026-10-12-unified-kefu-platform-design.md`
 - Phase 1 实施计划：`docs/superpowers/plans/2026-10-12-phase1-engine-merge-tenantization.md`
 - Phase 2 实施计划：`docs/superpowers/plans/2026-10-13-phase2-platform-layer.md`
+- Phase 3 实施计划：`docs/superpowers/plans/2026-10-13-phase3-admin-spa.md`
 - 部署坑手册：Phase 4 补 `docs/deploy-production.md`（尚未存在；Phase 4 部署记档段已锚定要点）