niuniu/gaokao-volunteer-system

Fork 0

Files

Hermes Agent 6e06e150b0

CI / pytest (Python 3.10) (push) Has been cancelled

Details

CI / pytest (Python 3.11) (push) Has been cancelled

Details

CI / pytest (Python 3.12) (push) Has been cancelled

Details

docs(cleanup): archive top-level historical reports

2026-06-18 11:01:15 +08:00

13 KiB

Raw Blame History

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 工程门禁

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. 当前真相源排序

当前建议按以下顺序理解项目状态：

代码与实跑结果（最高优先级）
- admin/
- data/orders/
- data/share/
- data/channel_sync/
- skills/gaokao-audit/
- 当前 pytest / ruff / mypy / bandit / coverage 输出
README + CHANGELOG（部分可信）
IMPLEMENTATION_PLAN_v2 / CHANNEL_INTEGRATION（部分过时，需结合代码）
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. 最短整改路径

先修真相层
- 统一 README / PRD / ROADMAP / IMPLEMENTATION_PLAN_v2 状态口径
- 旧报告降级为历史快照
再补工程门禁
- 修 CI 依赖装配
- 设定 mypy 可执行范围与配置
- 在 CI 中加入 ruff / mypy / bandit / coverage fail-under
再修真实安全问题
- X-Forwarded-For 信任边界
- 默认 admin 口令与登录节流
- CSV 公式注入
最后再决定产品方向
- 要么收缩对外口径，承认当前是运营系统
- 要么继续把用户端 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 仅保留历史参考价值
之后若继续推进，应以本报告与新的整改任务板作为当前真相源

13 KiB Raw Blame History Unescape Escape

gaokao-volunteer-system 系统性评审报告（历史快照）

1. 一句话结论

2. 本次新鲜证据

2.1 工程门禁

2.2 当前结果

2.3 CI 干净环境复核事实

3. 当前真相源排序

4. Stage 1：规格/规划对齐审查

4.1 已对齐的主线

4.2 关键漂移

A. 最严重范围错位：用户端 Web 自助产品未形成闭环

B. PRD / ROADMAP / README / IMPLEMENTATION_PLAN_v2 状态互相冲突

C. 旧报告已过时

5. Stage 2：代码质量 / 工程门禁审查

5.1 总体判断

5.2 真实高风险问题

H1. Webhook 来源 IP 信任边界错误

H2. 默认管理员弱口令 + 登录无节流

H3. CI 无法代表完整产品可构建/可测试

5.3 中风险问题

M1. 类型系统失控

M2. 覆盖率不达计划标准

M3. CSV 导出公式注入风险

M4. 异常吞噬导致审计可观测性下降

5.4 低风险与噪声

L1. Bandit B608 大量动态 SQL 报警，多数是 false positive

L2. 开发占位 JWT secret 是 intentional false positive

6. 模块真实状态表

7. 当前最准确的项目标签

不准确标签

更准确标签

8. 当前 Gate 结论

代码层 Gate

产品/范围 Gate

综合 Gate

9. 最短整改路径

10. 本报告与旧报告的关系

13 KiB

Raw Blame History