feat: 完成原型04-10全链路功能开发，包括AI助手、PDF导出等
This commit is contained in:
hujun
@@ -241,3 +241,58 @@ productSnapshot包含产品ID/版本/名称/机构/类型，amountMinYuan、amou
|
||||
报告入口携带assessmentId；列表三组统计与分页来自同次结果；卡片只预览最多三条主要理由，详情保留全部不符/待核实理由，已满足项可展开。无评估编号时选择历史或重新评估；非法编号明确错误，绝不读取最近结果。详情无assessmentId只展示公共资料，有assessmentId始终读取本人快照。页面离开清空结果，响应返回时校验当前Token和请求序号，防止旧账户迟到响应恢复界面。
|
||||
|
||||
本轮`tests/match_records.php --worker-stopped`62项验证接口身份/方法、三组、游标分页和篡改、快照归属、未知键投影、损坏数据、下架/过期/删除/改价后历史、旧版报告、重复读取无副作用。产品变化只在测试连接事务内发生并回滚，随机账户及队列清理；停止正式worker以避免恢复扫描拾取合成评估。浏览器结果及截图见开发进度6.13。
|
||||
|
||||
## 9. 单产品解释任务与原型04/05（2026-09-28已实现，覆盖第7/8节的未接入状态）
|
||||
|
||||
### 9.1 接口与状态
|
||||
|
||||
`POST /api/v1/assessments/:id/matches/:productId/explanation`要求会员Bearer Token、本人成功且未删除评估及该产品冻结结果，Content-Type为application/json。请求只允许`{"requestId":"explanation_20260928_001"}`；requestId为8—64位ASCII字母/数字/下划线/短横线，无金额或模型参数。重复读取GET不生成解释。
|
||||
|
||||
HTTP200沿用`{code:1,msg,time,data}`，data与匹配详情相同，不表示模型已经完成；客户端检查item.aiExplanation.status。queued/running期间轮询原GET匹配详情。例：
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "completed",
|
||||
"text": "该项信息来自自填资料，仍需核对证明材料。",
|
||||
"evidenceRefs": ["product:22:rule:base_amount"],
|
||||
"reasonExplanations": [{
|
||||
"reasonId": "product:22:rule:base_amount:reason",
|
||||
"text": "该项信息来自自填资料，仍需核对证明材料。",
|
||||
"evidenceRefs": ["product:22:rule:base_amount"]
|
||||
}],
|
||||
"generatedAt": "2026-09-28T07:07:00+00:00",
|
||||
"errorCode": null,
|
||||
"canRetry": false
|
||||
}
|
||||
```
|
||||
|
||||
上例只说明结构，不是完整产品样例。text/evidenceRefs兼容已有消费者；逐条渲染使用reasonExplanations，数值/来源仍取确定性证据，不能从模型文本反解析金额。首次not_requested；queued/running保留空文本/数组；失败为failed，errorCode仅固定错误码，canRetry表示未超过三次上限；成功为completed并带生成时间。有效的旧not_requested对象缺新增字段时，前端按空值兼容。
|
||||
|
||||
| HTTP/错误 | 含义与行为 |
|
||||
| --- | --- |
|
||||
| 401 AUTH_REQUIRED | 会话失效；客户端清理并回登录 |
|
||||
| 404 ASSESSMENT_NOT_FOUND / MATCH_NOT_FOUND | 非本人、已删记录或产品不在本次快照；不回退公共产品 |
|
||||
| 409 REPORT_NOT_READY / MATCH_RESULT_UNAVAILABLE | 报告未成功或存储结构损坏，不调用模型 |
|
||||
| 422 VALIDATION_ERROR | 非法requestId或多余请求字段 |
|
||||
| 503 ANALYSIS_NOT_CONFIGURED | 模型服务未配置，不预留新调用 |
|
||||
| 429 AI_DAILY_LIMIT | 与报告共用当日用户预留额度，开发默认二十次 |
|
||||
| 409 AI_ATTEMPT_LIMIT | 每评估每产品最多三次尝试，不再创建任务 |
|
||||
|
||||
模型/网络失败写入状态，不使用供应商异常正文：AI_TIMEOUT、AI_NETWORK、AI_AUTH、AI_CONFIGURATION、AI_BALANCE、AI_RATE_LIMIT、AI_PROVIDER_ERROR、AI_INVALID_RESPONSE、AI_INVALID_REPORT、AI_TASK_INTERRUPTED等。用户可读状态与规则理由仍保留；不自动重新调用收费模型。
|
||||
|
||||
### 9.2 持久化、幂等和恢复
|
||||
|
||||
- fa_ai_chat.match_result中的单项ai_explanation保存状态、reason_explanations及生成时间；内部还保存task_id/request_keys/attempts/lease_until。只更新这一个对象，不修改冻结参数、证据、判定、排序、报告或评估生命周期。不同产品更新同一JSON时使用会话行锁，防止相互覆盖。
|
||||
- fa_ai_chat_log使用role=assistant、request_id前缀`pex:`、pending/streaming/completed/failed以及已存在的模型/Token/耗时/错误字段。用户行锁串行预算预留；会话锁串行序号和快照写入。数据库事务原子保存任务和快照状态，不新增业务表/索引/迁移。
|
||||
- 相同requestId重放返回当前状态；queued/running期间不同键也合并为同一任务；成功后不同键返回历史解释。明确failed后用户使用新键重试，最多三次。次数包含失败和不确定超时，防止无限收费。
|
||||
- analysis:work继续优先处理既有报告队列，空闲时领取一条持久解释日志；pending任务无需Redis投递，进程重启不会丢失。租约为max(180秒,供应商超时+60秒)，streaming过期改失败；`--recover-only`也回收解释租约，不调用模型。服务停机期间queued保持等待，恢复进程后继续消费。
|
||||
- 多worker用日志状态和会话锁只允许一次领取。迟到回复不得回写已失效任务，已发生用量仍补记原日志。删除评估/禁用账户后不保存成功解释。运营需关注pending积压、失败错误码和调用用量；当前未实现独立解释后台管理页。
|
||||
- 分页摘要排除ai_explanation，解释生成不使产品分页失效；其他冻结字段仍参与摘要并校验。部署时已有旧摘要游标可收到一次MATCH_CURSOR_INVALID，重新从首屏读取即可，不改历史报告。
|
||||
|
||||
### 9.3 模型边界与页面
|
||||
|
||||
使用已配置deepseek-v4-flash-0731，只发该产品规则理由、字段白名单、actual/expected/source/outcome，不发送姓名、电话、证件、附件、机构说明自由文本或完整报告。模型输出仅reasons数组，每项reasonId/text；按ID集合检验恰好覆盖所有理由，无重复、遗漏和外来ID，恢复规则顺序后由服务端附原证据引用。每条最多九十字，数字/金额/期限/HTML/明显授信承诺等拦截。确定性校验不能替代真实产品人工语义金标准，正式机构资料仍待验收。
|
||||
|
||||
页面生成期间可离开，重新打开读取保存状态；每三秒查询、最多六十次，断网/轮询结束提供手动查询，不重提任务。页面离开清理个人数据和计时器；迟到回包校验Token/请求序号/可见性。初始依据、AI解释失败、已保存解释可区分；已有数值仍以万元精确展示。布局与有意差异见原型方案第8节。
|
||||
|
||||
验证入口：`php tests/product_explanations.php --worker-stopped`（51项，假模型）；可选`--live`额外调用一次真实Flash。`php tests/match_records.php --worker-stopped`更新为70项，含解释POST方法、归属、参数、删除记录和幂等回执。必须先停止worker，测试仅清理其随机账号/日志/评估/队列。真实模型和浏览器验证记录见开发进度6.18。
|
||||
|
||||
Reference in New Issue
Block a user