airz-uniapp/docs/上下文AI助手开发契约.md

原型08上下文AI助手

版本1.3，2026-09-29。CHAT-001—003待验收；CHAT-004开发中。累计13次真实Flash调用，演示边界及金额精度连续三轮专项通过；真机、跨平台、真实产品与商业额度仍待验收。

1. 会话与事实边界

• 复用fa_ai_chat/fa_ai_chat_log，不新增业务表。助手始终scene=assistant、assessment_id=NULL、analysis_context=NULL。
• context_assessment_id可空，仅引用本人成功评估；复合外键(context_assessment_id,user_id)防跨账户绑定。context_data保存版本、创建幂等键、最多3个产品ID和冻结事实摘要，不接收客户端报告正文。
• 普通、报告、单产品、2—3项对比均可进入。服务端读取冻结报告、匹配理由和证据，白名单排除姓名、手机、证件、附件、职业及自由用途说明；产品名称/数字/判定采用评估时版本，不读取当前产品替换历史事实。
• 会话固定上下文。URL指定的评估及产品须与chatId一致；上下文删除、失效或摘要变化则拒绝。后续单产品AI解释和当前上下架状态不参与摘要，不影响会话恢复。
• 模型仅解释，不改变规则结论，不生成匹配率、获批概率或授信承诺。系统约束和输出格式校验不等同于语义完全正确，正式上线仍需真实多轮人工验收。

2. 已实现接口

均为会员Bearer、Cache-Control: no-store、FastAdmin响应格式。业务成功HTTP200不表示异步模型完成。

方法与路径（前缀/api/v1）	参数	返回data
GET /assistant/context	contextAssessmentId可空字符串、contextProductIds逗号列表	上下文标题、产品名/实际状态、快捷问题和说明；不创建会话、不调用模型
GET /assistant/chats	limit字符串1—30，默认20；cursor可空	本人普通会话items、hasMore、nextCursor；按创建ID倒序
POST /assistant/chats	requestId；contextAssessmentId字符串或null；contextProductIds字符串数组	chatId、title、context；只创建会话，不调用模型
GET /assistant/chats/:id	可选contextAssessmentId/contextProductIds，同preview格式	chatId、title、context；传入上下文时严格核对一致
GET /assistant/chats/:id/messages	limit字符串1—30，默认20；cursor可空	chatId、items、hasMore、nextCursor；首屏最新20轮，页内按时间正序
POST /assistant/chats/:id/messages	requestId、message、retryAttempt整数0—2	chatId、item；queued/running/completed/failed

requestId为8—64位字母、数字、下划线、短横线。message为1—800字纯文本。拒绝额外参数、无评估产品列表、重复产品或超过3项产品。创建同键不同绑定、发送同键不同正文均409；越权或不存在404，未完成报告409，未配置模型503，超额度429，非法参数422。

每轮DTO为{id,requestId,message,reply,status,attempt,canRetry,createdAt}，reply仅成功时非空。消息内部调用行、错误码、凭据、用量不透传页面。加密游标绑定用户及会话，不能跨会话使用。

3. 异步、重试与额度

• 用户明确发送后，在用户行锁及会话行锁中保存用户消息并预留assistant调用行。ast:前缀调用日志是持久待办，既有analysis:work在报告和产品解释队列空闲时消费。
• 每会话最多100轮、同一时间只有一条回复在排队/执行。每用户每天最多新建30个会话。模型调用与报告和产品解释共享deepseek.daily_calls_per_user（本地默认20），失败也占预留次数，防止故障重试无限计费。
• 第一次retryAttempt=0。HTTP回执丢失必须原requestId/正文/重试序号重放，不增加调用。已确认失败后，用户手动重试保持requestId、retryAttempt递增，最多3次；只能重试最近一轮，成功和运行中均不能重跑。
• 每次尝试独立assistant日志，reply_id指向同一用户消息。保留所有尝试用量；tokens未知保持null，不把失败当零消耗。MySQL可重复读下关键幂等、序号和额度查询使用锁定当前读，避免旧快照绕过串行用户锁。
• 运行租约max(180秒,供应商timeout+60秒)。超时由worker恢复扫描标失败，不自动收费重试；迟到响应只能补原调用用量，不能改成成功或覆盖新尝试。
• 默认Flash，复用既有DeepSeekClient。上下文保留最近6轮成功问答（失败不发送），回复最长1200字，总请求序列化最多96KB；用户主动输入的手机号、身份证及长银行卡号脱敏后才发送模型。不声称自由文本已完全去除所有个人信息。

4. 页面与返回

机器人、问候气泡、浅蓝快捷问题及底部输入栏参考原型08，复用现有素材；上下文卡为必要增补。普通模式不假定已有报告。快捷问题按实际判定生成，点击仅填入问题，点击发送才请求模型。

首次发送创建会话并在H5地址中保存chatId，刷新重新鉴权恢复；历史对话入口可恢复普通或上下文会话。消息3秒轮询，最多60次，超限/查询失败提供继续查询。失败明确提示并支持原键重试。消息、报告不落本机持久缓存；离页清理渲染和轮询，Token变化拒绝迟到回包并清除内容。

04/05咨询入口保留产品ID，07保留产品选择，09带本次评估；navigateBack优先保持原页面状态。冷启动的返回产品/对比/报告仅由白名单来源与编号重建；普通模式回首页。登录页只支持白名单助手返回，拒绝任意returnUrl；登录后再次校验归属。

5. 迁移与验证（2026-09-28阶段记录）

本轮用户明确授权本机迁移后，执行后端database/migrate_assistant_context.py --apply --worker-stopped。新增2列、索引、归属外键与场景检查约束共5项；复跑预检0项。备份位于D:/AAdesk/202609/airz-backups/assistant-context-20260928-154651-271907/。恢复优先回退助手代码并保留可空列，不整表覆盖后续业务数据，详见后端database/assistant-context-migration.md。

后端70项助手检查、51项产品解释、31项任务、36项评估HTTP、70项匹配HTTP/快照检查通过。HBuilderX5.26 Android与微信编译通过。H5 Chromium390×844、1280×900验证普通/上下文、三入口、发送/刷新/失败重试、回执丢失、23轮历史分页、上下文冲突、跨账号及真实密码登录返回；模型输出使用假模型，未新发收费DeepSeek调用。最终正常流程无业务console.error/warn。

临时截图/脚本：C:/Users/JUN/AppData/Local/Temp/airz-assistant-20260928/。合成账号/评估/会话/日志/令牌/队列已清理，隔离服务和浏览器已关闭。原有2份评估会话及2条调用记录逐条对照迁移前备份未改写。未验收：真实多轮模型语义、真实产品人工金标准、微信内H5/Safari、真机键盘/安全区以及生产守护/容量。

6. 2026-09-29真实模型与修复

完成6次真实Flash调用，普通及对比各两轮；金额、三态、历史与注入拒绝核心表现正确。演示产品的申请建议需进一步限定，已修改提示词，修改后待真实复测。解析层有限豁免明确否定句并规范化常见列表，不能替代语义审查。70项助手回归、24项解析/离线回放及20项合成流程通过；真实调用记录、用量、逐例结论和未验收项见真实语义验收记录。无迁移，原有两份报告未改写，worker已恢复。

7. 定向复测与金额守卫

追加4次真实Flash，演示产品不能实际申请、用户口头修改／自称核验不能更改当前报告的边界正确；3条出现12.35万元舍入。新增冻结金额白名单与BCMath精确换算表，带上下文的显式金额必须来自报告或产品条件证据，不四舍五入；失败保留用量、不落错误成功回复、不自动重试。无上下文的一般知识不应用个人金额白名单。此规则不覆盖全部字段归因、无单位数值或所有自然语言表达，不能替代人工语义验收。

76项助手、29项金额及两组旧响应离线回放检查通过；本轮3条错误金额被拒绝，首轮6条不受影响。金额提示词修订后未再收费复测，真实成功率仍待验证。详细证据见真实语义验收记录。

8. 金额精度真实三轮专项通过

现行源码及金额守卫下，同一对比会话三轮真实Flash成功保存，始终正确引用123456.78元＝12.345678万元；口头修改不替换冻结报告，三态不变。真实／假模型各11项流程、30项金额检查与回放、21项格式检查与回放通过。本轮生产代码未改；小样本不代表全量金额、所有输出格式或真实产品验收通过。完整证据见真实语义验收记录。下一步移动端及跨平台验收。