# 千问千答一期全链路验收记录

## 1. 验收信息

- 验收日期：2026-07-31
- 验收分支：`codex/h5-qa-experience`
- 验收范围：权益体系、用户聊天、后台 Agent 预览、主题上下文、近期实修回顾、求助卡、分享稿、周期实修回顾、记录审计、数据库迁移与生产部署链路
- 验收方式：浏览器真实操作、接口调用、真实模型调用、自动化测试、隔离 MySQL 迁移、隔离生产编排及上线冒烟

## 2. 验收结论

一期功能主链路已打通，权益管理页面已完成布局重构，用户端和后台 Agent 预览均能够按学员、主题和权益运行。自动化测试、前后端构建、数据库迁移和隔离生产环境冒烟均通过。

2026-08-03 已完成主题沉淀异步化：结束主题接口只完成状态变更和任务入队，主题摘要、近期实修回顾由持久化后台任务生成；重复点击返回同一任务，失败自动重试，服务重启能够恢复，最终失败可由管理员手动重试。原先约 42 秒的同步等待不再阻塞用户请求。

2026-08-03 已完成实修记录 V2 改造：不再生成、展示或注入常见情绪、身体/关系模式、做过或有效功课、近期变化等长期画像字段；仅保留最近 30 天、最多 10 个新版主题形成的近期回顾、近期关注和可以继续留意的问题。旧版记录保留在数据库中用于兼容和回滚，但不会进入用户端或 Agent 上下文。

## 3. 功能验收结果

| 验收项 | 结果 | 实际结果 |
| --- | --- | --- |
| 权益管理页面 | 通过 | 编辑区按基础配置、能力权限拆分；桌面端和窄屏自适应；按钮、开关和表格不再拥挤错位 |
| 权益版本编辑 | 通过 | 编辑已有权益、退出编辑、启用状态和能力开关均可正常操作 |
| 用户登录 | 通过 | 通过真实页面完成验证码登录并进入聊天页 |
| 用户端流式问答 | 通过 | 显示“思考中”，随后流式展示 Markdown 回答；发送后输入框立即清空 |
| 用户端主题上下文 | 通过 | 连续消息均绑定同一主题，历史消息与主题上下文可继续使用 |
| 后台 Agent 预览 | 通过 | 可选择模拟学员和具体主题，能够加载权益、主题摘要、最近消息和近期实修回顾 |
| Agent 运行追踪 | 通过 | 能看到 `load_debug_user_context`、模型路由等追踪节点 |
| 主题沉淀 | 通过 | 结束主题快速入队；主题摘要与近期实修回顾后台生成；支持幂等、自动重试、重启恢复和管理员手动重试 |
| 求助卡 | 通过 | 可生成非空内容并记录复制状态 |
| 分享稿 | 通过 | 可生成非空内容并记录复制状态 |
| 周期实修回顾 | 通过 | 入队接口约 7 毫秒返回，后台任务能够完成并保存回顾；模型思考内容会在入库前剔除 |
| 近期实修回顾 | 通过 | 用户端只读取新版近期回顾、主题摘要和周期实修回顾，旧版画像不返回 |
| 后台用户详情 | 通过 | 可查看近期实修回顾、求助卡、分享稿和周期实修回顾 |
| 记录审计 | 通过 | 聊天列表与按需加载详情均正常 |

## 4. 工程与部署验收

| 验收项 | 结果 | 实际结果 |
| --- | --- | --- |
| 后端自动化测试 | 通过 | 114 项测试全部通过，包含 V2 数据隔离、异步入队、幂等、重试、重启恢复及推理内容过滤 |
| OpenAPI 检查 | 通过 | 成功生成并检查 95 个接口路径 |
| 管理后台构建 | 通过 | 生产构建成功 |
| 用户端构建 | 通过 | 生产构建成功 |
| Alembic 离线 SQL | 通过 | 成功生成 1154 行迁移 SQL，并覆盖到 `0025_recent_practice_review` |
| 现有数据库迁移 | 通过 | 开发 MySQL 已升级至 `0025_recent_practice_review`，数据库与 Redis 就绪 |
| 全新数据库迁移 | 通过 | 隔离 MySQL 从零升级到 `0025_recent_practice_review`，V2 字段与默认值均已生成，验收库随后清理 |
| 数据库与 Redis 就绪检查 | 通过 | `/api/ready` 返回数据库和 Redis 均已就绪，并返回 `X-Request-ID` |
| 隔离生产编排 | 通过 | 使用生产镜像、独立数据库和 Redis 启动，所有容器健康 |
| 生产冒烟 | 通过 | 用户端、管理后台、静态资源、健康接口和就绪接口均可访问 |
| 生产安全开关 | 通过 | `DEBUG`、短信模拟、模型模拟、飞书模拟均关闭；Redis 为强制就绪依赖 |
| 回滚与清理 | 通过 | 隔离生产容器、网络和临时数据卷均已完整移除，开发环境未受影响 |

## 5. 本次主动修复

全链路验证脚本在生成 Alembic 离线 SQL 时，被部分历史迁移中的在线数据库检查阻断。已为相关迁移补充分离的离线模式逻辑，并为默认权益数据补充明确字段类型。在线迁移行为保持不变，且已通过全新 MySQL 数据库实际迁移验证。

2026-08-03 浏览器验收时发现，个别模型可能把 `<think>` 推理过程和多个 JSON 草稿一起返回，旧解析逻辑可能将其降级为回顾正文。现已在结构化解析前剔除推理块，并从后向前选择最后一个可完整解析的 JSON；已补回归测试，思考过程不会再写入近期或周期实修回顾。

2026-08-03 对真实模型完成主题沉淀和阶段回顾验收：新版主题只保存“摘要 / 本次关注 / 可以继续留意”，近期回顾只保存“回顾正文 / 近期关注”；后台页面未出现旧画像字段，周期回顾正文未出现 `<think>` 或“思考过程”。

## 6. 上线前风险与建议

### 已关闭：结束主题接口等待时间过长

- 处理：主题结束与模型生成已拆分，持久化任务由独立 Worker 执行。
- 保护：数据库唯一约束和行锁保证重复请求只产生一条任务；最多自动重试 3 次；执行进程中断后自动恢复；后台支持手动重新入队。
- 用户体验：主题结束后立即提示“实修记录正在后台沉淀”，用户可以继续聊天；页面停留期间会自动查询完成状态。

### P2：前端构建体积提示

- 现象：管理后台构建仍有单个产物超过 500KB 的提示。
- 影响：不阻断功能，但会增加首次加载耗时。
- 建议：后续按页面拆包和延迟加载处理，不与本次权益页面重构混在一起修改。

## 7. 验收数据说明

验收使用专用测试学员和隔离生产数据库。隔离生产环境及数据卷已清理；测试学员最终恢复为基础版权益。开发数据库中保留的验收主题和聊天数据可用于后续问题追踪，不影响正式用户数据。
