gaokao-volunteer-system/reports/PRODUCT_TECH_REVIEW_2026-06-12.md

⚠️ 历史快照（非当前真相源）：本文件仅保留当时审查/收口结论。当前状态与执行顺序以 docs/CURRENT_STATE.md、docs/ACTIVE_REMEDIATION_2026-07-05_REVIEW.md、docs/ACTIVE_EXECUTION_BOARD_2026-07-05_REVIEW_REMEDIATION.md、docs/plans/2026-07-05-review-remediation-systemic-fix-plan.md 和 reports/REVIEW_REPORT_2026-07-05_COMPREHENSIVE_PROJECT_REVIEW.md 为准。

---

高考志愿填报系统 产品规划与技术实施评审报告（历史快照）

该文档是 2026-06-12 的评审快照；其中部分判断已被后续代码与验证结果更新。当前真相源请以 reports/PROJECT_SYSTEM_REVIEW_2026-06-13.md 为准。

项目: gaokao-volunteer-system
评审日期: 2026-06-12
评审范围: 产品规划、市场调研、业务场景、技术架构、实施计划、核心实现代码、CI 与测试结构
评审方法: 文档交叉核对 + 代码抽样核验 + 静态分析 + 本地测试验证

---

1. 结论摘要

1.1 总体结论

项目的产品方向是成立的，核心差异化也清楚：27省政策检查、反扎堆、真人服务、数据透明、AI审核 这条产品线在产品层面形成了闭环。

但从产品规划 -> 技术设计 -> 实施计划 -> 代码现状四层链路看，当前存在明显的文档状态漂移与实施范围收缩：

• 核心产品能力已经部分落地，但并未完全覆盖 PRD 中的全部关键路径。
• README.md、PRD.md、ROADMAP.md、IMPLEMENTATION_PLAN_v2.md 对“已完成 / 规划中 / 待实现”的标注存在不一致。
• 业务场景中的 Web 自助流程 仍然缺少完整实现路径。
• AI 审核链路已经具备解析器、扎堆检测、模板等局部模块，但距离技术架构里定义的 audit_service -> checker_integration -> crowd_detector -> report_generator 端到端服务还有缺口。

1.2 评审评级

维度	评级	说明
产品定位	A-	目标用户、价值主张、付费路径明确
行业差异化	A	反扎堆 + 政策合规 + 真人服务，差异点成立
业务场景设计	B	闲鱼/微信场景较完整，Web 场景未闭环
技术规划对齐	B-	方向对齐，但模块落地不完整，文档与代码不同步
实施计划可执行性	B-	任务拆分合理，但范围较大，且部分任务状态滞后
行业最佳实践符合度	B-	安全、CI、测试、审计方向对了，但门槛尚未完全达标

综合判断: 产品规划可用，技术实施计划需要按当前代码事实重新校准，不能直接按现有文档状态视为“全量已完成”。

---

2. 评审依据

2.1 产品与业务文档

• product/PRD.md
• product/ROADMAP.md
• product/MARKET_RESEARCH.md
• docs/BUSINESS_SCENE.md
• docs/TECH_ARCHITECTURE.md
• docs/IMPLEMENTATION_PLAN_v2.md
• docs/archive/2026-06-historical-snapshots/AUDIT_REPORT_2026-06-11.md

2.2 代码与运行时证据

• README.md
• admin/app.py
• admin/routes/orders.py
• admin/routes/users.py
• admin/routes/stats.py
• data/orders/schema.py
• data/orders/crypto.py
• data/crowd_db/loader.py
• data/crowd_db/crowd_detector.py
• data/share/short_link.py
• data/share/permission.py
• skills/gaokao-audit/SKILL.md
• skills/gaokao-audit/scripts/plan_parser.py
• .github/workflows/ci.yml

2.3 静态分析结果

• 深度分析报告：reports/code-analysis-review-input-2026-06-12.md
• 统计结果：107 个核心文件，25,582 行，123 个数据模型/DTO，218 条业务规则，66 个外部依赖

---

3. 产品规划审核

3.1 产品定位是否符合行业最佳实践

结论：基本符合。

PRD.md 中的定位不是泛 AI，而是“高考志愿填报的垂直决策支持”。这符合教育咨询类产品的最佳实践，因为它避免了通用聊天机器人最常见的两个问题：

1. 只给信息，不给行动建议。
2. 给建议但缺少政策约束与责任边界。

文档里给出的四维主张也合理：

• 兴趣
• 能力
• 家庭条件
• 就业导向

这四项和高考志愿的真实决策逻辑基本一致，不是拍脑袋的功能堆砌。

3.2 目标用户与场景是否匹配

结论：匹配度高。

PRD.md 中定义的三类用户画像，以及 BUSINESS_SCENE.md 中的两种核心交付路径，符合高考志愿填报服务的真实市场形态：

• 闲鱼 / 微信 / 学校渠道，适合低摩擦成交和人工深度服务。
• Web 自助路径，适合标准化、规模化和未来增长。

这个分层是合理的，且与 MARKET_RESEARCH.md 里“免费大厂工具负责流量教育，专业服务负责转化” 的市场判断一致。

3.3 产品优先级是否合理

结论：核心优先级合理，但当前文档状态存在冲突。

PRD.md 里把 反扎堆推荐、AI方案审核 作为核心差异化功能，这和当前市场竞争态势是一致的。 但同一文档里，管理后台、报告分享、数据溯源、AI审核、反扎堆 等状态标记混杂了“规划中”和“已落地”的语义，说明产品文档没有和实现进度同步更新。

这会带来两个问题：

• 对外部读者来说，不知道哪些是已交付能力，哪些只是规划。
• 对实施团队来说，无法据此准确排期。

3.4 产品层面的主要问题

问题 1: PRD 和当前实现状态不同步

PRD.md 第 144-155 行仍把 F011-F020 多个功能标成“规划中”，但 README.md 已明确写出管理后台、仪表盘、用户管理、订单管理、分享能力、渠道兜底等内容已进入落地阶段。

这不是功能本身的问题，而是产品文档治理问题。
如果不修正，后续会直接影响排期、验收与商业交付口径。

问题 2: Web 自助服务的产品路径没有真正闭环

BUSINESS_SCENE.md 第 15-23 行定义了 Web 自助流程，但 IMPLEMENTATION_PLAN_v2.md 的任务主线仍然围绕 AI 审核、反扎堆、数据溯源、订单管理展开，没有形成一个可直接上线的 Web 交易闭环。

也就是说：

• 产品层已经定义了 Web 场景。
• 代码层已经有管理后台和订单能力。
• 但前台自助购买、资料填写、交付浏览、支付闭环尚未形成完整产品。

这意味着场景 B 目前仍是规划态，而不是可交付态。

---

4. 技术规划审核

4.1 技术架构是否与产品方向对齐

结论：方向对齐，落地不完全。

TECH_ARCHITECTURE.md 的分层设计是合理的：

• Channels
• Gateway
• Services
• Data
• Infra

并且它明确了 4 个核心技术面：

• AI 审核服务
• 反扎堆检测
• 数据溯源
• 订单管理

这些都与 PRD 的核心卖点一致，说明技术规划没有偏题。

4.2 技术选型是否符合行业最佳实践

结论：符合“务实型最佳实践”。

当前选型没有过度复杂化：

• Python 3.10+
• SQLite
• FastAPI
• 本地优先
• 文件 / JSON / Markdown 为主

这对于一个以文档化规则、轻量交付和低并发为主的高考志愿辅助系统是合适的。
它避免了不必要的微服务、消息队列或过重前端框架，这一点符合 KISS 和 YAGNI。

4.3 技术规划的主要偏差

问题 1: AI 审核服务的模块结构与代码现状不完全一致

技术架构里定义的 AI 审核服务包含：

• audit_service.py
• checker_integration.py
• crowd_detector.py
• report_generator.py

但当前代码层已核验到的实际实现是：

• skills/gaokao-audit/scripts/plan_parser.py
• data/crowd_db/crowd_detector.py
• skills/gaokao-audit/templates/audit_report.html

也就是说，解析器、检测器、模板已经有了，但“编排服务层”仍然不完整。
这使 AI 审核能力更像“若干模块拼装”，还不是完全闭环的服务产品。

问题 2: 数据溯源的设计比实现更完整

TECH_ARCHITECTURE.md 要求数据溯源字段扩展、来源链接、置信度管理。
data/crowd_db/SCHEMA.md 与 loader.py 确实已经定义了 source / source_url / source_type / confidence / last_updated / data_year 等字段，并提供了 confidence < 0.5 的低置信度警告机制。

这说明数据溯源不是空谈，已经进入实现层。
但是从整体产品体验看，它仍然主要存在于数据结构和审核文档里，还没有在终端用户报告中形成足够强的可视化表达。

---

5. 实施计划审核

5.1 实施计划是否与产品规划对齐

结论：部分对齐，且存在“计划超前/文档滞后”并存现象。

IMPLEMENTATION_PLAN_v2.md 是在补齐先前审计缺口后修订的，这一版对齐意识很强，特别是新增了：

• T6 管理后台 MVP
• T7 分享功能 MVP
• T8 渠道 SDK 集成
• T9 错误处理体系
• T10 CI/CD 基础
• T11 性能与安全加固

这说明实施计划已经开始向行业化工程实践靠拢。

但存在两个现实问题：

1. 文档里仍然保留大量“待开始 / 规划中”的标记。
2. 代码仓库实际已经有部分 T6/T7/T8/T9 能力落地，计划文档没有完全反映现实。

这会导致一种典型风险：研发推进速度快于文档治理速度。

5.2 当前最关键的实施差距

差距 1: Web 产品闭环未形成

业务场景文档定义了 Web 购买、资料填写、生成方案、站内交付，但实施计划没有把它作为一个独立可交付的主线任务。

对业务来说，这意味着：

• 无法真正形成标准化产品入口。
• 规模化能力被限制在人工渠道。

差距 2: 核心服务的端到端编排层缺失

技术规划中的 AI 审核要成为商业卖点，必须有一个完整的服务编排层。
当前看，plan_parser、crowd_detector、audit_report.html 已存在，但主服务编排、规范检查集成、PDF/HTML 输出组合还没有形成统一入口。

差距 3: CI / 测试门槛没有完全兑现

IMPLEMENTATION_PLAN_v2.md 明确提出：

• 核心覆盖率 ≥ 80%
• 整体覆盖率 ≥ 60%
• CI 通过

但 .github/workflows/ci.yml 现在只是生成覆盖率报告，并没有在工作流中强制 --cov-fail-under 门槛。
也就是说，测试门槛在计划里有，在流水线里还没真正硬化。

---

6. 代码现状与文档一致性审核

6.1 已对齐部分

以下能力已经能从代码中看到真实实现，不是纯文档：

• 管理后台 FastAPI 入口：admin/app.py
• 用户管理：admin/routes/users.py
• 仪表盘统计：admin/routes/stats.py
• 订单管理：admin/routes/orders.py
• 订单加密与状态审计：data/orders/schema.py、data/orders/crypto.py
• 分享短链接与权限策略：data/share/short_link.py、data/share/permission.py
• 反扎堆数据加载与检测：data/crowd_db/loader.py、data/crowd_db/crowd_detector.py
• AI 审核解析器：skills/gaokao-audit/scripts/plan_parser.py

这说明项目已经不是“只停留在规划文档”的状态。

6.2 仍需警惕的部分

README.md、PRD.md、ROADMAP.md 与 IMPLEMENTATION_PLAN_v2.md 的状态描述存在明显不一致。
这类不一致本身就是产品与实施失配的信号，尤其在这种带有商业交付和合规风险的项目里，会直接影响：

• 交付验收
• 团队排期
• 商业对外口径
• 风险边界

---

7. 行业最佳实践符合度

7.1 符合的部分

• 产品定位清晰，不是泛 AI。
• 技术栈克制，没有引入多余复杂度。
• 核心功能围绕真实高考决策场景展开。
• 数据脱敏、加密、审计的方向正确。
• CI / 覆盖率 / TDD 的工程意识已经建立。

7.2 不足的部分

• 测试门槛尚未真正硬化。
• 文档状态治理不足。
• Web 自助闭环缺失。
• AI 审核端到端编排层未完全落地。
• 产品文档与实施计划没有统一“真相源”。

7.3 结论

按行业最佳实践标准，这个项目已经进入可用的工程化阶段，但还不能说已经达到成熟的产品化交付阶段。
最需要补的不是“再加功能”，而是把已经实现的能力、正在做的能力、尚未做的能力分层讲清楚，并让计划与代码同步。

---

8. 风险分级

8.1 高风险

1. 文档状态漂移
   影响：排期、验收、对外口径都可能出错。

2. Web 自助闭环缺失
   影响：规模化能力不足，场景 B 不能独立运行。

3. AI 审核链路未完全端到端
   影响：核心差异化卖点的交付完整性不足。

8.2 中风险

1. CI 没有硬性覆盖率门槛
2. 测试依赖未在当前系统环境可直接运行
3. 部分数据集仍以骨架或低置信度形式存在

8.3 低风险

1. 技术栈过重风险低
2. 数据模型扩展性尚可
3. 本地优先策略符合当前业务体量

---

9. 建议

9.1 立即修正

1. 统一 PRD / ROADMAP / TECH_ARCHITECTURE / IMPLEMENTATION_PLAN_v2 / README 的状态口径，先建立单一事实源。
2. 给 AI审核服务 补齐端到端编排层，明确输入、校验、检测、出报告的主入口。
3. 把 Web 自助流程 单独列为可交付范围，不要继续和人工渠道混在一个抽象里。
4. 在 CI 中强制覆盖率门槛，避免“只生成报告不阻断失败”。

9.2 短期优化

1. 给 README.md 增加“已完成 / 进行中 / 规划中”三态表，并明确更新时间。
2. 给 data/crowd_db 的骨架省份补充完整度分级，不要只靠目录存在代表能力存在。
3. 给 AI 审核报告增加更强的数据来源展示和修正建议链路。

9.3 中期优化

1. 把 Web 端做成真正的自助产品，而不是后台能力展示页。
2. 统一订单、用户、分享、报告的领域模型。
3. 建立基于真实用户案例的持续回归测试集。

---

10. 最终结论

结论一句话：
这个项目的产品规划是专业且有市场逻辑的，技术路线也整体正确，但当前最大问题不是方向，而是规划、实施和代码现状之间的同步失真。

如果按“产品是否值得继续推进”来判断，答案是值得。
如果按“实施计划是否已经与产品规划完全对齐”来判断，答案是还没有。

最准确的判断是：

核心产品方向成立，核心差异化成立，已有工程落地可见，但实施计划与产品文档仍需重新对齐，尤其是 Web 闭环、AI 审核编排、CI 门槛和文档状态治理。

---

11. 验证记录

11.1 已完成验证

• 已执行代码目录扫描与核心文档抽样阅读。
• 已执行 code-analyzer 静态分析，输出到 reports/code-analysis-review-input-2026-06-12.md。
• 已核验评审报告文件存在，当前报告共 400 行。

11.2 未完成验证

本地测试套件未能执行，原因是当前系统 Python 环境缺少 pytest：

pytest -q
# /bin/bash: line 1: pytest: command not found

python3 -m pytest -q
# /usr/bin/python3: No module named pytest

仓库存在 requirements-dev.txt，其中包含 pytest、pytest-cov、pytest-timeout、pytest-xdist、httpx、locust 等测试/性能依赖。
因此，本报告对代码健康度的判断基于静态分析和代码抽样，不声明当前测试套件通过。