lovife
9e78e1d239
起点：F-1/F-31/F-50/F-52 是同一个形状 —— 每处单看都对，编译/lint/review 全不红，只有从入口走一遍才暴露。先把这一类固化成命令，再按输出逐条修。
新增 scripts/check-wiring.py：权限码有没有地方校验、错误码有没有被引用、站内信模板有没有发送点、bizType 有没有被用过、菜单键 ↔ PC 端 XtMenu 双向核对。有意不接线的写进脚本上方例外表（带理由）。进 verify-all（第 5 项）与 CI 的 check 阶段。检查器自身修了三次假阳性：只数 @RequirePerm 漏掉服务层校验、按标识符数引用被同名常量骗过、注释里的提及被当成接线（改为先去 Java 注释再数）。
F-101 自动通知改走可配置模板（FR-1002 原来只兑现了手工发送那一半）：新增 NotifyTextResolver（单向依赖避开循环注入），库里改过的 > 内置；模板停用 = 这类通知不发且如实回 notifySent=false。F-102 加入申请三处通知（提交→审批人、通过/驳回→学生）。F-103 导出完成/失败通知发起人，正文不放签名 URL（模板里原本写着 {下载链接}，一并改掉）。F-104 自动催报从来没发出过任何一条（end_time = date::date 与库里的 23:59:59 永不相等，测试夹具用 SQL 摆的日期型恰好能匹配）+ 补 FR-1003 的「截止当日」。F-105 驳回达上限通知管理员（契约与注释都写了，代码只有一行日志）。F-106 字典/通知记录两个菜单没有任何角色持有（手册还写着去那里办）。F-107 6 个权限码挂到自己的接口。F-109 Map.of 不接受 null → 通知被吞成一行 warn。F-110/F-111 测试自身的两个坑。
验证：新增 e2e-m5-notify-wiring.py 43 条（改模板→真驳回→断言学生收到改过的那句、停用→一条不发、申请/审批/导出/催报/升级/菜单/权限各一节）；verify-all --with-e2e → 9 项全过 0 跳过，38 个脚本 / 1620 条断言 / 0 失败。
165 lines
10 KiB
Markdown
165 lines
10 KiB
Markdown
# 需求追溯矩阵（自审报告）
|
||
|
||
> 用途：把 PRD 的每条需求对上「**原型 / 库表 / 接口 / 验收**」四个交付面，找出**说了没做**和**做了没说**。
|
||
> 生成日期：2026-09-28
|
||
> 审计范围：**125 条 FR**（92 P0 / 30 P1 / 3 P2）+ **21 条 VAL 校验规则** + **121 个接口** + **20 张表**
|
||
> 结论：**主流程全覆盖。第三节的 10 个接口缺口已于 P3 补齐（共新增 21 个接口）；配置类页面缺口见 3.2**
|
||
|
||
---
|
||
|
||
## 一、总览
|
||
|
||
| 模块 | 条数 | P0 | 库表 | 接口 | 原型 | 判定 |
|
||
|---|:--:|:--:|:--:|:--:|:--:|:--:|
|
||
| FR-100 租户与组织 | 5 | 5 | ✅ | ✅ | ❌ | ⚠️ 缺平台运营端原型 |
|
||
| FR-200 账号与角色 | 6 | 5 | ✅ | ✅ | ❌ | ⚠️ 缺登录页与用户管理页 |
|
||
| FR-300 收集任务 | 12 | 9 | ✅ | ✅ | ⚠️ | ✅ 暂停接口已补（P3） |
|
||
| FR-400 动态表单 | 8 | 6 | ✅ | ✅ | ❌ | ⚠️ **缺表单设计器原型** |
|
||
| FR-500 名单管理 | 24 | 21 | ✅ | ✅ | ✅ | ✅ **全覆盖**（含客户确认新增的 FR-509 系列 10 条） |
|
||
| FR-600 材料与规则 | 23 | 18 | ✅ | ✅ | ⚠️ | ✅ 识别结果已并入审核详情（P3） |
|
||
| FR-800 审核工作台 | 10 | 7 | ✅ | ✅ | ✅ | ✅ 撤回接口已补（P3） |
|
||
| FR-900 汇总导出 | 10 | 8 | ✅ | ✅ | ✅ | ✅ **全覆盖** |
|
||
| FR-1000 通知催报 | 6 | 4 | ✅ | ✅ | ⚠️ | ✅ 消息中心与额度已补（P3）；⚠️ **FR-1002 / FR-1003 在 2026-10-08 才真正兑现** —— 模板原先只对手工发送生效、自动催报因日期比较写错**一条都没发过**（见《08》F-101 / F-104） |
|
||
| FR-1100 数据看板 | 5 | 2 | ✅ | ✅ | ✅ | ✅ **全覆盖** |
|
||
| FR-1200 系统管理 | 6 | 5 | ⚠️ | ✅ | ❌ | ⚠️ 接口已补（P3），原型仍缺 |
|
||
| FR-1300 SaaS 计费 | 4 | 2 | ⚠️ | ⚠️ | ❌ | ⚠️ 缺平台运营端 |
|
||
| FR-1400 历史整理器 | 6 | 0 | ✅ | ❌ | ❌ | ❌ **三面全缺**（P1，本轮未做） |
|
||
| **FR-700 校验引擎** | — | — | ✅ | ✅ | ✅ | ✅ 以 VAL-01~21 实现，三端均有体现 |
|
||
|
||
**图例**：✅ 完整覆盖 ⚠️ 部分覆盖 ❌ 未覆盖
|
||
|
||
---
|
||
|
||
## 二、覆盖亮点（这些是逐条核对过的）
|
||
|
||
| 能力 | 库表 | 接口 | 原型 | 备注 |
|
||
|---|:--:|:--:|:--:|---|
|
||
| **名单即预填报名表（18 业务列）** | ✅ | ✅ | ✅ | 已在 PG 16 实测；管理端③可视化呈现 |
|
||
| **门禁核验（含限流防枚举）** | ✅ | ✅ | ✅ | 学生端①②③；统一失败提示已实现 |
|
||
| **命名规范化引擎** | ✅ | ✅ | ✅ | 管理端②**试跑闸门**；学生端⑦结果卡 |
|
||
| **压缩引擎（五档 + 内存保护）** | ✅ | ✅ | ✅ | 实测 28/28 达标；管理端⑦报压缩率 |
|
||
| **材料识别（四层递进）** | ✅ | ✅ | ✅ | 学生端⑧；识别结果已并入审核详情响应 |
|
||
| **批量通过只带绿色项** | ✅ | ✅ | ✅ | 班主任端④ + ⑨（滑动层灰化） |
|
||
| **导出前置检查（禁止带问题打包）** | ✅ | ✅ | ✅ | 管理端⑦**禁用导出按钮** |
|
||
| **报考范围聚合与体检** | ✅ | ✅ | ✅ | 管理端④；plan-scope 接口已补 |
|
||
| **汇总 Excel 与目录树** | ✅ | ✅ | ✅ | 管理端⑦目录树预览 |
|
||
|
||
---
|
||
|
||
## 三、发现的缺口
|
||
|
||
### 3.1 接口缺口（**已在 P3 全部补齐**，共新增 21 个）
|
||
|
||
> 这些是"原型/PRD 里承诺了，但接口表里没有"的。放在 P3 接口设计里一并补齐。
|
||
|
||
| # | 缺口 | 对应需求 | 影响 | 建议接口 |
|
||
|:--:|---|---|---|---|
|
||
| I1 | **报考范围读取与确认** | FR-307~311 | 管理端④整屏无数据来源 | `GET/PUT /api/v1/tasks/{id}/plan-scope` |
|
||
| I2 | **历史数据整理器** | FR-1401~1406 | §5.14 六条需求**完全无接口** | `POST /api/v1/cleanup/jobs` 等 5 个 |
|
||
| I3 | **字典管理** | FR-1201 | 学历/等级/补考科目等下拉项无法维护 | `GET/POST/PUT /api/v1/dicts` |
|
||
| I4 | **操作日志** | FR-1202 | 审计留痕无法查询 | `GET /api/v1/logs/operations` |
|
||
| I5 | **登录日志** | FR-1203 | 同上 | `GET /api/v1/logs/logins` |
|
||
| I6 | **消息中心** | FR-1004~1005 | 学生端/教师端"消息"屏无数据来源 | `GET /api/v1/mp/messages`、`/mp/teacher/messages` |
|
||
| I7 | **订阅额度登记** | R12 对策 | 功能逻辑卷写 `/mp/subscribe`，**主 PRD 接口表漏登记** | `POST /api/v1/mp/subscribe` |
|
||
| I8 | **审核撤回** | FR-808、原型 | 原型承诺"终审前可撤回"，无接口 | `POST /api/v1/audit/submissions/{id}/revoke` |
|
||
| I9 | **任务暂停/恢复** | FR-301 | FR 要求"发布、**暂停**、截止、归档"，只有 publish/close/archive | `POST /api/v1/tasks/{id}/pause`、`/resume` |
|
||
| I10 | **材料识别结果读取** | FR-614d | 审核辅助要显示"系统判定：身份证 92%"，无处取 | 并入 `GET /api/v1/audit/submissions/{id}` 响应 |
|
||
|
||
> **合计 10 项，已在 P3 全部补齐**：I10 并入审核详情响应，其余新增 20 个接口（含 1 项登记遗漏 `/mp/files/{fileId}/process`）
|
||
|
||
### 3.2 原型缺口（管理端 10 个页面；**其中 3 个已在 P2.5 补齐**）
|
||
|
||
> 本轮原型聚焦"**高频主流程 + 设计难点**"，配置类页面未出。这不是遗漏，是优先级取舍，但需要明确记录，避免开发以为"不用做"。
|
||
|
||
| # | 页面 | 对应需求 | 复杂度 | 建议 |
|
||
|:--:|---|---|:--:|---|
|
||
| P1 | **表单设计器** | FR-401~408 | 高 | ⚠️ **必须补**——拖拽式字段编排是 P0，且交互复杂，光靠文字描述开发必理解偏 |
|
||
| P2 | **材料规则配置**（命名模板编辑器） | FR-601~609 | 高 | ⚠️ **建议补**——管理端②只做了"试跑"，配置界面本身没画 |
|
||
| P3 | 历史数据整理器 | FR-1401~1406 | 中 | 建议补（差异化获客功能，客户演示时最吸睛） |
|
||
| P4 | 登录页 | FR-201 | 低 | 可略 |
|
||
| P5 | 组织与用户管理 | FR-103、203~206 | 中 | 可略（标准 CRUD） |
|
||
| P6 | 任务列表与详情 | FR-301~306 | 中 | 建议补简版（克隆、二维码、暂停） |
|
||
| P7 | 通知模板管理 | FR-1001~1002 | 低 | 可略 |
|
||
| P8 | 字典管理 | FR-1201 | 低 | 可略 |
|
||
| P9 | 操作日志查询 | FR-1202~1203 | 低 | 可略 |
|
||
| P10 | 平台运营端（租户/套餐/计费） | FR-101~102、1301~1304 | 中 | 建议二期做（一期客户是学校，不关心平台运营） |
|
||
|
||
### 3.3 需求条目本身的核查
|
||
|
||
> 审计过程中发现 4 个疑似问题，逐条核实后 **3 个是统计脚本的正则缺陷（不是文档缺陷）**，仅 1 个为真实待办。
|
||
|
||
| # | 疑似问题 | 核实结论 | 处理 |
|
||
|:--:|---|---|---|
|
||
| D1 | FR-614 主条目编号缺位 | ❌ **假警报**——FR-614 在 §5.6 存在（脚本未匹配**加粗编号**写法） | 无需处理 |
|
||
| D2 | FR-608 未出现在抽取结果 | ❌ **假警报**——同上，且其优先级格含补充说明文字 | 无需处理 |
|
||
| D3 | FR-1000 模块分级计数与条数不符 | ❌ **假警报**——1001~1004 为 P0、1005 为 P1、1006 为 P2，相加正确 | 无需处理 |
|
||
| **D4** | **「压缩质量抽检机制」在功能逻辑卷有详述，主 PRD 无独立 FR** | ✅ **真实**——PRD 仅在 §6.3 与验收标准中提及，未立为需求条目 | 🟡 **补 FR-616**：清晰度分级标记与抽检机制（P1） |
|
||
|
||
> **教训**：脚本审计前必须先验证脚本本身。本次若直接采信 D1~D3，会在文档里"修"三个不存在的问题，反而引入错误。
|
||
|
||
### 3.4 已闭环（无需处理）
|
||
|
||
| 项 | 状态 |
|
||
|---|---|
|
||
| 报考范围来自名单（不存在计划文件） | ✅ 已澄清并改设计 |
|
||
| DDL 在 PG 16 实测 | ✅ 零错误 |
|
||
| 压缩参数实测标定 | ✅ 300dpi/q85，28/28 达标 |
|
||
| 材料来源三通道（无拍照） | ✅ 已实现并出原型 |
|
||
| 滑动交互规则 | ✅ 只右滑通过 |
|
||
|
||
---
|
||
|
||
## 四、结论与行动
|
||
|
||
### 覆盖度小结
|
||
|
||
```
|
||
主流程（填报→审核→导出） ████████████████████ 100%
|
||
规则引擎（命名/压缩/识别） ████████████████████ 100%
|
||
配置类页面 ██████░░░░░░░░░░░░░░ 30%
|
||
平台运营 ░░░░░░░░░░░░░░░░░░░░ 0%
|
||
历史整理器 ░░░░░░░░░░░░░░░░░░░░ 0%（仅库表）
|
||
```
|
||
|
||
### 必须行动的 3 项
|
||
|
||
| 优先级 | 行动 | 归属 |
|
||
|:--:|---|---|
|
||
| ✅ 已完成 | ~~补 10 个缺失接口（3.1）~~ | → **P3 已完成（新增 21 个）** |
|
||
| ✅ 已完成 | ~~补**表单设计器**原型（3.2 P1）~~ | → **P2.5 已完成** |
|
||
| ✅ 已完成 | ~~补**材料规则配置**原型（3.2 P2）~~ | → **P2.5 已完成** |
|
||
| ✅ 已完成 | ~~补 **FR-616**「清晰度分级标记与抽检机制」~~ 及 **VAL-18~20** 三条校验规则 | → 已补入 PRD |
|
||
|
||
### 对计划的调整
|
||
|
||
发现了一个原计划未覆盖的缺口，**追加为 P2.5**：
|
||
|
||
| # | 任务 | 产出 | 理由 |
|
||
|---|---|---|---|
|
||
| **P2.5** | **管理端补充原型**：表单设计器 + 材料规则配置 + 整理器 | 补充到 `admin-web.html` | 追溯矩阵发现的缺口，三者都是**复杂交互、不画会理解偏**的页面 |
|
||
|
||
---
|
||
|
||
## 附录 · 完整需求索引（115 条）
|
||
|
||
| 模块 | 编号范围 | 条数 | 备注 |
|
||
|---|---|:--:|---|
|
||
| FR-100 | FR-101 ~ 105 | 5 | 全 P0 |
|
||
| FR-200 | FR-201 ~ 206 | 6 | 含 FR-202 小程序登录 |
|
||
| FR-300 | FR-301 ~ 312 | 12 | 含 FR-307~311 报考范围 |
|
||
| FR-400 | FR-401 ~ 408 | 8 | 全为表单引擎 |
|
||
| FR-500 | FR-501 ~ 509 | **24** | 含 502a/b、504a~d、**509a~i（客户确认新增 10 条）** |
|
||
| FR-600 | FR-601 ~ 616 | 23 | 含 601a/b、614a~e（**编号连续，无跳号**） |
|
||
| FR-800 | FR-801 ~ 810 | 10 | 审核 |
|
||
| FR-900 | FR-901 ~ 910 | 10 | 导出 |
|
||
| FR-1000 | FR-1001 ~ 1006 | 6 | 通知 |
|
||
| FR-1100 | FR-1101 ~ 1105 | 5 | 看板 |
|
||
| FR-1200 | FR-1201 ~ 1206 | 6 | 系统管理 |
|
||
| FR-1300 | FR-1301 ~ 1304 | 4 | 计费 |
|
||
| FR-1400 | FR-1401 ~ 1406 | 6 | 整理器 |
|
||
| **合计** | | **125** | **92 P0 / 30 P1 / 3 P2** |
|
||
|
||
**校验规则**：VAL-01 ~ VAL-21（21 条，编号连续；18~20 为 P4 补充，**21 为客户确认后补充的归属校验**）
|
||
**接口**：**121 个已定义**（原 96 + 补齐 21 + 客户确认新增 5 − 客户要求移除 1，见 `03-接口设计.md`）
|
||
**库表**：**20 张**完整 DDL + 4 张"从略"标准表
|