feat: 实现用户画像、占卜历史与后端用户管理模块

2026-04-06 01:28:10 +08:00
parent d87b2e1e3a
commit 8a18b3528b
77 changed files with 5850 additions and 2604 deletions
@@ -0,0 +1,403 @@
+# Eryao 工程计划：历史解卦与个人档案后端化（单一数据源）
+
+日期：2026-04-05  
+状态：规划中（Planning Only）
+
+## 0. 约束与决策前提
+
+本计划基于已确认前提：
+
+1. 当前无生产兼容压力，旧字段可直接不兼容。
+2. 前端只做缓存层，不做权威数据源。
+3. `ui_schema` 属于通用迁移遗留，不在本项目范围，目标是移除。
+4. 头像存储必须使用 `avatars` bucket（`config.storage.avatar.bucket`）。
+
+---
+
+## 1. 目标
+
+在不引入额外业务表的前提下，完成以下工程目标：
+
+1. assistant 消息落库时，`metadata.agent_output` 持久化完整 `divination_derived`。
+2. `GET /api/v1/agent/history` 返回前端可直接消费的 `assistant.agent_output`（移除 `ui_schema`）。
+3. 新增 profile 后端 API，前端设置页改为后端读写。
+4. 头像上传改为预签名 + `avatars` bucket，后端校验路径和类型。
+
+---
+
+## 2. 系统边界与职责
+
+### 2.1 边界图
+
+```text
+[Flutter App]
+   |  Auth Token
+   v
+[API Router v1]
+   |---- /agent/runs + /agent/history
+   |---- /users/me/profile + /users/me/avatar/upload-url
+   v
+[Service Layer]
+   |---- AgentService: 会话、历史、消息转换
+   |---- UserProfileService: 档案读写、头像签名
+   v
+[Repository Layer]
+   |---- sessions/messages/profiles CRUD
+   v
+[Postgres + Supabase Storage]
+   |---- messages.metadata_json
+   |---- profiles
+   |---- bucket: avatars
+```
+
+### 2.2 分层职责
+
+- Router：参数校验、鉴权入口、RFC7807 错误转换。
+- Service：业务规则与信任边界控制。
+- Repository：纯查询和写入，不做鉴权决策。
+- Schema：协议强类型、禁止松散 dict 漂移。
+
+---
+
+## 3. 数据流设计
+
+## 3.1 解卦写入链路（新增 `divination_derived`）
+
+```text
+POST /agent/runs
+   -> Runner emit DIVINATION_DERIVED(divination)
+   -> StageEmitter merge into TEXT_MESSAGE_END payload
+   -> EventStore picks worker_output_fields
+   -> metadata.agent_output.divination_derived persisted
+   -> messages.metadata_json
+```
+
+### 关键点
+
+1. `AgentOutput` 增加 `divination_derived` 强类型字段。
+2. `EventStore` 字段白名单纳入 `divination_derived`。
+3. `extra="forbid"` 保留，防止脏字段入库。
+
+## 3.2 历史读取链路（移除 `ui_schema`）
+
+```text
+GET /agent/history
+   -> AgentService.get_history_snapshot
+   -> convert_message_to_history
+      user      -> content + attachments
+      assistant -> content + agent_output
+   -> HistoryMessage response
+```
+
+### 关键点
+
+1. 停止 `ui_hints -> ui_schema` 编译。
+2. assistant 返回受控 `agent_output` 子集，不透传任意 metadata。
+3. 前端结果页以 `agent_output.divination_derived` 为主数据源。
+
+## 3.3 Profile 与头像链路
+
+```text
+GET /users/me/profile
+   -> read profiles
+
+PATCH /users/me/profile
+   -> validate payload
+   -> update profiles
+
+POST /users/me/avatar/upload-url
+   -> validate mime/size/path
+   -> create signed upload url (bucket=avatars)
+```
+
+---
+
+## 4. API 契约（冻结版）
+
+## 4.1 History 响应（目标结构）
+
+```json
+{
+  "scope": "history_day",
+  "threadId": "uuid",
+  "day": "2026-04-05",
+  "hasMore": false,
+  "messages": [
+    {
+      "id": "uuid",
+      "seq": 12,
+      "role": "assistant",
+      "content": "...",
+      "timestamp": "2026-04-05T12:34:56Z",
+      "agent_output": {
+        "sign_level": "中上签",
+        "summary": "...",
+        "conclusion": ["..."],
+        "focus_points": ["..."],
+        "advice": ["..."],
+        "keywords": ["..."],
+        "answer": "...",
+        "divination_derived": {
+          "binaryCode": "101001",
+          "changedBinaryCode": "100001",
+          "guaName": "...",
+          "targetGuaName": "...",
+          "ganzhi": {},
+          "yaoInfoList": []
+        }
+      }
+    }
+  ]
+}
+```
+
+说明：
+
+- 本接口不再返回 `ui_schema`。
+- user 消息仍可返回 `attachments`。
+
+## 4.2 Profile API
+
+### `GET /api/v1/users/me/profile`
+
+```json
+{
+  "user_id": "uuid",
+  "display_name": "string",
+  "bio": "string",
+  "avatar_path": "avatars/{user_id}/...",
+  "avatar_url": "https://...",
+  "updated_at": "..."
+}
+```
+
+### `PATCH /api/v1/users/me/profile`
+
+请求：
+
+```json
+{
+  "display_name": "string<=30",
+  "bio": "string<=200",
+  "avatar_path": "avatars/{user_id}/..."
+}
+```
+
+### `POST /api/v1/users/me/avatar/upload-url`
+
+请求：
+
+```json
+{
+  "mime_type": "image/png",
+  "file_size": 123456,
+  "ext": "png"
+}
+```
+
+响应：
+
+```json
+{
+  "bucket": "avatars",
+  "path": "avatars/{user_id}/{uuid}.png",
+  "upload_url": "https://...",
+  "expires_in": 600
+}
+```
+
+---
+
+## 5. 信任边界与安全规则
+
+1. `user_id` 只能取 JWT `sub`，禁止客户端传 owner。
+2. 头像 path 必须前缀匹配：`avatars/{current_user.id}/`。
+3. bucket 必须等于 `config.storage.avatar.bucket`。
+4. mime 白名单：`image/png|image/jpeg|image/webp`。
+5. size 上限：`config.storage.avatar.max_size_mb`。
+6. history 读取严格校验 session owner。
+7. 错误统一 RFC7807 + `code`。
+
+---
+
+## 6. 失败模式与处理
+
+## 6.1 消息落库阶段
+
+1. `divination_derived` 校验失败
+   - 行为：拒绝写入该字段并记录结构化日志。
+   - 错误码：`AGENT_OUTPUT_DIVINATION_INVALID`（新）。
+2. TEXT_MESSAGE_END 缺失关键字段
+   - 行为：整条 assistant 消息按失败路径处理，不写半残对象。
+
+## 6.2 history 读取阶段
+
+1. `agent_output` 缺失或损坏
+   - 行为：assistant 消息返回 `content`，并标记 `agent_output=null`。
+   - 前端：展示“历史记录不完整”提示，不崩溃。
+2. 非 owner 访问
+   - 行为：403，`code=AGENT_SESSION_FORBIDDEN`。
+
+## 6.3 头像上传阶段
+
+1. bucket/path 越权
+   - 422，`AVATAR_PATH_SCOPE_INVALID`。
+2. mime/size 非法
+   - 422，`AVATAR_FILE_INVALID`。
+3. storage 签名失败
+   - 502，`AVATAR_SIGNED_URL_FAILED`。
+
+---
+
+## 7. 关键边缘场景
+
+1. 用户连续点击“保存资料”两次：
+   - 以后端最后一次写入为准，前端按钮防抖。
+2. 上传头像成功但 profile 更新失败：
+   - 前端重试 profile PATCH，不重复上传。
+3. history 返回空列表：
+   - 前端展示空态，不触发本地假数据。
+4. 助手消息存在但缺 `divination_derived`：
+   - 卡片可展示摘要，不允许进入完整结果页。
+5. 解卦完成后 history 立即读取：
+   - 允许短暂读到旧快照，前端做一次重拉。
+
+---
+
+## 8. 技术取舍
+
+### 方案 A（推荐）：在现有 messages.metadata 扩展
+
+- 优点：
+  - 最小变更，不新增表。
+  - 复用当前会话与历史体系。
+- 缺点：
+  - metadata 体积增大，需要关注单条消息大小。
+
+### 方案 B：新增 `divination_results` 独立表
+
+- 优点：
+  - 结构更纯，查询更明确。
+- 缺点：
+  - 迁移、回写、关联复杂度明显增加。
+
+结论：
+
+- 当前阶段选 A，满足速度与复杂度平衡。
+
+---
+
+## 9. 实施切片（按风险顺序）
+
+### Slice 1：协议与 schema
+
+1. 更新协议文档：history + profile + 错误码。
+2. 更新 `AgentOutput` 模型字段。
+
+### Slice 2：写链路改造
+
+1. runner/emitter/store 打通 `divination_derived` 落库。
+2. 增加单元测试与集成测试。
+
+### Slice 3：读链路改造
+
+1. history 转换改为返回 `agent_output`。
+2. 移除 `ui_schema` 响应字段。
+
+### Slice 4：profile API + 头像
+
+1. users 路由、service、schema。
+2. 头像 upload-url 接口。
+
+### Slice 5：前端切换
+
+1. 历史列表/详情改消费后端 `agent_output`。
+2. 设置页改 profile 接口。
+3. 清理本地真源。
+
+---
+
+## 10. 测试覆盖计划
+
+## 10.1 后端测试矩阵
+
+### A. AgentOutput 落库
+
+1. `divination_derived` 正常写入。
+2. `divination_derived` 非法结构拒绝写入。
+
+### B. history 接口
+
+1. assistant 返回 `agent_output`。
+2. 响应不含 `ui_schema`。
+3. 非 owner 403。
+4. 空历史返回空数组。
+
+### C. profile 接口
+
+1. GET 返回当前用户档案。
+2. PATCH 字段边界（空、超长、非法字符）。
+3. 并发 PATCH 最终一致性。
+
+### D. avatar upload-url
+
+1. 合法 mime/size/path 成功签名。
+2. bucket/path 越权失败。
+3. mime/size 超限失败。
+4. storage 异常返回 502 问题体。
+
+## 10.2 前端测试矩阵
+
+1. history 列表从接口渲染。
+2. 点击历史项进入结果页并解析 `divination_derived`。
+3. profile 读写回显。
+4. 头像上传后刷新显示。
+5. 异常提示（网络失败、数据缺失）不崩溃。
+
+---
+
+## 11. 可观测性
+
+新增日志字段建议：
+
+1. history 响应统计：`thread_id`, `message_count`, `assistant_with_agent_output_count`。
+2. profile 更新：`user_id`, `updated_fields`。
+3. avatar 签名：`user_id`, `mime_type`, `file_size`, `success/failure_code`。
+
+指标建议：
+
+1. `history_agent_output_missing_rate`。
+2. `avatar_upload_url_failure_rate`。
+3. `profile_patch_error_rate`。
+
+---
+
+## 12. 风险与回滚
+
+### 风险
+
+1. 单条 metadata 变大，可能影响查询性能。
+2. 前端解析新结构时存在字段名误配风险。
+
+### 回滚
+
+1. 若读链路异常，先回滚 history 输出层（保持落库不回滚）。
+2. profile 接口异常时，可临时只读禁写，保护账户信息。
+
+---
+
+## 13. 验收标准（Done）
+
+1. 新产生 assistant 消息均含 `metadata.agent_output.divination_derived`。
+2. history 接口返回 `agent_output`，且不再返回 `ui_schema`。
+3. 前端历史页与结果页不依赖本地真源。
+4. profile 读写和头像上传全走后端。
+5. 测试矩阵项全部落地并通过。
+
+---
+
+## 14. NOT in Scope
+
+1. 大规模清理 `backend/src/schemas/domain/**`。
+2. 历史数据回填脚本。
+3. 新增独立 `divination_results` 表。