> ⚠️ **历史快照（非当前真相源）**：本文件仅保留当时审查/收口结论。当前状态与执行顺序以 `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`： ```bash 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` 等测试/性能依赖。 因此，本报告对代码健康度的判断基于静态分析和代码抽样，不声明当前测试套件通过。