325 lines
13 KiB
Markdown
325 lines
13 KiB
Markdown
# gaokao-volunteer-system 系统性评审报告（历史快照）
|
||
|
||
> 该文档保留 2026-06-13 当时的评审分析，但不应直接作为当前执行门禁。当前真相源请优先阅读：`docs/CURRENT_STATE.md` → `docs/ACTIVE_EXECUTION_BOARD_2026-06-13.md` → `docs/ACTIVE_REMEDIATION_2026-06-13.md`。
|
||
|
||
**评审日期**: 2026-06-13
|
||
**评审对象**: `/home/long/project/gaokao-volunteer-system`
|
||
**评审方法**: 文档交叉核对 + 关键代码抽样 + 工程门禁实跑 + 两阶段 review（规格对齐 / 代码质量）
|
||
|
||
---
|
||
|
||
## 1. 一句话结论
|
||
|
||
> 项目已经从“纯规划/纯 skill 仓库”演进为“运营后台 + 订单/分享/渠道同步 + AI 审核链路”的可运行系统，但**文档真相严重漂移、用户端 Web 自助闭环仍未落地、CI/类型/安全门禁未形成可信闭环**。当前更准确的项目标签是：**内部运营与人工服务增强系统已成形，面向用户的完整产品化交付仍未完成**。
|
||
|
||
---
|
||
|
||
## 2. 本次新鲜证据
|
||
|
||
### 2.1 工程门禁
|
||
|
||
```bash
|
||
git status --short
|
||
python3 -m pytest -q
|
||
python3 -m ruff check . --exclude .worktrees
|
||
python3 -m mypy .
|
||
python3 -m bandit -r admin data skills scripts -x .worktrees,tests,admin/tests,data/channel_sync/tests,data/orders/tests,data/share/tests,data/crowd_db/tests,skills/gaokao-audit/tests,scripts/legacy
|
||
pytest --cov=admin --cov=data --cov=skills --cov=scripts --cov-report=term-missing -q
|
||
pytest -q admin/tests
|
||
```
|
||
|
||
### 2.2 当前结果
|
||
|
||
- `git status --short`：**大量未提交修改/新增文件**，当前真实状态主要存在于 working tree，而不是稳定交付基线
|
||
- `python3 -m pytest -q`：**459 passed, 2 warnings**
|
||
- `python3 -m ruff check . --exclude .worktrees`：**All checks passed**
|
||
- `python3 -m mypy .`：**97 errors / 19 files**
|
||
- `python3 -m bandit ...`：原始输出噪声很高；聚焦后仍有若干真实问题
|
||
- `pytest --cov=admin --cov=data --cov=skills --cov=scripts --cov-report=term-missing -q`：**TOTAL 61%**
|
||
- `pytest -q admin/tests`：**115 passed**
|
||
|
||
### 2.3 CI 干净环境复核事实
|
||
|
||
- `.github/workflows/ci.yml` 只安装 `requirements-dev.txt`
|
||
- `requirements-dev.txt` **不包含** `fastapi / uvicorn / PyJWT / cryptography / pydantic`
|
||
- 因此 CI 对 `admin/*` 的 clean env 可复现性并不成立
|
||
- 这意味着“本地 pytest 通过”≠“CI 对完整产品可复现”
|
||
|
||
---
|
||
|
||
## 3. 当前真相源排序
|
||
|
||
当前建议按以下顺序理解项目状态：
|
||
|
||
1. **代码与实跑结果**（最高优先级）
|
||
- `admin/`
|
||
- `data/orders/`
|
||
- `data/share/`
|
||
- `data/channel_sync/`
|
||
- `skills/gaokao-audit/`
|
||
- 当前 pytest / ruff / mypy / bandit / coverage 输出
|
||
2. **README + CHANGELOG（部分可信）**
|
||
3. **IMPLEMENTATION_PLAN_v2 / CHANNEL_INTEGRATION（部分过时，需结合代码）**
|
||
4. **PRODUCT_TECH_REVIEW_2026-06-12 / archive/AUDIT_REPORT_2026-06-11 / archive/REMEDIATION_TASK_BOARD_2026-06-11（历史快照，不能直接继承为当前结论）**
|
||
|
||
---
|
||
|
||
## 4. Stage 1：规格/规划对齐审查
|
||
|
||
### 4.1 已对齐的主线
|
||
|
||
| 领域 | 当前状态 | 证据 |
|
||
| ----------------------------------------------------- | ------------ | ----------------------------------------------------------------------------- |
|
||
| 场景A：闲鱼/微信/学校 → 管理端录单 → 顾问交付 | **基本对齐** | `docs/BUSINESS_SCENE.md` + `admin/routes/orders.py` + `data/channel_sync/*` |
|
||
| 管理后台（认证/用户/订单/案例/仪表盘） | **已落地** | `admin/app.py`、`admin/routes/*`、`README.md` |
|
||
| AI 审核主链（解析/规则检查/扎堆/报告/CLI） | **已落地** | `skills/gaokao-audit/scripts/*.py` |
|
||
| 分享能力（短链/权限/公开分享） | **已落地** | `data/share/short_link.py`、`data/share/permission.py`、`admin/share_page.py` |
|
||
| 渠道同步（闲鱼 webhook/poller、微信/企微最小 client） | **已落地** | `data/channel_sync/*` |
|
||
| crowd_db 溯源与风险展示 | **已落地** | `data/crowd_db/*`、`scripts/gaokao-data-trace` |
|
||
|
||
### 4.2 关键漂移
|
||
|
||
#### A. 最严重范围错位：用户端 Web 自助产品未形成闭环
|
||
|
||
文档定义的场景B是：
|
||
|
||
- 用户访问 Web
|
||
- 站内先付费
|
||
- 付费后填写资料
|
||
- 自动/人工生成方案
|
||
- 站内查看 + 邮件 PDF 交付
|
||
|
||
当前代码现实：
|
||
|
||
- 仓库中**没有** `package.json`、`*.tsx`、用户端前台 Web 应用
|
||
- 只有：
|
||
- 管理后台 FastAPI
|
||
- 公开分享页
|
||
- 管理端仪表盘页面 `admin/static/dashboard.html`
|
||
- **未见用户注册/下单/支付/资料填写/邮件交付闭环**
|
||
|
||
结论：
|
||
|
||
- 当前系统更像“运营后台 + 人工服务增强链路”
|
||
- 不是“文档中描述的双流程完整产品”
|
||
|
||
#### B. PRD / ROADMAP / README / IMPLEMENTATION_PLAN_v2 状态互相冲突
|
||
|
||
- `PRD.md` 仍把 F016-F020（分享/管理后台/反扎堆/数据溯源/AI审核）标成“规划中”
|
||
- `ROADMAP.md` 仍把多项已实现能力放在后续阶段
|
||
- `IMPLEMENTATION_PLAN_v2.md` 顶层总览大量任务仍是 `📋`，但局部又写“已实现”
|
||
- `README.md` 写入了较新能力，但目录树和整体叙事仍偏旧
|
||
|
||
结论：
|
||
|
||
- 当前没有单一文档可以单独代表真实现状
|
||
- **文档真相层已经失效**
|
||
|
||
#### C. 旧报告已过时
|
||
|
||
| 文档 | 当前判断 |
|
||
| ------------------------------------------- | ---------------------------------- |
|
||
| `docs/archive/2026-06-historical-snapshots/AUDIT_REPORT_2026-06-11.md` | **严重过时** |
|
||
| `docs/archive/2026-06-historical-snapshots/REMEDIATION_TASK_BOARD_2026-06-11.md` | **严重过时** |
|
||
| `reports/PRODUCT_TECH_REVIEW_2026-06-12.md` | **部分仍有效，但若直接继承会失真** |
|
||
|
||
仍有效的旧判断：
|
||
|
||
- Web 自助闭环缺失
|
||
- 文档状态漂移
|
||
- 覆盖率/CI 硬门槛未闭环
|
||
|
||
已失真的旧判断：
|
||
|
||
- “AI 审核编排层未形成”
|
||
- “pytest 环境不可运行”
|
||
- “测试规模极低”
|
||
|
||
---
|
||
|
||
## 5. Stage 2：代码质量 / 工程门禁审查
|
||
|
||
### 5.1 总体判断
|
||
|
||
| 维度 | 状态 | 结论 |
|
||
| --------- | ---- | ------------------------------- |
|
||
| pytest | ✅ | 功能回归层当前可通过 |
|
||
| ruff | ✅ | 代码风格/显性低级错误当前可通过 |
|
||
| mypy | ❌ | 类型门禁不可用 |
|
||
| bandit | ⚠️ | 噪声很大，但存在真实问题 |
|
||
| coverage | ⚠️ | 总覆盖率仅 61%，结构性短板明显 |
|
||
| CI 完整性 | ❌ | 不是可信质量门禁 |
|
||
|
||
### 5.2 真实高风险问题
|
||
|
||
#### H1. Webhook 来源 IP 信任边界错误
|
||
|
||
- `data/channel_sync/webhook_server.py` 定义了 `_trust_x_forwarded_for()`
|
||
- 但 `_client_ip()` 实际**始终优先信任** `X-Forwarded-For`
|
||
- 结果：
|
||
- 限流可被伪造头绕过
|
||
- 审计 `remote_addr` 可被污染
|
||
|
||
这是**真实安全问题**，不是 bandit 噪声。
|
||
|
||
#### H2. 默认管理员弱口令 + 登录无节流
|
||
|
||
- `admin/config.py` 默认：`GAOKAO_ADMIN_USER=admin`, `GAOKAO_ADMIN_PASS=admin123`
|
||
- 空库会 bootstrap 管理员
|
||
- 登录接口未见失败次数限制 / 限流 / 锁定
|
||
|
||
虽然 prod 对 JWT secret 有强校验，但**admin 密码强度没有同级保护**。
|
||
|
||
#### H3. CI 无法代表完整产品可构建/可测试
|
||
|
||
- `.github/workflows/ci.yml` 只装 `requirements-dev.txt`
|
||
- 未安装 admin 运行依赖
|
||
- clean env 下 `admin/tests` 不可保证可运行
|
||
|
||
### 5.3 中风险问题
|
||
|
||
#### M1. 类型系统失控
|
||
|
||
`mypy .` 失败 97 个错误，集中在：
|
||
|
||
- `data/share/short_link.py`
|
||
- `data/cases/dao.py`
|
||
- `skills/gaokao-audit/*`
|
||
- `scripts/*`
|
||
- tests/legacy 噪声
|
||
|
||
含义不是“仓库不能跑”，而是：
|
||
|
||
- 类型门禁当前没有工程可信度
|
||
- 也无法直接接入 CI 做阻断
|
||
|
||
#### M2. 覆盖率不达计划标准
|
||
|
||
新鲜证据：
|
||
|
||
- TOTAL: **61%**
|
||
- admin 核心模块覆盖率明显偏低：
|
||
- `admin/routes/orders.py` 57%
|
||
- `admin/routes/ui.py` 55%
|
||
- `admin/users.py` 38%
|
||
- `admin/share_page.py` 14%
|
||
- `admin/errors/exceptions.py` 33%
|
||
- `admin/logging_utils.py` 23%
|
||
- skills 审核链路也有薄弱点：
|
||
- `checker_integration.py` 63%
|
||
- `report_generator.py` 67%
|
||
|
||
说明：
|
||
|
||
- `channel_sync`、`orders`、`crowd_db` 测试成熟度较高
|
||
- `admin`、`report_generator`、集成胶水层明显偏弱
|
||
|
||
#### M3. CSV 导出公式注入风险
|
||
|
||
`admin/routes/orders.py` 直接导出用户可控文本字段到 CSV，未做 Excel 公式注入防护。
|
||
|
||
#### M4. 异常吞噬导致审计可观测性下降
|
||
|
||
`data/channel_sync/webhook_server.py` 多处 `except Exception: pass`，虽然提高了兜底可用性，但也会削弱取证与排障能力。
|
||
|
||
### 5.4 低风险与噪声
|
||
|
||
#### L1. Bandit B608 大量动态 SQL 报警，多数是 false positive
|
||
|
||
例如：
|
||
|
||
- `data/orders/dao.py`
|
||
- `data/cases/dao.py`
|
||
- `data/share/short_link.py`
|
||
- `admin/stats.py`
|
||
|
||
这些位置多数是：
|
||
|
||
- 拼接**白名单列名/固定 where 片段**
|
||
- 值仍通过参数绑定传入
|
||
|
||
需要人工甄别，**不能直接按 SQL 注入漏洞上报**。
|
||
|
||
#### L2. 开发占位 JWT secret 是 intentional false positive
|
||
|
||
- `admin/config.py` 的 `_DEV_JWT_SECRET` 在 prod 启动时会被阻止
|
||
- 它本身不是生产漏洞，但会污染 bandit 输出
|
||
|
||
---
|
||
|
||
## 6. 模块真实状态表
|
||
|
||
| 模块 | 真实状态 | 说明 |
|
||
| ---------------------- | ------------------------------------ | --------------------------------------------------------- |
|
||
| `admin/` | **Partial / 可运行但质量门禁不闭环** | 后台功能已明显成形；CI 依赖、类型、覆盖率仍薄弱 |
|
||
| `data/orders/` | **Done-ish / 质量较好** | DAO、状态机、加密、CLI、测试都比较成熟 |
|
||
| `data/channel_sync/` | **Done-ish / 质量较好** | webhook/poller/adapter/monitor 已成形，存在 XFF 安全缺口 |
|
||
| `data/share/` | **Partial / 能用但有安全与类型债** | 功能全，但密码哈希策略偏弱，类型门禁差 |
|
||
| `data/cases/` | **Partial** | CRUD 有了，但类型安全与工程化不足 |
|
||
| `data/crowd_db/` | **Done-ish / 数据能力较强** | loader/trace/risk/report 成熟，但骨架省份仍有低置信度数据 |
|
||
| `skills/gaokao-audit/` | **Partial to Good** | 主链已落地，集成胶水层覆盖率与类型质量不足 |
|
||
| 用户端 Web 产品 | **Not started / Missing main chain** | 只有管理端与分享页，没有用户端自助闭环 |
|
||
|
||
---
|
||
|
||
## 7. 当前最准确的项目标签
|
||
|
||
### 不准确标签
|
||
|
||
- “完整产品”
|
||
- “双流程（人工 + Web 自助）已完成”
|
||
- “工程门禁完善、可稳定交付”
|
||
|
||
### 更准确标签
|
||
|
||
> **高考志愿填报运营与审核增强系统（已具备后台、订单、分享、渠道同步、AI审核主链），但用户端 Web 自助产品与工程化质量门禁仍未闭环。**
|
||
|
||
---
|
||
|
||
## 8. 当前 Gate 结论
|
||
|
||
### 代码层 Gate
|
||
|
||
- `pytest`: ✅
|
||
- `ruff`: ✅
|
||
- `mypy`: ❌
|
||
- `bandit`: ⚠️（有噪声，但存在真实中高风险）
|
||
- `coverage`: ⚠️（总量与关键模块均未达理想值）
|
||
|
||
### 产品/范围 Gate
|
||
|
||
- 场景A（人工服务）: ✅ 基本闭环
|
||
- 场景B（用户端 Web 自助）: ❌ 未闭环
|
||
- 文档真相: ❌ 漂移严重
|
||
|
||
### 综合 Gate
|
||
|
||
**结论: REQUEST_CHANGES / 条件通过，不可宣称整体完成。**
|
||
|
||
---
|
||
|
||
## 9. 最短整改路径
|
||
|
||
1. **先修真相层**
|
||
- 统一 README / PRD / ROADMAP / IMPLEMENTATION_PLAN_v2 状态口径
|
||
- 旧报告降级为历史快照
|
||
2. **再补工程门禁**
|
||
- 修 CI 依赖装配
|
||
- 设定 mypy 可执行范围与配置
|
||
- 在 CI 中加入 ruff / mypy / bandit / coverage fail-under
|
||
3. **再修真实安全问题**
|
||
- X-Forwarded-For 信任边界
|
||
- 默认 admin 口令与登录节流
|
||
- CSV 公式注入
|
||
4. **最后再决定产品方向**
|
||
- 要么收缩对外口径，承认当前是运营系统
|
||
- 要么继续把用户端 Web 自助闭环真正落地
|
||
|
||
---
|
||
|
||
## 10. 本报告与旧报告的关系
|
||
|
||
- 本报告是 **2026-06-13 的新鲜实跑结论**
|
||
- `docs/archive/2026-06-historical-snapshots/AUDIT_REPORT_2026-06-11.md`、`docs/archive/2026-06-historical-snapshots/REMEDIATION_TASK_BOARD_2026-06-11.md`、`reports/PRODUCT_TECH_REVIEW_2026-06-12.md` 仅保留历史参考价值
|
||
- 之后若继续推进，应以本报告与新的整改任务板作为当前真相源
|