gaokao-volunteer-system/CHANGELOG.md

变更日志

记录高考志愿填报智能系统的所有变更。

---

v2.1.8 (2026-06-24) — 测试弃用 warning 清零

🧪 测试依赖

• requirements-dev.txt 新增 httpx2>=2.0.0
• starlette.testclient → httpx2 的弃用 warning 已清除

✅ 验证

• ./.venv/bin/python -m pytest -q admin/tests/test_order_status_page.py admin/tests/test_web_public.py admin/tests/test_web_public_content_pages.py admin/tests/test_web_public_review_flow.py admin/tests/test_web_public_portal_info.py admin/tests/test_order_deletion.py admin/tests/test_routes_cases.py admin/tests/test_routes_stats_dashboard.py admin/tests/test_admin_ui_pages.py admin/tests/test_order_info_form.py data/orders/tests/test_schema.py data/orders/tests/test_public_flow.py tests/test_backup_restore_service_level.py → 149 passed

v2.1.7 (2026-06-24) — 严格审查汇总版与最新入口切换

📄 审查与文档

• 新增 reports/STRICT_SYSTEM_REVIEW_2026-06-24.md
  • 以当前仓库状态重写严格审查汇总版，不再继续在 6/23 过程稿上叠加历史结论
  • 明确当前结论：前台主链路、后台安全边界、恢复演练口径、后台录单契约、第五轮补充问题均已修复
• docs/CURRENT_STATE.md 已切换为以 STRICT_SYSTEM_REVIEW_2026-06-24.md 作为最新严格审查结论
• docs/NAVIGATION.md 已新增 6/24 汇总版入口，同时保留 6/23 过程稿作为历史轨迹参考

✅ 验证

• ./.venv/bin/python -m pytest -q admin/tests/test_order_status_page.py admin/tests/test_web_public.py admin/tests/test_web_public_content_pages.py admin/tests/test_web_public_review_flow.py admin/tests/test_web_public_portal_info.py admin/tests/test_order_deletion.py admin/tests/test_routes_cases.py admin/tests/test_routes_stats_dashboard.py admin/tests/test_admin_ui_pages.py admin/tests/test_order_info_form.py data/orders/tests/test_schema.py data/orders/tests/test_public_flow.py tests/test_backup_restore_service_level.py → 149 passed, 1 warning

v2.1.6 (2026-06-23) — 主链路真实 TestClient 覆盖收口

🧪 测试可信度收口

• 用户端主链路不再依赖 RouteClient 自证
  • 公开页、内容页、资料页、状态页、报告页、CWB、full-plan、payment-success 的关键页面访问已迁到真实 TestClient
  • POST /api/public/orders、POST /review/action（真实 form + 303）、POST /pay/mock/{payment_id}/complete 的主链路已迁到真实 client
• 前台关键测试文件已清零 RouteClient
  • admin/tests/test_web_public.py
  • admin/tests/test_web_public_content_pages.py
  • admin/tests/test_web_public_review_flow.py
  • admin/tests/test_web_public_portal_info.py
  • admin/tests/test_order_status_page.py
• 剩余 RouteClient 已降级为非前台主证据
  • 仅作为仓库中的轻量辅助夹具保留，不再用于这批关键前台测试文件

📄 文档

• 新增 reports/TEST_CLIENT_COVERAGE_2026-06-23.md
• reports/STRICT_SYSTEM_REVIEW_2026-06-23.md 与覆盖报告已互链
• docs/CURRENT_STATE.md 已将两份 6/23 报告纳入真相源优先级前部

✅ 验证

• ./.venv/bin/python -m pytest -q admin/tests/test_web_public.py admin/tests/test_web_public_review_flow.py admin/tests/test_web_public_portal_info.py → 54 passed, 1 warning
• ./.venv/bin/python -m pytest -q admin/tests/test_order_status_page.py admin/tests/test_web_public.py admin/tests/test_web_public_content_pages.py admin/tests/test_web_public_review_flow.py admin/tests/test_web_public_portal_info.py data/orders/tests/test_schema.py → 89 passed, 1 warning

v2.1.5 (2026-06-23) — P1/P2 页面升级与轻量版本管理

✨ 新增

• Step 2-4 / P2 偏好收口
  • Portal Step 2 新增 target_cities 输入控件
  • submit_order_info 现在保留 profile_versions[] 与 latest_profile_version_id，相同快照不重复记版本
• 报告页 / 冲稳保页辅助能力升级
  • 报告页新增“基于最新档案生成 / 基于历史档案版本生成，建议刷新”判断
  • 报告页与冲稳保页新增政策中心、同分段参考入口与辅助判断因子区块
  • 完整规划入口页新增版本历史与辅助判断因子区块
• 统一信任条
  • 政策中心与同分段参考页改为共用统一信任条：来源、更新时间、适用范围、适用省份、置信等级、边界文案
  • 同分段页继续保留“非高置信数据不得作为强推荐依据”约束
• 轻量报告版本元数据
  • order_intakes.payload_json 新增 report_versions[] / latest_report_version_id
  • 报告页外显与 profile_versions[] / review_results{} 形成最小版本关系

🧪 测试

• admin/tests/test_web_public_portal_info.py
  • test_portal_info_page_renders_target_cities_field
  • test_submit_order_info_creates_profile_version_history_without_duplicate_snapshots
• admin/tests/test_web_public_review_flow.py
  • test_cwb_page_links_policy_same_score_and_auxiliary_factors
  • test_report_page_shows_latest_profile_state_and_helper_links
  • test_report_page_warns_when_based_on_historical_profile_version
  • test_full_plan_page_shows_profile_versions_and_assessment_context
• admin/tests/test_web_public_content_pages.py
  • test_policy_and_same_score_pages_expose_helper_navigation
• 回归：./.venv/bin/python -m pytest -q admin/tests/test_web_public_content_pages.py admin/tests/test_web_public_portal_info.py admin/tests/test_web_public_review_flow.py data/orders/tests/test_schema.py → 60 passed

v2.1.4 (2026-06-23) — 审核优先主线第三轮质量收敛

✨ 新增

• 审核页最小输入 / 约束 / 输出 / 分流四区块收口
  • admin/routes/web_public.py 的 ReviewResultContract 新增 review_input_summary / review_input_attachments / review_constraints
  • /review/start 现在支持承接首页 province / score / goal / consult 查询参数，并把最小约束与现有方案说明写入轻量 review result
  • 审核结果页不再只展示 JSON，占位页已补齐“审核输入 / 最小约束 / 审核输出摘要 / 下一步分流”四区块
• 首页咨询卡回到审核主线
  • 首页咨询表单由 /pricing 改为 /review/start
  • 增加隐藏字段 source=home，保持 review_entry_source 可追踪
• 工作台主动作按资料完整度收口
  • 当 Step 1 已完成且还没有最近一次复核结果时，首页工作台默认动作改为“开始方案复核”
  • 仍保留“继续补充 Step 1”与“继续查看最近一次复核”两种路径

🐛 修复

• 第三轮质量收敛残留：首页咨询卡此前仍把用户导向 /pricing，与 P0“先审核再规划”主线不一致
• 第三轮质量收敛残留：审核页此前只有轻量 JSON 占位，未满足“输入区 / 最小约束区 / 结果区 / 分流区”结构验收
• 第三轮质量收敛残留：Step 1 已完整但无复核结果时，首页工作台仍默认指向补资料，造成主动作偏移

🧪 测试

• admin/tests/test_web_public_review_flow.py
  • test_landing_page_review_consult_form_targets_review_start
  • test_landing_page_uses_review_as_workspace_primary_action_when_step1_complete
  • test_review_start_page_renders_input_constraints_result_and_diversion
• 回归：./.venv/bin/python -m pytest -q admin/tests/test_web_public.py admin/tests/test_web_public_content_pages.py admin/tests/test_web_public_portal_info.py admin/tests/test_web_public_review_flow.py data/orders/tests/test_schema.py → 70 passed

v2.1.3 (2026-06-20) — 生产加固 + L-A 送审前修复 + crowd_db 质量契约

✨ 新增

• admin /health 端点增强 (6/20 加固)
  • 主键契约: status: "ok" (PRODUCTION_DEPLOYMENT_CHECKLIST §4 liveness probe)
  • 新增 checks 子对象: db_writable / disk_writable / settings_valid
  • DB 可写: connect + CREATE TEMP TABLE + INSERT + SELECT + DROP
  • 磁盘可写: 在 ops_alert_log_path 目录创建临时文件 + 删除
  • settings_valid: 复用 is_jwt_secret_secure 判断配置就绪
  • 仍不暴露环境/路径/版本细节
• _enforce_jwt_secret_policy (P2-4 同级, 6/20 加固)
  • GAOKAO_ENV=prod + dev 默认 JWT secret → RuntimeError fail-closed
  • GAOKAO_ENV=prod + JWT secret 长度 < 32 → RuntimeError fail-closed
• _enforce_default_admin_password_policy (6/20 加固)
  • GAOKAO_ENV=prod + GAOKAO_ADMIN_PASS=admin123 → RuntimeError fail-closed
  • GAOKAO_ENV=prod + 密码 < 10 字符 / 字符类 < 3 → RuntimeError fail-closed
• tests/test_crowd_db_data_quality.py (Q-A 闭环, CROWD_DB_DATA_QUALITY §7 承诺的锁死文件)
  • 锁住 27 省总数 + 仅湖南 high + 其它 26 省 ≤ usable + 高考生源大省不在 high 集合
  • 锁住 data_year=2025 (6/25 后需显式更新)
  • 防止"27 省高置信"合规假象回归
• admin 后台 footer 隐私政策链接 (L-A R7)
  • admin/static/dashboard.html (592 行) 加 <footer> 块, 链接 /privacy + /deletion-policy + /service-terms
  • admin/routes/ui.py 内联 admin/orders/new 模板 (line 182 闭包) 同步加 footer
  • 与 portal 前台 _render_footer_links() 同口径

🐛 修复

• L-A R1: docs/LEGAL_PRIVACY_BASELINE.md §6 consent_channel 列表移除孤儿 admin 渠道值 (代码侧从未实际产生)
• L-A R4: docs/LEGAL_PRIVACY_BASELINE.md §7 "已具备/尚缺" 同步 6/20 A-2 + T12-D 进展 (后台/外部渠道补录同意审计 + 数据删除 SOP 脚本化)

📝 文档

• docs/LEGAL_PRIVACY_BASELINE.md §6 增注释说明 admin 渠道值移除原因
• docs/LEGAL_PRIVACY_BASELINE.md §7 重写"已具备/尚缺"分区, 显式归到 6/20 增量
• docs/CURRENT_STATE.md 状态词段升级 (见下)
• docs/ACTIVE_REMEDIATION_2026-06-20.md 加固项标记 ✅ completed
• reports/PRODUCTION_HARDENING_AUDIT_2026-06-20.md (子代理失信, 主代理自跑)
• reports/LA_LEGAL_PRIVACY_PRE_AUDIT_2026-06-20.md (子代理 363 行交付)
• reports/QA_CROWD_DB_NON_HUNAN_DENSITY_AUDIT.md (子代理 45 行交付)

🧪 测试

• admin/tests/test_health.py:
  • test_health_endpoint_returns_minimal_readiness_only (升级: 断言 checks 子对象)
  • test_load_settings_prod_rejects_dev_jwt_secret (新)
  • test_load_settings_prod_rejects_short_jwt_secret (新)
  • test_load_settings_prod_rejects_default_admin_password (新)
• data/crowd_db/tests/test_crowd_db_data_quality.py (新, 8 个测试):
  • test_total_provinces_is_27
  • test_hunan_is_the_only_high_quality_province
  • test_hunan_confidence_meets_high_threshold
  • test_non_hunan_provinces_not_high
  • test_high_population_provinces_acknowledged_as_skeleton_or_lower
  • test_quality_levels_are_valid_enum
  • test_confidence_values_in_valid_range
  • test_data_year_is_2025_until_2026_published

---

v2.1.2 (2026-06-20) — A-2 后台/外部渠道补录同意审计统一化

✨ 新增

• admin POST /api/orders 强制要求 consent 块（A-2 落地）
  • CreateOrderRequest 新增必填字段 consent: ConsentInfo
  • ConsentInfo.consent_method 白名单: verbal_chat / phone_recording / screenshot / written_form / self_declared
  • ConsentInfo.consent_note 可选, 表示"已确认但无备注"
  • 缺失或非法 → HTTP 422
  • 4 个 source (xianyu / wechat / web / school) 一致处理
• Order 冗余字段: consent_method + consent_given_at
  • 落 orders 表, 避免每次列表 join order_intakes
  • schema 增量升级: ALTER TABLE orders ADD COLUMN consent_method TEXT (幂等)
  • schema 增量升级: ALTER TABLE orders ADD COLUMN consent_given_at TEXT (幂等)
  • DAO _WRITABLE_COLUMNS 加新字段
• 创建订单后同步写 order_intakes 记录
  • 与 portal 路径同口径: consent_version / consent_scope / consent_channel / consent_operator / consent_method / consent_given_at / consent_note
  • consent_channel = 渠道 source (xianyu / wechat / school / web)
  • consent_operator 严格按 LEGAL_PRIVACY_BASELINE §4 白名单 self / guardian / admin_import:
    • web 渠道: guardian (用户本人或监护人自助 portal, 与 intake_store.save 默认值一致)
    • 其他渠道 (xianyu / wechat / school): admin_import (后台代录, 同意来源是渠道商)

🐛 修复

• 后台代录合规盲区: 6/20 之前 admin create_order 路径完全不入任何 consent 字段 (consent 字段在 admin/routes/orders.py grep 0 命中), 直接违反 LEGAL_PRIVACY_BASELINE §6。现已统一审计口径。

📝 文档

• docs/LEGAL_PRIVACY_BASELINE.md §6 已隐含 admin 补录需 consent 字段, 本次落地后真正闭环
• docs/ACTIVE_REMEDIATION_2026-06-20.md A-2 状态从 pending 升级为 completed
• CHANGELOG.md 顶部加 v2.1.2 段

🧪 测试

• test_create_order_rejects_missing_consent_block[xianyu|wechat|school|web] (4 个参数化)
• test_create_order_writes_intake_record_with_consent_audit
• test_create_order_external_channel_marks_consent_operator_as_admin
• test_create_order_rejects_invalid_consent_method
• test_order_detail_returns_consent_method_and_given_at
• 更新: test_create_order_returns_masked_payload_with_history (加 consent 块)

---

v2.1.1 (2026-06-20) — T12-D retention cleanup 生产化部署验收

🐛 修复

• retention cleanup 多订单 anonymize 崩溃（P0 — T12-D 端到端 acceptance 必现）
  • 现象: retention_cleanup.run_cleanup(apply=True) 在一次命中 ≥ 2 笔终端态订单时， 第二笔开始全部 sqlite3.ProgrammingError: Cannot operate on a closed database
  • 根因: OrdersDAO.__exit__ 不区分连接所有权，对外部 service 传入的 self._conn 也 close()。deletion_service.anonymize_order 把 service 持有的 连接包成 OrdersDAO(self._conn) 走 with-block，第一笔执行完就把连接关掉
  • 触发条件: 生产 retention_days=180 + 周日 03:30 timer 触发时极易命中
  • 修复: OrdersDAO.__init__ 新增 owns_conn: bool = False 参数； __exit__ 仅在 owns_conn=True 时 close；connect() classmethod 创建的连接自动设 owns_conn=True（保持原行为）
  • 回归测试: tests/test_retention_cleanup.py::test_retention_cleanup_apply_anonymizes_multiple_old_orders_in_sequence 锁住多订单连续 anonymize 契约

📝 文档

• docs/DELIVERY_RETENTION_OPS_RUNBOOK.md §8 新增 T12-D 本地端到端 acceptance 步骤
  • 验收通过判定表（6 项全过）+ 部署前 checklist
• 历史 bug 背景已写入 runbook §8.4，避免后续误判为"运行环境问题"

---

v2.1 (2026-06-13)

🚧 进行中

新增（T5.3 已完成）

• 📝 T5 集成测试与文档收口
  • T5.1 端到端主链已固化到 tests/test_t5_e2e_workflows.py：覆盖“咨询→方案生成 / 审核→报告 / 订单→交付 / 升级流程 / 数据溯源展示”5 条主链
  • T5.2 性能与并发门禁已固化到 tests/test_t5_performance.py：
    • gaokao-quick-3min.py 的真实 parse_quick_response + generate_quick_summary + generate_quick_recommendation 链路 100 次执行断言 < 5s
    • locustfile.py 对 admin.app 做 10 并发、15 秒 headless 压测，断言聚合成功率 >95%
  • T5.3 文档同步：重写 docs/API.md、docs/ARCHITECTURE.md 以匹配当前已落地真相，并补充 T5 验证入口与当前系统边界说明
  • 定向验证：python3 -m pytest tests/test_t5_e2e_workflows.py tests/test_t5_performance.py -q 通过；其中性能基准覆盖 100 次方案生成与 10 并发后台访问两条验收路径
  • 当前定位修正：项目应描述为“管理后台 + 订单/分享/渠道同步 + AI 审核链路”的可运行系统；用户端 Web 自助闭环仍未落地

新增（T6.4 已完成）

• ✨ 管理后台订单管理 admin/routes/orders.py
  • 端点落地：GET /api/orders（真实列表）/ GET /api/orders/{id}（详情 + 状态历史）/ GET /api/orders/export（CSV 导出）/ POST /api/orders（手工录单）/ PATCH /api/orders/{id}（业务字段更新 + 状态流转 + 退款）
  • 状态机守护：写路径复用 OrdersDAO.update() 与 transition_status()，非法流转统一映射到 E02301，不允许绕过 6 态状态机直接写库
  • 默认脱敏：列表、详情和 CSV 导出均走 Order.to_dict(decrypt_sensitive="mask")，避免管理后台直接导出完整手机号/身份证号
  • 手工兜底：支持 external_id 留空的人工补录路径，与 docs/CHANNEL_INTEGRATION.md 约定一致；退款仅更新本地订单状态，不主动触发第三方退款 API
  • 测试 6 个全部通过（admin/tests/test_routes_orders.py）：创建、列表/详情、PATCH 更新+付款、退款、非法状态冲突、CSV 导出
  • 定向验证：python3 -m pytest admin/tests/test_routes_orders.py admin/tests/test_routes.py -q → 20 passed；ruff check admin/routes/orders.py admin/tests/test_routes_orders.py admin/tests/test_routes.py 通过
  • 文档同步：README.md 新增 T6.4 章节；docs/plans/T6-admin-mvp.md 标记 T6.4 已落地并更新路由清单

新增（T6.2 已完成）

• ✨ 管理后台仪表盘 — 真实 SQL 聚合层 admin/stats.py（434 行）
  • 端点落地：GET /api/stats/dashboard（一站式仪表盘）+ GET /api/stats/orders（沿用 T6.1 stub 字段名，去掉 _stub 标记）
  • 纯函数聚合层：build_dashboard_payload / compute_summary / compute_by_status / compute_by_source / compute_by_service_version / compute_trends / generate_day_series
  • 响应契约：summary(订单/用户/收入 + 今日/7d/30d 切片 9 字段) + by_status / by_source / by_service_version (完整 0 填充) + trends (today=1, 7d=7, 30d=30 个点, 日粒度, 0 填充) + generated_at
  • 关键口径：
    • 收入 = paid / serving / delivered / completed 四态订单的 amount_cents 累计值；pending（未付款）与 refunded（已退款）排除
    • 趋势桶粒度 = 日（UTC，YYYY-MM-DD），用 substr(created_at, 1, 10) 切片
    • 0 填充 = 窗口内的"无订单日"也返回 0 点，前端拿到稠密序列
    • 数据源隔离 = orders 走 GAOKAO_ORDERS_DB_PATH（默认 data/orders.db），admin_users 走 GAOKAO_DB_PATH（默认 data/orders/admin.db）
    • 不读 PII：统计路径只触碰 amount_cents / status / source / service_version / created_at
  • 配置新增：Settings.orders_db_path（GAOKAO_ORDERS_DB_PATH 环境变量，默认 data/orders.db），与 data.channel_sync.webhook_server 已有的同名变量对齐
  • 测试 12 个全部通过（admin/tests/test_routes_stats_dashboard.py）：
    • 鉴权（无 token 401 / 有 token 200）
    • 空库形状契约：summary / by_* / trends 三层结构稳定
    • 趋势序列：1 / 7 / 30 个点，按日期严格升序
    • 0 填充点：包含完整三字段（date / orders / revenue_cents）
    • 真实数据：窗口边界（45 天前的订单被 30d 窗口排除，但计入 total）
    • 收入口径：pending / refunded 不计入 revenue
    • 0 填充：范围内无订单的日也返回 0 点
    • 兼容层：/api/stats/orders 字段名不变，_stub 标记已移除
  • T9.3 已知缺口已闭环：admin/tests/conftest.py 新增 orders_db autouse fixture（T6.2 起，所有测试默认带空 orders DB），pytest -q admin/tests 87/87 通过
  • 测试套件：pytest -q admin/tests 87/87 passed；pytest -q 仓库全量 392/392 passed；ruff check admin/stats.py admin/routes/stats.py admin/tests/test_routes_stats_dashboard.py admin/tests/conftest.py admin/config.py admin/tests/test_routes.py All checks passed
  • 文档同步：docs/plans/T6-admin-mvp.md 新增 §10（T6.2 设计与 DoD）；§12 后续任务衔接标 [x]；README.md 新增 T6.2 章节；CHANGELOG.md 本条

新增（T9.3 已完成）

• ✨ 结构化 JSON 日志 admin/logging_utils.py
  • 新增 JsonLogFormatter：单行 JSON 输出 ts / level / logger / msg / ctx / exc
  • 新增 log_event() / log_event_exc()：业务侧一行写结构化事件，避免散落字符串拼接
  • 新增 contextvars 请求上下文：自动注入 request_id / path / method，并在请求结束后清理，避免串请求污染
  • admin/app.py 新增 request_context_middleware 与 --log-format json|plain 启动参数；CLI 默认输出 JSON，保留 plain 便于本地调试
  • admin/errors/exceptions.py 的 BusinessError / HTTPException / RequestValidationError / 兜底异常日志全部升级为结构化事件
  • 新增 admin/tests/test_logging.py 8 个测试，覆盖 formatter、上下文绑定、异常 traceback、FastAPI 端到端 JSON 日志
  • 定向验证通过：pytest -q admin/tests/test_logging.py admin/tests/test_errors.py = 34/34 passed；ruff check admin/app.py admin/errors/exceptions.py admin/logging_utils.py admin/tests/test_logging.py admin/tests/test_errors.py 通过
  • 已知缺口（T6.2 已闭环）：pytest -q admin/tests 之前有 1 个非 T9.3 失败（test_stats_orders_real_shape 报 sqlite3.OperationalError: no such table: orders）— 根因是 stats 端点读 orders 表，但 T6.1 阶段 conftest 没建 orders DB；T6.2 在 conftest 加 orders_db autouse fixture 闭环，当前 pytest -q admin/tests 87/87 通过

新增（T4.3 已完成）

• ✨ 订单管理 CLI scripts/gaokao-order-manager + data/orders/cli.py
  • 子命令落地：create / list / show / update / pay / deliver / stats
  • 默认 JSON 输出，订单详情默认走 Order.to_dict() 遮罩模式，避免 CLI 直接泄露完整手机号/身份证
  • create 直接复用 OrdersDAO.create()；show 返回订单详情 + order_status_history
  • update 只允许业务字段，空更新返回 exit code 2，继续强制 status 变更走 DAO 状态机
  • pay 推进 pending -> paid；deliver 在 paid 时自动串联 serving -> delivered，兼容已在 serving 的最后一步交付
  • stats 输出 total_orders / by_status / by_source / by_service_version
  • 新增 data/orders/tests/test_cli.py 5 个 pytest 用例：
    • 脚本级端到端主链路（create/list/show/update/pay/deliver/stats）
    • 缺失订单错误码
    • 空更新防御
    • 模块内 direct-main 覆盖，data.orders.cli 覆盖率 90%
  • 定向验证：pytest -q data/orders/tests/test_cli.py 5/5 passed；pytest -q data/orders/tests 166/166 passed；ruff check data/orders/cli.py data/orders/tests/test_cli.py scripts/gaokao-order-manager 通过；py_compile 通过
• 📝 data/orders/README.md 新增 T4.3 CLI 使用示例与子命令语义

新增（T4.2 已完成）

• ✨ 订单 DAO 数据访问层 data/orders/dao.py（530 行，OrdersDAO 类）
  • CRUD 完整：create() / get() / get_by_external_id() / find_by_phone() / list() / count() / stats_by_status() / update() / delete()
  • 事务守护：dao.transaction() 上下文管理器；嵌套语义（外层在事务中时内层不重复 commit，异常统一回滚外层）
  • 加密透明化：API 入口接收 Order dataclass（明文 PII），DAO 内部用 to_db_row() 加密落盘 / from_db_row() 解密读回；调用方无需接触 *_enc 字段
  • 状态机守护：transition_status() 走 assert_valid_transition() 单事务内 UPDATE orders + INSERT order_status_history；非法抛 InvalidStateTransition 并回滚
  • 时间戳联动：paid → paid_at / serving → started_at / delivered → delivered_at / completed → completed_at 由状态自动置位（COALESCE 保留首次值）
  • 幂等 upsert：upsert_by_external_id() 接管 T8.1 闲鱼 Webhook 路径，4 种 action 与 data/channel_sync/dao_extension.py 完全对齐（inserted / updated / unchanged / illegal_transition）
  • 防御设计：_row_factory_ctx() 临时切 sqlite3.Row、退出后恢复外部 row_factory；update() 显式拒绝 status 字段（强制走 transition_status()）
  • 51 个 pytest 用例全绿（覆盖加密透明化、状态机合法/非法路径、事务回滚、upsert 4 种 action、状态历史时间线、row_factory 不污染、删除 cascade）
  • data/orders 模块总测试 163/163 通过（含 T4.1 既有 112 + T4.2 新增 51）；data/ 全模块 386/386 通过；ruff 0 warning
• 🔧 data/orders/__init__.py 导出 DAO 公共 API：OrdersDAO / UpsertResult / StatusChange / OrderNotFound / DuplicateOrder 一行 import
• 📝 data/orders/README.md 更新 T4.2 DAO 一览表、加密透明化边界表、DoD 勾选、API 下游衔接

新增（T2.4 已完成）

• ✨ 扎堆报告生成器 risk_report.py（data/crowd_db/risk_report.py，183 行）
  • build_crowd_risks(plan, user_score, province, loader=None) — 把 crowd_detector.detect_crowd_risk 的 RiskFinding 列表转换为 templates/audit_report.html 模板所需的 crowd_risks 字典格式
  • 三色 emoji 标识：high → 🔴、medium → 🟡、low → 🟢（随 RISK_LEVEL_META 自动匹配）
  • 模板字段完整：school / major / frequency / predicted_increase / risk_level / risk_level_label / risk_emoji / platforms / alternatives
  • alternatives 字段重映射：name → school，score 强制 int（防御非数字字符串）
  • 辅助能力：
    • group_by_risk() — 按风险等级分组（永远返回 high/medium/low 三个 key）
    • format_risk_summary() — 单行汇总（如 "🔴 1 个高风险、🟡 2 个中风险"），给报告顶部用
    • render_risk_table() — CLI / 微信消息场景的纯文本表格（含替代院校行）
  • 类型设计：用 Protocol 定义 _LoaderProtocol，避免对 CrowdDBLoader 强依赖（支持 mock 注入与未来的不同实现）
  • 22 个 pytest 单元测试全部通过（三色 emoji / 字段完整性 / 替代项重映射 / 防御性 fallback / 空方案 / 不存在省份 / 自定义 loader 注入）
• ✨ 端到端集成验证脚本 scripts/verify_t2_4_e2e.py（95 行）
  • 用真实湖南 575 分数据 + audit_report.html 模板渲染一遍
  • 断言：模板必需字段全部存在 / alternatives 重映射正确 / 三色 emoji 在渲染输出可见
  • 跑法：python3 scripts/verify_t2_4_e2e.py
  • 6/6 集成断言通过
• ✅ 质量门禁
  • data/crowd_db/tests/ 105/105 通过（含本次新增 22 + 历史 83）
  • 仓库全量 pytest：392 passed
  • ruff check data/crowd_db/ scripts/verify_t2_4_e2e.py — All checks passed
  • validate_template.py 仍 PASS（模板字段契约未破坏）

新增（T2.5 已完成）

• ✅ 扎堆检测单元测试 T2.5 — data/crowd_db/tests/test_crowd_detector.py 由 35 增至 55 个测试（新增 20 个）
  • 用例 1 高风险识别：test_high_risk_use_case_frequency_4_full_payload（freq=4 全平台 + predicted_increase + alternatives）/ test_high_risk_boundary_frequency_exactly_4（>=4 闭合区间边界）/ test_high_risk_distinct_from_medium_and_low（high/medium 互不混淆）
  • 用例 2 替代方案：test_alternatives_use_case_contains_required_keys（每个 alt 必须含 name/major/score, 0-100 区间）/ test_alternatives_use_case_sortable_by_score（detector 透传 alternatives 字段不丢）/ test_alternatives_use_case_empty_list_is_valid（空列表合法）
  • 用例 3 跨省份：test_cross_province_hunan_hit_guangdong_miss（湖南 575 命中 vs 广东 575 无数据隔离）/ test_cross_province_beijing_at_690（同校不同省命中不同记录 — 清华 工科试验班）/ test_cross_province_loader_called_with_correct_province（province 透传给 loader, 不做全局查询）
  • 用例 4 异常处理：test_exception_use_case_loader_returns_none_field（name=None 不崩）/ test_exception_use_case_loader_returns_non_dict（混入 None/str/int 时优雅过滤）/ test_exception_use_case_loader_raises_propagates（loader 抛错向上传播）/ test_exception_use_case_unrecognized_entry_type（int/float/object 走 str 兜底）/ test_exception_use_case_entry_with_int_school_dict（school=0 falsy 跳过）/ test_exception_use_case_province_is_none（province=None 不抛）/ test_exception_use_case_tuple_with_non_string_school（tuple 元组非 str school 走 str() 兜底）/ test_exception_use_case_dict_with_truthy_non_string_school（0.5 这种 truthy 非 str school 走 str() 兜底）/ test_exception_use_case_dict_with_name_truthy_non_string（name 字段 truthy 非 str 同样兜底）/ test_exception_use_case_single_element_tuple_non_string（单元素 tuple 非 str 兜底）/ test_exception_use_case_malformed_frequency_in_record（frequency="not a number"/None 时 try/except 按 0 处理）
• 🛡️ crowd_detector.py 根因加固 — 与测试同步，detector 主循环加入三层防御：
  • if not isinstance(rec, dict): continue — 防止 loader 混入非 dict 元素时 rec["name"] 抛 TypeError
  • if not isinstance(rec_name, str) or not rec_name.strip(): continue — 防止 name 缺失/非 str 时 .strip() 抛 AttributeError
  • try/except (TypeError, ValueError): freq = 0 — 防止 frequency 字段异常时 int(...) 崩溃
  • _normalize_entry 增加 truthy 非 str school 的 str() 兜底（dict / tuple / list 三分支）
  • 取值统一用 or 兜底空值：rec.get("platforms") or [] / rec.get("predicted_increase") or 0 / rec.get("alternatives") or []
• ✅ 质量门禁
  • crowd_detector.py 单模块覆盖率：93%（101 statements / 7 missed 仅 __main__ CLI demo 块）
  • 远高于 T2.5 PRD 阈值 ≥80%
  • data/crowd_db/tests/test_crowd_detector.py 55/55 passed
  • data/crowd_db/tests/ 全量 125/125 passed（不动 T2.1/T2.2/T2.4 既有测试）
  • pytest -q --ignore=data/orders 仓库全量 249 passed
  • ruff check data/crowd_db/ — All checks passed

新增（T1.3 已完成）

• ✨ 方案解析器 plan_parser.py（skills/gaokao-audit/scripts/plan_parser.py，295 行）
  • 解析大厂AI志愿方案文本（纯文本/PDF提取/截图OCR）→ ParsedPlan dataclass
  • 字段提取：省份（27 省 + 别名）、分数、位次、选科、来源（千问/元宝/百度/豆包）、志愿列表
  • 志愿行识别支持 4 种行首编号格式：1. xxx / 1、xxx / 1) xxx / 1 xxx（PDF 提取常见）
  • 学校/专业分隔支持 4 种风格：学校 - 专业 / 学校：专业 / 学校（专业组） / 学校 专业（按大学/学院关键字兜底）
  • 健壮边界：空文本/无志愿/编号异常均返回 ParsedPlan 默认值，不抛异常
  • CLI：python3 -m skills.gaokao-audit.scripts.plan_parser <file> 输出 JSON
  • 10 个 pytest 单元测试全部通过（基础解析/志愿列表/省份别名/选科/PDF 格式/空文本/无志愿/编号多样性/序列化/真实样本回归）
  • 真实样本回归 fixture：tests/fixtures/sample_xianyu.txt（百度AI方案）
• 🔒 T1.2 review 闭环修复（skills/gaokao-audit/scripts/validate_template.py）
  • 模板渲染 Environment(autoescape=False) → autoescape=True——修复用户派生字段（policy_errors/crowd_risks/data_issues）XSS 注入风险
  • 标签平衡检查：原 "(HTML5 void elements ignored)" 注释与实际行为不符（regex 未排除 void 元素），改为显式 VOID_ELEMENTS 集合减去空元素计数（103=103，7 void 元素正确排除）
  • T1.2 验证脚本仍 PASS（mock payload 全部 7 个 must_contain 字符串命中）
• 📝 docs/plans/T1-2-audit-skill-and-parser.md 实施记录：10/10 测试 ✓ · 真实样本解析正确 ✓ · 省份别名 27 省 ✓ · 编号格式 4 种 ✓

新增（T1.2 已完成）

• ✨ AI方案审核服务 Skill（skills/gaokao-audit/）
  • SKILL.md（143 行）— 角色边界 + 49 元服务定价 + 四维审核框架 + 合规红线 + DoD
  • templates/audit_report.html（262 行，Jinja2）— 报告模板，含政策合规/扎堆风险/数据存疑/改进建议 4 区块 + 升级到 99 元完整方案卡片
  • examples/sample_audit.md（144 行）— 输入样例（大厂AI方案文本/PDF/截图）+ 输出报告样例 + 渲染数据契约表
  • scripts/validate_template.py（137 行）— 模板渲染校验器，16 个占位符 + 7 个渲染输出字符串断言
  • tests/test_validate_template.py（33 行）— pytest 入口，1 用例通过
  • 关键设计：T1.1 review 暴露的 4 个反模式（吞错、模糊 substring、vacuous 测试、缺失档位）已显式列入"对齐 T1.1 review 教训"表，由 T1.3 实施时强制规避
  • T1.2 测试套件：1/1 通过（含项目原有 6 个 spec_checker 测试 → 7/7 通过）

新增（T7.1 已完成）

• ✨ 短链接生成（data/share/short_link.py + scripts/gaokao-shortlink）
  • base62 短码生成（默认 6 位，4-16 位可配，加密随机 + 冲突重试）
  • SQLite 映射表 share_links（WAL 模式，code 主键 + report/owner/expires 三索引）
  • ShortLinkService 完整 API：create / get / resolve / revoke / list_by_report / list_by_owner / get_stats / purge_expired
  • 访问控制：permission（read/comment/edit/admin）+ 密码（PBKDF2-HMAC-SHA256，兼容历史 sha256 读时迁移）+ expires_at + revoked
  • route_short_link(code, password, base_url) 路由辅助，可挂载任意 Web 框架的 /s/<code>
  • CLI：create / resolve / revoke / list / stats / purge，全部子命令 JSON 输出
  • 25 个 pytest 用例全部通过（base62 编解码、碰撞重试、TTL、密码、撤销、列表、统计、清理、路由）

新增（T7.3 已完成）

• ✨ 分享权限策略（data/share/permission.py）
  • 新增 PermissionPolicy.for_permission(permission)：把 read/comment/edit/admin 归一化成分享页能力策略
  • 能力判断：can_view / can_comment / can_edit / allows_field / can("...")
  • 安全兜底：未知 permission 一律回退到最严格的 read 策略，防止越权
• ✨ 姓名脱敏策略复用
  • 复用 data/orders/masking.py::mask_name，避免在分享链路重复实现脱敏算法
  • read/comment 默认回传脱敏姓名；公开分享场景额外收紧为：3 字及以上中文名统一 姓+**，非中文名统一 **
  • edit（以及历史兼容 admin）下姓名原样展示，但 password_hash / internal_note / note / debug_info / raw_payload 等内部字段仍强制隐藏
• ✨ 权限感知路由辅助（data.share.short_link.route_short_link_with_report）
  • 在 route_short_link() 之上叠加报告 payload 渲染，支持 report= 直接注入或 report_loader(report_id) 懒加载
  • resolve 失败（not_found / revoked / expired / password_required / password_wrong）时不下发 rendered payload，避免泄露报告元数据
  • render_report_payload(permission, report, share_url=...) 输出统一结构：policy + visible_fields + payload + masked_fields
• ✅ 测试验证
  • 新增 data/share/tests/test_permission.py，34 个 pytest 用例覆盖：三档权限、admin alias、未知 permission fallback、字段裁剪、姓名脱敏、公开分享收敛规则、route + report_loader 端到端
  • python3 -m pytest data/share/tests/test_permission.py -q → 34 passed
  • python3 -m pytest data/share/tests/ -q → 61 passed
  • python3 -m pytest data/share/ data/orders/ -q → 231 passed
  • python3 -m ruff check data/share/permission.py data/share/tests/test_permission.py data/share/short_link.py → All checks passed

新增（T10.1 已完成）

• ✨ GitHub Actions CI 流水线
  • 自动化测试（push / pull_request 触发）
  • 多 Python 版本矩阵（3.10 / 3.11 / 3.12）
  • pytest + pytest-cov 覆盖率报告（XML 产物供 T10.2 codecov 集成）
  • pip 依赖缓存（加速运行）
• ✨ requirements-dev.txt — 测试依赖（pytest / pytest-cov / pytest-timeout / pytest-xdist）
• ✨ pytest.ini — 统一本地与 CI 测试发现配置
• ✨ README 顶部 CI 状态徽章

新增（T10.2 已完成）

• ✨ Codecov 覆盖率报告与徽章
  • .github/workflows/ci.yml 集成 codecov/codecov-action@v4，3.11 单点上传 coverage.xml
  • codecov.yml 定义 project 目标 80% / 核心 skills 目标 100% / patch 目标 70%，与 T5.5 硬门槛对齐
  • fail_ci_if_error: false：codecov 不可达时不影响 CI 通过（适配多镜像仓库场景）
  • README 顶部新增 codecov 覆盖率徽章
• ✨ PR 浮动容忍 1%（project）/ 2%（core），避免噪声红灯

新增（T11.2 已完成）

• ✨ 敏感字段展示脱敏工具 data/orders/masking.py（127 行）
  • mask_phone / mask_id_card / mask_name / mask_sensitive_dict 四个纯函数
  • 手机号：11 位 → 138****1234；支持 +86 / 86 国家码剥离、常见分隔符（空格 / 横杠）
  • 身份证：18 位 → 430102********1234（保留前 6 行政区划 + 末 4 位）；15 位老版兼容；非 18/15 位且 ≥13 位的非标准输入也走"前 6 后 4"遮罩
  • 姓名：1 字原样 / 2 字 张* / 3 字 张*丰 / 4+ 字 张**；非中日韩字符全遮 *****
  • 默认安全：None / 空串 / 非字符串均不抛错，统一返回 None / ""
  • mask_sensitive_dict 一键遮罩订单字典中所有已知 PII 字段（不动 _enc / _hash 等索引/密文字段）
• ✨ Order.to_dict 扩展 decrypt_sensitive 三态策略
  • True : 完整明文（权限内接口使用，如后台人工核对）
  • False: 完全移除明文（对外公开统计 / 审计日志）
  • "mask" (默认): 部分遮罩（列表 / 详情默认 — 推荐且默认安全）
  • 未知字符串策略值回退为 mask（防误传"plaintext"导致明文泄露）
• ✨ data/orders/tests/test_masking.py — 32 个 pytest 用例覆盖：手机号 11/12/带 +86 / 短串 / 非法输入、身份证 18/15/X 校验位 / 短串 / 13 位非标准、姓名 1/2/3/4+ 字 / 英文 / 混合、mask_sensitive_dict 不变性、Order.to_dict 三态与默认 mask
• ✅ 测试验证：data/orders/tests 全套 112 用例通过（含原有 80 + 新增 32）；全仓 344/344 通过；ruff check 0 warning；ruff format --check 3 文件已规范
• 🔒 与 T4.1 落盘加密的关系：crypto.py 负责"落盘形态"（密文 + hash），masking.py 负责"展示形态"（部分遮罩），两者正交 — 落盘加密是底层保险，脱敏展示是上层最小特权

新增（T8.3 已完成）

• ✨ 企业微信最小客户端（data/channel_sync/wecom_adapter.py）
  • WeComBotClient.from_env()：从 GAOKAO_WECOM_BOT_KEY / GAOKAO_WECOM_API_BASE / GAOKAO_WECOM_TIMEOUT_SECONDS 读取机器人 webhook 配置，缺失时 fail-fast
  • WeComAppClient.from_env()：从 GAOKAO_WECOM_CORP_ID / GAOKAO_WECOM_CORP_SECRET / GAOKAO_WECOM_AGENT_ID / GAOKAO_WECOM_API_BASE / GAOKAO_WECOM_TIMEOUT_SECONDS 读取应用消息配置
  • 机器人消息：send_text(...) 覆盖文本通知，支持 mentioned_list / mentioned_mobile_list
  • 应用消息：send_text(...) 覆盖 touser / toparty / totag 文本推送，支持 safe 与重复消息检查参数
  • access_token 自动缓存 + 提前刷新窗口：避免每次应用推送都重新拉 token
  • 错误模型统一：HTTP 非 2xx、上游 errcode != 0、transport 异常、非 JSON 响应统一包装为 WeComAPIError
• ✨ 企业微信集成测试（data/channel_sync/tests/test_wecom_adapter.py）
  • 覆盖机器人 webhook payload、应用 token 缓存/消息 payload、上游 errcode、transport 异常、环境变量缺失 fail-fast
  • 同时补上 WeChatClient transport 异常包装回归，避免标准库 transport 网络错误直接泄漏原始异常

新增（T8.2 已完成）

• ✨ 微信 SDK 最小客户端（data/channel_sync/wechat_adapter.py）
  • WeChatClient.from_env()：从 GAOKAO_WECHAT_APP_ID / GAOKAO_WECHAT_APP_SECRET / GAOKAO_WECHAT_API_BASE / GAOKAO_WECHAT_TIMEOUT_SECONDS 读取配置，缺失时 fail-fast
  • access_token 自动缓存 + 提前刷新窗口：避免每次发送都重新拉 token，也避免临近过期 token 被继续复用
  • 订阅消息：send_subscribe_message(...) 自动规范化 data 为 {key: {value: ...}} 形状，并透传 page / miniprogram_state / lang
  • 客服消息：send_custom_message(...) / send_custom_text(...) 覆盖文本客服场景，支持可选 kf_account
  • 纯标准库 HTTP：UrllibTransport + 可注入 Transport 协议，便于测试 fake transport 与后续 T8.3 复用
  • 错误模型统一：HTTP 非 2xx、上游 errcode != 0、非 JSON 响应全部包装为 WeChatAPIError
• ✨ 微信集成测试（data/channel_sync/tests/test_wechat_adapter.py）
  • 覆盖 token 缓存/刷新、订阅消息 payload、客服文本消息 payload、上游 errcode、HTTP 500、环境变量缺失 fail-fast
  • pytest --cov=data.channel_sync.wechat_adapter 覆盖率 90%（8/8 通过）
  • pytest -q data/channel_sync/tests → 75 passed；ruff check data/channel_sync/wechat_adapter.py data/channel_sync/tests/test_wechat_adapter.py data/channel_sync/__init__.py → All checks passed

新增（T8.1 已完成）

• ✨ 闲鱼 Webhook + poller 兜底同步（data/channel_sync/）

• webhook_server.py：POST /webhook/xianyu + /healthz，覆盖签名校验、时间戳过期、重复 event、非法状态迁移、审计落库、单 IP 限流

• poller.py：共享 upsert_by_external_id 幂等链路，支持 cursor 推进与 poller_state / poller_run 运行记录

• audit.py + dao_extension.py + xianyu_adapter.py + signature.py：补齐渠道同步所需审计、适配、验签与订单写库能力

• data/channel_sync/tests/test_xianyu_channel.py：129 个 data/orders + data/channel_sync 测试通过；data.channel_sync 覆盖率 90%，ruff check data/channel_sync 0 warning

• 修复关键缺陷：Webhook server 预热 SQLite 连接原先在主线程创建，server 线程复用时触发 sqlite3.ProgrammingError，导致 accepted/duplicate/illegal-transition 路径误报 500 且拒绝审计落库失败；现改为 schema bootstrap 后以 check_same_thread=False 重新打开连接

新增（T2.3 已完成）

• ✨ 扎堆检测算法（data/crowd_db/crowd_detector.py）
  • detect_crowd_risk(plan, user_score, province) → list[RiskFinding]：遍历方案每条志愿，匹配该分数段内的 crowd_db 记录，返回风险列表 + 替代方案
  • 风险等级映射：frequency ≥4 high / 2-3 medium / 1 low / 0 跳过
  • 院校模糊匹配（互相包含），专业可选（计划未指定专业时按院校命中）

新增（T3.1 已完成）

• ✨ 27 省院校数据模型扩展溯源字段（data/crowd_db/{province}.json + loader.py）
  • 27 省 JSON 顶层新增 6 字段：source / source_url / source_type / data_year / confidence / last_updated
  • 现有 26 省骨架数据：confidence=0.45，source_type=manual_summary，data_year=2025
  • 湖南数据：confidence=0.85，含 68 条推荐（专科批→省外顶尖，10 段连续 440-690 覆盖）
  • CrowdDBLoader 扩展 warn_low_confidence / load_metadata(province) → 8 字段 / list_supported_provinces() / list_provinces() / load_province 对 confidence<0.5 发 UserWarning
  • 新增 data/crowd_db/SCHEMA.md：顶层/分数段/推荐条目三表 schema + source_type 枚举（manual_summary / official_release / platform_scrape / derived）+ 骨架文件约定
  • 测试：data/crowd_db/tests/test_provenance.py 9 用例（27 存在性、顶层字段、score_range schema、confidence 区间、loader 27 报告、metadata 8 字段、低 confidence 警告、端到端匹配），T2.1/T2.2/T2.3 46 用例无回归
  • 与 T2.3 协同：crowd_detector._risk_level_from_frequency 与 CrowdRecommendation.risk_level 在 frequency 0-5 边界完全一致

新增（T3.2 已完成）

• ✨ 溯源字段查询 + 验证 API（data/crowd_db/loader.py + tests/test_provenance_query.py）
  • 新增 dataclass ProvenanceValidation：含 ok / errors / warnings / is_usable / summary 5 字段 + to_dict()
  • 类常量：USABLE_CONFIDENCE_THRESHOLD = 0.5 / VALID_SOURCE_TYPES（4 枚举）/ ISO_DATE_PATTERN / REQUIRED_PROVENANCE_FIELDS（7 字段）
  • validate_provenance(data, province) → ProvenanceValidation（@classmethod，不需 loader 实例）：校验字段类型/范围/枚举/日期格式，区分硬错误与软警告
  • validate_province(province) → ProvenanceValidation：加载 + 校验一体化
  • validate_all() → dict[province, ProvenanceValidation]：27 省一次性扫描
  • filter_provinces(*, source_type, min_confidence, max_confidence, data_year, updated_since, updated_before, only_usable) → list[province]：多维溯源过滤，按 PROVINCE_FILE_MAP 顺序返回
  • get_provenance_report(*, only_usable, source_type) → dict：汇总 total / usable_count / failed_count / by_source_type / items
  • 27 省现状：全部 schema 校验通过（failed=0），仅湖南 1 省 is_usable=True（confidence=0.85），26 省 low_confidence warning
  • 测试：data/crowd_db/tests/test_provenance_query.py 33 用例全通过，覆盖 validate_all/27、validate_province 单省、validate_provenance 边界（None/空 dict/confidence 越界/source_type 非法/data_year 类型错/date 格式错/empty source warning）、filter_provinces 9 维 + 组合、get_provenance_report 5 统计项、未知省份 load_failed、ProvenanceValidation.to_dict、load_metadata 兼容性、validate_provenance 不可变性
  • 不破坏既有 API：load_province / find_recommendations / find_recommendation_by_school / load_metadata 行为与契约完全不变；T2.x 46 用例 + T3.1 9 用例 + T3.2 33 用例 = 88/88 通过
  • 多种 plan 形态：dict / CrowdRecommendation / tuple / list
  • 支持注入 loader 便于测试，频率降序排序
  • 20 个单元测试覆盖：高/中风险识别、替代方案、分数段边界、模糊匹配、专业匹配、空/异常输入、部分命中、排序
• ✨ data/crowd_db/tests/test_crowd_detector.py — 20 个测试覆盖算法各分支

📅 计划中

• T5.5 覆盖率硬门槛（全局 ≥80% / 核心 =100% / E2E模拟通过）

---

v2.0 (2026-06-11)

🎉 重大变化

新增

• ✨ 规范检查Skill V2：支持27个省份自动适配
  • 院校专业组模式（14省）
  • 专业+学校模式（8省）
  • 传统模式（5省）
• ✨ 省份规则库（rules/provinces/）
• ✨ 错误模式库（rules/errors/）
• ✨ 真实案例库（docs/case-studies/）
• ✨ 优化日志（docs/optimization-log/）
• ✨ 完整项目目录结构

修复

• 🐛 修正"院校专业组"概念（原错误为"45个学校"）
• 🐛 修正调剂规则（原错误为"全校调剂"）
• 🐛 修正投档后规则（原错误为"退到下个志愿"）
• 🐛 移除主观概率（原错误为"35%、80%"）
• 🐛 修正选科一刀切（原错误为"所有会计都要求物+化+生"）

改进

• ⚡ 院校数据从2025年位次精确化
• ⚡ 风险提示前置
• ⚡ 数据来源明确标注
• ⚡ 强调"以官方为准"

📝 起源事故

• 真实用户咨询：湖南578分/物化生
• 原方案出现致命错误（院校专业组概念错误）
• 用户质疑"是否符合规范"触发自查
• 创建本检查Skill防止错误复发

---

v1.0 (2026-06-10 → 2026-06-11)

初始版本

• gaokao-college-advisor Skill
• 可视化报告脚本
• 1分钟/3分钟/7步三套问卷
• 邮件发送功能

已知问题

• ❌ 政策理解停留在2024年水平
• ❌ 数据主观化严重
• ❌ 缺乏方案检查机制
• ❌ 部分细节不符合本省规范

用户反馈

• "符合今年对应区域志愿填报规范吗？" ← 触发v2.0创建

---

📊 版本对比

维度	v1.0	v2.0
省份支持	湖南	27个
检查机制	无	规范检查Skill
错误模式库	无	8+种错误
数据精度	主观	基于2025位次
风险提示	后置	前置
项目结构	散落	集中
文档体系	简单	完善

---

🎯 下一步

• 添加更多省份（覆盖完整30+省）
• 完善数据自动化对接
• 增强算法精度
• 完善UI/UX

详见 docs/optimization-log/future-plan.md