root/airz-uniapp
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: 重构评估流程为内存状态管理并接入真实提交与报告接口

Browse Source 
本次重构将评估草稿改为内存状态管理，移除本地存储草稿，新增评估流程内存状态模块；接入真实的账户资料获取、头像上传接口，新增账户缓存清理逻辑；重构评估提交逻辑，接入真实提交接口并返回评估ID；新增分析页和报告页的真实状态查询、报告获取功能；更新README文档，记录开发进度和接口状态。
This commit is contained in:
hujun
2026-09-24 11:50:07 +08:00
parent dcf12a4471
commit dbfd637388
22 changed files with 1468 additions and 434 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/开发文档.md
+188 -74
View File
@@ -1,25 +1,106 @@
# AI 融资平台开发文档
> 版本：v1.0 · 基线日期：2026-09-22 · 状态：M0与账户基础已启动，真实短信/AI/产品依赖未就绪
> 配套台账：[开发进度](开发进度.md)。本文定义范围、接口和验收口径，台账记录实际执行与证据。
> 版本：v1.4 · 基线日期：2026-09-22 · 更新日期：2026-09-24 · 状态：需求输入与报告v2自填支线已实现；完整度/准备状态及执行策略冻结已接入，真实产品匹配待实施
> 配套台账：[开发进度](开发进度.md)。本文定义范围、接口和验收口径，台账记录实际执行与证据。
> 文档初始规划后已开始开发；以下更新记录优先于原始基线。除明确列为已实现的部分外，计划接口和增量数据仍待开发。
## 0. 2026-09-22 实施更新
- 用户最新决定：删除fa_user_token，会员Token仅存Redis；已备份并删除本地表，当前25张表。fa_user和各业务关系保持不变。运行配置不再依赖MySQL Token驱动。
- 已接通Bearer、FastAdmin响应解包、业务错误/401处理；新增v1密码登录、本人资料读取、退出、原密码改密。短信接口返回明确未配置状态。
- 前端开发环境指向本地真实接口，按稳定userId隔离本机缓存；测试/生产地址、匿名旧草稿显式导入和敏感缓存清理仍待完成。内容等尚未开发模块仍存在原型数据，不能判一期已完成。
- 前端开发环境指向本地真实接口，按稳定userId隔离本机缓存；测试/生产地址、旧草稿已清理且不导入；生产缓存策略仍待验收。内容等尚未开发模块仍存在原型数据，不能判一期已完成。
- Redis驱动使用独立前缀、摘要Token键、TTL和Lua原子索引/撤销。登录和改密按用户行锁串行，Redis故障不降级到MySQL。
- 短信服务商、DeepSeek测试权限、首批真实产品资料目前均未具备；不创建模拟凭证、不伪造AI结果或导入演示产品充当真实资料。
- 短信服务商和首批真实产品资料未具备；DeepSeek两个指定模型已通过真实连通性验证，自填资料分析已接入；不创建模拟凭证、不伪造AI结果或导入演示产品充当真实资料。
- 开发任务编号及原69–117人日估算基线保留，尚未填写实际耗时，不凭实施条目推算剩余工期。最新状态与证据见进度文档第0章。
### 0.1 最新范围调整与账户实施（2026-09-22）
- **取消评估草稿功能**：不提供云端创建/更新草稿API，不在本机持久化未提交表单，不提供保存、续填或旧草稿导入。填写页→确认页只传递内存对象；退出账户、离开流程、刷新后清空。正式提交成功才保存fa_user_info及关联评估会话；该接口已于2026-09-23接通，当前边界见0.2。
- 账户GET/PUT profile、POST avatar已实现；头像限制500KB，校验真实图片类型和尺寸、重新编码PNG，附件归属校验。昵称和头像从服务端读取，恢复默认头像传avatarId=null。
- 退出、过期及401清理对应userId账户缓存及临时表单；启动时清理旧草稿缓存键。其他用户的普通缓存不做全局清空。
- fa_user_info仅新增city_code和operating_months标准字段。中途草稿专用revision/client_draft_id及唯一索引已备份撤回，没有新增评估表。原draft状态仅保留为既有内部生命周期兼容，不表示提供用户草稿功能；后续正式提交须在同一事务完成建记录和转processing。
- DeepSeek通过[腾讯云TokenHub官方文档](https://cloud.tencent.com/document/product/1823/132248)所述OpenAI兼容接口接入：`https://tokenhub.tencentmaas.com/v1/chat/completions`，Bearer认证。模型按用户指定使用`deepseek-v4-pro-0813`、`deepseek-v4-flash-0731`，不自动更换别名。密钥仅在后端忽略的.env中，application/extra/deepseek.php读取；2026-09-23两个指定模型真实请求通过；Flash已生成个人/企业自填分析，商业预算及供应商余额仍待运营确认。
- 任务编号保留，ASSESS-002改为正式评估历史读取。69–117人日保留为原估算基线，取消草稿后尚未重新估算，不将其表述为最新剩余工时。
### 0.2 2026-09-23 正式评估提交与历史查询（当前实现）
- 新增POST /assessments及GET列表、详情、状态；无新增表、字段或迁移。复用fa_user_info、fa_ai_chat、uk_user_request与现有生命周期。
- 同一事务保存完整输入、唯一评估会话和最终状态；在用户行锁内检查幂等键，比较规范化冻结字段（身份证仅内部解密比较，不下发）。响应为HTTP201、`{assessmentId,submissionStatus:"accepted"}`，不把未来变化的taskId或分析状态放入固定提交回执。旧键异内容/已删除记录返回409。
- 分析Job/DeepSeek尚未接通时，当前正式记录为failed，errorCode=ANALYSIS_NOT_CONFIGURED，显示“资料已保存，分析服务尚未开放”。这是此前关闭分析的行为；当前报告/retry已接入，匹配仍待开发，最新状态见下文“DeepSeek与可靠任务实施”。
- 前端提交前精确把万元换成元字符串，空值转null；后端严格白名单并拒绝数值型金额、超范围或多余字段。文字选项映射稳定枚举；五个现有城市使用已核实代码，自填城市代码为null；经营月数/计数0与未知null分开。
- 私有附件及正式外部授权未接通，documents、consentIds当前只接受空数组；选图/勾选仍是本次流程内存，提交时明确阻止而非丢弃。身份证仅格式校验，不代表实名认证。
- 历史列表使用id游标，最多50条，默认20条；详情只读且敏感字段脱敏；不存在、内部draft、软删除与越权均不公开。前端具有空态、错误重试、加载更多和按编号刷新详情。
- 无草稿原则继续有效；幂等键只存在当前填写流程内存，网络失败重试不换键、内容变化才换键。刷新后未提交内容丢弃；若怀疑上一请求已保存，先查历史，不承诺跨刷新恢复提交键。
- 测试和任务证据见开发进度2026-09-23记录；任务剩余工时仍保留原基线，未据此推算完成率。
## DeepSeek与可靠任务实施（2026-09-23，当前实现）
- 默认模型为 `deepseek-v4-flash-0731`；`deepseek-v4-pro-0813` 已通过真实连通性验证，可配置选用，不自动回退或换模型。官方协议使用 `thinking:{type:"disabled"}`、`response_format:{type:"json_object"}`，后端Bearer调用。前端不保存密钥。
- 正式提交在事务内创建评估、会话及调用预留，事务提交后投Redis队列 `airz-analysis-v1`。队列只携带 assessmentId/taskId，任务事实保存在数据库。stage从queued→running→completed/failed；整体status仍为processing/succeeded/failed。
- 新增任务字段均在fa_user_info：task_requests JSON、task_stage、attempt_count、lease_until、dispatched_at及idx_task_dispatch索引。没有新增评估/报告/匹配表。迁移工具 `database/migrate_analysis_tasks.py --apply` 已在本地执行，执行前评估表0行；备份 `D:/AAdesk/202609/airz-backups/analysis-tasks-20260923-172957-846359/user_info.sql`。
- running通过行锁和taskId抢占。漏投、Redis丢消息及消费前崩溃由queued扫描补投；执行租约过期记AI_TASK_INTERRUPTED，不自动重复调用收费模型。迟到结果不得覆盖新taskId或报告，但原调用用量仍计入原日志。外部服务未提供幂等保证时，无法承诺重试零重复计费。
- 默认开发配额：每用户自然日20次预留，单评估最多3次（首次＋2次重试）；用户行锁串行化预留，失败也占一次。按PRC时区计日；待定的商业收费/月预算仍属DEC-AI。超时未知tokens记录null，绝不能当作0或免收费。fa_ai_chat_log记录模型快照、状态、tokens、耗时及固定错误码，不保存密钥/供应商错误原文。
- 报告输入仅白名单数值事实和个人/企业类型，不发送姓名、手机号、身份证、企业名称、雇主、自由文本或附件。数值由服务端提供，未知字段为null；模型解释只作定性分析。禁止正文复述阿拉伯/全角数字及中文金额、期限、比例，结构/引用/长度不合格即失败。此校验不替代人工评估模型语义。
- 当前reportType=self_reported_analysis，overallScore=null；facts每项包含id/label/value:string或null/unit:yuan或month或count/source:self_reported。客户端金额统一精确转换万元。observations引用已知factId；无评分规则时不展示固定分数/雷达。match_result=[]且matchingStatus=unavailable，明确“未执行匹配”，不能误称“匹配后没有产品”。模型和报告内容作为历史快照保存。
- 分析页每5秒读取状态，可离开后从档案恢复；失败时提供重试，网络失败复用该次requestId，taskId变化后生成下一键。成功后由用户打开绑定assessmentId的报告。档案和个人中心报告入口均指向真实记录；页面离开清报告，账户切换拒绝旧请求回写。无草稿、无新增页面。
运行与恢复（在后端目录执行，需PHP Redis/cURL/BCMath/mbstring及MySQL/Redis就绪）：
```powershell
php think analysis:work
php think analysis:work --once
php think analysis:work --recover-only
```
本地私密.env已开启deepseek.enabled；示例配置默认false。修改模型/配置/任务代码需重启常驻worker。开发终端进程不等同生产守护；生产Supervisor/systemd、告警及备份恢复仍由RELEASE/ADMIN验收。关闭开关后新提交仍保存资料，状态为failed/ANALYSIS_NOT_CONFIGURED，可在服务恢复后手动重试。
新增错误码：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、AI_DAILY_LIMIT、AI_ATTEMPT_LIMIT；客户端只显示安全中文信息。401/404维持账户鉴权和归属语义。任务运行失败不改变原始提交的HTTP201固定回执。
测试：先停全部analysis worker，再执行 `php tests/analysis_tasks.php --worker-stopped`（29项，假模型）；`php tests/analysis_http.php --worker-stopped`（15项，随机本机HTTP端口及测试队列）。恢复扫描以数据库为准，仅隔离Redis队列不能阻止常驻worker发现测试行，因此必须停worker；测试会清理合成用户/记录。`--live`仅在任务测试中额外真实调用一次；`php tests/deepseek_smoke.php --live`会真实调用两个模型。原tests/api_assessments.php为分析关闭分支回归，开关开启时主动SKIP，禁止忽略该提示当作通过。
验证边界：已完成个人合成资料真实分析、企业H5失败重试→队列worker→真实报告→刷新恢复；Chrome普通H5与Android编译通过，不代表微信内H5、Safari、原生真机或生产已验收。真实产品与评分规则、外部查询/私有授权尚未具备，因此REPORT-003/004完整范围保持未验收。
### 0.4 2026-09-23 需求与评估结果契约补充（历史阶段，仅文档）
已根据用户补充的原型和旧开发说明书，新增[需求与评估结果数据契约](需求与评估结果数据契约.md)，作为融资需求、完整度/准备等级、匹配解释三个范围的具体规范。其新增定义优先于本文中同名目标类型的简略说明；“当前实现”段落仍只代表已经运行的v1能力。
- 新输入inputVersion=2，计划补requestedAmountYuan、requestedTermMonths、purposeCode、purposeDetail；数据库存元的DECIMAL(11,2)，客户端万元，不恢复草稿。
- 完整度由版本化字段清单计算；准备等级是资料状态，规则需DEC-READINESS发布。未发布不展示分数或等级；与授信/审批概率严格区分。
- 产品硬准入pass/fail/unknown合并为eligible/ineligible/unknown，保留证据；score可空，理由按事实最多展示三条，不凑数。未执行、零候选、执行失败分别表达。
- 结果resultVersion=2计划新增，v1历史不重算；提交事务冻结输入/用途字典依据，worker首次抢占后、外部调用前补入计算策略/产品快照，重试复用。新输入列及fa_ai_chat.analysis_context仅为迁移设计，本次没有执行迁移。
- 新增DEC-DEMAND、DEC-READINESS决策项；DEC-MATCH继续确认产品规则与排序。字段字典建议、完整度字段集合和准备等级建议尚未发布，不写成已确认商业规则。
- 本次仅补文档，相关业务子项均未开始。保持原60个任务编号并同步扩展范围；原工时为历史基线，增量待重估。本次不自动纳入渠道、注销、RAG、对比或PDF开发。
### 0.5 2026-09-24 融资需求v2实施（历史阶段，报告版本以0.6为准）
- DEC-DEMAND按用户授权采用契约用途字典及必填规则，已发布 `financing-purposes-20260923-v1`。个人/企业在原第2步录入金额、整数月期限、资金用途及other说明；确认页独立展示，历史详情按冻结标签回显，旧v1显示“当时未采集”。无草稿，刷新/离开清空未提交输入。
- GET `/api/v1/dictionaries` 已公开实现，返回支持输入版本、最低新建版本、带版本的用途项；响应no-store。当前只发布融资用途及输入版本，不宣称地区等全部字典已动态化。配置位于后端 `application/extra/assessment.php`；修改用途须提升字典版本，移除条目即停止新建使用，旧回放读取冻结内容；后台编辑尚未实现。
- POST `/assessments` 新建最低inputVersion=2。需求金额使用元两位十进制字符串（0.01—999999999.99），前端万元字符串精确转换；期限1—9999整数月。用途按个人/企业区分；other说明trim后2—200字，非other只接受null/缺省；信用卡已用大于总额返回422 FIELD_INCONSISTENT。
- 已有请求先按原版本和冻结字典比较：同内容HTTP201原回执，合法内容或版本改变409，非法格式422；v1原键可重放，新v1键422 INPUT_VERSION_UNSUPPORTED。详情只返回本人脱敏资料；用途字典/哈希失效明确503，不套当前配置猜历史含义。
- 本地2026-09-23已执行 `database/migrate_assessment_demand.py --apply`：fa_user_info增加input_version及需求四列，fa_ai_chat增加analysis_context，新增3个CHECK；共9项变更，无新表。迁移前两表均0行，复跑预检0项DDL。恢复点：`D:/AAdesk/202609/airz-backups/assessment-demand-20260923-195131-493172/before.sql`。默认只预检，禁止把备份覆盖后续业务数据；优先保留兼容列回退代码。
- 提交事务冻结 `input_snapshot={inputVersion,normalizationVersion,purposeDictionary}`，字典保存完整内容，规范排序JSON后计算inputHash。基础字段校验仍由固定normalizationVersion代码解释，未冻结全部字段规则全文；后续修改必须保留旧版本处理。execution_snapshot、executionHash、contentHash当前为null，执行策略/产品快照仍待REPORT-002实施。
- 输入版本与报告版本独立：新v2输入继续生成resultVersion=1自填报告。本轮需求未进入模型事实、准备等级或产品匹配；自由用途说明不外发。REPORT-003/004及DEC-READINESS/DEC-MATCH保持未完成，不把本次录入闭环称为报告v2。
- 验证：2026-09-24专项76项通过；2026-09-23基础41项、任务29项、隔离HTTP15项通过。个人/企业H5提交及历史刷新、金额精度、旧未采集、用途失败恢复与无草稿已验证；Web/Android本地编译通过，未验收微信内H5、Safari或真机。此次未调用真实模型，完整证据见开发进度0.5与6.5。
### 0.6 2026-09-24 资料完整度、准备状态与报告v2（当前实现）
- 根据用户继续下一步的授权，采用专项契约首版等权字段集和三种资料准备状态；DEC-READINESS开发版发布为 `self-reported-base-20260924-v1`。个人14项、企业9项，other各加1；有效零值/none计已填写。缺失、无效、不适用分开记录，按整数四舍五入计算百分比；invalid或一致性问题优先“需核实资料”，其次“待完善资料”，全部填写为“可进入资料核对”。这是自填资料准备状态，不是信用或授信等级。
- 策略配置在 `application/extra/readiness.php`，引擎版本 `equal-fields-v1` 固定定义字段类型、范围、条件项、计数和优先级；字段定义、适用清单、条件规则、标签及版本完整复制至execution_snapshot。变更业务含义须提升策略版本；变更算法/类型须提升引擎版本并保留旧版处理，不能原地改变历史策略含义。
- 新提交input_snapshot冻结targetResultVersion=2；升级前缺该标记或标记1的评估继续生成v1报告，已有成功报告不重算。本轮没有迁移或改写原业务记录。首次worker抢占后、外部调用前持有评估行锁，写入执行策略、evaluatedAt、目标报告版本和明确的匹配unavailable原因，生成executionHash/contentHash；失败重试沿用原快照。策略异常/分母为0报ASSESSMENT_POLICY_INVALID，快照损坏报ASSESSMENT_CONTEXT_UNAVAILABLE，均在模型调用前失败。
- GET `/assessments/:id/report` 现按resultVersion支持v1/v2；v2为financing_needs_analysis，包含demand、带类型/单位/来源的facts、completeness、readiness、consistencyIssues、matching、policyVersions以及AI定性区块。服务端固定提示另存systemWarnings:string[]，不混作AI证据。completeness.items额外提供label；事实可带state，异常原值保留评估资料、报告value置null并显示需核实。
- DeepSeek v2仅接数值/枚举白名单事实与确定性准备依据，不发姓名、证件、手机、企业名、城市/职业自由文本或用途说明。仅接受summary/strengths/improvements/riskWarnings四个模型字段；数组条目必须引用已外发的fact或readiness依据，拒绝无效/重复/空引用、数值改写、HTML及明确审批承诺。模型无权覆盖金额、完整度和准备状态；语义正确性仍需真实模型与人工样例验收。
- 报告页已展示需求、完整度逐项状态、准备依据、优势/建议/风险及证据标签；金额万元，期限/月数整数。未发布策略不显示0分，旧v1不事后添分。缺少真实产品时matching.status=unavailable、计数null、match_result=[]；产品集合/匹配规则/排序快照仅保留明确不可用状态，真实匹配和产品解释仍待PRODUCT实施。
- 本轮验证：54项报告专项、76项需求、41项基础、15项HTTP检查通过；Chromium手机/桌面报告和历史刷新通过，Web及Android本地编译通过。用合成数据/假模型，未调用真实DeepSeek；v2提示词真实语义、微信内H5、Safari、真机和生产守护未验收。REPORT-002/004整体开发中，REPORT-003完整产品/外部数据范围仍阻塞，不能把内部报告支线记为一期完成。
## 1. 项目目标与现状
### 1.1 已确认范围
一期将现有 **25 个页面全部接入真实业务，H5 优先首发**。包含手机号/密码/微信/一键登录、个人与企业评估、私有资料、正式授权、外部征信或数据查询、产品匹配、DeepSeek 报告、历史档案、AI 助手、新闻、图文课堂、搜索、消息、积分邀请、帮助反馈及人工客服。相关运营后台一并验收。
按 **1 人全栈＋AI 辅助**排期。AI 服务商确定为 **DeepSeek**；具体模型、预算和测试权限待核验。短信、号码认证、外部数据、客服、存储等渠道待选型。微信内网页与普通 H5 的登录方式分别核实平台能力。一期必做渠道未接通时保持未验收，不以模拟成功替代。
按 **1 人全栈＋AI 辅助**排期。AI 服务商确定为 **DeepSeek**；模型为deepseek-v4-pro-0813和deepseek-v4-flash-0731，密钥已收妥；真实权限已验证，预算和可用余额待运营确认。短信、号码认证、外部数据、客服、存储等渠道待选型。微信内网页与普通 H5 的登录方式分别核实平台能力。一期必做渠道未接通时保持未验收，不以模拟成功替代。
微信小程序、Android、iOS 的平台适配、真机、签名和发布列入后续里程碑，不计入本期 69–117 人日。保留现有跨端代码结构。贷款功能止于申请准备和资料引导；当前范围不包含金融机构受理、授信、放款、支付或资金交易。课堂保持图文形式。
@@ -30,9 +111,9 @@
| 前端 | uni-app x / Vue 3 / UTS，25 页，无独立 npm 构建入口 | 沿用 HBuilderX 和现有分包，不重新搭建前端 |
| 后端 | FastAdmin / ThinkPHP 5.0.28 / PHP 7.4 | 复用认证、后台、模型与队列依赖，新增业务 API/服务 |
| 数据库 | MySQL 8.0.44，删除空 Token 表后实际 25 张 InnoDB 表 | 已核对本地库并更新结构快照；恢复点见进度第0节 |
| 当前前端模式 | 开发环境已连接本地 v1 API，模拟请求开关关闭 | 密码账户流程已接入，内容与报告等页面仍有原型数据，不按页面数计算完成度 |
| 当前前端模式 | 开发环境已连接本地 v1 API，模拟请求开关关闭 | 密码账户流程已接入，内容与产品匹配等页面仍有原型数据，不按页面数计算完成度 |
| 当前后端能力 | 评估生命周期、加密、密码兼容、产品后台等基础已存在 | 内部服务不等于已暴露并联调的业务 API |
| 第三方接入 | 尚未验证真实短信、DeepSeek、外部查询、客服闭环 | 各渠道独立记录测试环境与验收证据 |
| 第三方接入 | DeepSeek自填分析已真实验证；短信、外部查询、客服闭环未验收 | 各渠道独立记录测试环境与验收证据 |
源代码位置：
@@ -42,14 +123,14 @@
### 1.3 已有基础与首要缺口
已有基础：万元与元精确转换、个人/企业草稿交互、产品范围字段和版本、评估提交/完成/失败/重试内部服务、敏感字段加密、旧密码兼容、Token Redis切换（早期曾恢复表，现已删除）、日志脱敏及基础验证。
已有基础：万元与元精确转换、个人/企业分步填写交互、产品范围字段和版本、评估提交/完成/失败/重试内部服务、敏感字段加密、旧密码兼容、Token Redis切换（早期曾恢复表，现已删除）、日志脱敏及基础验证。
首要缺口：
1. Bearer、FastAdmin响应解析和401处理已接通；全量字段字典、requestId日志关联、生产环境配置仍待完成。
2. 确认页未承接评估编号，分析页计时跳转，报告使用固定分数；必须打通 assessmentId 全链路。
3. 本机草稿、学习进度、签到和消息状态已按userId隔离；旧匿名草稿显式导入、退出后敏感缓存清理与云端持久化仍待完成。
4. 产品准入、业务 API、评估队列、DeepSeek 请求与真实报告均待开发。
2. assessmentId已贯穿提交、真实分析、报告和历史；需求金额/期限/用途、完整度/准备等级及确定性产品匹配仍待按新增契约实现。
3. 账户缓存已按userId隔离并在退出时清理；评估只使用当前流程内存。学习进度、签到和消息的服务端业务仍待接入。
4. 产品准入和其他业务API待开发；评估队列、DeepSeek自填报告及读取API已接通。
5. 通用公共上传不能直接存正式证件；授权勾选和插件钩子不代表第三方服务已接入。
## 2. 页面与功能覆盖
@@ -67,7 +148,7 @@
| 7 | packages/finance/matches/matches | 当前评估匹配、排序、无结果说明 | PRODUCT-004 |
| 8 | packages/finance/product/product | 产品范围、快照、当前可用性与申请准备 | PRODUCT-003、PRODUCT-004 |
| 9 | packages/finance/assistant/assistant | 持久会话、报告解读 | CHAT-001、CHAT-002、CHAT-003、CHAT-004 |
| 10 | packages/finance/archive/archive | 草稿、评估历史、复制新评估 | ASSESS-002、ASSESS-004、REPORT-004 |
| 10 | packages/finance/archive/archive | 已提交评估历史、开始新评估 | ASSESS-002、ASSESS-004、REPORT-004 |
| 11 | packages/account/index/index | 启动引导及登录回跳 | BASE-003、BASE-004 |
| 12 | packages/account/login/login | 手机号、密码、微信、一键登录 | AUTH-001、AUTH-002、LOGIN-001、LOGIN-002、LOGIN-003、LOGIN-004 |
| 13 | packages/account/profile/profile | 用户信息、档案、入口和退出 | AUTH-002、AUTH-003、ASSESS-004 |
@@ -94,8 +175,8 @@
- fa_ai_chat_log 的角色为 system/user/assistant/tool；状态为 pending/streaming/completed/failed。会话内序号唯一；(chat_id,request_id,role) 保证消息级幂等。一期普通助手默认异步完整回复，不要求流式传输。
- 评估状态为 draft → processing → succeeded 或 failed；仅 failed 可重试并进入 processing。填写步骤 step=0–4 与状态分离。排队、数据查询、匹配、生成报告属于任务阶段，不擅自加入现有 status 枚举。
- requestId 使用 8–64 位字母、数字、下划线或横线，作为用户内提交幂等键。taskId 为服务端每次尝试生成的标识；重试更换，旧任务禁止覆盖新任务。
- 当前 submit/complete/fail/retry 已有内部实现；submit重复调用现返回当前taskId，尚不能代表稳定的原尝试响应。计划在评估运行元数据task_requests中持久保存每个提交/重试键、规范化参数摘要、原taskId与接受响应；重复旧键只返回原响应，不启动新任务。写映射与状态变更同一事务锁定评估行，最新状态另查status接口。草稿并发版本、任务阶段与可靠派发仍需补充。
- result_version 是结果 JSON 结构版本，rule_version 是规则版本字符串，product.version 是产品整数版本。当前 complete 尚未显式写入 result_version，REPORT-003 补齐。
- 内部submit/complete/fail/retry只供服务端使用；外部提交返回固定assessmentId/submissionStatus，重试通过task_requests保存每个键的原taskId与回执。初次提交比较规范化冻结输入，同键异内容409；重试仅接受requestId。映射和状态变更同事务锁定用户/评估行，最新状态另查status。可靠派发、租约及失败恢复已接入，不提供用户草稿版本。
- result_version 是结果 JSON 结构版本，rule_version 是规则版本字符串，product.version 是产品整数版本。当前分析任务已显式写入 result_version=1；产品快照部分随REPORT-003继续补齐。
- 外部查询结果不回写已提交表单。使用单独查询流水保存来源、授权和标准化结果，任务在生成报告前冻结所用结果集合/截止时间；最终报告保存引用、来源及必要摘要。后到结果不得悄悄重写历史报告。
### 3.2 金额、产品与数据字典
@@ -109,7 +190,7 @@
| 期限 | 整数月；产品 term_min_months/term_max_months |
| 评估类型 | API personal/enterprise → DB type=1/2 |
| 婚姻 | API已定义枚举 → DB 1已婚、2未婚、3离异、4丧偶；未知NULL |
| 房/车 | API布尔值或null → DB house/vehicle=1/0/NULL；旧“有/无”在适配层转换 |
| 房/车 | 当前API yes/no/null → DB house/vehicle=1/0/NULL；界面“有/无”在适配层转换 |
| 产品对象 | DB object 为 SET，可同时适用于个人和企业；不是单一类型值 |
| 产品状态 | switch=0草稿、1上架、2下架；还需检查有效期 |
| 地区 | 使用统一版本的地区代码；regions=[]才表示全国，NULL视为未配置并阻止上架 |
@@ -128,32 +209,38 @@
| --- | --- | --- |
| type | fa_user_info.type | personal/enterprise转1/2 |
| name / idCard / phone | name / card_no / mobile | card_no加密；只向所属用户按必要范围回显 |
| city / regionCode | city / 拟增region_code | 保留展示名，匹配使用标准代码；不恢复fa_area |
| city / cityCode | city / city_code（已增） | 保留展示名，匹配使用标准代码；不恢复fa_area |
| maritalStatus | marriage | 文字转稳定枚举，再映射数字 |
| occupation / company | profession / employer | 企业occupation表示行业 |
| monthlyIncome / annualRevenue | monthly_income / year_income | 元字符串；分别用于个人/企业 |
| socialSecurity / housingFund | social_security / housing_provident_fund | 统一枚举，区分无、未知与未填写 |
| house / car | house / vehicle | 布尔值或null |
| house / car | house / vehicle | 当前API yes/no/null；不混用布尔值 |
| creditLoanCount / totalDebtBalance | credit_num / credit_total_money | 笔数整数，金额元 |
| monthlyLoanPayment | credit_month_still_money | 元 |
| creditCardCount / creditCardTotalLimit / creditCardUsedLimit | credit_card_num / credit_card_quota / credit_card_use_quota | 已用不得大于总额；未知不填0 |
| enterpriseName / businessCode | enterprise_name / business_code | 企业名称、统一社会信用代码 |
| operatingMonths | 拟增operating_months | 保留旧operating_years供兼容，稳定准入只用规范月数 |
| operatingMonths | operating_months（已增） | 保留旧operating_years供兼容，稳定准入只用规范月数 |
| inputVersion | 已增input_version，默认1 | 已实现v2；历史保持1，新建版本与幂等回放分开处理 |
| requestedAmountYuan | 已增requested_amount DECIMAL(11,2) NULL | v2必填，元字符串且>0；不是负债或收入 |
| requestedTermMonths | 已增requested_term_months SMALLINT UNSIGNED NULL | v2必填整数月1—9999，产品规则另行限制 |
| purposeCode / purposeDetail | 已增purpose_code / purpose_detail | 已发布版本化用途字典，other时才要求说明；自由说明不进入AI/规则 |
| documents | documents JSON | 类型、attachmentId、元信息；不接受name/path临时文件作为持久资料 |
| consentIds | consent_data快照 | 服务端读取授权事件并形成快照，不相信客户端时间或协议正文 |
| savings / creditCard / otherAssets | 拟增supplementary_data JSON | 保存旧表单补充输入，标明来源和版本，不据此猜测精确金额或准入事实 |
| step / draftVersion | step / 拟增draft_version | step控制续填；draft_version为服务端乐观锁，区别本机格式draftVersion=2 |
| step | step | 仅当前页面步骤；不保存草稿版本或续填进度 |
本机格式标记 moneyUnit=wan、draftVersion=2 继续用于旧草稿规范化；服务器修订字段在API命名为 revision，避免混淆。提交与存储DTO只接受 moneyUnit=yuan。
当前流程金额以moneyUnit=wan表示，正式提交与数据库使用moneyUnit=yuan。旧草稿不恢复，无revision契约。
### 3.4 增量数据设计工作
以下为待实现的最小数据方案，由对应任务提交增量迁移和回滚说明。本次未创建任何表或字段。所有新增关系都采用服务端所有者校验；必要唯一索引以数据库保证并发一致性。
以下按已实现和计划增量区分；本轮已补city_code、operating_months，其他增量仍待对应任务实施。所有新增关系都采用服务端所有者校验；必要唯一索引以数据库保证并发一致性。
| 需求 | 复用位置 | 计划增量与约束 | 负责任务 |
| --- | --- | --- | --- |
| 草稿、标准字段、补充输入 | fa_user_info | region_code、operating_months、supplementary_data、draft_version、create_request_id；用户+create_request_id唯一，对应clientDraftId；提交后输入冻结 | ASSESS-001、ASSESS-002 |
| 任务可靠执行 | fa_user_info及现有生命周期 | task_requests JSON持久保存每次提交/重试键到参数摘要、原taskId和接受响应的映射；补task_stage、attempt_count、lease_until，按task_id抢占与失联补偿；运行元数据不改已冻结输入 | ASSESS-003、REPORT-002 |
| 标准字段、补充输入 | fa_user_info | city_code、operating_months已新增；supplementary_data按正式提交字段需求补充；不增加草稿版本或创建草稿键；正式提交后输入冻结 | ASSESS-001、ASSESS-002 |
| 任务可靠执行 | fa_user_info及现有生命周期 | task_requests JSON保存重试键→原taskId及接受回执；初次提交仍用request_id和冻结输入比较；task_stage、attempt_count、lease_until、dispatched_at已补齐，按task_id抢占和补投；不改已冻结输入 | ASSESS-003、REPORT-002 |
| 融资需求v2 | fa_user_info | input_version、requested_amount、requested_term_months、purpose_code、purpose_detail；历史需求NULL；新版本与原键幂等回放见专项契约第7节 | ASSESS-001、ASSESS-003 |
| 输入/计算依据快照与报告v2 | fa_ai_chat | 已增analysis_context JSON并冻结input_snapshot；新目标v2首次抢占后且外部调用前已补入execution_snapshot；真实产品/匹配快照仍待接，两个部分均不可覆盖；report_data、match_result仍复用原字段，不新建报告表 | ASSESS-003、REPORT-002、REPORT-003、PRODUCT-002 |
| 私有附件 | fa_attachment | 存储可见性、文件用途、存储键、生命周期状态；路径不作为权限依据 | FILE-001、FILE-002 |
| 协议与授权事件 | fa_acticle + fa_user_info.consent_data | 协议版本不可变修订；拟增fa_user_consent保存范围、版本、授权与撤销事件，再复制评估快照 | FILE-003 |
| 第三方身份 | fa_user + token | 拟增fa_user_identity，以provider+app_id+subject唯一；不能只靠单个openid列覆盖所有微信应用 | LOGIN-001 |
@@ -167,9 +254,13 @@
变更只追加有明确业务目的的字段或关系。新增这些支撑表不改变“不新增独立评估、报告、匹配表”的约定。详细DDL在对应数据任务内提交审阅；已有数据需先预检、备份、回填验证，再收紧约束。不能直接重跑原空业务表限定的迁移脚本。
### 3.5 需求与评估结果详细契约
融资需求字段及校验、完整度字段集和公式、准备等级发布闸门、规则证据、三态结果、报告v2及历史迁移以[专项契约](需求与评估结果数据契约.md)第2—8节为准。需求输入、完整度、准备状态及报告v2自填支线已实现；真实产品匹配及其证据仍为计划增量。输入版本、结果版本、业务策略与产品版本分别保存。
## 4. 模块开发任务
任务编号与[开发进度](开发进度.md)一一对应；每个模块4项，共60项。工时为剩余工程人日，含模块内开发者测试，不含外部审核等待。任务级验收是具体交付条件，模块整体还需通过M4的真实联调。
任务编号与[开发进度](开发进度.md)一一对应；每个模块4项，共60项。工时保留初始工程人日基线（本轮取消草稿后尚待重估），含模块内开发者测试，不含外部审核等待。任务级验收是具体交付条件，模块整体还需通过M4的真实联调。
### 4.1 BASE｜基础接口与环境
@@ -179,7 +270,7 @@
- **现状：** 页面、导航、安全区已有；共享请求已接本地API，处理Bearer、业务失败与401；全量契约、requestId及生产配置仍待完成。
- **前端：** 统一请求与账户专用请求，处理认证、业务错误、重复点击、加载/空态、401回跳；首页聚合公共内容与登录后状态。
- **后端：** 新路由显式绑定控制器和方法；解析JSON并逐字段校验，不能对结构化输入机械套用HTML转义；兼容旧Token入口但新客户端只发送Bearer。
- **数据：** 以userId建立缓存命名空间。旧匿名草稿由用户明确导入；不自动认领其他本机数据。
- **数据：** 以userId建立账户缓存命名空间；旧草稿键清理，不提供导入；未提交内容只在当前流程内存中传递。
- **接口：** GET /home、GET /dictionaries，以及所有接口共用协议。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 生产缺API地址直接报配置错误；禁止静默降级成demo。断网不删除服务端事实。
@@ -187,14 +278,14 @@
| --- | --- | --- | --- | --- | ---: |
| BASE-001 | 接口契约与字段字典：定义版本路由、响应、错误、分页、ID、金额、时间及接口状态；确认前后端字段映射。 | P0 | 无 | 接口样例可同时被 PHP 和 UTS 解析；区分占位接口与后端现有实现。 | 0.5–1 |
| BASE-002 | 统一请求与认证适配：统一共享/账户请求；后端识别 Bearer；解析业务失败和401；限定 CORS；记录 requestId。 | P0 | BASE-001 | HTTP 200 中业务失败不判成功；过期 Token 清会话；普通业务按所有者鉴权。 | 1–1.5 |
| BASE-003 | 环境与用户缓存隔离：开发/测试/生产配置；生产禁用 mock；会话和草稿等缓存按不可变 userId 隔离。 | P0 | BASE-002 | 切换账户无串数据；匿名旧草稿仅在用户明确选择导入后绑定；退出清理敏感缓存。 | 1–1.5 |
| BASE-003 | 环境与用户缓存隔离：开发/测试/生产配置；生产禁用 mock；会话等账户缓存按不可变 userId 隔离；未提交表单只存当前流程内存。 | P0 | BASE-002 | 切换账户无串数据；旧草稿键清理且不恢复；退出清理敏感缓存和临时填写内容。 | 1–1.5 |
| BASE-004 | 首页和联调骨架：首页接入聚合数据、加载/空态/失败重试及登录回跳；建立接口冒烟入口。 | P1 | BASE-002、BASE-003 | 深链接与刷新正确恢复；首页无硬编码账户数据；真实未读数后续由 MSG 接入。 | 0.5–1 |
### 4.2 AUTH｜账户与短信安全
**目标：** 让账户身份、个人资料和安全操作形成真实服务端闭环。 **阶段：** M1。**剩余：** 5–8人日。
- **现状：** 密码登录、本人资料读取、退出和原密码改密已接Redis会话；短信注册/登录、换绑和资料更新仍待完成，本机资料仅作回显缓存。
- **现状：** 密码登录、本人资料读取、退出和原密码改密已接Redis会话；资料修改与头像上传已完成本地验证；短信注册/登录、换绑仍待完成，本机资料仅作回显缓存。
- **前端：** 接通短信/密码登录，读取profile；头像独立上传；安全操作成功后重新登录。
- **后端：** 验证码用途、用户和手机号绑定；换绑核验当前及新号码；修复旧免登录改绑声明；修改密码/手机号撤销全部会话。
- **数据：** 复用fa_user/fa_sms；会话改用Redis；手机号冲突由唯一约束兜底；昵称不覆盖实名。
@@ -246,21 +337,21 @@
### 4.5 ASSESS｜评估与融资档案
**目标：** 个人与企业评估可云端续填、重复评估、可靠提交并查看历史。 **阶段：** M2。**剩余：** 5–8人日。
**目标：** 个人与企业评估正式提交后持久保存，可重复评估并查看只读历史；不提供草稿。 **阶段：** M2。**剩余：** 5–8人日。
- **现状：** 表单、金额规范化和内部生命周期已有；无草稿API和真实提交链路。
- **前端：** 草稿revision控制、字段映射、服务端校验错误定位；保留assessmentId在所有后续路由。
- **后端：** 认证用户创建草稿，保存时条件更新；完整校验后调用生命周期服务；提交后不可修改，修改需求转新评估。
- **数据：** 使用fa_user_info和唯一评估会话；前端本机版本与服务端revision区分；taskId用于任务尝试。
- **接口：** POST/GET /assessments、GET/PUT /assessments/:id、POST /assessments/:id/submit、GET /assessments/:id/status、POST /assessments/:id/retry。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 草稿版本冲突提示重新读取；重复提交返回同一任务；跨用户记录统一404；失败重试保持原输入。
- **现状：** 无草稿；需求v2录入/确认/提交、v1/v2历史分页与详情已接通。分析任务和重试继续生成v1自填报告；准备状态和报告v2自填支线已实现；真实产品匹配待实施。
- **前端：** 字段映射、服务端校验错误定位；确认前只保留内存，正式提交返回assessmentId后贯穿所有后续路由。
- **后端：** 认证用户正式提交后，同一事务创建评估和接受任务；完整校验、请求幂等；提交后不可修改，修改需求转新评估。
- **数据：** 使用fa_user_info和唯一评估会话；不新增草稿版本字段；taskId用于任务尝试。
- **接口：** POST/GET /assessments、GET /assessments/:id、GET /assessments/:id/status、POST /assessments/:id/retry均已实现自填支线；具体版本与字段见第5章。附件和正式授权待接。
- **异常与边界：** 未提交内容不恢复；重复正式提交返回同一接受回执；跨用户记录统一404；失败重试保持原输入。
| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| ASSESS-001 | 评估字段与增量模型：确定枚举、地区代码、经营月数、附件引用、授权快照和前后端完整字段映射。 | P0 | BASE-001 | 未知与0区分；个人/企业必填口径明确；新增字段列独立迁移，不重建结果表。 | 1–2 |
| ASSESS-002 | 云端草稿与档案：新建/保存/读取草稿、版本冲突、列表、复制既往资料新建评估及用户隔离。 | P0 | ASSESS-001、AUTH-002 | 同用户可有多次同类型评估；不同账号不能读写；历史输入不被编辑覆盖。 | 1–2 |
| ASSESS-003 | 提交与生命周期API：接入submit/owned/retry，服务端校验；持久保存每次提交/重试请求键、参数摘要与taskId，返回原接受响应。 | P0 | ASSESS-002、FILE-004 | 同requestId只提交一次；多次重试后回放旧键仍返回原taskId；旧任务不可回写，完成方法不对客户端开放。 | 1.5–2 |
| ASSESS-004 | 评估全页面联调：评估/确认/分析/档案传递assessmentId；处理金额、退出续填、并发及历史跳转。 | P0 | ASSESS-003 | 同一评估ID贯穿流程；0.800001万元精确提交为8000.01元；处理中不显示假报告。 | 1.5–2 |
| ASSESS-001 | 评估字段与增量模型：统一现有字典并补融资需求四字段、inputVersion及增量列；用途字典/必填规则按专项契约确认，保留附件和授权映射。 | P0 | BASE-001、DEC-DEMAND | 现有与v2字段映射明确，元字符串/整数月/用途条件校验；历史新字段NULL，不新建评估表。 | 1–2 |
| ASSESS-002 | 正式评估记录与历史：本人历史分页/只读详情及用户隔离；补v1/v2需求回显与旧未采集提示，无草稿保存或续填。 | P0 | ASSESS-001、AUTH-002 | 同用户可多次评估；越权拒绝；历史v1不回填需求、不重算，v2显示冻结需求且不可编辑。 | 1–2 |
| ASSESS-003 | 提交与生命周期API：保留提交201及重试202幂等；补inputVersion切换、新需求校验、输入字典冻结、同键全字段比较和旧请求重放兼容。 | P0 | ASSESS-002、FILE-004 | 同键同内容原回执，合法需求或版本变化409、非法格式422；最低新建版本2或用途停用不阻断原键回放；旧重试返回原taskId。 | 1.5–2 |
| ASSESS-004 | 评估全页面联调：评估/确认/分析/报告/档案贯穿assessmentId；新增资金需求分组和只读展示，保留金额、清理与并发回归。 | P0 | ASSESS-003 | 个人/企业需求均能提交及回显；12.345678万元=123456.78元；无草稿，历史不串账户，处理中无假报告。 | 1.5–2 |
### 4.6 DATA｜外部征信或数据查询
@@ -293,16 +384,16 @@
| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| PRODUCT-001 | 规则字典与评分口径：统一硬准入、未知值处理、补充规则白名单、匹配评分和理由；准备人工确认样例。 | P0 | ASSESS-001、DEC-MATCH | 版本化规则与样例可审阅；地区/经营时间可确定比较；规则不执行任意表达式。 | 1.5–2 |
| PRODUCT-002 | 准入与排序执行器：筛选上架/有效期/地区/对象及硬条件；执行补充规则、排序并输出可解释理由。 | P0 | PRODUCT-001 | 下架/过期/硬条件不符不推荐；缺失条件不当已满足；同数据同版本结果稳定。 | 2–3 |
| PRODUCT-003 | 产品后台与公共查询：补齐规则编辑校验、发布预检、产品列表/详情与范围字段；录入真实测试产品。 | P0 | PRODUCT-001、BASE-002、DEC-PRODUCT | 上架完整校验；版本递增；公共详情无用户分数；真实产品有运营确认依据。 | 1.5–2 |
| PRODUCT-004 | 匹配页面与快照：独立MatchResult类型、额度/期限/利率范围、匹配列表排序、产品分享与申请准备。 | P0 | PRODUCT-002、PRODUCT-003、ASSESS-004 | 按assessmentId显示；参数历史快照稳定；当前不可用产品清晰提示；无匹配有说明。 | 1–2 |
| PRODUCT-001 | 规则字典与评分口径：确定准入三态、来源要求、单产品需求覆盖、用途规则、证据结构和版本化排序；评分未发布时null。 | P0 | ASSESS-001、DEC-MATCH | 发布规则与人工样例可审阅；非法字段/操作符阻止发布；fail优先于unknown，匹配指标不作为审批概率。 | 1.5–2 |
| PRODUCT-002 | 准入与排序执行器：执行上架/有效期/对象/地区及需求硬规则；保存pass/fail/unknown证据，生成eligibility和稳定rank。 | P0 | PRODUCT-001 | 同输入/快照结果稳定；未知不当满足，配置错误不归咎用户；需求不拆额、不改期；未运行与零候选区分。 | 2–3 |
| PRODUCT-003 | 产品后台与公共查询：补规则条件编辑、来源/用途依据、发布预检、版本与公共详情；录入真实产品，缺依据阻止发布。 | P0 | PRODUCT-001、BASE-002、DEC-PRODUCT | 产品用途/地区/额度/期限有真实依据；规则可配置并启停，版本变化留依据；公共详情无个人分数。 | 1.5–2 |
| PRODUCT-004 | 匹配页面与快照：按assessmentId展示三态分组、最多三个候选及分页；结果详情展示依据/注意项/AI解释，保留产品快照与申请准备。 | P0 | PRODUCT-002、PRODUCT-003、ASSESS-004 | 每条解释可追溯且不凑三正三反；当前产品变化不改历史；跨账户拒绝；unavailable/零候选/failed不混淆。 | 1–2 |
### 4.8 REPORT｜AI任务、报告与历史
**目标：** 把真实输入、查询依据和产品匹配生成可追溯的DeepSeek报告。 **阶段：** M2。**剩余：** 8–12人日。
- **现状：** report_data/match_result及complete服务已有；队列配置存在但没有业务Job，页面为计时和静态分数。
- **现状：** v1自填报告已真实模型联调；v2需求、完整度、准备状态和冻结策略已完成假模型与页面联调。v2真实模型语义、产品证据/解释及外部渠道仍待验收。
- **前端：** 轮询真实状态、刷新恢复、失败重试；渲染数据驱动维度、来源时间和版本；查看历史。
- **后端：** DeepSeek适配、结构校验、任务抢占/超时/漏投补偿、输入最小化、用量记录；在事务中同时落报告、匹配和成功状态。
- **数据：** result_version/rule_version/model与产品快照分别记录；模型输出不能覆盖金额、硬准入或数据来源。
@@ -312,9 +403,9 @@
| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| REPORT-001 | DeepSeek适配与配额：配置模型标识、服务端密钥读取、超时、结构化输出校验、配额预留和消耗记录。 | P0 | BASE-002、EXT-AI、DEC-AI | 模型可配置；密钥不下发；失败与使用量可追踪；数值事实不被模型改写。 | 1.5–2 |
| REPORT-002 | 异步任务与补偿：think-queue/Redis业务Job、提交后派发、漏投扫描、租约/超时、重试和任务隔离。 | P0 | ASSESS-003、REPORT-001 | 派发失败/worker重启可恢复；旧taskId不能落结果；重复消费不重复完成。 | 2.5–4 |
| REPORT-003 | 报告生成与持久化：冻结已授权查询结果和产品匹配快照，调用AI解释，原子写report_data/match_result及状态。 | P0 | REPORT-002、DATA-004、PRODUCT-004、DEC-MATCH | 结构无效不得记成功；评分/证据来源明确；产品改动不改历史；部分资料缺失有标注。 | 2–3 |
| REPORT-004 | 分析报告历史联调：状态轮询、刷新恢复、失败重试、真实雷达维度、历史详情和模型版本展示。 | P0 | REPORT-003、ASSESS-004 | 个人/企业各完成一条真实闭环；分析失败不会跳成功报告；再次评估生成独立记录。 | 2–3 |
| REPORT-002 | 异步任务与补偿：保留Redis派发、补投、租约和taskId隔离；沿用提交时input_snapshot，一次性补入execution_snapshot并在重试时复用，支持跨部署v1/v2任务。 | P0 | ASSESS-003、REPORT-001 | 漏投/中断可恢复或明确失败；旧任务不可回写；输入/目标结果/策略/产品快照重试不隐式变化。 | 2.5–4 |
| REPORT-003 | 报告生成与持久化：保留v1自填报告；补v2需求、完整度/准备等级、规则证据及定性AI区块；版本快照和正式结果原子落库。 | P0 | REPORT-002、DATA-004、PRODUCT-004、DEC-MATCH、DEC-READINESS | 完整度按发布字段集复算，等级有依据且非审批；null rank/score按状态验证；格式错误不成功，产品/规则更新不改旧报告。 | 2–3 |
| REPORT-004 | 分析报告历史联调：保留轮询/重试和v1历史；接v2需求、完整度、准备等级、三态匹配及证据解释，不显示无规则分数/雷达。 | P0 | REPORT-003、ASSESS-004 | 个人/企业真实链路按版本展示；未发布无分或等级，100%不等于授信；旧报告不重算；新复评新assessmentId。 | 2–3 |
### 4.9 CHAT｜AI助手
@@ -447,15 +538,19 @@
### 5.1 实现状态与通用规则
**本章为目标契约；已实现子集为密码登录、本人资料读取、退出、原密码改密，短信仅实现503未配置响应，其余仍待开发。** 已有FastAdmin通用控制器，现新增api/controller/v1/Base.php和Session.php；未列为已实现的前端同名方法仍是接口占位。AUTH可复用通用服务实现，其他模块需新增业务控制器及路由。旧接口保留兼容，新H5统一走版本前缀；管理后台保持原路由。
**本章区分已实现与目标契约；已实现密码登录、本人资料读取/更新、头像上传、退出、原密码改密、正式评估提交/历史/详情/状态。短信仅实现503未配置响应，其余仍待开发。** 已有FastAdmin通用控制器，现使用api/controller/v1/Base.php、Session.php和Assessments.php；未列为已实现的前端同名方法仍是接口占位。AUTH可复用通用服务实现，其他模块需新增业务控制器及路由。旧接口保留兼容，新H5统一走版本前缀；管理后台保持原路由。
| 方法与路径（省略/api/v1） | 当前实现状态 | 本轮边界 |
| --- | --- | --- |
| POST /auth/password-login | 已实现并本地联调 | 既有手机号账户、密码验证、旧散列升级、Redis会话；沿用账户失败次数限制，IP级频控待补 |
| GET /account/profile | 已实现并HTTP验证 | 返回userId/nickname/avatarUrl/phoneMasked；完整security字段与资料修改待补 |
| GET /account/profile | 已实现并HTTP验证 | 返回userId/nickname/avatarUrl/phoneMasked；完整security字段待补 |
| POST /auth/logout | 已实现并本地联调 | 撤销当前Token；成功或已401清本机会话，网络失败保留以便重试撤销 |
| PUT /account/password | 原密码方式已实现并验证 | verification=password；成功撤销全部会话；sms方式返回503 |
| POST /auth/sms-code、/auth/sms-login | 仅未配置响应 | HTTP 503、data.errorCode=SMS_NOT_CONFIGURED，无短信发送或注册 |
| PUT /account/profile、POST /account/avatar | 已实现并本地验证 | 昵称持久化、头像校验上传与附件归属；avatarId=null恢复默认 |
| POST /assessments、GET /assessments、GET /assessments/:id、GET /assessments/:id/status | 已实现并本地联调 | 已支持v2需求提交及v1/v2只读历史；自填报告/任务/retry已接，产品匹配待开发 |
| GET /dictionaries | 已实现并本地验证 | 公开用途字典及输入版本，no-store，地区等字典仍待补 |
| POST /assessments/:id/retry、GET /assessments/:id/report | 已实现并本地联调 | 幂等重试及resultVersion=1/2自填报告；真实产品/外部数据支线待开发 |
| 其余本章接口 | 计划新增 | 当前未配置的v1路由返回JSON 404，不判业务成功 |
| 项目 | 约定 |
@@ -468,7 +563,7 @@
| 失败包装 | code非1；data包含errorCode、可选fieldErrors、requestId；前端不把HTTP 200业务失败当成功 |
| HTTP错误 | 400格式错误，401登录失效，403操作无权限，404记录不存在/不属于本人，409状态/版本冲突，422字段错误，429频控，503依赖不可用 |
| 错误实现 | FastAdmin默认状态推导不足时显式传statuscode；兼容旧接口错误体但新接口使用稳定errorCode |
| 分页 | page默认1，pageSize默认20、最大50；items/total/page/pageSize；稳定排序含唯一ID |
| 分页 | 默认目标为page/pageSize；已实现评估历史使用cursor/limit和items/hasMore/nextCursor，默认20最大50，以第5.4节为准 |
| 列表范围 | 公开列表只取已发布有效内容；用户列表查询始终带user_id |
| 金额与比例 | 元字符串两位小数；利率为百分数；月数整数；展示时通过统一金额服务换算 |
| 幂等 | 表格注明业务键；同键不同业务参数返回409；成功重复调用返回同一业务结果；前端显式重试复用原键 |
@@ -515,14 +610,16 @@
| --- | --- |
| Session | token:string、userId:string、expiresAt:ISO时间、profile:Profile；令牌只在认证响应出现 |
| Profile | userId、nickname:string(2–20字符)、avatarUrl:string或null、phoneMasked、security状态；手机号完整值仅在必要且认证的操作中使用 |
| AssessmentDraft | assessmentId、type:personal/enterprise、revision:int、step:0–4、moneyUnit:yuan、第3.3节表单字段、documents数组、consentIds数组；未填字段null |
| AssessmentStatus | assessmentId、taskId、status:draft/processing/succeeded/failed、stage:string或null、submittedAt/completedAt、errorCode、可显示错误、canRetry |
| AssessmentInput | 已有v1字段保留；已实现inputVersion=2及需求四字段，详见专项契约第2节；新建最低版本2，旧v1仅原键重放；新建与历史重放版本策略见第7节 |
| AssessmentStatus | 已实现assessmentId、type、status:processing/succeeded/failed、statusLabel、message、submittedAt、city、errorCode；现已返回taskId:string、stage:queued/running/completed/failed、attemptCount:int、canRetry:boolean；completedAt暂不返回 |
| Document | attachmentId、type、name、mime、sizeBytes、status、createdAt；无永久公开证件URL |
| Consent | consentId、scope、agreementCode、agreementVersion、grantedAt、revokedAt；第三方授权完成状态独立于本地意向 |
| Product | id、name、bankName、objects数组、amountMinYuan/amountMaxYuan:string、termMinMonths/termMaxMonths:int、annualRateMin/annualRateMax:string、regions、version、说明字段、当前可用状态 |
| MatchResult | productId、rank:int、score:number、reasons:string[]、productSnapshot:ProductSnapshot；score范围与计算由DEC-MATCH定稿 |
| MatchResult（计划v2） | productId/productVersion、eligibility、rank:int或null、score:number或null、positiveReasons/blockingReasons/cautions、evidence、aiExplanation、productSnapshot；当前complete的rank/score非空校验需升级，详见专项契约第5节 |
| ProductSnapshot | 产品ID/名称/版本、额度元字符串、期限月、年化百分数及必要准入说明；不可用当前产品字段覆盖 |
| Report | resultVersion:int、ruleVersion:string、assessmentId、generatedAt、modelCode、overallScore:number或null、dimensions数组、summary、suggestions、dataGaps、sourceRefs |
| Report（已有自填版本） | resultVersion:1、reportType:self_reported_analysis、assessmentId:string、generatedAt:ISO、modelCode:string、overallScore:null、facts数组、summary:string、observations:[{factId,text}]、suggestions:string[]、dataGaps:string[]、matchingStatus:unavailable、matchingMessage、disclaimer；有规则评分及产品快照版本仍计划新增 |
| Report（已有v2自填支线） | resultVersion:2、reportType:financing_needs_analysis、inputVersion、demand、facts、completeness、readiness、consistencyIssues、matching、summary/strengths/improvements/riskWarnings、policyVersions、systemWarnings、disclaimer；见专项契约第6节，matching当前只支持unavailable |
| Completeness / Readiness | 服务器计算，均含status/policyVersion；未发布规则时计数/percent或code为null，不由模型生成；详见专项契约第3—4节 |
| ReportDimension | code、label、score:number或null、explanation、evidenceRefs；数据不足明确null，区分用户自填和渠道核验 |
| Chat | chatId、title、scene:assistant、contextAssessmentId:string或null、updatedAt |
| ChatMessage | messageId、chatId、sequence:int、role、status、text、requestId、errorCode、createdAt；模型用量按权限返回摘要 |
@@ -531,7 +628,7 @@
| PointsLedger | id、delta:int、before:int、after:int、businessType、businessId、memo、createdAt |
| Feedback | id、content、attachmentIds、status、reply、createdAt、handledAt；用户端不暴露无关管理信息 |
数据库JSON采用已有snake_case字段时，由DTO统一转换为camelCase；文档中的API对象不是直接暴露数据库行。例如持久match_result仍含product_id/rank/score/reasons/product_snapshot，API转换为productId/productSnapshot。
数据库JSON采用已有snake_case字段时，由DTO统一转换为camelCase；文档中的API对象不是直接暴露数据库行。当前match_result结构使用product_id/rank/score/reasons/product_snapshot；计划v2补eligibility、positive_reasons/blocking_reasons/cautions及evidence等字段，具体映射见专项契约第5.3节，不沿用单一reasons表达所有类型的解释。
### 5.3 基础、账户与第三方登录接口
@@ -540,7 +637,7 @@
| 方法与路径 | 权限 | 入参 | data响应 | 错误/幂等要点 |
| --- | --- | --- | --- | --- |
| GET /home | 公开，登录后附本人摘要 | 无 | banners、recommendations、assessmentSummary、unreadCount | 未登录的个人字段null；内部聚合失败不伪造数据 |
| GET /dictionaries | 公开 | version可选 | 字典版本、地区、枚举和表单选项 | 支持版本缓存；不能读取已删除fa_area |
| GET /dictionaries | 公开 | 无 | assessmentInputVersions:int[]、minNewAssessmentInputVersion:int、financingPurposes:{version,items} | 已实现；no-store；用途项type/code/label:string、requiresDetail/enabled:boolean；地区等字典待补，不读取已删除fa_area |
| POST /auth/sms-code | 公开；绑定用途需有效bindingTicket | phone:string、purpose:login/bind-phone、bindingTicket仅绑定时必填、requestId | challengeId、retryAfterSeconds | 频控；同requestId不重复发送；绑定挑战关联bindingTicket与目标手机号，登录验证码不可用于绑定 |
| POST /auth/sms-login | 公开 | phone、challengeId、code:string | Session | 验证码核销；手机号唯一；错误不暴露账户细节 |
| POST /auth/password-login | 公开 | phone、password:string | Session | 限流；旧密码登录遵循原验证，成功后升级散列 |
@@ -569,25 +666,37 @@
| GET /consents | 登录 | scope可选 | Consent列表 | 仅当前用户 |
| POST /consents | 登录 | scope、agreementCode、agreementVersion、requestId | Consent | 服务端记录时间；协议版本与展示一致；业务键幂等 |
| POST /consents/:id/revoke | 所有者 | requestId | Consent | 重复撤销返回既有时间；停止新查询，保留历史证据 |
| POST /assessments | 登录 | type、clientDraftId、sourceAssessmentId可选 | AssessmentDraft | 用户+clientDraftId唯一；仅可复制本人历史，复制时不继承旧授权 |
| GET /assessments | 登录 | type/status可选、page/pageSize | 草稿和历史分页 | 只本人且未软删除；按create_time/id稳定倒序 |
| GET /assessments/:id | 所有者 | 无 | AssessmentDraft及状态 | 非draft为只读；敏感字段按用途返回 |
| PUT /assessments/:id | 所有者 | revision、step、form、documents、consentIds、moneyUnit:yuan | 更新后的AssessmentDraft | 仅draft；revision条件更新，冲突409；逐字段白名单 |
| POST /assessments/:id/submit | 所有者 | requestId、revision | assessmentId、taskId、status、stage | 全量校验后冻结；同键同结果；返回HTTP202 |
| GET /assessments/:id/status | 所有者 | 无 | AssessmentStatus | 前端依据状态，不将动画作为进度事实 |
| POST /assessments/:id/retry | 所有者 | requestId | assessmentId、taskId、status | 仅failed可创建新尝试；同重试键返回同一尝试；不覆盖输入 |
| POST /assessments | 登录 | 当前v2：type、requestId、form、documents:[]、consentIds:[]、moneyUnit:yuan；必填inputVersion=2及form.requestedAmountYuan/requestedTermMonths/purposeCode/purposeDetail | assessmentId、submissionStatus:accepted | v1原键回放与v2新建均HTTP201；v2已按专项契约校验元字符串/整数月/用途字典并冻结输入依据；同键同规范化内容同回执，异内容409，非法格式422；仅确认资料持久保存，不等于已派发分析任务 |
| GET /assessments | 登录 | type/status可选、cursor:string可选、limit:string默认20上限50 | items、hasMore:boolean、nextCursor:string或null | 已实现；只本人且未软删除、非draft；id倒序且后页id小于cursor，避免新增记录挤动页码 |
| GET /assessments/:id | 所有者 | 无 | AssessmentStatus + moneyUnit:yuan + form；已返回inputVersion、四个需求字段及冻结purposeLabel（金额元字符串） | 已实现v1/v2只读；旧v1需求字段为null并标注未采集，v2已提交需求不可编辑；手机号掩码、身份证仅已提供标记，无密文/完整号码；越权与不存在均404 |
| GET /assessments/:id/status | 所有者 | 无 | AssessmentStatus | 已实现；仅processing时每5秒轮询，离开停止；不自动跳转原型报告 |
| POST /assessments/:id/retry | 所有者 | requestId:string，8–64位字母/数字/下划线/短横线 | assessmentId:string、taskId:string、status:processing、stage:queued | 已实现HTTP202；仅failed创建新尝试；同键始终回放原尝试；不同用户404、状态/次数上限409、日额度429、配置未开放503；不覆盖输入 |
| GET /assessments/:id/data-queries | 所有者 | 无 | 查询列表及来源摘要 | 原始敏感结果不直接下发 |
| POST /assessments/:id/data-queries | 所有者 | scope、consentId、requestId | queryId、status | 服务端按状态与渠道限制发起；有效授权+业务键；HTTP202 |
| GET /data-queries/:id | 所有者 | 无 | queryId、status、source、sourceAt、errorCode、可显示摘要 | 费用/权限错误有明确状态；不返回渠道凭据 |
| POST /callbacks/data/:provider | 渠道验签 | 供应商原始格式 | 供应商要求的ACK | 原始体验签、防重放、单号映射、幂等；不适用用户Bearer |
| GET /assessments/:id/report | 所有者 | 无 | Report | 未成功返回409及状态；不生成临时假报告 |
| GET /assessments/:id/matches | 所有者 | 排序选项可选 | resultVersion、items:MatchResult[] | 只读取已完成快照；排序不修改历史rank |
| GET /assessments/:id/report | 所有者 | 无 | Report（v1/v2自填版本） | 已实现；未成功409 REPORT_NOT_READY，不存在/越权404，旧结构409 REPORT_FORMAT_UNAVAILABLE；Cache-Control:no-store |
| GET /assessments/:id/matches | 所有者 | eligibility默认eligible、limit默认3上限50、cursor可空 | assessmentId、resultVersion、matching、items、hasMore、nextCursor | 计划新增，三态分组、冻结快照与游标绑定，见专项契约第5.3节；当前尚未实现 |
| GET /assessments/:id/matches/:productId | 所有者 | 无 | 该次匹配结果、理由、证据和快照 | 计划新增；只读本次已评估项；越权/快照无该产品404；不从当前公共产品拼历史 |
| GET /products | 公开 | type/regionCode可选、page/pageSize | Product分页 | 仅当前有效上架产品；不返回用户分数 |
| GET /products/:id | 公开 | 无 | Product | 下架/过期返回不可用语义；历史快照从本人匹配接口读取 |
评估主流程由服务端任务编排：提交后检查授权 → 获取选定的外部结果 → 冻结查询引用 → 规则匹配 → DeepSeek解释 → 原子保存正式结果。未选择可选外部授权时使用自填资料并标记来源；已选择查询但失败时是否允许降级到自填，需要DEC-QUERY形成明确规则。该规则未定稿前，相应错误按失败处理，不静默忽略。
当前已实现自填分析支线（提交→数据库queued→Redis→DeepSeek→报告）；以下授权查询和产品规则主流程仍待实现：提交后检查授权 → 获取选定的外部结果 → 冻结查询引用 → 规则匹配 → DeepSeek解释 → 原子保存正式结果。未选择可选外部授权时使用自填资料并标记来源；已选择查询但失败时是否允许降级到自填，需要DEC-QUERY形成明确规则。该规则未定稿前，相应错误按失败处理，不静默忽略。
分析页建议2秒起轮询，逐步退避到5秒，离开页面停止前端轮询但不取消服务端任务；重新进入按assessmentId恢复。供应商超时和任务租约由配置控制并在REPORT-002用实际接口时限确定，不按前端10秒请求超时推断AI执行失败。
分析页当前只对processing每5秒轮询，离开页面停止前端轮询但不取消服务端任务；重新进入按assessmentId恢复。供应商总超时90秒、连接超时10秒，执行租约至少180秒、Redis reserved到期240秒，不按前端10秒请求超时推断AI执行失败。
#### 当前v2正式提交示例（所有路径前缀/api/v1，Bearer必填）
```json
{"inputVersion":2,"type":"enterprise","requestId":"submission_example_001","moneyUnit":"yuan","form":{"name":"示例联系人","phone":"19900000001","city":"深圳市","cityCode":"440300","enterpriseName":"示例企业","businessCode":"91440300123456789A","annualRevenue":"1201234.56","operatingMonths":18,"creditLoanCount":0,"totalDebtBalance":null,"requestedAmountYuan":"123456.78","requestedTermMonths":12,"purposeCode":"working_capital","purposeDetail":null},"documents":[],"consentIds":[]}
```
成功HTTP201：`{code:1,msg:"评估资料已保存",time:<Unix秒>,data:{assessmentId:"123",submissionStatus:"accepted"}}`。同键相同规范化内容重复返回相同data。GET /assessments?limit=20&cursor=123继续读取更小ID；data为`{items:[AssessmentStatus],hasMore:boolean,nextCursor:string|null}`。详情额外含form，金额始终是元字符串或null，客户端转万元。当前新建最低版本为2，示例已包含需求四字段；历史v1原键回放仍保留。
422 VALIDATION_ERROR表示字段、枚举、金额或分页错误；422 ASSESSMENT_ATTACHMENTS_UNAVAILABLE表示携带尚不支持的附件/授权；401 AUTH_REQUIRED表示未登录；404 ASSESSMENT_NOT_FOUND不区分越权与不存在；409 REQUEST_CONFLICT表示同键异内容或记录已移除。草稿路径及修改已提交资料未开放；retry已按上表实现；路由采用完整匹配。
当前枚举：maritalStatus=married/single/divorced/widowed；house/car=yes/no；socialSecurity/housingFund=six_months_plus/under_six_months/none，均允许null。计数字段creditLoanCount/creditCardCount/operatingMonths是0–9999的整数或null。个人必填name/idCard/phone/city/monthlyIncome>0，企业必填name/phone/city/enterpriseName/businessCode/annualRevenue>0；类型专属字段不得交叉混入。
### 5.5 助手、内容、消息、积分与客服接口
@@ -624,7 +733,7 @@
### 5.6 对现有占位接口的迁移
- 原POST /assessments“整包提交”拆成创建/更新草稿与submit；确认页必须保存返回assessmentId。
- POST /assessments仅负责正式提交，不创建可续填草稿；确认页必须保存返回assessmentId。
- 原GET /matches替换为GET /assessments/:id/matches，避免读取不明确的“最近结果”。
- 原POST /assistant/messages的message→reply同步接口，替换为会话消息异步接口，避免前端超时导致重复请求模型。
- 原FinanceProduct同时承载公共信息和score的结构，拆成Product与MatchResult；旧amount万元兼容仅在过渡适配器，正式API始终返回amountMinYuan/amountMaxYuan。
@@ -635,9 +744,9 @@
## 6. 工时、里程碑与实施顺序
### 6.1 剩余工程量
### 6.1 初始工程量基线（当前剩余量待重估）
| 模块 | 功能板块 | 阶段 | 剩余人日 |
| 模块 | 功能板块 | 阶段 | 基线人日 |
| --- | --- | --- | ---: |
| BASE | 基础接口与环境 | M0 | 3–5 |
| AUTH | 账户与短信安全 | M1 | 5–8 |
@@ -697,7 +806,7 @@ flowchart LR
| EXT-ONE | 待选型 | H5号码认证产品、运营商/网络/浏览器矩阵、SDK与服务端校验、测试环境 | LOGIN-001、LOGIN-003 |
| EXT-STORAGE | 待选型 | 私有存储方案、访问控制、文件限制、备份与生命周期 | FILE-001 |
| EXT-DATA | 待选型 | 实际可开通数据产品、个人/企业接口、授权要求、样例、回调/查询和费用状态 | DATA-001 |
| EXT-AI | DeepSeek已选定，接入待核验 | 具体模型标识、测试权限、额度、超时/结构化输出支持及实际用量字段；实施时核对官方接口文档 | REPORT-001 |
| EXT-AI | 两个指定模型已真实可用，Flash自填分析通过 | JSON输出及tokens/耗时已核实；供应商余额、价格对账、商业预算仍待确认 | REPORT-001 |
| EXT-CS | 待选型 | H5接入、访客身份、坐席、在线/离线、历史与附件能力、工作时间 | SUPPORT-001、SUPPORT-003 |
| EXT-DEPLOY | 待确认 | 测试/生产资源、域名/HTTPS、Redis/worker守护、备份与监控 | RELEASE-003 |
@@ -705,14 +814,16 @@ flowchart LR
| --- | --- | --- |
| DEC-PRIVACY | 资料用途、可选项、正式协议正文与版本、保留期限、撤销后处置、第三方必要字段 | FILE-001、FILE-003：协议和数据生命周期清单 |
| DEC-QUERY | 首发数据查询种类与个人/企业范围、拒绝/失败后的自填路径、重查与费用归属 | DATA-001：页面授权到数据产品映射及失败策略 |
| DEC-MATCH | 硬准入、未知处理、分数/等级/排序、报告维度、同分规则及人工样例 | PRODUCT-001、REPORT-003：版本化规则与金标准样例 |
| DEC-DEMAND | 已确认并于本地发布：用途字典、other说明、v2新建必填及最低版本2；见0.5 | ASSESS-001：发布的需求字典、校验样例与兼容计划；见专项契约第2/7节 |
| DEC-READINESS | 已按用户授权采用首版并发布开发版：等权字段集/条件项、准备状态及一致性规则；生产业务验收待完成 | REPORT-003：发布策略、策略版本与人工样例；未发布返回policy_unconfirmed |
| DEC-MATCH | 硬准入三态、来源要求、需求覆盖、用途依据、排序/可选匹配指标和解释证据；资料等级另由DEC-READINESS确认 | PRODUCT-001、REPORT-003：版本化规则与金标准样例 |
| DEC-PRODUCT | 首发真实产品及金额/期限/利率/地区/准入依据、有效期和运营责任人 | PRODUCT-003：可发布产品资料与运营确认记录 |
| DEC-AI | DeepSeek具体模型、单用户/评估额度、超时重试、成本预算与超额策略 | REPORT-001：配置及额度规则 |
| DEC-AI | 模型已确定；单用户/评估额度、超时重试、成本预算与超额策略待定 | REPORT-001：配置及额度规则 |
| DEC-POINT | 签到/资料/邀请奖励数额、次数、可信达成条件、权益/有效期 | POINT-001：活动规则及正反样例 |
技术默认项：每类服务商首期一个；站内消息优先；课堂为图文；助手先异步完整回复；时间业务口径Asia/Shanghai；列表pageSize=20、上限50。业务分数、奖励数额、查询费用、模型名和数据保留期限不擅自定为上线规则。
DeepSeek只选定服务商，不能据此宣布模型可用或已通过真实调用。一键登录也不能依据“原生App有SDK”推断H5全场景可用；若渠道不支持已承诺场景，先形成能力差异和影响，再记录用户的范围决定，不能静默删项。
DeepSeek已通过真实请求与自填报告验证，但不代表供应商余额充足或生产容量已验收。一键登录也不能依据“原生App有SDK”推断H5全场景可用；若渠道不支持已承诺场景，先形成能力差异和影响，再记录用户的范围决定，不能静默删项。
## 8. 验证、发布与文档维护
@@ -729,11 +840,14 @@ DeepSeek只选定服务商，不能据此宣布模型可用或已通过真实调
| 场景 | 必须满足的结果 | 归属 |
| --- | --- | --- |
| 金额换算 | 0.800001万元=8000.01元；最大值、超限、负数、空值、0和精度均校验；不重复换算 | ASSESS-004、PRODUCT-004 |
| 身份与越权 | 用户A不能读取/修改B的草稿、证件、报告、会话、消息和反馈；改密/换绑后旧Token失效 | AUTH-004、RELEASE-001 |
| 身份与越权 | 用户A不能读取/修改B的评估、证件、报告、会话、消息和反馈；改密/换绑后旧Token失效 | AUTH-004、RELEASE-001 |
| 重复提交/历史重试回放 | 相同requestId只一条正式会话；多次重试后重放任一旧键仍返回其原taskId、不再次执行；同键参数冲突拒绝 | ASSESS-003 |
| 任务故障 | 派发失败、重复消费、worker退出、旧taskId回写均可恢复或安全拒绝 | REPORT-002 |
| 历史稳定 | 同类型多次评估分别保留；产品改价/下架不改变历史快照 | PRODUCT-004、REPORT-004 |
| 缺失事实 | 未知字段不当0，渠道失败不当无风险；AI不得创造不存在的额度/审批承诺 | PRODUCT-002、REPORT-003 |
| 融资需求v2 | 金额/期限/用途校验、版本切换和旧键重放通过；历史NULL不补造需求 | ASSESS-001、ASSESS-003、ASSESS-004 |
| 完整度与准备等级 | 0与null、条件分母、四舍五入和一致性分开；未发布无分/等级；不等同授信 | REPORT-003、REPORT-004 |
| 匹配解释v2 | fail+unknown不推荐，证据可复算；不凑理由；配置错误不变用户不符；null rank/score合法 | PRODUCT-001、PRODUCT-002、PRODUCT-004、REPORT-003 |
| 私有资料 | 无登录/跨用户无法读取，撤销后不新增查询；授权版本可追溯 | FILE-004、DATA-004 |
| 课程进度 | 章节重排不串记录，重复完成幂等，换设备一致 | CONTENT-003 |
| 积分并发 | 同日并发只奖励一次，流水与余额一致；复制/分享不视为实际邀请成功 | POINT-004 |