QuestionProject/ai_knowledge_base_v2/docs/一期全链路验收记录.md

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

1. 验收信息

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

2. 验收结论

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

当前仍有一项上线前性能风险：结束主题时会同步生成主题摘要和成长档案，本次真实模型验收耗时约 42 秒。结果能够正确生成，但等待时间容易让用户误认为操作无响应，也会放大重复点击和网络超时风险。本项不影响数据正确性，但不应按“完全无风险”关闭。

3. 功能验收结果

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

4. 工程与部署验收

验收项	结果	实际结果
后端自动化测试	通过	107 项测试全部通过
OpenAPI 检查	通过	成功生成并检查 93 个接口路径
管理后台构建	通过	生产构建成功
用户端构建	通过	生产构建成功
Alembic 离线 SQL	通过	成功生成 1106 行迁移 SQL，并覆盖到 0023_simple_knowledge_route
全新数据库迁移	通过	在隔离 MySQL 数据库从零升级至最新版本，共生成 39 张表
数据库与 Redis 就绪检查	通过	/api/ready 返回数据库和 Redis 均已就绪，并返回 X-Request-ID
隔离生产编排	通过	使用生产镜像、独立数据库和 Redis 启动，所有容器健康
生产冒烟	通过	用户端、管理后台、静态资源、健康接口和就绪接口均可访问
生产安全开关	通过	DEBUG、短信模拟、模型模拟、飞书模拟均关闭；Redis 为强制就绪依赖
回滚与清理	通过	隔离生产容器、网络和临时数据卷均已完整移除，开发环境未受影响

5. 本次主动修复

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

6. 上线前风险与建议

P1：结束主题接口等待时间过长

• 现象：结束主题后同步执行主题摘要和成长档案两次模型处理，本次耗时约 42 秒。
• 影响：用户容易认为按钮没有生效；弱网或网关超时会使前端收到失败，但后端可能已经成功；重复点击可能产生重复任务。
• 建议：把主题结束本身改为快速提交，摘要和成长档案转为后台任务；增加处理中状态、幂等键和失败重试；前端轮询或通过现有任务状态刷新结果。
• 上线判断：内部小范围试用可继续；正式扩大用户前建议完成该项。

P2：前端构建体积提示

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

7. 验收数据说明

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