fix deployment and frontend build regressions

DEPLOYMENT.md

@@ -1,27 +1,27 @@
 # LLM Intelligence Hub - 部署指南
 
-> 版本: v1.0  
-> 日期: 2026-05-10  
-> 适用版本: Phase 1
+> 版本: v1.1
+> 日期: 2026-05-21
+> 适用版本: Phase 1 / Phase 2 基础部署
 
 ---
 
 ## 环境要求
 
 ### 硬件
-- CPU: 1核+
-- 内存: 512MB+
-- 磁盘: 5GB+
+- CPU: 1 核+
+- 内存: 512 MB+
+- 磁盘: 5 GB+
 
 ### 软件
 - Go 1.22+
 - Node.js 20+
 - PostgreSQL 16+
-- Docker 或 Podman (可选)
+- Docker / Docker Compose
 
 ---
 
-## 快速开始
+## 本地开发启动
 
 ### 1. 克隆仓库
 ```bash
@@ -29,13 +29,14 @@ git clone <repo-url> llm-intelligence
 cd llm-intelligence
 ```
 
-### 2. 配置数据库
+### 2. 初始化数据库
 ```bash
-# 创建数据库
 createdb llm_intelligence
-
-# 运行迁移
 psql llm_intelligence < db/migrations/001_phase1_core_tables.sql
+psql llm_intelligence < db/migrations/002_sprint1_complete_schema.sql
+psql llm_intelligence < db/migrations/003_phase2_region_pricing_metadata.sql
+psql llm_intelligence < db/migrations/004_backfill_models_batch_id.sql
+psql llm_intelligence < db/migrations/005_subscription_plan.sql
 ```
 
 ### 3. 配置环境变量
@@ -50,29 +51,40 @@ export FEISHU_WEBHOOK="your-webhook-url"  # 可选
 go run cmd/server/main.go
 ```
 
-### 5. 启动前端 (开发)
+### 5. 启动前端开发服务
 ```bash
 cd frontend
 npm install
 npm run dev
 ```
 
-### 6. 配置定时任务
-```bash
-crontab -e
-# 添加: 0 8 * * * cd /path/to/llm-intelligence && bash scripts/run_daily.sh
-```
-
 ---
 
 ## Docker 部署
 
-```bash
-# 构建
-docker build -t llm-hub .
+当前容器镜像已经内置前端静态资源，`app` 服务会同时提供页面和 API。
 
-# 或 docker-compose
-docker-compose up -d
+### 使用 compose 启动完整环境
+```bash
+docker-compose up -d --build
+```
+
+启动后访问:
+- Web UI: `http://localhost:8080/`
+- Health: `http://localhost:8080/health`
+- API: `http://localhost:8080/api/v1/models`
+
+### 只构建镜像
+```bash
+docker build -t llm-hub .
+```
+
+运行示例:
+```bash
+docker run --rm -p 8080:8080 \
+  -e DATABASE_URL="postgres://llm_hub:changeme@host.docker.internal:5432/llm_intelligence?sslmode=disable" \
+  -e OPENROUTER_API_KEY="your-api-key" \
+  llm-hub
 ```
 
 ---
@@ -81,42 +93,63 @@ docker-compose up -d
 
 | 变量 | 必填 | 说明 |
 |------|------|------|
-| DATABASE_URL | ✅ | PostgreSQL 连接串 |
-| OPENROUTER_API_KEY | ✅ | OpenRouter API Key |
-| FEISHU_WEBHOOK | ❌ | 飞书告警 Webhook |
-| API_PORT | ❌ | 默认 8080 |
+| `DATABASE_URL` | 是 | PostgreSQL 连接串 |
+| `OPENROUTER_API_KEY` | 是 | OpenRouter API Key |
+| `FEISHU_WEBHOOK` | 否 | 飞书告警 Webhook |
+| `PORT` | 否 | 服务端监听端口，默认 `8080` |
+| `FRONTEND_DIST_DIR` | 否 | 自定义静态资源目录，默认自动查找 `frontend/dist` |
 
 ---
 
 ## 验证安装
 
 ```bash
-# 数据库连接
 curl http://localhost:8080/health
+curl http://localhost:8080/api/v1/models
+```
 
-# 采集器测试
-go run scripts/fetch_openrouter.go
+前端构建校验:
+```bash
+cd frontend
+npm run build
+```
 
-# 日报生成
-go run scripts/generate_daily_report.go
+Go 测试校验:
+```bash
+go test ./...
 ```
 
 ---
 
 ## 常见问题
 
-### Q: 数据库迁移失败？
-确保 PostgreSQL 已启动，且用户有创建表的权限。
+### Q: 前端构建失败?
+确认:
+- Node.js >= 20
+- `frontend/package-lock.json` 与 `npm ci` 一致
+- 本地没有依赖已删除的 `frontend/src/data/latest_models.json`
 
-### Q: 前端构建失败？
-检查 Node.js 版本 >= 20，npm 版本 >= 10。
+### Q: `docker-compose up -d` 后页面空白?
+先执行:
+```bash
+docker-compose up -d --build
+```
 
-### Q: 采集器返回模拟数据？
-未提供 OPENROUTER_API_KEY 时使用模拟数据，提供 Key 后获取真实数据。
+然后检查:
+```bash
+docker-compose logs -f app
+curl http://localhost:8080/
+```
+
+### Q: API 返回 `database not configured`?
+说明 `DATABASE_URL` 未注入或格式不正确，先执行:
+```bash
+echo "$DATABASE_URL"
+```
 
 ---
 
 ## 升级路径
 
 - Phase 2: 告警订阅 / 用户系统 / 付费分析
-- Phase 3: 多数据源 / 自动发现 / ELO评分
+- Phase 3: 多数据源 / 自动发现 / ELO 评分