docs(reports): add 2026-06-13 planning review artifacts

reports/PRODUCT_PLANNING_TECH_ALIGNMENT_REVIEW_2026-06-13.md

@@ -0,0 +1,795 @@
+# 高考志愿填报系统产品规划、技术规划与实施对齐评审报告
+
+**项目路径**: `/home/long/project/gaokao-volunteer-system`  
+**评审日期**: 2026-06-13  
+**评审对象**: 产品规划设计、业务场景、技术架构、实施计划、当前代码实现与工程门禁  
+**评审方法**: `code-analyzer` 静态分析 + 文档交叉核对 + 关键代码抽样 + 现有门禁证据复核  
+**本轮产物**:
+
+- 本报告: `reports/PRODUCT_PLANNING_TECH_ALIGNMENT_REVIEW_2026-06-13.md`
+- 静态分析输入: `reports/code-analysis-review-input-2026-06-13.md`
+
+---
+
+## 1. 执行摘要
+
+### 1.1 总体结论
+
+项目已经从早期的“高考志愿填报 Skill + 脚本工具”演进为一个较完整的**人工服务运营增强系统**：
+
+- 管理后台已成形。
+- 订单、用户、案例、统计、分享、渠道同步已具备代码实现。
+- AI 审核链路已补齐 `audit_service / checker_integration / crowd_detector / report_generator / audit_cli` 等主干模块。
+- CI 配置已加入运行依赖安装、覆盖率采集、整体覆盖率门槛和核心覆盖率脚本。
+- Docker Compose 本地部署路径已形成。
+
+但从“产品规划设计是否满足完整场景要求”的角度看，当前仍不能认定为完整的商业化 Web 产品。更准确的定位是：
+
+> **当前已基本满足场景 A：闲鱼/微信/学校等人工服务渠道的运营后台与交付增强；尚未满足场景 B：用户端 Web 自助下单、支付、资料填写、自动/人工处理、站内交付的完整闭环。**
+
+### 1.2 评审门禁结论
+
+**结论**: `CONDITIONAL_PASS / REQUEST_CHANGES`
+
+含义：
+
+- 对“人工服务运营后台 + AI 审核增强链路”目标：**条件通过**。
+- 对“PRD 与业务场景中定义的完整产品化系统”：**需要变更后再通过**。
+
+### 1.3 综合评分
+
+| 维度 | 评级 | 结论 |
+| --- | --- | --- |
+| 产品定位 | A- | 垂直领域定位清晰，差异化成立 |
+| 用户场景覆盖 | B- | 人工服务场景强，Web 自助场景缺失 |
+| 产品规划完整性 | B | 主线完整，但路线图状态未完全同步 |
+| 技术架构合理性 | B+ | Python/FastAPI/SQLite/LocalFS 对当前阶段务实 |
+| 技术规划与产品对齐 | B | 核心模块已对齐，但 Web/H5 接入层未落地 |
+| 实施计划可执行性 | B- | T1-T11 主线清楚，但时间表与当前状态冲突 |
+| 工程质量 | B | 测试/CI/覆盖率已有门槛，但本轮环境无法重跑 |
+| 数据与合规 | B- | 脱敏/加密/审计有实现，真实数据完整性仍需加强 |
+
+---
+
+## 2. 本轮证据
+
+### 2.1 代码静态分析
+
+本轮重新执行 `code-analyzer`，排除 `.git/.worktrees/__pycache__/.pytest_cache/.mypy_cache/.ruff_cache/.tmp/.benchmarks` 后得到：
+
+| 指标 | 数值 |
+| --- | ---: |
+| 核心文件数 | 128 |
+| 总行数 | 28,852 |
+| 架构识别 | MVC / 分层模块 |
+| 数据模型 / DTO | 147 |
+| 业务规则 | 239 |
+| 外部依赖 | 72 |
+
+相较 2026-06-12 的静态分析结果，项目规模和模块完整度明显提升。
+
+### 2.2 当前工作区状态
+
+本轮检查 `git status --short` 时，除本轮新生成的静态分析报告外，工作区没有发现业务代码脏改：
+
+```text
+?? reports/code-analysis-review-input-2026-06-13.md
+```
+
+本报告写入后会新增：
+
+```text
+?? reports/PRODUCT_PLANNING_TECH_ALIGNMENT_REVIEW_2026-06-13.md
+```
+
+### 2.3 本轮门禁复核限制
+
+本轮在当前系统 Python 环境中尝试执行：
+
+```bash
+python3 -m pytest -q
+python3 -m ruff check . --exclude .worktrees
+python3 -m mypy .
+```
+
+结果均无法执行，原因是当前系统 Python 缺少对应模块：
+
+```text
+/usr/bin/python3: No module named pytest
+/usr/bin/python3: No module named ruff
+/usr/bin/python3: No module named mypy
+```
+
+因此，本报告不声明“本轮新鲜测试通过”。  
+但仓库已有 `coverage.xml`，时间为 `2026-06-13 15:18:16 +0800`，用当前 `scripts/check_coverage_gate.py` 复核结果为：
+
+```text
+coverage gate summary: overall=60.53%, core=82.54%
+```
+
+这个结果可以作为**最近一次覆盖率产物证据**，但不是本轮重新跑完整测试套件得到的证据。
+
+---
+
+## 3. 产品规划设计审核
+
+### 3.1 产品定位
+
+产品定位基本符合行业最佳实践。
+
+`product/PRD.md` 将产品定义为：
+
+- 不是替代人工规划师，而是 AI 赋能的规划助手。
+- 不是简单查询，而是智能决策支持。
+- 不是通用 AI 对话，而是垂直领域专业服务。
+
+这个定位是正确的。高考志愿填报是高风险、高焦虑、强规则、强解释性的决策场景，单纯聊天式 AI 无法满足家长对可信度、合规性、责任边界的要求。项目选择“AI + 规则检查 + 人工服务 + 报告交付”的方向，符合该行业的实际服务形态。
+
+### 3.2 用户画像
+
+PRD 中定义的三类用户画像基本合理：
+
+- 普通工薪家庭家长。
+- 县城 / 农村考生。
+- 一线城市知识型家长。
+
+这三类人群覆盖了低信任、低信息、高焦虑、高付费意愿等不同组合。产品的分层定价策略 `49 / 99 / 199 / 299` 也能对应这些差异。
+
+### 3.3 价值主张
+
+核心价值主张成立：
+
+- 政策合规检查。
+- 方案风险提示。
+- 数据溯源。
+- 反扎堆推荐。
+- 大厂 AI 方案审核。
+- 真人服务兜底。
+
+其中“反扎堆 + 大厂 AI 方案审核”是当前最强差异化。大厂免费 AI 工具越普及，同质推荐风险越明显，项目用 49 元审核服务承接“我拿到 AI 方案但不敢填”的用户心理，产品策略成立。
+
+### 3.4 产品规划主要问题
+
+#### P-1: PRD 状态已更新，但 ROADMAP 仍未完全同步
+
+`product/PRD.md` 已把 F016-F020 标为已完成，包括：
+
+- 报告分享。
+- 管理后台。
+- 反扎堆推荐。
+- 数据溯源。
+- AI 方案审核。
+
+但 `product/ROADMAP.md` 的“差异化功能开发”部分仍然保留大量未勾选项，例如：
+
+- 上传大厂 AI 方案入口。
+- 政策合规自动检查。
+- 扎堆风险检测。
+- AI 审核报告 PDF。
+- 数据溯源展示。
+
+这说明产品文档已经开始修正，但没有形成一致状态模型。对后续计划而言，这会造成“已完成能力仍出现在未来路线图待办中”的管理混乱。
+
+#### P-2: P3 功能编号与 P2 功能编号冲突
+
+`PRD.md` 中 P2 已使用：
+
+- F018 反扎堆推荐。
+- F019 数据溯源。
+- F020 AI 方案审核。
+
+但 P3 再次使用 F018/F019/F020 表示强基计划、艺术类、国际本科。  
+这是产品需求编号治理问题，应修正为唯一 ID，避免后续任务、测试、验收和沟通混淆。
+
+#### P-3: 非功能需求状态仍偏乐观
+
+PRD 中仍有一些表述需要更严谨：
+
+- “准确率政策合规性 >95% 已达标”缺少评估样本、统计口径和测试证据。
+- “数据隐私已实现”需要区分订单 PII 加密、分享页脱敏、日志脱敏、报告文件存储等不同层面。
+- “数据备份 Git 版本控制”不应作为订单数据库、报告文件、用户资料的备份策略。
+
+从行业最佳实践看，这类高风险教育咨询产品需要更明确的数据质量和责任边界。
+
+---
+
+## 4. 业务场景要求审核
+
+### 4.1 场景 A: 闲鱼 / 微信 / 学校人工服务流程
+
+结论：**基本满足**。
+
+业务场景定义：
+
+```text
+用户先给资料 -> 管理端录入 -> 生成方案 -> 闲鱼/微信交付
+```
+
+当前代码证据：
+
+- `admin/routes/orders.py`: 订单创建、状态流转、导出。
+- `admin/routes/users.py`: 用户聚合、搜索、详情。
+- `admin/routes/cases.py`: 案例管理。
+- `admin/routes/stats.py`: 统计仪表盘。
+- `data/channel_sync/*`: 闲鱼 webhook / poller、微信、企微适配。
+- `data/share/*`: 分享短链接与权限。
+- `skills/gaokao-audit/scripts/*`: AI 审核链路。
+
+这些模块已经能支撑人工服务运营：
+
+- 运营人员录单。
+- 跟踪订单状态。
+- 管理用户与案例。
+- 生成审核报告。
+- 通过短链分享。
+- 使用渠道同步减少手工搬运。
+
+不足：
+
+- 真实支付对账仍主要依赖外部渠道或人工确认。
+- 渠道同步还应继续强化失败重放、幂等、告警与人工处理队列。
+- 运营 SOP 与系统权限模型还需要继续细化。
+
+### 4.2 场景 B: 用户端 Web 自助服务流程
+
+结论：**不满足**。
+
+业务场景文档定义：
+
+```text
+访问 Web -> 选择服务版本 -> 系统内支付 -> 填资料 -> 生成方案 -> 站内查看 + 邮件 PDF
+```
+
+当前仓库实际情况：
+
+- 未发现 `package.json`。
+- 未发现 React/Vue/Next 等用户端前台应用。
+- `admin/static/` 下只有管理后台相关静态页：`dashboard.html`、`dashboard.js`、`echarts.min.js`。
+- 没有用户注册、服务套餐选择、支付、资料填写、用户订单页、邮件交付等前台主链路。
+
+因此，当前系统不能被描述为“完整 Web 自助产品”。  
+更准确的说法是：
+
+> **系统已具备后台运营能力和部分公开分享能力，但用户端商业闭环尚未实现。**
+
+### 4.3 场景满足度矩阵
+
+| 场景 | 满足度 | 结论 |
+| --- | --- | --- |
+| 闲鱼成交后人工录单 | 高 | 管理后台与订单模型支持 |
+| 微信 / 私域人工服务 | 中高 | 订单、分享、报告支持，客服流程仍偏人工 |
+| 学校地推后人工服务 | 中高 | 可通过后台录单与顾问交付支撑 |
+| 大厂 AI 方案审核 | 高 | 审核服务主链已成形 |
+| 报告短链分享 | 中高 | 短链、权限、公开页已有实现 |
+| Web 自助下单支付 | 低 | 未形成前台闭环 |
+| Web 付费后资料填写 | 低 | 未形成用户端表单主链 |
+| Web 站内交付 / 邮件交付 | 低 | 未形成完整交付闭环 |
+
+---
+
+## 5. 技术规划与架构审核
+
+### 5.1 技术架构是否合理
+
+结论：**当前阶段合理**。
+
+技术栈选择：
+
+- Python 3.10+ / 3.12。
+- FastAPI。
+- SQLite。
+- LocalFS。
+- Markdown / HTML / PDF 报告。
+- Docker Compose 单机部署。
+
+对于当前阶段的服务规模、人工交付属性和快速迭代目标，这是务实选择。没有过早引入微服务、Kafka、Kubernetes、复杂前端框架，符合 KISS/YAGNI。
+
+### 5.2 技术规划与产品核心卖点的对齐
+
+对齐度明显提升。
+
+| 产品卖点 | 技术实现证据 | 结论 |
+| --- | --- | --- |
+| AI 方案审核 | `skills/gaokao-audit/scripts/audit_service.py` | 已对齐 |
+| 政策合规检查 | `checker_integration.py` 复用 spec-checker | 已对齐 |
+| 反扎堆检测 | `crowd_detector.py` + `data/crowd_db` | 已对齐 |
+| 数据溯源 | `data/crowd_db` schema + trace CLI | 部分对齐 |
+| 订单管理 | `data/orders/*` + `admin/routes/orders.py` | 已对齐 |
+| 用户管理 | `admin/users.py` + `admin/routes/users.py` | 已对齐 |
+| 分享能力 | `data/share/*` + `admin/share_page.py` | 已对齐 |
+| 渠道同步 | `data/channel_sync/*` | 已对齐 |
+| Web 自助 | 无用户端前台主链 | 未对齐 |
+
+### 5.3 技术架构主要问题
+
+#### T-1: 技术架构文档状态仍标记为“设计中”
+
+`docs/TECH_ARCHITECTURE.md` 仍写“状态：设计中”，但代码已经大量落地。  
+建议将技术架构拆成：
+
+- 当前实现架构。
+- 规划中架构。
+- 未落地能力。
+
+否则架构文档会同时承担愿景和现状，降低可信度。
+
+#### T-2: 架构图包含 Web/H5 和客户端，但实现不存在对应接入层
+
+技术架构图中包含 `Web/H5`、`客户端`、`Gateway` 等，但当前实际主要是：
+
+- FastAPI 管理后台。
+- 静态仪表盘。
+- CLI / Skills。
+- 渠道 webhook。
+
+建议在架构图中明确：
+
+- 已落地：Admin API、CLI、Skills、Webhook。
+- 未落地：用户端 Web/H5、支付、邮件交付、客户端。
+
+#### T-3: 数据完整性与“27 省能力”需要分层表达
+
+`data/crowd_db/*.json` 覆盖 27 个省级文件，但本轮抽样统计显示：
+
+- 湖南：`confidence=0.85`，10 个分数段，68 条推荐。
+- 其他多数省份：`confidence=0.45`，推荐数量非常少。
+
+这意味着“27 省文件覆盖”不等于“27 省高质量推荐数据覆盖”。  
+建议对外表述拆分为：
+
+- 政策规则 27 省支持。
+- crowd_db 27 省具备结构化骨架。
+- 高置信推荐数据当前重点覆盖湖南。
+
+---
+
+## 6. 实施计划与产品规划对齐审核
+
+### 6.1 实施计划整体评价
+
+`docs/IMPLEMENTATION_PLAN_v2.md` 的任务拆分是完整的，覆盖：
+
+- T1 AI 审核。
+- T2 反扎堆。
+- T3 数据溯源。
+- T4 订单。
+- T5 集成测试与发布。
+- T6 管理后台。
+- T7 分享。
+- T8 渠道。
+- T9 错误处理。
+- T10 CI/CD。
+- T11 性能与安全。
+
+这条实施主线与 PRD 中的 F016-F020 基本对齐。
+
+### 6.2 当前实施计划状态问题
+
+#### I-1: 时间表仍是未来排期，但任务已经大量完成
+
+计划中仍写：
+
+- 2026-06-15 至 2026-07-25。
+- 第 1 周、第 2 周、第 3 周等未来时间表。
+
+但当前代码已经包含 T1-T11 大量成果，且 `docs/FINAL_COMPLETION_REPORT_2026-06-13.md` 声称 T1-T11 Goal 执行闭环条件完成。  
+这会造成计划文档和实际状态冲突。
+
+#### I-2: 顶层状态与子项状态仍不完全一致
+
+`IMPLEMENTATION_PLAN_v2.md` 顶层写：
+
+- T5 进行中。
+- T10 进行中。
+- T11 进行中。
+
+但同仓库中存在：
+
+- `scripts/check_coverage_gate.py`
+- `.github/workflows/ci.yml` 覆盖率门槛。
+- `Dockerfile`
+- `docker-compose.yml`
+- `tests/test_t5_e2e_workflows.py`
+- `tests/test_t5_performance.py`
+- `docs/FINAL_COMPLETION_REPORT_2026-06-13.md`
+
+说明实际状态比计划文档更靠前。建议将实施计划转为“计划 vs 实际”格式，不再只保留原始排期。
+
+#### I-3: Web 自助产品没有成为实施计划主线
+
+这是最关键的产品/实施错位。
+
+PRD 和业务场景中有 Web 自助路径，但 T1-T11 主要解决的是：
+
+- 后台。
+- 订单。
+- 分享。
+- 渠道。
+- AI 审核。
+- 运维质量。
+
+没有把用户端 Web 自助支付/资料填写/站内交付作为一个完整 Epic。  
+因此当前实施计划可以支撑人工服务商业化，但不能支撑完整自助 SaaS 化。
+
+---
+
+## 7. 工程质量与行业最佳实践审核
+
+### 7.1 已符合的实践
+
+1. **模块边界清晰**  
+   `admin / data / skills / scripts / tests` 的分层已经形成。
+
+2. **核心链路具备测试体系**  
+   本轮统计到 45 个测试文件，覆盖 admin、orders、share、channel_sync、crowd_db、gaokao-audit、E2E、性能等方向。
+
+3. **CI 配置有实质门槛**  
+   当前 CI 会安装 dev + admin 依赖，并执行覆盖率采集、`--cov-fail-under=60` 和 `check_coverage_gate.py`。
+
+4. **安全基础在加强**  
+   生产环境 JWT secret 校验、默认管理员密码校验、登录限流、XFF 信任边界、CSV 导出公式防护已经可见。
+
+5. **部署路径开始成形**  
+   Dockerfile / docker-compose 已提供单机部署路径，并使用 volume 避免运行数据覆盖仓库。
+
+### 7.2 未完全符合的实践
+
+1. **本轮环境不可复现门禁**  
+   当前系统 Python 缺少 pytest/ruff/mypy，说明本地开发环境或工具链没有被统一固化。本轮不能直接复跑门禁。
+
+2. **覆盖率门槛偏基础**  
+   总覆盖率 60.53% 刚过线，核心 82.54% 达标，但 admin、分享页、报告生成等模块仍需提高。
+
+3. **mypy/ruff 的本轮状态无法确认**  
+   旧任务板声称已通过，但本轮环境无法执行，报告不能复用为新鲜事实。
+
+4. **数据质量与准确率没有可审计评估集**  
+   对外声称政策合规准确率 >95%，需要固定样本、预期答案、回归测试和误判分析。
+
+5. **备份、恢复、审计仍需产品级设计**  
+   Git 不应作为业务数据备份策略。订单库、报告文件、分享数据、审计日志需要独立备份与恢复方案。
+
+---
+
+## 8. 风险清单
+
+### 8.1 P0 风险
+
+#### R-1: 用户端 Web 自助闭环缺失
+
+影响：
+
+- 无法支撑自助转化。
+- 不能兑现业务场景 B。
+- 商业化规模仍依赖人工服务。
+
+建议：
+
+- 新增 `T12: 用户端 Web 自助 MVP`。
+- 范围至少包括套餐页、支付占位/支付回调接口、资料表单、订单状态页、报告查看页。
+
+#### R-2: 文档状态仍未完全统一
+
+影响：
+
+- PRD、ROADMAP、IMPLEMENTATION_PLAN、FINAL_REPORT 对项目状态理解不一致。
+- 后续执行容易误判已完成范围。
+
+建议：
+
+- 建立 `docs/CURRENT_STATE.md` 作为唯一状态源。
+- 所有历史报告顶部标注“历史快照”。
+- ROADMAP 改为“已完成 / 进行中 / 未开始 / 废弃”四态。
+
+### 8.2 P1 风险
+
+#### R-3: 数据质量不足以支撑全国化反扎堆宣传
+
+影响：
+
+- 湖南样本较强，其他省份多为低置信、小样本。
+- 如果直接宣传“27省反扎堆高质量推荐”，有误导风险。
+
+建议：
+
+- 对 crowd_db 引入数据完整度等级。
+- 对报告输出加入置信度文案。
+- 高置信数据不足的省份不输出强结论。
+
+#### R-4: 覆盖率刚过门槛，仍有质量脆弱区
+
+影响：
+
+- 后续迭代容易引入回归。
+
+建议：
+
+- 保留 60% 总门槛，新增关键模块门槛。
+- 优先补 admin 路由、分享页、报告生成、checker integration。
+
+#### R-5: 本地开发工具链未固化
+
+影响：
+
+- 不同机器结果不一致。
+- 本轮无法重新验证 pytest/ruff/mypy。
+
+建议：
+
+- 增加 `make test` / `make verify` 或 `scripts/dev-verify.sh`。
+- 文档明确 `python -m venv .venv && pip install -r requirements-dev.txt -r requirements-admin.txt`。
+- 可选增加 `requirements-ci.txt` 或 `uv.lock`。
+
+### 8.3 P2 风险
+
+#### R-6: 技术架构图偏未来态
+
+影响：
+
+- 新成员误以为 Web/H5、客户端、Gateway 已经落地。
+
+建议：
+
+- 架构图分成 Current / Target。
+
+#### R-7: 业务数据备份策略不足
+
+影响：
+
+- SQLite、报告文件、分享数据丢失风险。
+
+建议：
+
+- 最低限度做本地定时备份 + 异地备份 + 恢复演练 SOP。
+
+---
+
+## 9. 改进路线
+
+### 9.1 立即处理
+
+1. 新建 `docs/CURRENT_STATE.md`，统一当前真实状态。
+2. 修正 `product/ROADMAP.md` 中已完成能力仍未勾选的问题。
+3. 修正 PRD P3 功能编号重复。
+4. 明确对外口径：当前是“人工服务运营增强系统”，不是完整 Web 自助 SaaS。
+
+### 9.2 一周内处理
+
+1. 新增 `T12 用户端 Web 自助 MVP` 实施计划。
+2. 固化本地验证脚本，保证 pytest/ruff/mypy 能一键安装并执行。
+3. 为低覆盖关键模块补测试。
+4. 将 crowd_db 数据置信度展示接入报告文案。
+
+### 9.3 一个月内处理
+
+1. 完成 Web 自助 MVP。
+2. 建立真实案例评估集，用于验证“政策合规准确率”。
+3. 建立备份恢复 SOP。
+4. 将支付、交付、售后、退款形成完整运营闭环。
+
+---
+
+## 10. 最终判断
+
+### 10.1 是否符合行业最佳实践
+
+**部分符合。**
+
+符合点：
+
+- 垂直领域定位清晰。
+- 使用规则检查和数据溯源降低 AI 幻觉风险。
+- 保留人工服务兜底，符合高风险教育咨询场景。
+- 技术栈务实，工程结构逐步成熟。
+- 安全、CI、覆盖率、部署都有可见进展。
+
+不足点：
+
+- Web 自助商业闭环缺失。
+- 数据质量证据不足。
+- 文档状态仍不完全一致。
+- 本轮环境无法复现完整门禁。
+
+### 10.2 是否满足场景要求
+
+| 场景 | 判断 |
+| --- | --- |
+| 闲鱼 / 微信 / 学校人工服务 | 基本满足 |
+| 大厂 AI 方案审核 | 基本满足 |
+| 管理后台运营 | 基本满足 |
+| 报告分享 | 基本满足 |
+| 渠道同步 | 部分满足 |
+| 用户端 Web 自助 | 不满足 |
+| 标准 SaaS 化交付 | 不满足 |
+
+### 10.3 技术规划和实施计划是否与产品规划设计对齐
+
+**对人工服务运营链路基本对齐；对完整 Web 产品规划未对齐。**
+
+T1-T11 已经较好承接了后台、订单、分享、渠道、审核、工程质量这些能力。  
+但 PRD 与业务场景里定义的 Web 自助流程没有进入实施主线，因此还存在产品规划与实施计划之间的关键缺口。
+
+### 10.4 最终结论
+
+> 项目当前已具备较强的人工服务运营能力和 AI 审核增强能力，适合支撑 2026 高考季的低规模人工服务交付；但尚未达到完整用户端 Web 自助产品或教育 SaaS 的成熟标准。下一阶段不应继续泛化扩功能，而应优先补齐 Web 自助闭环、统一文档真相、固化验证环境、提升数据质量与关键模块测试覆盖。
+
+---
+
+## 11. 增量严格复审补充（2026-06-13）
+
+### 11.1 复审方法
+
+本轮采用不同于前序代码结构分析的复审方法，重点做三类反向校验：
+
+1. **需求可追踪矩阵反查**：从 PRD、ROADMAP、BUSINESS_SCENE、UX/DESIGN 文档中的用户承诺出发，逐项追踪到实际代码、脚本、依赖清单和测试。
+2. **负向证据搜索**：针对支付、退款、邮件交付、上传、备份恢复、隐私同意等关键闭环能力，搜索“应存在但未出现”的实现痕迹。
+3. **场景穿透走查**：按“用户下单付款 -> 提交资料 -> AI 审核 -> 报告生成 -> 交付 -> 售后/退款 -> 审计/恢复”的真实业务链路检查断点。
+
+本轮新增问题不改变前文总体结论，反而进一步确认当前状态应维持为 `CONDITIONAL_PASS / REQUEST_CHANGES`。若项目目标是内部人工运营后台，可以有限投产；若目标是 Web 用户自助闭环，仍不满足上线条件。
+
+### 11.2 新增问题总览
+
+| 编号 | 严重度 | 新增问题 | 影响 |
+|---|---:|---|---|
+| N-01 | P0 | 支付闭环缺少真实第三方支付接入、回调验签、对账与退款流水 | 无法支撑 PRD/业务场景中的 Web 自助购买 |
+| N-02 | P0 | 邮件/PDF 自动交付未进入当前主系统，仅存在 legacy、模板或指南 | 用户支付后无法形成系统化交付闭环 |
+| N-03 | P1 | “上传大厂 AI 方案/用户资料提交”仍停留在 CLI 或文档层 | 用户端资料提交场景无法闭环 |
+| N-04 | P1 | 依赖清单与实际导入不一致，报告生成依赖未被明确声明 | 干净环境、CI 与交付环境存在不可重复风险 |
+| N-05 | P1 | 隐私政策、服务协议、未成年人/监护人同意、数据保留与删除流程缺失 | 高考场景涉及学生个人信息，合规风险高 |
+| N-06 | P1 | 备份恢复方案以 Git 代替业务备份，缺少恢复演练和密钥托管 | 订单、报告、审计和加密数据存在恢复不可控风险 |
+| N-07 | P2 | legacy 邮件脚本/指南中保留个人 Gmail 示例，容易误导生产配置 | 运维配置边界不清，存在交付误用风险 |
+| N-08 | P2 | 部分审计失败路径仍以静默吞异常为主 | 安全事件与数据写入失败时可观测性不足 |
+
+### 11.3 新增问题详情
+
+#### N-01 支付闭环缺少真实第三方支付能力（P0）
+
+**证据**
+
+- `product/ROADMAP.md` 中仍将“支付接入”“微信支付/支付宝”列为后续待办。
+- `docs/BUSINESS_SCENE.md` 描述了 Web 内支付、订单状态更新、报告交付等完整用户链路。
+- 当前订单能力主要体现为本地订单状态、渠道同步事件和后台退款状态推进；`README.md` 明确说明退款不主动调用第三方渠道 API。
+
+**判断**
+
+当前系统更接近“人工收款后后台登记订单”的运营工具，而不是“用户自助下单支付系统”。这与 PRD/业务场景中的 Web 自助购买承诺不一致。
+
+**建议**
+
+- 明确 MVP 是否包含系统内支付：若不包含，PRD、BUSINESS_SCENE、UX 文档必须降级为“人工收款/线下确认”。
+- 若包含支付，需要补齐支付订单表、支付单号、回调验签、幂等处理、金额校验、对账任务、退款流水和异常补偿。
+- 支付相关测试至少覆盖：重复回调、金额不一致、订单不存在、已退款订单重复退款、支付成功但报告生成失败。
+
+#### N-02 邮件/PDF 自动交付未进入当前主系统（P0）
+
+**证据**
+
+- `docs/BUSINESS_SCENE.md` 和 `docs/SHARING_DESIGN.md` 描述了站内查看、PDF 下载、邮件发送等交付体验。
+- 实际邮件发送能力主要出现在 `scripts/legacy/gaokao-report-send.sh`、模板文档和技能参考指南中。
+- 当前后台主链路没有形成“订单完成后自动触发报告生成与交付”的服务编排。
+
+**判断**
+
+报告生成能力与用户交付能力不是一回事。当前项目可以生成或处理报告，但尚未证明具备稳定的系统化交付能力。
+
+**建议**
+
+- 将报告交付建模为一等业务对象：`delivery_job`、`delivery_attempt`、`delivery_status`、`recipient`、`failure_reason`。
+- 支持至少一种 MVP 交付方式：后台手动标记交付、站内下载链接、或邮件发送。不要在文档中同时承诺多种未落地能力。
+- 交付链路需要具备幂等、重试、失败告警、交付记录和用户可追溯状态。
+
+#### N-03 用户资料/AI 方案上传入口缺失（P1）
+
+**证据**
+
+- `product/ROADMAP.md` 中仍保留“上传大厂 AI 方案入口”等待办项。
+- `skills/gaokao-audit/scripts/audit_cli.py` 主要接受本地文件路径，属于 CLI/内部工具入口。
+- `docs/BUSINESS_SCENE.md` 中描述的是用户 Web 表单提交分数、位次、偏好、院校方案和附件。
+
+**判断**
+
+AI 审核引擎具备内部处理能力，但用户端资料采集和上传没有形成产品级入口。若面向真实用户，这会直接阻断从“购买”到“审核”的主流程。
+
+**建议**
+
+- 将“资料提交”拆成明确的 MVP 表单字段：考生省份、科类、分数、位次、选科、目标城市、专业偏好、已有方案文件。
+- 文件上传需要限制类型、大小、病毒/恶意内容检查、存储路径隔离和审计记录。
+- AI 审核入口应提供 API 或后台任务，而不是只依赖本地 CLI。
+
+#### N-04 依赖清单与实际导入不一致（P1）
+
+**证据**
+
+- `skills/gaokao-audit/scripts/report_generator.py` 在模块导入阶段依赖 `jinja2`，生成 PDF 时动态依赖 `weasyprint`。
+- 当前依赖清单中能看到 `fastapi`、`uvicorn`、`PyJWT`、`pydantic`、`cryptography`、`pytest` 等，但未明确声明 `jinja2`、`weasyprint`。
+- 文档与门禁中提到 `ruff`、`mypy` 等质量工具，但当前依赖清单未统一声明这些工具。
+
+**判断**
+
+这会造成“开发机可运行、CI 或新环境不可运行”的不可重复问题。尤其报告生成是交付主链路的一部分，依赖未声明会直接影响投产可靠性。
+
+**建议**
+
+- 将运行时依赖、报告生成依赖、开发测试依赖分层声明，例如 `requirements.txt`、`requirements-report.txt`、`requirements-dev.txt`。
+- 对可选 PDF 依赖做清晰降级：没有 `weasyprint` 时只生成 HTML/Markdown，并在接口层返回明确错误。
+- CI 应从干净环境安装依赖并执行最小报告生成 smoke test，避免依赖本机残留包。
+
+#### N-05 隐私政策与未成年人合规材料不足（P1）
+
+**证据**
+
+- 模板与报告中存在免责声明，强调审核结果仅供参考。
+- UX 文档出现“查看隐私政策”等入口描述，但没有看到正式隐私政策、服务协议、监护人同意、数据保留周期、删除申请流程的落地文档和系统实现。
+- 高考志愿服务天然处理考生姓名、成绩、位次、省份、偏好、联系方式、报告内容等敏感程度较高的数据。
+
+**判断**
+
+免责声明不能替代隐私政策和个人信息处理规则。该项目面向高考考生，其中相当一部分用户可能未成年，合规要求应高于普通工具型网站。
+
+**建议**
+
+- 补齐正式文档：隐私政策、用户服务协议、免责声明、未成年人/监护人授权说明。
+- 在产品流程中加入明确同意记录：同意版本、时间、IP/设备摘要、同意范围。
+- 定义数据保留和删除规则：订单数据、报告文件、AI 审核输入、审计日志、渠道同步记录分别保留多久。
+- 管理后台增加数据删除/匿名化 SOP，避免“只加密、不删除”的误区。
+
+#### N-06 备份恢复与密钥托管方案不足（P1）
+
+**证据**
+
+- `product/PRD.md` 将“Git 版本控制”作为数据备份/系统故障恢复的主要依据。
+- 项目存在 SQLite、订单、报告、分享、审计、加密字段等业务数据形态，不能等同于源码版本控制。
+- 加密相关实现已经考虑 key fingerprint 等工程细节，但缺少密钥轮换、密钥托管、恢复演练和备份介质策略。
+
+**判断**
+
+Git 可以备份源码和部分文档，不能作为业务数据备份恢复方案。若发生磁盘损坏、误删、密钥丢失或数据库损坏，当前规划无法证明可恢复。
+
+**建议**
+
+- 制定并实现最小备份策略：数据库、报告文件、上传文件、审计日志、配置密钥分别备份。
+- 明确 RPO/RTO：例如 MVP 阶段 RPO 24 小时、RTO 4 小时。
+- 增加恢复演练脚本和文档，至少每次发布前能在临时目录恢复一份可读数据。
+- 密钥不得只依赖单机环境变量；需要有托管、轮换和应急恢复策略。
+
+#### N-07 legacy 邮件脚本存在生产误用风险（P2）
+
+**证据**
+
+- `scripts/legacy/gaokao-report-send.sh` 和相关操作指南中保留 Gmail/SMTP 示例。
+- 示例中出现个人邮箱风格的配置痕迹，且与当前主系统的交付链路没有清晰边界。
+
+**判断**
+
+legacy 脚本本身不是问题，但在产品文档、运维指南和主系统能力没有分层时，容易被误认为正式交付方案。
+
+**建议**
+
+- 将 legacy 目录增加 `README.md`，明确“不属于当前生产主链路”。
+- 所有邮箱、SMTP、收件人配置必须通过环境变量或配置文件注入，不应在脚本中保留个人账号示例。
+- 若保留邮件交付，迁移到正式 delivery service，并纳入审计、重试和测试。
+
+#### N-08 审计失败路径可观测性不足（P2）
+
+**证据**
+
+- webhook 服务中对部分审计写入失败仍采用静默吞异常策略。
+- 当前实现已经修复了请求体大小限制和 `X-Forwarded-For` 信任边界问题，但审计失败时的最低可见性仍不足。
+
+**判断**
+
+审计系统的价值在于异常时仍尽量保留线索。完全静默会让安全事件、磁盘写入失败、权限异常和数据损坏问题难以及时发现。
+
+**建议**
+
+- 审计写入失败至少输出结构化 stderr 日志，包含事件类型、错误类型、订单/渠道标识摘要。
+- 对连续审计失败增加健康检查状态或后台告警。
+- 审计失败不一定阻断业务请求，但不能完全不可见。
+
+### 11.4 对前文结论的影响
+
+本轮新增问题使结论更明确：
+
+- 若定位为**内部人工服务运营后台**：当前工程基础可继续收敛，但上线前仍需补齐依赖、备份、隐私和最小交付 SOP。
+- 若定位为**用户 Web 自助志愿填报产品**：当前仍缺少支付、资料提交、自动交付、协议同意和售后闭环，不能按 PRD 中描述的完整场景上线。
+- 技术规划应从“扩展更多能力”调整为“补齐主链路断点”。在 N-01、N-02、N-03 未解决前，不建议继续投入复杂推荐算法、多渠道自动化或平台化抽象。

reports/code-analysis-review-input-2026-06-13.md

@@ -0,0 +1,276 @@
+# 🔍 Deep Code Analysis Report
+
+**Generated:** 2026-06-13T16:27:02.003950
+
+**Path:** /home/long/project/gaokao-volunteer-system
+
+
+## 📋 Executive Summary
+
+- **Total Files:** 128
+- **Total Lines:** 28,852
+- **Architecture Style:** MVC
+- **Entry Points:** 1
+- **Data Models:** 147
+- **Business Rules:** 239
+- **External Dependencies:** 72
+
+
+## 🏗️ Architecture
+
+**Style:** MVC
+
+**Layers/Modules:**
+
+- `admin/`
+- `data/`
+- `scripts/`
+- `tests/`
+- `skills/`
+
+## 🚀 Entry Points & Execution Flow
+
+
+### main
+
+- **Location:** `admin/app.py`
+- **Parameters:** argv
+- **Business Logic:** ❌ No
+- **Calls:** ArgumentParser, add_argument, add_argument, add_argument, add_argument
+
+## 📊 Data Models
+
+
+### Core Entities
+
+
+**UserOrderRecord** (`admin/users.py`)
+
+
+**CaseRecord** (`data/cases/models.py`)
+
+
+### DTOs/Value Objects
+
+- **OrderSummaryResponse** - admin/routes/orders.py
+- **OrderMutationResponse** - admin/routes/orders.py
+- **CreateOrderRequest** - admin/routes/orders.py
+- **UpdateOrderRequest** - admin/routes/orders.py
+- **UserSummaryResponse** - admin/routes/users.py
+
+## 📜 Business Rules
+
+
+### Validation Rules (219)
+
+**rule_1:** Validation in login
+
+- Location: `locustfile.py:login`
+- Priority: medium
+- Condition: `if not token:
+                resp.failure("login response missing access_token")
+                se...`
+
+**rule_2:** Validation in hash_password
+
+- Location: `admin/password.py:hash_password`
+- Priority: high
+- Condition: `if not plain:
+        raise ValueError("password cannot be empty")
+    salt = secrets.token_bytes(_S...`
+
+**rule_3:** Validation in verify_password
+
+- Location: `admin/password.py:verify_password`
+- Priority: high
+- Condition: `if not plain or not stored or _STORED_SEPARATOR not in stored:
+        return False
+    salt_hex, ha...`
+
+**rule_4:** Validation in authenticate
+
+- Location: `admin/db.py:authenticate`
+- Priority: medium
+- Condition: `if result is None:
+        return None
+    user, password_hash = result
+    if not user.is_active:
+ ...`
+
+**rule_5:** Validation in authenticate
+
+- Location: `admin/db.py:authenticate`
+- Priority: medium
+- Condition: `if not user.is_active:
+        return None
+    if not verify_password(password, password_hash):
+    ...`
+
+
+### Constraint Rules (20)
+
+**rule_11:** Business constraint in log_event
+
+- Location: `admin/logging_utils.py:log_event`
+- Priority: critical
+- Condition: `if not event:
+        raise ValueError("log_event: 'event' is required")
+
+    safe_fields: Dict[str,...`
+
+**rule_14:** Business constraint in log_event_exc
+
+- Location: `admin/logging_utils.py:log_event_exc`
+- Priority: critical
+- Condition: `if not event:
+        raise ValueError("log_event_exc: 'event' is required")
+    safe_fields: Dict[s...`
+
+**rule_36:** Business constraint in main
+
+- Location: `scripts/check_coverage_gate.py:main`
+- Priority: critical
+- Condition: `if overall < OVERALL_MIN:
+        failures.append(
+            f"overall coverage {_format_percent(o...`
+
+**rule_37:** Business constraint in main
+
+- Location: `scripts/check_coverage_gate.py:main`
+- Priority: critical
+- Condition: `if core < CORE_MIN:
+        failures.append(
+            f"core coverage {_format_percent(core)} < r...`
+
+**rule_70:** Business constraint in main
+
+- Location: `skills/gaokao-audit/scripts/validate_template.py:main`
+- Priority: critical
+- Condition: `if needle not in text:
+            print(f"FAIL: placeholder missing: {needle!r}")
+            retur...`
+
+
+## 🔗 External Dependencies
+
+
+### Other Dependencies
+
+- contextlib
+- contextvars
+- secrets
+- checker_integration
+- models
+- io
+- dataclasses
+- unittest
+- xml
+- base64
+- datetime
+- weasyprint
+- schema
+- sys
+- csv
+
+## 💧 Data Flows
+
+- **external** → **admin/password.py:verify_password**
+  - Data: plain, stored
+  - Trigger: function_call
+- **external** → **admin/db.py:create**
+  - Data: username, password, role
+  - Trigger: function_call
+- **external** → **admin/db.py:update_last_login**
+  - Data: user_id
+  - Trigger: function_call
+- **external** → **admin/app.py:_validate_and_log_settings**
+  - Data: settings
+  - Trigger: function_call
+- **external** → **admin/app.py:create_app**
+  - Data: settings
+  - Trigger: function_call
+- **external** → **admin/stats.py:generate_day_series**
+  - Data: db_path
+  - Trigger: function_call
+- **external** → **scripts/gaokao-quick-3min.py:generate_quick_summary**
+  - Data: info
+  - Trigger: function_call
+- **external** → **scripts/gaokao-quick-3min.py:generate_quick_recommendation**
+  - Data: info
+  - Trigger: function_call
+- **external** → **scripts/gaokao-visual-report-v2.py:generate_student_radar**
+  - Data: student_profile
+  - Trigger: function_call
+- **external** → **scripts/gaokao-visual-report-v2.py:generate_school_comparison**
+  - Data: volunteer_list
+  - Trigger: function_call
+
+## 🛤️ Key Execution Paths
+
+
+### main
+
+Entry point: admin/app.py
+
+**Steps:**
+
+1. `main`
+2. `test_visual_report_usage_message`
+3. `test_visual_report_demo_mode`
+4. `test_visual_report_json_input`
+5. `test_audit_cli_end_to_end_generates_pdf_and_report_content`
+6. `test_audit_to_report_flow`
+7. `test_traceability_display_flow`
+8. `test_main_generates_pdf_and_prints_report_path`
+... and 1 more
+
+### main
+
+Entry point: scripts/check_coverage_gate.py
+
+**Steps:**
+
+1. `main`
+2. `test_visual_report_usage_message`
+3. `test_visual_report_demo_mode`
+4. `test_visual_report_json_input`
+5. `test_audit_cli_end_to_end_generates_pdf_and_report_content`
+6. `test_audit_to_report_flow`
+7. `test_traceability_display_flow`
+8. `test_main_generates_pdf_and_prints_report_path`
+... and 1 more
+
+### main
+
+Entry point: scripts/gaokao-quick-3min.py
+
+**Steps:**
+
+1. `main`
+2. `test_visual_report_usage_message`
+3. `test_visual_report_demo_mode`
+4. `test_visual_report_json_input`
+5. `test_audit_cli_end_to_end_generates_pdf_and_report_content`
+6. `test_audit_to_report_flow`
+7. `test_traceability_display_flow`
+8. `test_main_generates_pdf_and_prints_report_path`
+... and 1 more
+
+## 💡 Recommendations
+
+
+### For Understanding This Codebase
+
+1. Start with entry points listed above
+2. Review core entities and their relationships
+3. Trace execution paths for key features
+4. Review business rules for domain logic
+5. Check external dependencies for integration points
+
+
+### For Code Quality
+
+1. Add documentation to entry points
+2. Document business rules explicitly
+3. Create architecture decision records (ADRs)
+4. Add data flow diagrams