IMPLEMENTATION_PLAN.md

# LLM Intelligence Hub — 生产级实施计划（修正版 v1.1）

> 文档版本: v1.1
> 日期: 2026-05-10
> 负责人: 宰相
> 状态: Phase 1 执行中
> **修正说明**: 根据评审报告补充国内厂商覆盖、数据质量规则、非功能需求验证、容错降级设计、审计日志

---

## 一、项目状态快照

### 已完成 ✅
| 组件 | 说明 |
|------|------|
| PRD.md v0.3 | 产品需求文档 |
| TECHNICAL_DESIGN.md v1.1 | 技术设计文档 |
| FEATURE_LIST.md v1.1 | 功能清单 |
| BUSINESS_MODEL.md | 商业模型 |
| fetch_openrouter.go | OpenRouter采集器 |
| generate_daily_report.go | 日报生成器 |
| db/migrations/001_phase1_core_tables.sql | 3张核心表 |
| frontend/src/pages/Explorer.tsx | Explorer页面脚手架 |
| verification_executor.go | 验证执行器 |

### 进行中/待完善 🟡
| 组件 | 说明 |
|------|------|
| 数据库Schema升级 | 3张表 → 8张完整表 + audit_log |
| 数据质量规则 | CHECK约束 + stale标记 |
| 国内厂商数据 | 7家种子数据（DeepSeek/阿里/Moonshot/智谱/字节/百度/腾讯） |
| Explorer页面 | 分页/排序/stale显示 |
| 日报推送 | cron配置+降级策略 |
| 前端构建配置 | package.json/vite.config.ts |
| 生产部署 | Dockerfile/docker-compose |
| 审计日志 | audit_log表 + 写入集成 |

---

## 二、修正说明（对照评审报告）

| 评审发现 | 修正措施 | 所在Sprint |
|----------|----------|-----------|
| 国内厂商覆盖缺失 | Sprint 2 新增7家种子数据录入 | Sprint 2 |
| 数据质量规则缺4/6 | Sprint 1 新增CHECK约束+stale标记+质量摘要 | Sprint 1 |
| 非功能需求缺5/6 | Sprint 2~6 新增采集成功率监控+连续失败告警+性能门禁 | Sprint 2~6 |
| 容错降级缺5项 | Sprint 3~5 新增日报降级+Explorer stale显示+维护模式 | Sprint 3~5 |
| 审计日志缺失 | Sprint 1 新增audit_log表，Sprint 2 集成写入 | Sprint 1~2 |
| 3个TBD验证 | 全部改为自动化验证命令 | 全量修正 |
| 前端基础假设 | T-Q2-2.34拆分为34a+34b | Sprint 4 |

---

## 三、详细任务清单（74个Task）

> 强制规则：每个Task必须有可自动验证的 command，禁止 TBD/semantic 兜底

### Sprint 1: 数据层补全（Week 1-2）
**目标**: 3张表 → 8张完整表 + audit_log + 质量约束

| Task ID | 任务 | 验证方式 |
|---------|------|----------|
| T-Q2-2.9 | model_provider 表创建 | `psql -c "\dt" \| grep model_provider` |
| T-Q2-2.10 | operator 表创建 | `psql -c "\dt" \| grep operator` |
| T-Q2-2.11 | region_pricing 表创建 | `psql -c "\dt" \| grep region_pricing` |
| T-Q2-2.12 | pricing_history 表创建 | `psql -c "\dt" \| grep pricing_history` |
| T-Q2-2.13 | free_tier 表创建 | `psql -c "\dt" \| grep free_tier` |
| T-Q2-2.14 | daily_report 表创建 | `psql -c "\dt" \| grep daily_report` |
| T-Q2-2.15 | user_subscription 表创建 | `psql -c "\dt" \| grep user_subscription` |
| **T-Q2-2.15a** | **audit_log 表创建** | `psql -c "\dt" \| grep audit_log` |
| T-Q2-2.16 | model_prices → region_pricing 迁移 | `SELECT COUNT(*) FROM region_pricing` |
| T-Q2-2.16a | models 表字段扩充 | `psql -c "\d models"` |
| **T-Q2-2.16b** | **CHECK 约束（price≥0, context≤10M, currency枚举）** | `psql -c "\d region_pricing" \| grep Check` |
| T-Q2-2.17 | Provider 种子数据 | `SELECT COUNT(*) FROM model_provider` >= 6 |
| **T-Q2-2.16c** | **血缘字段强制写入验证** | `SELECT COUNT(*) FROM models WHERE batch_id IS NULL` = 0 |
| **T-Q2-2.16d** | **stale 标记定时任务** | 插入48h前数据，运行SQL后验证 |
| T-Q2-2.18 | 审计触发器 | 更新记录验证 updated_at 自动变化 |

### Sprint 2: 采集器强化 + 国内厂商（Week 3-4）
**目标**: 采集器重构 + 国内7家厂商种子数据 + 审计日志集成

| Task ID | 任务 | 验证方式 |
|---------|------|----------|
| T-Q2-2.19 | ProviderMapper 模块提取 | `go test ./internal/collectors/` |
| T-Q2-2.20 | ProviderNameMap 完整映射 | 单元测试覆盖所有映射 |
| T-Q2-2.21 | Collector 接口抽象 | `go test ./internal/collectors/` |
| T-Q2-2.22 | 指数退避重试包 | `go test ./internal/retry/ -v` |
| T-Q2-2.23 | 采集器集成重试 | 模拟API失败验证重试 |
| T-Q2-2.24 | 批量插入优化 | 采集371条 < 30秒 |
| T-Q2-2.25 | 价格变动检测（>5%） | 修改价格验证 history 表记录 |
| T-Q2-2.25a | 事务边界优化（每批次事务） | 中断采集验证已提交数据保留 |
| T-Q2-2.26 | 结构化日志（slog JSON） | 日志含 collector/duration/records |
| **T-Q2-2.26a** | **采集成功率监控** | `SELECT success_rate_7d FROM collector_stats` >= 95 |
| **T-Q2-2.27a** | **国内厂商录入：DeepSeek** | DeepSeek模型数 >= 3 |
| **T-Q2-2.27b** | **国内厂商录入：阿里/Moonshot/智谱** | 每家至少2个模型 |
| **T-Q2-2.27c** | **国内厂商录入：字节/百度/腾讯** | 每家至少1个模型 |
| **T-Q2-2.27d** | **国内厂商CNY定价录入** | `SELECT COUNT(*) FROM region_pricing WHERE currency='CNY'` >= 10 |
| **T-Q2-2.27e** | **采集器写入 audit_log** | `SELECT COUNT(*) FROM audit_log WHERE table_name='models'` >= 371 |

### Sprint 3: 日报与报告（Week 5-6）
**目标**: 日报增强 + 降级策略 + 飞书推送

| Task ID | 任务 | 验证方式 |
|---------|------|----------|
| T-Q2-2.28 | 日报从DB读取（非JSON） | 删除 models.json 后日报仍能生成 |
| T-Q2-2.29 | 新模型检测逻辑 | 插入测试模型验证报告含"新模型" |
| T-Q2-2.30 | 价格变动高亮（>5%） | 修改价格>5%验证报告高亮 |
| T-Q2-2.31 | 场景推荐算法 | 推荐含 TOP 3 模型及理由 |
| **T-Q2-2.31a** | **数据质量摘要段落** | `grep "数据质量" reports/daily/*.md` |
| T-Q2-2.32 | HTML报告模板 | 浏览器正常打开 |
| T-Q2-2.33 | Markdown报告优化 | 飞书/钉钉渲染正常 |
| **T-Q2-2.33a** | **run_daily.sh 完整脚本** | 手动执行 exit code = 0 |
| T-Q2-2.34 | cron配置（每日08:00） | `crontab -l \| grep llm-intelligence` |
| **T-Q2-2.35** | **日报失败降级（复制昨日+"[数据延迟]"）** | 模拟失败验证复制和标题 |
| **T-Q2-2.36** | **日报飞书告警（失败时）** | 测试webhook模拟失败验证消息到达 |
| T-Q2-2.37 | 日报写入 daily_report 表 | `SELECT * FROM daily_report WHERE report_date = TODAY` |
| T-Q2-2.38 | 报告文件归档 | `ls reports/daily/2026/05/` |

### Sprint 4: 前端完善（Week 7-8）
**目标**: Explorer完善 + 可视化 + 降级显示

| Task ID | 任务 | 验证方式 |
|---------|------|----------|
| **T-Q2-2.39a** | **package.json 创建** | `cd frontend && npm install` |
| **T-Q2-2.39b** | **vite.config.ts + tsconfig.json** | `cd frontend && npm run build` |
| T-Q2-2.40 | index.html 入口页 | `npm run dev` 可访问 |
| T-Q2-2.41 | App.tsx 路由配置 | 路由切换正常 |
| T-Q2-2.42 | 数据服务层封装 | API返回正确结构 |
| T-Q2-2.43 | 分页功能 | 100+条分页正常 |
| T-Q2-2.44 | 排序功能 | Jest单元测试通过 |
| T-Q2-2.45 | 免费标记样式 | 所有免费模型标记正确 |
| T-Q2-2.46 | 厂商筛选动态加载 | 新增厂商自动出现 |
| T-Q2-2.47 | 模态筛选修正 | vision/text/code分类正确 |
| **T-Q2-2.48** | **stale 状态显示（红标）** | 插入stale数据验证显示 |
| **T-Q2-2.49** | **pricing unavailable 显示** | 单元测试null/undefined显示 |
| T-Q2-2.50 | ECharts 集成 | 渲染柱状图 |
| T-Q2-2.51 | 价格趋势占位图替换 | 显示趋势曲线 |
| T-Q2-2.52 | Dashboard 首页 | 显示今日报告摘要 |

### Sprint 5: 生产部署（Week 9-10）
**目标**: 容器化 + CI/CD + 运维脚本

| Task ID | 任务 | 验证方式 |
|---------|------|----------|
| T-Q2-2.53 | Dockerfile多阶段构建 | `docker build -t llm-hub .` |
| T-Q2-2.54 | docker-compose.yml | `docker-compose up -d` |
| T-Q2-2.55 | .env.example | 文件存在且密钥为空 |
| T-Q2-2.56 | Nginx配置 | `curl http://localhost/health` = 200 |
| **T-Q2-2.56a** | **Nginx 维护模式** | curl 返回503 + maintenance.html |
| T-Q2-2.57 | GitHub Actions CI | Push自动触发CI |
| T-Q2-2.58 | 测试覆盖率检查（≥80%） | 不达标CI失败 |
| T-Q2-2.59 | 构建产物上传 | Artifacts含产物 |
| T-Q2-2.60 | 数据库备份脚本 | 手动执行验证OSS上传 |
| T-Q2-2.61 | 数据库恢复脚本 | 恢复后数据完整 |
| **T-Q2-2.62** | **健康检查脚本** | `./healthcheck.sh` 输出正常 |
| **T-Q2-2.63** | **日志轮转配置（30天）** | `ls /var/log/llm-hub/` |
| **T-Q2-2.64** | **连续3天失败告警** | 插入3条失败记录验证告警 |

### Sprint 6: 验收与优化（Week 11-12）
**目标**: 全面验收 + 性能优化 + 文档完善

| Task ID | 任务 | 验证方式 |
|---------|------|----------|
| **T-Q2-2.65** | **采集覆盖率：OpenRouter 371+ + 国内7家** | models数 >= 371 + 国内厂商 >= 10 |
| **T-Q2-2.66** | **数据质量：自动抽样核对脚本** | exit code = 0，差异 < 1% |
| **T-Q2-2.67** | **采集性能 < 30秒** | `time ./fetch_openrouter` < 30s |
| T-Q2-2.68 | 日报生成验收（连续7天） | 含新模型/价格变动/场景推荐/质量摘要 |
| T-Q2-2.69 | Explorer页面验收 | 所有交互无报错 |
| **T-Q2-2.70** | **API响应 < 500ms** | `curl -w "%{time_total}"` < 0.5 |
| **T-Q2-2.71** | **前端首屏 < 2s** | Lighthouse >= 80 |
| **T-Q2-2.72** | **7日采集成功率 >= 95%** | `SELECT AVG(success_rate_7d)` >= 95 |
| T-Q2-2.73 | 密钥管理检查 | `grep -r "sk-" --include="*.go" .` 无结果 |
| T-Q2-2.74 | SQL注入检查 | 所有SQL参数化查询 |

---

## 四、质量保障措施

| 措施 | 实施方式 |
|------|----------|
| 每个Task必须有可自动验证的command | 禁止 TBD/semantic，全部 test_pass/artifact_present |
| 关键路径双重验证 | 数据采集类：单元测试 + 集成测试 + DB验证 |
| Sprint结束门禁 | 最后1个任务必须是"全链路回归测试" |
| Weekly数据质量报告 | Sprint 2起，每周自动生成质量摘要 |
| 生产放行标准 | 采集成功率>95%、报告<30秒、20+厂商、500+模型、审计日志完整 |