airz-uniapp/docs/开发文档.md

# AI 融资平台开发文档

> 版本：v1.0 · 基线日期：2026-09-22 · 状态：M0与账户基础已启动，真实短信/AI/产品依赖未就绪  
> 配套台账：[开发进度](开发进度.md)。本文定义范围、接口和验收口径，台账记录实际执行与证据。  
> 文档初始规划后已开始开发；以下更新记录优先于原始基线。除明确列为已实现的部分外，计划接口和增量数据仍待开发。

## 0. 2026-09-22 实施更新

- 用户最新决定：删除fa_user_token，会员Token仅存Redis；已备份并删除本地表，当前25张表。fa_user和各业务关系保持不变。运行配置不再依赖MySQL Token驱动。
- 已接通Bearer、FastAdmin响应解包、业务错误/401处理；新增v1密码登录、本人资料读取、退出、原密码改密。短信接口返回明确未配置状态。
- 前端开发环境指向本地真实接口，按稳定userId隔离本机缓存；测试/生产地址、匿名旧草稿显式导入和敏感缓存清理仍待完成。内容等尚未开发模块仍存在原型数据，不能判一期已完成。
- Redis驱动使用独立前缀、摘要Token键、TTL和Lua原子索引/撤销。登录和改密按用户行锁串行，Redis故障不降级到MySQL。
- 短信服务商、DeepSeek测试权限、首批真实产品资料目前均未具备；不创建模拟凭证、不伪造AI结果或导入演示产品充当真实资料。
- 开发任务编号及原69–117人日估算基线保留，尚未填写实际耗时，不凭实施条目推算剩余工期。最新状态与证据见进度文档第0章。

## 1. 项目目标与现状

### 1.1 已确认范围

一期将现有 **25 个页面全部接入真实业务，H5 优先首发**。包含手机号/密码/微信/一键登录、个人与企业评估、私有资料、正式授权、外部征信或数据查询、产品匹配、DeepSeek 报告、历史档案、AI 助手、新闻、图文课堂、搜索、消息、积分邀请、帮助反馈及人工客服。相关运营后台一并验收。

按 **1 人全栈＋AI 辅助**排期。AI 服务商确定为 **DeepSeek**；具体模型、预算和测试权限待核验。短信、号码认证、外部数据、客服、存储等渠道待选型。微信内网页与普通 H5 的登录方式分别核实平台能力。一期必做渠道未接通时保持未验收，不以模拟成功替代。

微信小程序、Android、iOS 的平台适配、真机、签名和发布列入后续里程碑，不计入本期 69–117 人日。保留现有跨端代码结构。贷款功能止于申请准备和资料引导；当前范围不包含金融机构受理、授信、放款、支付或资金交易。课堂保持图文形式。

### 1.2 代码与数据依据

| 项目 | 当前事实 | 规划用途 |
| --- | --- | --- |
| 前端 | 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，模拟请求开关关闭 | 密码账户流程已接入，内容与报告等页面仍有原型数据，不按页面数计算完成度 |
| 当前后端能力 | 评估生命周期、加密、密码兼容、产品后台等基础已存在 | 内部服务不等于已暴露并联调的业务 API |
| 第三方接入 | 尚未验证真实短信、DeepSeek、外部查询、客服闭环 | 各渠道独立记录测试环境与验收证据 |

源代码位置：

- 前端：[README](../README.md)、[页面注册](../pages.json)、[共享请求](../services/api.uts)、[金额转换](../services/money.uts)。
- 后端：[数据库约定](D:/AAdesk/202609/airz/database/README.md)、[当前结构](D:/AAdesk/202609/airz/database/schema.sql)、[评估生命周期](D:/AAdesk/202609/airz/application/common/library/Assessment.php)、[API 基类](D:/AAdesk/202609/airz/application/common/controller/Api.php)。
- 原根目录 airz.sql 是历史导出；不能作为当前库结构依据。双方已有未提交改动属于现状基线，不在文档任务中覆盖或提交。

### 1.3 已有基础与首要缺口

已有基础：万元与元精确转换、个人/企业草稿交互、产品范围字段和版本、评估提交/完成/失败/重试内部服务、敏感字段加密、旧密码兼容、Token Redis切换（早期曾恢复表，现已删除）、日志脱敏及基础验证。

首要缺口：

1. Bearer、FastAdmin响应解析和401处理已接通；全量字段字典、requestId日志关联、生产环境配置仍待完成。
2. 确认页未承接评估编号，分析页计时跳转，报告使用固定分数；必须打通 assessmentId 全链路。
3. 本机草稿、学习进度、签到和消息状态已按userId隔离；旧匿名草稿显式导入、退出后敏感缓存清理与云端持久化仍待完成。
4. 产品准入、业务 API、评估队列、DeepSeek 请求与真实报告均待开发。
5. 通用公共上传不能直接存正式证件；授权勾选和插件钩子不代表第三方服务已接入。

## 2. 页面与功能覆盖

路由以 [pages.json](../pages.json) 为准。以下覆盖现有全部 25 页；反馈表单、历史列表等优先补入所属现有页面，若交互确需新增页面，在所属分包注册并同步台账。

| 序号 | 页面路由 | 功能职责 | 主要任务 |
| --- | --- | --- | --- |
| 1 | pages/home/home | 首页、融资入口、推荐、消息红点 | BASE-004、CONTENT-002、MSG-003 |
| 2 | packages/finance/entry/entry | 个人/企业融资入口 | ASSESS-004 |
| 3 | packages/finance/assessment/assessment | 分步填写、上传及授权 | ASSESS-001、ASSESS-002、FILE-004、DATA-004 |
| 4 | packages/finance/confirm/confirm | 确认资料、幂等提交 | ASSESS-003、ASSESS-004 |
| 5 | packages/finance/analyzing/analyzing | 真实分析状态、失败重试 | REPORT-002、REPORT-004 |
| 6 | packages/finance/report/report | 真实报告、维度与结论 | REPORT-003、REPORT-004 |
| 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 |
| 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 |
| 14 | packages/account/edit-profile/edit-profile | 昵称与头像 | AUTH-003 |
| 15 | packages/account/security/security | 账户安全状态及入口 | AUTH-004 |
| 16 | packages/account/password/password | 原密码/验证码修改密码 | AUTH-004 |
| 17 | packages/account/change-phone/change-phone | 原新手机号验证与换绑 | AUTH-004 |
| 18 | packages/account/points/points | 签到、流水、任务及邀请 | POINT-001、POINT-002、POINT-003、POINT-004 |
| 19 | packages/account/messages/messages | 消息与未读管理 | MSG-001、MSG-002、MSG-003、MSG-004 |
| 20 | packages/content/search/search | 新闻和课程搜索 | CONTENT-004 |
| 21 | packages/content/help/help | FAQ、反馈、人工客服 | CONTENT-004、SUPPORT-001、SUPPORT-002、SUPPORT-003、SUPPORT-004 |
| 22 | packages/content/news/news | 资讯分类与列表 | CONTENT-002 |
| 23 | packages/content/article/article | 新闻、协议和说明内容 | CONTENT-001、CONTENT-002、FILE-003 |
| 24 | packages/content/classroom/classroom | 课程分类和推荐 | CONTENT-002 |
| 25 | packages/content/lesson/lesson | 图文章节、学习状态 | CONTENT-001、CONTENT-003 |

## 3. 数据与架构约定

### 3.1 评估、报告、会话

- fa_user_info **一行代表一次评估**；再次评估新建记录，可从本人既往输入复制。提交后的输入不可被前端或后台 CRUD 改写。
- fa_ai_chat 的 scene=assessment 必须关联唯一 assessment_id；report_data 保存报告对象，match_result 保存有序匹配数组。**不新增独立评估、报告或匹配结果表。**
- scene=assistant 时 assessment_id 必须为 NULL。助手要引用某次评估时，计划增加单独的 context_assessment_id，并校验同一用户；它不承担正式报告唯一关系，也不改变已有 scene 约束。
- 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 补齐。
- 外部查询结果不回写已提交表单。使用单独查询流水保存来源、授权和标准化结果，任务在生成报告前冻结所用结果集合/截止时间；最终报告保存引用、来源及必要摘要。后到结果不得悄悄重写历史报告。

### 3.2 金额、产品与数据字典

| 数据 | 客户端/API/数据库口径 |
| --- | --- |
| 业务金额 | 客户端万元；API 元的两位小数字符串；DB DECIMAL(11,2)，非负范围 0–999999999.99 |
| 精度 | 0.800001 万元 → 8000.01 元；万元最多6位小数，上限99999.999999；不使用二进制浮点乘除形成入库金额 |
| 未填写 | API使用null，适配器将表单空字符串转null；不把未知金额/计数当0 |
| 利率 | 年化百分数，3.85表示3.85%；API建议十进制字符串，禁止误作0.0385 |
| 期限 | 整数月；产品 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；旧“有/无”在适配层转换 |
| 产品对象 | DB object 为 SET，可同时适用于个人和企业；不是单一类型值 |
| 产品状态 | switch=0草稿、1上架、2下架；还需检查有效期 |
| 地区 | 使用统一版本的地区代码；regions=[]才表示全国，NULL视为未配置并阻止上架 |
| 经营时间 | 用户明确填写经营月数；旧operatingYears文字无法确定时要求补填，不猜测 |
| 日期时间 | API事件时间ISO 8601带时区；有效期为YYYY-MM-DD；业务签到时区Asia/Shanghai；数据库现有int/datetime由DTO转换 |

产品额度上下限、期限上下限、年化利率上下限、发布状态、有效期、版本及稳定准入字段保持独立列。regions 为地区代码数组；eligibility_rules 为带版本的补充规则对象。现有 condition/grade/information/recommendation/deprecated/other 保留文本用途；公共 recommendation 不保存用户个性化理由。

硬准入、未知值策略、评分权重、维度和样例在 PRODUCT-001 / DEC-MATCH 定稿。AI不决定产品是否满足硬条件，不编造审批概率或外部征信结论。无可靠依据时报告维度和总分可以为空并说明资料不足，不能继续展示固定85分。

### 3.3 前后端字段映射

以下为目标DTO主要映射，BASE-001和ASSESS-001补齐校验器与兼容适配；不直接把前端payload整包入库。

| 前端/目标API字段 | 数据库字段或目标处理 | 说明 |
| --- | --- | --- |
| 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 |
| 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 |
| 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供兼容，稳定准入只用规范月数 |
| 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 |

本机格式标记 moneyUnit=wan、draftVersion=2 继续用于旧草稿规范化；服务器修订字段在API命名为 revision，避免混淆。提交与存储DTO只接受 moneyUnit=yuan。

### 3.4 增量数据设计工作

以下为待实现的最小数据方案，由对应任务提交增量迁移和回滚说明。本次未创建任何表或字段。所有新增关系都采用服务端所有者校验；必要唯一索引以数据库保证并发一致性。

| 需求 | 复用位置 | 计划增量与约束 | 负责任务 |
| --- | --- | --- | --- |
| 草稿、标准字段、补充输入 | 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_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 |
| 外部查询审计 | fa_user_info关联 | 拟增fa_data_query：用户/评估/授权、渠道、请求和渠道单号、状态、受保护结果引用、来源时间、错误/费用状态 | DATA-002、DATA-003 |
| 普通助手引用报告 | fa_ai_chat | context_assessment_id可空，仅同用户；assistant.assessment_id保持NULL | CHAT-001 |
| 课程内容与进度 | fa_finance | 课程章节JSON带稳定chapterId/版本；拟增fa_user_lesson_progress，唯一(user_id,lesson_id,chapter_id) | CONTENT-001、CONTENT-003 |
| FAQ与发布资料 | fa_acticle | 扩展明确定义的FAQ类型、展示分类/排序；增加标题之外所需摘要/封面字段 | CONTENT-001 |
| 消息去重 | fa_user_message | 新增事件键；按用户+事件键唯一，批量已读按请求时的最大ID水位更新 | MSG-001、MSG-002 |
| 签到与邀请 | fa_user、fa_user_score_log | 流水写入business_type/business_id；share_code去重后加唯一索引；拟增fa_user_invitation，受邀用户仅绑定一次，禁止自邀 | POINT-002、POINT-003 |
| 反馈处理与客服 | fa_feedback | 处理状态、回复、处理人/时间；客服历史优先使用供应商能力，只保存必要关联标识 | SUPPORT-002、SUPPORT-003 |

变更只追加有明确业务目的的字段或关系。新增这些支撑表不改变“不新增独立评估、报告、匹配表”的约定。详细DDL在对应数据任务内提交审阅；已有数据需先预检、备份、回填验证，再收紧约束。不能直接重跑原空业务表限定的迁移脚本。

## 4. 模块开发任务

任务编号与[开发进度](开发进度.md)一一对应；每个模块4项，共60项。工时为剩余工程人日，含模块内开发者测试，不含外部审核等待。任务级验收是具体交付条件，模块整体还需通过M4的真实联调。


### 4.1 BASE｜基础接口与环境

**目标：** 建立所有模块共用且可联调的网络、会话和环境基础。 **阶段：** M0。**剩余：** 3–5人日。

- **现状：** 页面、导航、安全区已有；共享请求已接本地API，处理Bearer、业务失败与401；全量契约、requestId及生产配置仍待完成。
- **前端：** 统一请求与账户专用请求，处理认证、业务错误、重复点击、加载/空态、401回跳；首页聚合公共内容与登录后状态。
- **后端：** 新路由显式绑定控制器和方法；解析JSON并逐字段校验，不能对结构化输入机械套用HTML转义；兼容旧Token入口但新客户端只发送Bearer。
- **数据：** 以userId建立缓存命名空间。旧匿名草稿由用户明确导入；不自动认领其他本机数据。
- **接口：** GET /home、GET /dictionaries，以及所有接口共用协议。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 生产缺API地址直接报配置错误；禁止静默降级成demo。断网不删除服务端事实。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| 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-004 | 首页和联调骨架：首页接入聚合数据、加载/空态/失败重试及登录回跳；建立接口冒烟入口。 | P1 | BASE-002、BASE-003 | 深链接与刷新正确恢复；首页无硬编码账户数据；真实未读数后续由 MSG 接入。 | 0.5–1 |

### 4.2 AUTH｜账户与短信安全

**目标：** 让账户身份、个人资料和安全操作形成真实服务端闭环。 **阶段：** M1。**剩余：** 5–8人日。

- **现状：** 密码登录、本人资料读取、退出和原密码改密已接Redis会话；短信注册/登录、换绑和资料更新仍待完成，本机资料仅作回显缓存。
- **前端：** 接通短信/密码登录，读取profile；头像独立上传；安全操作成功后重新登录。
- **后端：** 验证码用途、用户和手机号绑定；换绑核验当前及新号码；修复旧免登录改绑声明；修改密码/手机号撤销全部会话。
- **数据：** 复用fa_user/fa_sms；会话改用Redis；手机号冲突由唯一约束兜底；昵称不覆盖实名。
- **接口：** /auth/sms-code、/auth/sms-login、/auth/password-login、/auth/logout、/account/profile、/account/avatar、/account/password、/account/phone。已实现与计划范围见第5章；短信仅返回未配置状态，不代表渠道已实现。
- **异常与边界：** 验证码重复/过期、账户禁用、号码占用、原手机号不可用分别返回可操作提示；失去原号需进入人工核验流程，不能跳过身份证明。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| AUTH-001 | 短信接入与验证码服务：供应商适配、签名模板、验证码用途/有效期/频控/核销、测试发送。 | P0 | BASE-002、EXT-SMS | 发送成功才倒计时；验证码过期、复用、跨用途和频繁发送均拒绝。 | 1–2 |
| AUTH-002 | 真实登录与会话：短信登录/首次注册、密码登录、资料读取、登出、禁用账户、旧密码散列升级。 | P0 | AUTH-001、BASE-003 | 真实账户登录成功；登录失败无假 Token；登出撤销当前 Token；旧散列兼容。 | 1.5–2 |
| AUTH-003 | 资料与头像持久化：昵称、头像 API 和文件校验；以服务端 profile 为准，迁移本机回显逻辑。 | P1 | AUTH-002 | 不同设备资料一致；昵称不覆盖评估实名；头像不依赖临时路径。 | 1–2 |
| AUTH-004 | 改密与手机换绑：登录校验、原/新手机双挑战、号码占用、事务及全部会话撤销；修复旧改绑免登录声明。 | P0 | AUTH-002 | 跨账户或单个验证码不能换绑；修改后旧 Token 全失效；新密码8–32位且含字母和数字。 | 1.5–2 |

### 4.3 LOGIN｜微信与一键登录

**目标：** 使微信和运营商号码认证在获批H5场景真正可用。 **阶段：** M1。**剩余：** 5–10人日。

- **现状：** 两个入口均只弹出未开放提示；User::third仅有插件调用骨架。
- **前端：** 按微信内/普通浏览器/桌面浏览器展示受支持登录方式，处理跳出返回、取消和短信回退。
- **后端：** 服务端code/credential交换，state和回调防重放；已有账户绑定需账户证明，禁止按昵称自动合并。
- **数据：** 独立第三方身份关系以provider/appId/subject唯一；unionid仅在取得并验证适用范围后辅助绑定。
- **接口：** GET /auth/wechat/authorize、GET /auth/wechat/callback、POST /auth/oneclick、POST /auth/bind-phone。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 渠道授权失败不创建半登录会话；不支持的网络或浏览器回到短信；只有支持矩阵中场景通过才记完成。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| LOGIN-001 | 登录渠道能力与身份方案：确认微信内/普通H5方式、号码认证H5能力；定义渠道身份与手机号账户绑定方案。 | P0 | BASE-001、EXT-WX、EXT-ONE | 形成渠道支持矩阵、回调和身份唯一键方案；不以昵称/openid跨应用猜测同一账户。 | 1–2 |
| LOGIN-002 | 微信登录接入：授权发起、state校验、code服务端交换、首次手机号绑定与已有账户冲突处理。 | P0 | LOGIN-001、AUTH-002、EXT-WX | 授权取消和重放安全失败；绑定现有账户需原账户证明；获批H5场景真机通过。 | 1.5–3 |
| LOGIN-003 | 一键登录接入：号码认证SDK/网页流程、服务端验证、能力检测、账号绑定、短信回退。 | P0 | LOGIN-001、AUTH-002、EXT-ONE | 按渠道支持的网络/运营商/浏览器验收；客户端自报手机号不能登录。 | 1.5–3 |
| LOGIN-004 | 身份渠道联调：微信内、普通移动H5和桌面H5分别验证；解绑/冲突与失败恢复按已选渠道能力实现。 | P0 | LOGIN-002、LOGIN-003 | 身份关联不误合并账户；重放无效；不支持场景有清晰短信回退。 | 1–2 |

### 4.4 FILE｜资料与授权

**目标：** 资料可安全持久化，授权可追溯且可以撤销。 **阶段：** M1。**剩余：** 4–7人日。

- **现状：** 前端仅本机预览；documents和consent_data已预留；现有上传默认公共用途。
- **前端：** 资料类型、上传进度/失败重试、已上传列表、协议全文、授权状态和撤销入口。
- **后端：** 私有文件服务、归属/MIME/内容/大小校验、鉴权下载、协议版本和授权事件；评估提交时由服务端形成快照。
- **数据：** 复用附件表与评估JSON；协议修订和独立授权事件保留历史；文件保留/删除期限在DEC-PRIVACY定稿。
- **接口：** POST /documents、GET/DELETE /documents/:id、GET /agreements/:code、GET/POST /consents、POST /consents/:id/revoke。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 临时路径、他人附件、无效授权全部拒绝；可选资料不强迫提交；撤销后停止新查询，历史留存按已确认规则处理。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| FILE-001 | 私有资料存储方案：区分公开头像与私有证件；确定文件白名单、大小限制、存储密钥、附件元数据与保留策略。 | P0 | BASE-001、EXT-STORAGE、DEC-PRIVACY | 私有文件不在公开web目录；形成文件用途/权限/生命周期配置清单。 | 1–1.5 |
| FILE-002 | 私有上传与下载：持久附件ID、归属校验、大小/MIME/内容校验、鉴权读取、失败重试和删除策略。 | P0 | FILE-001、AUTH-002 | 无登录/跨用户不能读取；客户端临时路径不能提交为附件；失效链接不可访问。 | 1–2 |
| FILE-003 | 协议与授权版本：协议全文展示、同意/撤销事件、范围与协议版本、历史快照及外部授权凭据边界。 | P0 | FILE-001、AUTH-002、DEC-PRIVACY | 提交可追溯所见协议版本；撤销阻止新查询；前端布尔勾选不冒充第三方授权。 | 1–2 |
| FILE-004 | 资料授权页面联调：替换选图预览和占位协议；展示上传/授权状态；拒绝、取消、断网恢复。 | P0 | FILE-002、FILE-003 | 仅已上传且有权访问的附件入评估；拒绝可选授权仍可自填，不显示已查询。 | 1–1.5 |

### 4.5 ASSESS｜评估与融资档案

**目标：** 个人与企业评估可云端续填、重复评估、可靠提交并查看历史。 **阶段：** 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；失败重试保持原输入。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| 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 |

### 4.6 DATA｜外部征信或数据查询

**目标：** 把已授权的真实外部数据纳入评估，且来源与查询过程可追溯。 **阶段：** M2。**剩余：** 6–12人日。

- **现状：** 只有授权意向和预留JSON；尚无真实数据服务。
- **前端：** 展示实际可用查询种类、授权状态、查询中/成功/失败/拒绝/撤销，不把选择框当查询完成。
- **后端：** 服务商适配、签名、异步状态、回调验签/去重、对账、费用状态；原始证件标识只在必要服务端流程使用。
- **数据：** 查询记录与评估/用户/授权绑定；必要结果加密或私有存储；输入冻结后只追加查询事件。
- **接口：** GET/POST /assessments/:id/data-queries、GET /data-queries/:id、POST /callbacks/data/:provider。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 超时收费不明先查渠道状态；未取得或已撤销授权不新调用；缺失数据标未知，不能伪装征信正常。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| DATA-001 | 查询渠道与范围定稿：确认实际可开通数据产品、个人/企业范围、授权凭证、测试样例、计费与返回解释。 | P0 | BASE-001、EXT-DATA、DEC-QUERY | 每种首发授权都有明确数据来源和支持范围；缺失渠道记阻塞并更新估算。 | 1–2 |
| DATA-002 | 授权查询适配与记录：服务端发起、请求唯一键、渠道凭证隔离、查询事件持久化及assessmentId绑定。 | P0 | DATA-001、FILE-003、ASSESS-003 | 无有效授权不调用；重复发起不重复建本地请求；不得将他人结果用于本次评估。 | 2–4 |
| DATA-003 | 回调与结果标准化：验签、防重放、回调幂等、主动查询对账、结果字段/来源/时间映射与受限留存。 | P0 | DATA-002 | 伪造/过期回调拒绝；迟到结果不覆盖冻结输入；查询失败不转换成零风险。 | 2–4 |
| DATA-004 | 异常与渠道端到端验收：超时、撤销、拒绝、余额不足、重复回调、重查和H5往返恢复。 | P0 | DATA-003 | 成功和失败均可追踪；超时收费不明先对账；各已承诺首发场景有真实渠道证据。 | 1–2 |

### 4.7 PRODUCT｜产品库与匹配规则

**目标：** 可运营的产品库与可解释、可复现的个性化匹配。 **阶段：** M2。**剩余：** 6–9人日。

- **现状：** 范围字段、版本、上架校验等基础已有；补充JSON尚无执行器，前端是demo产品。
- **前端：** 拆Product与MatchResult；显示范围而非单点额度/利率；保持历史快照并提示当前产品状态。
- **后端：** 确定性规则、白名单操作符、类型校验、版本化排序；只推荐状态/有效期/地区及硬条件满足的产品。
- **数据：** 产品独立字段+regions/eligibility_rules；个性化分数和理由放match_result，快照含产品版本。
- **接口：** GET /products、GET /products/:id、GET /assessments/:id/matches；后台沿用产品CRUD并补运营校验。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 暂无匹配是合法完成结果；规则未知不执行任意表达式；产品下架不删除历史快照。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| 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 |

### 4.8 REPORT｜AI任务、报告与历史

**目标：** 把真实输入、查询依据和产品匹配生成可追溯的DeepSeek报告。 **阶段：** M2。**剩余：** 8–12人日。

- **现状：** report_data/match_result及complete服务已有；队列配置存在但没有业务Job，页面为计时和静态分数。
- **前端：** 轮询真实状态、刷新恢复、失败重试；渲染数据驱动维度、来源时间和版本；查看历史。
- **后端：** DeepSeek适配、结构校验、任务抢占/超时/漏投补偿、输入最小化、用量记录；在事务中同时落报告、匹配和成功状态。
- **数据：** result_version/rule_version/model与产品快照分别记录；模型输出不能覆盖金额、硬准入或数据来源。
- **接口：** GET /assessments/:id/status、GET /assessments/:id/report；内部worker调用complete/fail，不公开完成接口。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 模型输出错误/配额不足/队列故障进入可追踪失败；重试不允许旧taskId回写；供应商超时可能计费，不承诺外部零重复收费。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| 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 |

### 4.9 CHAT｜AI助手

**目标：** 可恢复、隔离且能基于本人评估解释的AI会话。 **阶段：** M3。**剩余：** 4–7人日。

- **现状：** 页面消息仅内存，回复固定；消息结构、序号和用量字段已预留。
- **前端：** 创建/切换/恢复会话、分页历史、发送状态、异步回复轮询与重试；保留requestId。
- **后端：** DeepSeek对话、上下文裁剪、所有者校验、消息和本地额度幂等；用户输入不可触发任意管理操作。
- **数据：** 普通scene的assessment_id保持NULL；context_assessment_id只引用本人可访问评估；工具结果记录来源。
- **接口：** POST/GET /assistant/chats、GET/POST /assistant/chats/:id/messages、GET /assistant/messages/:id、POST /assistant/messages/:id/retry。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 失败消息保留错误和可重试状态；切换账号不带上旧会话；渠道取消不能保证停止已发生计费，一期不要求生成中强制取消。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| CHAT-001 | 会话与消息API：普通会话创建/列表/消息分页/归属；明确可引用评估上下文且不占用正式assessment_id。 | P1 | AUTH-002、BASE-001 | 用户只能读自身会话；评估会话与普通会话分离；重进恢复历史。 | 1–1.5 |
| CHAT-002 | DeepSeek对话调用：上下文裁剪、敏感信息最小化、消息幂等、异步回复与本地配额记录。 | P1 | CHAT-001、REPORT-001、REPORT-002 | 同请求不重复建消息或记本地消耗；错误回复不标成功；不会发送无关证件资料。 | 1–2 |
| CHAT-003 | 助手页面接入：chatId/requestId、历史加载、发送状态、失败重试、由报告进入解释上下文。 | P1 | CHAT-002、REPORT-004 | 切换会话不串上下文；超时保留可重试消息；重进页面能继续。 | 1–2 |
| CHAT-004 | 对话异常与额度验收：并发消息、重复点击、额度耗尽、供应商超时及失效会话。 | P1 | CHAT-003 | 配额并发不超扣；供应商计费不明可对账；仅真实成功回复显示完成。 | 1–1.5 |

### 4.10 CONTENT｜内容、课堂、搜索与FAQ

**目标：** 后台发布的内容、图文课程和FAQ可被前端检索阅读，进度跨设备一致。 **阶段：** M3。**剩余：** 4–6人日。

- **现状：** 前端本地资讯/课程/FAQ，课程进度为设备级键；后台存在表和CRUD但发布流程不完整。
- **前端：** 新闻、文章、课堂、课程页接真实分页/详情；处理404/下架，搜索竞态和章节完成状态。
- **后端：** 发布/下架、富文本清洗、分类与首页推荐、搜索和FAQ；稳定章节ID与进度幂等。
- **数据：** 复用fa_acticle/fa_finance；章节数据结构化；用户章节完成关系独立存储；不引入视频和付费课程。
- **接口：** /content/articles、/content/lessons、/content/lessons/:id/progress、/content/search、/help/faqs。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 未发布内容不可访问；新增/重排章节不沿用索引作为进度ID；搜索慢响应不得覆盖新查询。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| CONTENT-001 | 内容模型与发布后台：补齐文章/课程结构、稳定章节ID、分类、封面/摘要、发布状态、FAQ类型及协议入口。 | P1 | BASE-001 | 后台可发布/下架；章节重排不换ID；草稿不可公开；FAQ可维护。 | 1–1.5 |
| CONTENT-002 | 列表详情与首页推荐：新闻/文章/课堂/详情真实API、分页、富文本清洗、缺失内容与首页推荐接入。 | P1 | CONTENT-001、BASE-004 | 首页/列表/详情ID一致；无模拟兜底内容；下架详情有明确不可用状态。 | 1–1.5 |
| CONTENT-003 | 云端课程进度：按用户/课程/章节记录完成，章节版本兼容、跨设备恢复和本机缓存策略。 | P1 | CONTENT-002、AUTH-002 | 用户隔离；重复完成幂等；章节排序变化不串进度；跨设备一致。 | 1–1.5 |
| CONTENT-004 | 搜索与FAQ联调：真实全文字段检索、分类/分页、请求竞态、FAQ读取、无结果和断网恢复。 | P1 | CONTENT-002 | 旧搜索响应不覆盖新关键词；返回ID可开详情；FAQ与实际业务行为一致。 | 1–1.5 |

### 4.11 MSG｜消息中心

**目标：** 将真实业务通知、阅读状态与首页红点保持一致。 **阶段：** M3。**剩余：** 2–4人日。

- **现状：** 前端静态通知和本机已读；表含read_at与业务引用，没有用户端业务API。
- **前端：** 分类分页、未读数、已读/全部已读、与正确评估记录跳转。
- **后端：** 在业务事务完成后可靠生成通知，事件唯一键去重；读取和更新均限定当前用户。
- **数据：** 复用fa_user_message，补事件唯一键；is_read和read_at同步；全部已读采用最大ID水位。
- **接口：** GET /messages、GET /messages/unread-count、POST /messages/:id/read、POST /messages/read-all。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 队列重试不重复通知；全部已读期间新增消息仍未读；本期站内消息不等同App推送。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| MSG-001 | 通知事件与去重：定义评估结果等事件、通知去重键及写入时机，补齐唯一性保障。 | P1 | BASE-001、REPORT-004 | 重复任务不会重复通知；成功/失败通知关联正确assessmentId。 | 0.5–1 |
| MSG-002 | 消息读写API：当前用户分页/分类/未读数/单条已读/全部已读，read_at与is_read一致。 | P1 | MSG-001、AUTH-002 | 跨用户读写拒绝；已读重复操作幂等；列表/计数一致。 | 0.5–1 |
| MSG-003 | 消息页面与首页红点：替换静态通知与固定红点，处理业务跳转、空态、刷新及批量已读。 | P1 | MSG-002、BASE-004 | 换设备状态一致；打开通知到对应历史；关联记录不可用有提示。 | 0.5–1 |
| MSG-004 | 事件消息验收：事件重复、失败重试、分页期间新通知和并发全部已读测试。 | P1 | MSG-003 | 全部已读不误吞操作后新增消息；通知去重和未读数通过数据库核对。 | 0.5–1 |

### 4.12 POINT｜积分、任务与邀请

**目标：** 积分与真实任务事件一致，邀请可归因且奖励不会重复发放。 **阶段：** M3。**剩余：** 4–7人日。

- **现状：** 本机签到+10，固定体验邀请码；底层score方法未使用业务唯一键。
- **前端：** 真实积分、流水、服务端签到状态、邀请码和任务进度，显示已发布规则版本。
- **后端：** 积分事务和并发锁、日期与任务幂等、防自邀、可信事件奖励；错误需向业务层传播。
- **数据：** 复用score及score_log，明确business_type/business_id；邀请码唯一、受邀用户一次绑定。
- **接口：** GET /points、GET /points/ledger、POST /points/check-in、GET /points/tasks、GET /invitations、POST /invitations/bind。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 默认保留每日签到10分作为待业务确认建议；其他奖励金额不编造。复制文案或客户端上报完成不直接发积分。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| POINT-001 | 积分规则定稿：确认签到、资料完成、邀请奖励的条件/次数/额度、业务时区和权益范围。 | P1 | BASE-001、DEC-POINT | 形成版本化活动规则；复制/分享不等于奖励；未确认奖励规则不得上线。 | 0.5–1 |
| POINT-002 | 积分账户与签到：事务更新score与流水、业务唯一键、服务端日期签到、余额/流水查询。 | P1 | POINT-001、AUTH-002 | 同用户同日并发只加一次；流水与积分一致；错误不静默吞掉。 | 1.5–2 |
| POINT-003 | 邀请码与邀请关系：生成唯一邀请码、首次有效绑定、防自邀、可信奖励事件与发放幂等。 | P1 | POINT-002 | 客户端不能自报完成奖励；重复/自邀拒绝；已有关系不随分享覆盖。 | 1–2 |
| POINT-004 | 任务积分页面联调：真实余额、流水、签到状态、个人邀请码、任务状态和规则说明。 | P1 | POINT-003、ASSESS-004 | 真实到账后才提示成功；跨账户/跨设备一致；邀请复制不立即发奖励。 | 1–2 |

### 4.13 SUPPORT｜反馈与人工客服

**目标：** 帮助页既能提交可追踪反馈，也能真实到达人工服务。 **阶段：** M3。**剩余：** 3–6人日。

- **现状：** FAQ可展开，客服仅未开放提示，反馈表有基础CRUD。
- **前端：** 反馈表单/附件/记录/回复；客服在线/排队/离线状态及失败回退。
- **后端：** 反馈归属与后台处理、服务端访客签名、客服会话关联；外部系统消息遵循渠道身份规则。
- **数据：** 复用fa_feedback补处理结果；不把反馈图片当公共文件；客服历史优先由供应商维护。
- **接口：** POST/GET /feedback、GET /feedback/:id、POST /support/session。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 无坐席能留言且后台有责任人；SDK失败提示可使用站内反馈；退出切换账号清理客服身份。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| SUPPORT-001 | 客服方案与运营准备：选定H5客服、身份签名、坐席/工作时间、离线策略、反馈状态及责任人。 | P0 | BASE-001、EXT-CS | 具有可测试坐席和离线处理渠道；确认SDK/隐私及首发支持范围。 | 0.5–1 |
| SUPPORT-002 | 反馈提交与处理闭环：帮助页增加反馈表单/记录；附件权限、后台状态/回复、用户查看处理结果。 | P1 | AUTH-002、FILE-002 | 反馈可提交到后台并回复；仅当前用户可查；附件无越权。 | 1–2 |
| SUPPORT-003 | H5人工客服接入：服务端签发访客身份、前端打开客服、在线/排队/离线、失败回退。 | P0 | SUPPORT-001、AUTH-002、EXT-CS | 真实到达人工坐席；不由前端伪造用户身份；离线可留言并有处理路径。 | 1–2 |
| SUPPORT-004 | 客服反馈联调：普通/微信内H5、账户切换、关闭重开、无坐席、SDK失败和消息记录。 | P0 | SUPPORT-002、SUPPORT-003、CONTENT-004 | 会话无跨账户泄漏；客户可获回复；供应商不支持项准确提示。 | 0.5–1 |

### 4.14 ADMIN｜后台运营与排障

**目标：** 让运营人员能管理业务、定位故障并执行受控操作。 **阶段：** M3。**剩余：** 3–5人日。

- **现状：** 通用管理员权限和业务CRUD基础已有；不能据此认为完整运营流程已完成。
- **前端：** FastAdmin后台增加任务、模型额度、查询状态和运营入口，非移动端新增主导航。
- **后端：** 角色授权、敏感字段掩码、任务/查询定位、受控重试和审计；不允许手改已提交评估输入及正式结果。
- **数据：** 复用管理员fa_auth_*；保留被删除会员组/规则表的删除状态；不恢复历史无关业务表。
- **接口：** 沿用后台路由与权限体系；不将管理查询、complete/fail或密钥管理暴露到用户API。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 权限不足不可越权；重试需要有效状态和当前taskId；日志不得输出证件或模型密钥。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| ADMIN-001 | 菜单与角色权限：将新增运营能力纳入现有管理员权限；明确运营/客服/技术可见字段。 | P0 | BASE-001 | 管理员权限最小化；无需恢复已删除会员组/规则；敏感字段继续掩码。 | 0.5–1 |
| ADMIN-002 | 任务与查询排障：按assessmentId/taskId/requestId查进度/错误、人工重试/对账入口及操作审计。 | P1 | REPORT-004、DATA-004、ADMIN-001 | 可定位失败原因；重试仍走生命周期和幂等；不允许后台手改正式结果。 | 1–1.5 |
| ADMIN-003 | 模型额度与服务检查：DeepSeek配置、密钥状态、用户额度、调用消耗、队列/存储/短信状态检查。 | P1 | REPORT-001、CHAT-004、ADMIN-001 | 密钥不回显；配置失败可定位；本地消耗与渠道对账有入口。 | 1–1.5 |
| ADMIN-004 | 运营交接验收：真实产品、内容、课程、积分、消息、反馈及客服操作演练，形成操作说明。 | P1 | ADMIN-002、ADMIN-003、CONTENT-004、MSG-004、POINT-004、SUPPORT-004 | 运营可独立发布/下架/处理反馈及定位异常；业务字段无占位数据。 | 0.5–1 |

### 4.15 RELEASE｜联调、测试与发布

**目标：** 使一期全量范围在真实H5和实际服务渠道完成可复验发布。 **阶段：** M4。**剩余：** 7–11人日。

- **现状：** 此前基础测试与Web/Android编译通过，仅证明对应基础范围；未有全业务上线验收。
- **前端：** 普通桌面/手机/微信内H5、上传/键盘/回跳/弱网、深链接和版本更新回归。
- **后端：** 全链路、并发、权限、真实渠道、迁移和恢复；部署队列守护及错误/费用监控。
- **数据：** 使用脱敏测试数据与独立环境；新增迁移先预检/备份/演练；禁止用旧备份覆盖新业务数据。
- **接口：** 对本章所有一期API及渠道执行自动与手动验收，记录版本、环境和证据。 具体方法和字段见第5章；均按计划新增/改造处理。
- **异常与边界：** 未完成任一必做能力不能标首发完成；生产配置不允许模拟Token、固定报告和占位协议。

| 任务编号 | 任务与交付范围 | 优先级 | 前置任务/外部条件 | 验收条件 | 人日 |
| --- | --- | --- | --- | --- | ---: |
| RELEASE-001 | 核心与权限回归：完整个人/企业流程、跨用户攻击、金额边界、幂等、产品变更及并发用例。 | P0 | REPORT-004、LOGIN-004、AUTH-004、ADMIN-004 | 关键用例通过且有证据；无阻断或高危未解决缺陷；所有一期模块进入验收。 | 2–3 |
| RELEASE-002 | H5与第三方真实验收：普通手机/桌面/微信内浏览器，键盘/上传/回跳/断网/弱网及全部渠道成功失败验证。 | P0 | RELEASE-001 | 真实渠道与目标浏览器矩阵通过；不是仅编译通过或mock成功。 | 2–3 |
| RELEASE-003 | 部署与恢复演练：分环境配置、增量迁移预检、HTTPS、队列守护/告警、备份恢复、发布回滚手册。 | P0 | RELEASE-001、ADMIN-003、EXT-DEPLOY | 干净测试环境可部署；有数据环境升级可恢复；不重跑旧空表限定迁移。 | 1.5–2.5 |
| RELEASE-004 | 首发验收与发布记录：核对范围/外部依赖/验收证据，正式发布检查，发布后冒烟及回退条件。 | P0 | RELEASE-002、RELEASE-003 | 所有一期必做项已验收；生产无demo数据/占位协议/模拟Token；记录实际版本和时间。 | 1.5–2.5 |


## 5. 目标 API 契约

### 5.1 实现状态与通用规则

**本章为目标契约；已实现子集为密码登录、本人资料读取、退出、原密码改密，短信仅实现503未配置响应，其余仍待开发。** 已有FastAdmin通用控制器，现新增api/controller/v1/Base.php和Session.php；未列为已实现的前端同名方法仍是接口占位。AUTH可复用通用服务实现，其他模块需新增业务控制器及路由。旧接口保留兼容，新H5统一走版本前缀；管理后台保持原路由。

| 方法与路径（省略/api/v1） | 当前实现状态 | 本轮边界 |
| --- | --- | --- |
| POST /auth/password-login | 已实现并本地联调 | 既有手机号账户、密码验证、旧散列升级、Redis会话；沿用账户失败次数限制，IP级频控待补 |
| 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，无短信发送或注册 |
| 其余本章接口 | 计划新增 | 当前未配置的v1路由返回JSON 404，不判业务成功 |

| 项目 | 约定 |
| --- | --- |
| API根地址 | 环境配置为https://业务域名/api/v1；前端服务函数只传后缀路径 |
| 鉴权 | Authorization: Bearer会话令牌；用户ID来自认证上下文；管理端继续使用管理员权限 |
| 请求体 | 普通写请求application/json；文件multipart/form-data；回调按供应商要求读取原始体后验签 |
| ID | API统一字符串；DB仍用原主键类型；客户端不对ID做数值运算 |
| 成功包装 | {code:1,msg:string,time:Unix秒,data:对象或数组}；HTTP 200/201/202与实际行为一致 |
| 失败包装 | 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 |
| 列表范围 | 公开列表只取已发布有效内容；用户列表查询始终带user_id |
| 金额与比例 | 元字符串两位小数；利率为百分数；月数整数；展示时通过统一金额服务换算 |
| 幂等 | 表格注明业务键；同键不同业务参数返回409；成功重复调用返回同一业务结果；前端显式重试复用原键 |
| 日志 | 可关联requestId/assessmentId/taskId；禁止输出令牌、密码、身份证、证件路径和模型密钥 |

写接口不采用“遇到任何超时自动重发”。只有明确具有幂等键或条件更新保障的操作可以安全重试；短信、授权交换和收费查询需确认服务端/供应商状态。

成功示例（模拟标识仅用于说明字段，不是实际测试数据）：

```json
{
  "code": 1,
  "msg": "评估已提交",
  "time": 1790000000,
  "data": {
    "assessmentId": "123",
    "taskId": "0123456789abcdef0123456789abcdef",
    "status": "processing",
    "stage": "queued"
  }
}
```

失败示例：

```json
{
  "code": 0,
  "msg": "请检查填写内容",
  "time": 1790000000,
  "data": {
    "errorCode": "VALIDATION_ERROR",
    "fieldErrors": {"monthlyIncome": "金额必须大于0，单位为元"},
    "requestId": "req_example_0001"
  }
}
```

统一错误至少覆盖：VALIDATION_ERROR、AUTH_REQUIRED、RESOURCE_NOT_FOUND、STATE_CONFLICT、REVISION_CONFLICT、IDEMPOTENCY_CONFLICT、CONSENT_REQUIRED、ATTACHMENT_FORBIDDEN、RATE_LIMITED、QUOTA_EXCEEDED、PROVIDER_UNAVAILABLE、PROVIDER_RESULT_INVALID。面向用户的message使用中文；内部异常堆栈不直接返回。

### 5.2 主要数据类型

| 类型 | 字段与约束 |
| --- | --- |
| 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 |
| 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定稿 |
| ProductSnapshot | 产品ID/名称/版本、额度元字符串、期限月、年化百分数及必要准入说明；不可用当前产品字段覆盖 |
| Report | resultVersion:int、ruleVersion:string、assessmentId、generatedAt、modelCode、overallScore:number或null、dimensions数组、summary、suggestions、dataGaps、sourceRefs |
| 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；模型用量按权限返回摘要 |
| Article/Lesson | id、title、summary、imageUrl、category、publishedAt、version；课程chapters包含稳定chapterId、title、body |
| Message | id、type、title、content、isRead、readAt、createdAt、target:{type,id}或null |
| 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。

### 5.3 基础、账户与第三方登录接口

以下表格均省略 /api/v1 前缀。公开表示可匿名，其他接口须登录，回调须通过指定渠道校验。

| 方法与路径 | 权限 | 入参 | data响应 | 错误/幂等要点 |
| --- | --- | --- | --- | --- |
| GET /home | 公开，登录后附本人摘要 | 无 | banners、recommendations、assessmentSummary、unreadCount | 未登录的个人字段null；内部聚合失败不伪造数据 |
| GET /dictionaries | 公开 | version可选 | 字典版本、地区、枚举和表单选项 | 支持版本缓存；不能读取已删除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 | 限流；旧密码登录遵循原验证，成功后升级散列 |
| POST /auth/logout | 登录 | 无 | 空对象 | 撤销当前Token；成功或已401清本机会话，网络失败保留并提示重试 |
| GET /account/profile | 登录 | 无 | Profile | 只能当前账户 |
| PUT /account/profile | 登录 | nickname、avatarId可选 | Profile | 头像需归属当前用户；不再传任意data URL直接落资料字段 |
| POST /account/avatar | 登录 | file | attachmentId、avatarUrl | 仅支持白名单图片，按现有500KB约束起步并服务端复核 |
| POST /account/security/sms-code | 登录 | purpose:password/phone-current/phone-new、newPhone可选、requestId | challengeId、retryAfterSeconds | 当前手机号从账户取；新号码验证绑定当前用户与目标号码 |
| PUT /account/password | 登录 | verification:password/sms、oldPassword或challengeId+code、newPassword | reLoginRequired:true | 新密码8–32位可打印ASCII、含字母和数字、无空格；撤销全部Token |
| PUT /account/phone | 登录 | newPhone、currentChallengeId/currentCode、newChallengeId/newCode | reLoginRequired:true | 两组挑战同事务核销；唯一约束冲突409；不能仅验新号码 |
| GET /auth/wechat/authorize | 公开 | scene、returnPath白名单路径 | authorizeUrl、flowId | state服务端生成绑定流程；禁止开放跳转 |
| GET /auth/wechat/callback | 渠道回调 | code、state | 受控重定向至前端的一次性ticket | 核销state；不把Token放URL |
| POST /auth/wechat/exchange | 公开 | flowId、ticket | Session或bindingRequired+bindingTicket | ticket一次性使用，过期拒绝 |
| POST /auth/oneclick/init | 公开 | scene、requestId | flowId、expiresAt、必要的短期SDK初始化配置 | 独立生成并绑定当前浏览器流程，不复用微信flowId；不返回渠道私钥；同键复用未过期流程 |
| POST /auth/oneclick | 公开 | flowId、providerCredential | Session或bindingRequired+bindingTicket | 验证独立流程未过期并核销；服务端向供应商验证号码，不接受自报手机号；重复交换不得创建多个绑定 |
| POST /auth/bind-phone | 公开短期绑定凭证 | bindingTicket、phone、challengeId、code | Session | 验证bind-phone用途及凭证/手机号绑定，同事务核销；现有账户必须证明所有权，冲突禁止自动合并 |

### 5.4 资料、评估、查询与报告接口

| 方法与路径 | 权限 | 入参 | data响应 | 错误/幂等要点 |
| --- | --- | --- | --- | --- |
| POST /documents | 登录 | file、type、requestId | Document | 用户+requestId复用已成功附件；MIME/大小/内容/用途校验 |
| GET /documents/:id | 所有者 | 无 | Document及短期访问凭证或鉴权文件响应 | 所有者检查；凭证过期；不提供公开证件URL |
| DELETE /documents/:id | 所有者 | 无 | 删除状态 | 重复删除幂等；已被冻结评估引用的资料按留存规则处理 |
| GET /agreements/:code | 公开 | version可选 | code、version、title、content、effectiveAt | 请求指定版本必须得到同一正文 |
| 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可创建新尝试；同重试键返回同一尝试；不覆盖输入 |
| 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 /products | 公开 | type/regionCode可选、page/pageSize | Product分页 | 仅当前有效上架产品；不返回用户分数 |
| GET /products/:id | 公开 | 无 | Product | 下架/过期返回不可用语义；历史快照从本人匹配接口读取 |

评估主流程由服务端任务编排：提交后检查授权 → 获取选定的外部结果 → 冻结查询引用 → 规则匹配 → DeepSeek解释 → 原子保存正式结果。未选择可选外部授权时使用自填资料并标记来源；已选择查询但失败时是否允许降级到自填，需要DEC-QUERY形成明确规则。该规则未定稿前，相应错误按失败处理，不静默忽略。

分析页建议2秒起轮询，逐步退避到5秒，离开页面停止前端轮询但不取消服务端任务；重新进入按assessmentId恢复。供应商超时和任务租约由配置控制并在REPORT-002用实际接口时限确定，不按前端10秒请求超时推断AI执行失败。

### 5.5 助手、内容、消息、积分与客服接口

| 方法与路径 | 权限 | 入参 | data响应 | 错误/幂等要点 |
| --- | --- | --- | --- | --- |
| POST /assistant/chats | 登录 | title可选、contextAssessmentId可选、requestId | Chat | 创建键幂等；引用评估须本人；scene由服务端固定 |
| GET /assistant/chats | 登录 | page/pageSize | Chat分页 | 当前用户普通会话 |
| GET /assistant/chats/:id/messages | 所有者 | beforeSequence可选、pageSize | items、nextBeforeSequence | 序号稳定；不泄露内部system提示词和密钥 |
| POST /assistant/chats/:id/messages | 所有者 | message:string、requestId | userMessageId、assistantMessageId、status:pending | HTTP202；会话+请求+角色唯一；文本长度限制在CHAT-001冻结 |
| GET /assistant/messages/:id | 所有者 | 无 | ChatMessage | 用于异步回复轮询 |
| POST /assistant/messages/:id/retry | 所有者 | requestId | assistantMessageId、status | 仅失败回复；保留历史尝试信息，成功消息不重复调用模型 |
| GET /content/articles | 公开 | category、page/pageSize | Article分页 | 仅已发布；分类白名单 |
| GET /content/articles/:id | 公开 | 无 | Article及正文 | 下架/不存在返回404 |
| GET /content/lessons | 公开 | category、page/pageSize | Lesson分页 | 图文课程 |
| GET /content/lessons/:id | 公开 | 无 | Lesson及chapters | 稳定章节ID |
| GET /content/lessons/:id/progress | 登录 | 无 | completedChapterIds、lessonVersion | 只当前用户 |
| PUT /content/lessons/:id/progress | 登录 | chapterId、lessonVersion、completed:true | 最新进度 | 重复完成幂等；不存在章节拒绝 |
| GET /content/search | 公开 | keyword、type:all/news/lesson、page/pageSize | items及分页 | 仅已发布；多词AND沿用现有体验；长度/频率限制 |
| GET /help/faqs | 公开 | category可选 | items:{id,category,question,answer}[] | 后台可维护，实际行为变更时同步文案 |
| GET /messages | 登录 | type、page/pageSize | Message分页 | 当前用户；排序稳定 |
| GET /messages/unread-count | 登录 | 无 | count:int | 与列表读状态一致 |
| POST /messages/:id/read | 所有者 | 无 | Message | 幂等，不重复改首次readAt |
| POST /messages/read-all | 登录 | upToId | affected、unreadCount | 仅更新水位及之前消息，防误读并发新增通知 |
| GET /points | 登录 | 无 | balance:int、signedToday、ruleVersion | 服务端账本为准 |
| GET /points/ledger | 登录 | page/pageSize | PointsLedger分页 | 只本人 |
| POST /points/check-in | 登录 | requestId | delta、balance、signedDate | 唯一业务键=用户+签到日期；服务端时区 |
| GET /points/tasks | 登录 | 无 | 任务规则、状态、奖励条件 | 状态来源真实业务事件 |
| GET /invitations | 登录 | 无 | personalCode、shareUrl、统计摘要 | 真实唯一邀请码，隐去受邀人敏感信息 |
| POST /invitations/bind | 登录 | inviteCode、requestId | bindStatus | 首次绑定、禁止自邀、已有关系不覆盖 |
| POST /feedback | 登录 | content、attachmentIds、requestId | Feedback | 非空且当前表内容最长255字符；附件归属；幂等 |
| GET /feedback | 登录 | page/pageSize | Feedback分页 | 只本人 |
| GET /feedback/:id | 所有者 | 无 | Feedback | 处理回复可读 |
| POST /support/session | 登录 | scene、returnPath可选 | 客服渠道、短期会话配置、online/offline状态 | 服务端身份签名；不下发供应商私钥；会话复用策略按供应商核验 |

### 5.6 对现有占位接口的迁移

- 原POST /assessments“整包提交”拆成创建/更新草稿与submit；确认页必须保存返回assessmentId。
- 原GET /matches替换为GET /assessments/:id/matches，避免读取不明确的“最近结果”。
- 原POST /assistant/messages的message→reply同步接口，替换为会话消息异步接口，避免前端超时导致重复请求模型。
- 原FinanceProduct同时承载公共信息和score的结构，拆成Product与MatchResult；旧amount万元兼容仅在过渡适配器，正式API始终返回amountMinYuan/amountMaxYuan。
- 账户修改资料从data URL改为上传得到avatarId；安全短信增加challengeId并绑定用途/目标，旧客户端占位字段同步修改。
- news/lesson/search必须同时替换数据源，防止搜索返回真实ID但详情仍查本机数组。
- 模拟与真实模式在开发环境显式区分；生产构建禁止缺配置时回退模拟。


## 6. 工时、里程碑与实施顺序

### 6.1 剩余工程量

| 模块 | 功能板块 | 阶段 | 剩余人日 |
| --- | --- | --- | ---: |
| BASE | 基础接口与环境 | M0 | 3–5 |
| AUTH | 账户与短信安全 | M1 | 5–8 |
| LOGIN | 微信与一键登录 | M1 | 5–10 |
| FILE | 资料与授权 | M1 | 4–7 |
| ASSESS | 评估与融资档案 | M2 | 5–8 |
| DATA | 外部征信或数据查询 | M2 | 6–12 |
| PRODUCT | 产品库与匹配规则 | M2 | 6–9 |
| REPORT | AI任务、报告与历史 | M2 | 8–12 |
| CHAT | AI助手 | M3 | 4–7 |
| CONTENT | 内容、课堂、搜索与FAQ | M3 | 4–6 |
| MSG | 消息中心 | M3 | 2–4 |
| POINT | 积分、任务与邀请 | M3 | 4–7 |
| SUPPORT | 反馈与人工客服 | M3 | 3–6 |
| ADMIN | 后台运营与排障 | M3 | 3–5 |
| RELEASE | 联调、测试与发布 | M4 | 7–11 |
| 合计 | 15模块、60任务 | M0–M4 | **69–117** |

每周按5个工程工作日计算，约14–24个工作周。AI辅助效率已经纳入估算，不再乘额外提速系数。该区间不是承诺发布日期，未包括供应商商务、资质、短信模板、域名、审核和运营资料等待。

每类渠道暂按一个服务商、一次首发H5方案计。若个人/企业数据需要多个供应商、更多独立授权或首次方案不支持目标浏览器，必须据实调整DATA/LOGIN相关任务与总量。模块工时包含自身开发者测试，RELEASE为跨模块真实联调和发布演练；历史数据库优化不重复计量。

### 6.2 阶段门槛

| 阶段 | 交付目标 | 工程人日 | 累计人日 | 退出门槛 |
| --- | --- | ---: | ---: | --- |
| M0 契约与接入准备 | BASE；同时启动各供应商与业务规则准备 | 3–5 | 3–5 | 统一契约可解析，环境与用户隔离方案可联调；依赖清单有责任人 |
| M1 账户与资料 | AUTH、LOGIN、FILE | 14–25 | 17–30 | 真实账户、支持场景的第三方登录、私有资料和正式授权通过 |
| M2 融资核心 | ASSESS、DATA、PRODUCT、REPORT | 25–41 | 42–71 | 个人/企业真实评估→查询→匹配→DeepSeek报告→历史各完成闭环 |
| M3 全部页面业务化 | CHAT、CONTENT、MSG、POINT、SUPPORT、ADMIN | 20–35 | 62–106 | 所有功能有真实数据与后台操作，助手/人工客服可用 |
| M4 H5首发 | RELEASE | 7–11 | 69–117 | 所有一期必做项验收、恢复演练、发布后冒烟与证据完整 |

M0启动其他模块的渠道申请不重复计算其工程工时；设计和等待可提前，实施工时仍记对应任务。单人不能按多人并行把独立模块时长直接减半。受阻时优先穿插CONTENT/产品规则/后台等具备前置条件的工作，不把一期项目降为二期。

```mermaid
flowchart LR
    A["M0 接口、环境与渠道准备"] --> B["M1 账户、身份与私有资料"]
    B --> C["M2 评估与授权查询"]
    P["产品资料与版本化规则"] --> D["匹配与 DeepSeek 报告"]
    C --> D
    D --> E["M3 助手、消息与运营"]
    F["内容、课堂、积分、客服"] --> E
    E --> G["M4 H5 全量验收"]
    T["所有第三方真实接入证据"] --> G
```

后续多端单独开里程碑：微信小程序的AppID/合法域名/包体/平台授权与审核，Android签名与真机上传/登录能力，iOS的macOS/Xcode/签名与审核。继续保留跨端编译回归，但不把Windows生成iOS源码视为真机或IPA验证。

## 7. 外部依赖与必须定稿的规则

下表只记录准备要求，不收集密钥。具体状态、责任人、预计解除时间和证据维护在[开发进度](开发进度.md)第5章。未选供应商不影响文档交付，但会阻塞真实接入及全量上线。

| 编号 | 当前状态 | 需要取得的条件 | 对应任务 |
| --- | --- | --- | --- |
| EXT-SMS | 待选型 | 服务商、签名模板、用途、测试号码、频控及发送回执 | AUTH-001 |
| EXT-WX | 待确认产品和平台资源 | 公众号/开放平台类型、适用H5场景、回调域名、授权和身份字段能力 | LOGIN-001、LOGIN-002 |
| EXT-ONE | 待选型 | H5号码认证产品、运营商/网络/浏览器矩阵、SDK与服务端校验、测试环境 | LOGIN-001、LOGIN-003 |
| EXT-STORAGE | 待选型 | 私有存储方案、访问控制、文件限制、备份与生命周期 | FILE-001 |
| EXT-DATA | 待选型 | 实际可开通数据产品、个人/企业接口、授权要求、样例、回调/查询和费用状态 | DATA-001 |
| EXT-AI | DeepSeek已选定，接入待核验 | 具体模型标识、测试权限、额度、超时/结构化输出支持及实际用量字段；实施时核对官方接口文档 | REPORT-001 |
| EXT-CS | 待选型 | H5接入、访客身份、坐席、在线/离线、历史与附件能力、工作时间 | SUPPORT-001、SUPPORT-003 |
| EXT-DEPLOY | 待确认 | 测试/生产资源、域名/HTTPS、Redis/worker守护、备份与监控 | RELEASE-003 |

| 编号 | 需确认内容 | 定稿任务及产物 |
| --- | --- | --- |
| DEC-PRIVACY | 资料用途、可选项、正式协议正文与版本、保留期限、撤销后处置、第三方必要字段 | FILE-001、FILE-003：协议和数据生命周期清单 |
| DEC-QUERY | 首发数据查询种类与个人/企业范围、拒绝/失败后的自填路径、重查与费用归属 | DATA-001：页面授权到数据产品映射及失败策略 |
| DEC-MATCH | 硬准入、未知处理、分数/等级/排序、报告维度、同分规则及人工样例 | PRODUCT-001、REPORT-003：版本化规则与金标准样例 |
| DEC-PRODUCT | 首发真实产品及金额/期限/利率/地区/准入依据、有效期和运营责任人 | PRODUCT-003：可发布产品资料与运营确认记录 |
| DEC-AI | DeepSeek具体模型、单用户/评估额度、超时重试、成本预算与超额策略 | REPORT-001：配置及额度规则 |
| DEC-POINT | 签到/资料/邀请奖励数额、次数、可信达成条件、权益/有效期 | POINT-001：活动规则及正反样例 |

技术默认项：每类服务商首期一个；站内消息优先；课堂为图文；助手先异步完整回复；时间业务口径Asia/Shanghai；列表pageSize=20、上限50。业务分数、奖励数额、查询费用、模型名和数据保留期限不擅自定为上线规则。

DeepSeek只选定服务商，不能据此宣布模型可用或已通过真实调用。一键登录也不能依据“原生App有SDK”推断H5全场景可用；若渠道不支持已承诺场景，先形成能力差异和影响，再记录用户的范围决定，不能静默删项。

## 8. 验证、发布与文档维护

### 8.1 测试分层与验收条件

1. **纯逻辑/服务测试**：金额边界、字段映射、规则执行、版本快照、密码兼容、授权状态和评分人工样例。
2. **数据库/API集成**：两个以上账户进行越权读写；并发提交/重试/积分；鉴权、业务错误、附件归属、事务和幂等。
3. **故障与渠道测试**：短信失败、OAuth取消/重放、查询拒绝/超时/回调伪造、DeepSeek无效输出/配额不足、队列漏投和worker中断、客服离线。
4. **H5端到端**：个人和企业各完成真实流程；刷新恢复、历史报告、产品更新、助手、课程跨设备、消息、积分邀请、反馈与人工坐席。
5. **发布恢复**：干净环境初始化、有数据增量升级、备份恢复、密钥恢复、队列守护、回退后数据保全及发布冒烟。

必须覆盖的具体结果：

| 场景 | 必须满足的结果 | 归属 |
| --- | --- | --- |
| 金额换算 | 0.800001万元=8000.01元；最大值、超限、负数、空值、0和精度均校验；不重复换算 | ASSESS-004、PRODUCT-004 |
| 身份与越权 | 用户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 |
| 私有资料 | 无登录/跨用户无法读取，撤销后不新增查询；授权版本可追溯 | FILE-004、DATA-004 |
| 课程进度 | 章节重排不串记录，重复完成幂等，换设备一致 | CONTENT-003 |
| 积分并发 | 同日并发只奖励一次，流水与余额一致；复制/分享不视为实际邀请成功 | POINT-004 |
| 消息一致 | 重复事件只一条通知，全部已读不吞之后的新通知 | MSG-004 |
| 第三方登录/客服 | 真实支持场景成功与失败都验证；真人接待/离线留言有证据 | LOGIN-004、SUPPORT-004 |
| 上线完整性 | 25页均有真实数据来源；无模拟Token、固定报告或占位协议；必做渠道全验收 | RELEASE-004 |

完整执行台账见[开发进度](开发进度.md)第6章。每条实际记录需包含日期、环境/构建版本、前置测试数据、操作、预期/实际、脱敏证据、缺陷和验收人。文档中的“待执行”不能自动转为通过。

### 8.2 已有验证与后续命令

前序任务记录：2026-09-22，41项基础测试通过、Web与Android本地编译通过、金额相关浏览器检查通过。它们不覆盖本章真实业务；初始文档交付未重跑；实施后的验证另见进度文档第0章。测试脚本存在可复核，前序浏览器/编译独立日志未归档，不能补写不存在的证据路径。

后续业务实施可使用下列现有命令。PHP基础测试会操作数据库并在外层事务回滚，应在核对后的测试环境执行；当前文档任务不执行它。HBuilderX命令是运行/本地编译，不是正式发布。

```powershell
# 后端基础回归：在后端目录，确认使用测试数据库后执行
Set-Location 'D:\AAdesk\202609\airz'
& 'D:\Develop\phpstudy_pro\Extensions\php\php7.4.3nts\php.exe' tests/finance.php

# 前端：在HBuilderX中运行及本地编译
Set-Location 'D:\WorkSpace\cyun\ai融资'
& 'D:\Develop\HBuilderX\cli.exe' open
& 'D:\Develop\HBuilderX\cli.exe' launch web --project 'D:\WorkSpace\cyun\ai融资' --compile false --continue-on-error false
& 'D:\Develop\HBuilderX\cli.exe' launch app-android --project 'D:\WorkSpace\cyun\ai融资' --compile true --continue-on-error false
```

目标H5矩阵包括桌面Chrome/Edge、Android主流浏览器、iOS Safari及微信内置浏览器。具体版本/设备在RELEASE-002记录；iOS Safari的H5验证与iOS原生App构建是两件事。共享UTS修改后保留Android编译回归，正式App发布另计。

### 8.3 部署、迁移与恢复

- 部署材料需说明前端静态资源/路由回退、后端入口、HTTPS/CORS、环境变量、私有文件存储和数据库版本。
- Redis与think-queue配置存在不代表worker已运行；配置守护、重启、积压/失败/超时告警及失联任务补偿。
- 新环境初始化需依赖顺序、管理员/配置等必要种子数据；现有schema.sql是结构快照，不能当完整安装包直接导入。
- 增量迁移记录前置版本、数据预检、备份、回填、约束验证和失败恢复；已有业务数据环境禁止盲目重跑旧空表限定迁移。
- 回滚需保留上线后新增业务数据；数据库DDL不能当作整批事务可回滚。密文恢复依赖对应加密密钥，备份恢复演练须包含密钥恢复且不将其写入文档。
- 监控至少记录任务积压/耗时/失败、短信和查询失败、DeepSeek消耗/预算、文件访问拒绝和接口错误，并通过业务ID关联排障。
- 发布前所有一期必做任务有验收证据；上线后完成登录、个人/企业评估、历史、内容及客服冒烟。实际发布是后续RELEASE任务；当前仅在本地实施与验证，未发布。

### 8.4 两份文档的维护方式

开发文档维护“要做什么、接口和验收是什么”；进度文档维护“做到哪里、依据是什么、谁来处理阻塞”。任务新增/拆分保留旧编号和变更理由，工时与依赖在两份文档同步。维护者每次任务结束更新状态、实际证据、日期和下一步。

初始文档交付验收清单：25页覆盖、60任务编号和字段一致、所有内部依赖存在且无环、模块与总工时相符、互链和源码链接有效、UTF-8无BOM、无凭据/个人数据。初次交付仅新增两份Markdown；后续代码与本地数据库变更见第0节及进度台账。文档完成不计为业务任务完成。