docs(project): add production-ready documentation

Add a top-level README plus production configuration, API, and rollout documentation. Also align deployment and runbook docs with the current runtime semantics, ports, and daily pipeline entrypoints.
2026-05-14 19:55:12 +08:00
parent a8999abcb0
commit dd58c18fe3
7 changed files with 759 additions and 10 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,160 @@
+# LLM Intelligence Hub
+
+面向 LLM 模型、定价与日报产出的情报采集项目，当前仓库提供：
+
+- Go 采集脚本：采集 OpenRouter、多源补充数据与官方补录数据
+- PostgreSQL 数据层：保存模型、区域定价、订阅套餐、日报与运行审计
+- Go HTTP API：提供模型列表、套餐列表、最新正式日报入口
+- Vite + React 前端：提供 Dashboard / Explorer 两个只读页面
+- Shell 运维脚本：迁移、调度、备份、恢复、验收与性能门禁
+
+## 当前能力边界
+
+- 真实生产主链路是“采集/导入脚本 + PostgreSQL + 日报生成器 + API Server + Nginx”
+- 最新正式日报由 `scripts/run_daily.sh` 生成，并写入 `daily_report` / `report_runs`
+- 手工复跑使用 `scripts/run_real_pipeline.sh`，不会把产物标记成正式日报
+- 历史补跑使用 `scripts/rebuild_historical_report.sh YYYY-MM-DD`
+- HTTP API 当前未内建认证、授权和限流；公网暴露前必须在网关层补齐
+
+## 目录概览
+
+```text
+cmd/server/                  Go API Server
+internal/                    通用内部库（collector、retry）
+scripts/                     采集、导入、日报、验收、运维脚本
+db/migrations/               PostgreSQL 迁移
+frontend/                    Vite + React 前端
+reports/daily/               日报产物与归档
+ops/                         运维配置（如 logrotate）
+docs/                        补充说明与上线文档
+```
+
+## 本地启动
+
+### 1. 准备环境
+
+```bash
+cp .env.example .env
+```
+
+至少需要配置：
+
+- `DATABASE_URL`
+- `OPENROUTER_API_KEY`（仅真实采集需要）
+
+详细变量说明见 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)。
+
+### 2. 应用数据库迁移
+
+```bash
+bash scripts/apply_migration.sh
+```
+
+### 3. 启动 API Server
+
+```bash
+go run ./cmd/server
+```
+
+默认端口为 `8080`，可通过 `PORT` 覆盖。
+
+### 4. 启动前端开发环境
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+## 生产运行主链路
+
+### 正式日报调度
+
+```bash
+bash scripts/run_daily.sh
+```
+
+该脚本负责：
+
+1. OpenRouter 真实采集
+2. 多源补充同步
+3. 官方导入脚本执行
+4. 数据质量检查
+5. Markdown / HTML 日报生成
+6. 日报归档
+7. `daily_report` / `report_runs` 审计写入
+8. 失败时降级复制昨日报告并可选飞书告警
+
+### 手工真实复跑
+
+```bash
+bash scripts/run_real_pipeline.sh
+```
+
+适用于联调、排障、上线后人工验证。该入口写入：
+
+- `run_kind=manual`
+- `trigger_source=pipeline`
+- `is_official_daily=false`
+
+### 历史补跑
+
+```bash
+bash scripts/rebuild_historical_report.sh 2026-05-13
+```
+
+该入口写入：
+
+- `run_kind=historical_rebuild`
+- `trigger_source=rebuild_script`
+- `is_official_daily=false`
+
+## 常用命令
+
+```bash
+go test ./...
+bash scripts/test.sh
+bash scripts/verify_pre_phase6.sh
+bash scripts/verify_phase6.sh
+bash healthcheck.sh
+cd frontend && npm run test -- --run
+cd frontend && npm run build
+```
+
+## API 概览
+
+- `GET /health`
+- `GET /api/v1/models`
+- `GET /api/v1/subscription-plans`
+- `GET /api/v1/reports/latest`
+- `GET /api/v1/reports/latest/markdown`
+- `GET /api/v1/reports/latest/html`
+
+完整字段与示例见 [docs/API_REFERENCE.md](docs/API_REFERENCE.md)。
+
+## 文档索引
+
+- [docs/CONFIGURATION.md](docs/CONFIGURATION.md)：环境变量、运行语义、配置约束
+- [docs/API_REFERENCE.md](docs/API_REFERENCE.md)：API 入口、返回体与排障说明
+- [docs/PRODUCTION_CHECKLIST.md](docs/PRODUCTION_CHECKLIST.md)：生产上线前检查、发布与回滚流程
+- [DEPLOYMENT.md](DEPLOYMENT.md)：部署步骤与快速启动
+- [RUNBOOK.md](RUNBOOK.md)：运维巡检、故障排查、备份恢复
+- [TECHNICAL_DESIGN.md](TECHNICAL_DESIGN.md)：详细技术设计与数据模型演进背景
+- [docs/PERFORMANCE_TEST.md](docs/PERFORMANCE_TEST.md)：性能基线
+
+## 生产上线最低门禁
+
+建议把以下检查作为发布前硬门禁：
+
+```bash
+bash scripts/verify_pre_phase6.sh
+bash scripts/verify_phase6.sh
+```
+
+上线后首轮冒烟建议至少覆盖：
+
+```bash
+curl -fsS http://127.0.0.1:8080/health
+curl -fsS http://127.0.0.1:8080/api/v1/models
+curl -fsS http://127.0.0.1:8080/api/v1/reports/latest
+```