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`：

```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` 等测试/性能依赖。  
因此，本报告对代码健康度的判断基于静态分析和代码抽样，不声明当前测试套件通过。