feat(report): improve daily intelligence UX and price tracking

docs/API_REFERENCE.md

@@ -7,8 +7,10 @@
 - 基础地址：`http://<host>:<port>`
 - 默认端口：`8080`
 - 返回格式：成功接口统一返回 `{ "data": ... }`
-- 失败格式：当前直接返回纯文本错误信息，不是统一 JSON 错误结构
-- 鉴权：当前仓库未内建认证、鉴权与限流；公网暴露前应由网关或反向代理补齐
+- 失败格式：失败接口统一返回 `{ "error": { "code": "...", "message": "..." } }`
+- 访问控制：`/health` 仅允许本机或私网访问；`/api/*` 对外访问默认要求 `Authorization: Bearer <token>` 或 Basic Auth，详见下文
+- 限流：`/api/*` 默认按来源 IP 做窗口限流；可通过 `API_RATE_LIMIT_PER_WINDOW` 与 `API_RATE_LIMIT_WINDOW_SEC` 调整
+
 
 ## `GET /health`
 
@@ -24,18 +26,30 @@
 
 ### 失败
 
-- `503 database not configured`：未配置 `DATABASE_URL`
-- `503 database unavailable`：数据库 Ping 失败
+```json
+{
+  "error": {
+    "code": "database_not_configured",
+    "message": "database not configured"
+  }
+}
+```
 
+- `503 database_not_configured`：未配置 `DATABASE_URL`
+- `503 database_unavailable`：数据库 Ping 失败
 ### 示例
 
 ```bash
 curl -fsS http://127.0.0.1:8080/health
 ```
 
+### 访问控制
+- 仅允许本机或私网请求；外部地址返回 `403 health_endpoint_internal_only`
+
+
 ## `GET /api/v1/models`
 
-返回模型列表，数据来源于 `models`、`model_provider`、`region_pricing` 当前最新价格快照。
+返回模型列表，数据来源于 `models`、`model_provider`、`region_pricing`；当同一模型存在多条价格记录时，API 按“`global` 区域优先、`official` > `reseller` > `free_tier`、再按 `effective_date`/`id` 倒序”的规则选取主价格。
 
 ### 返回体
 
@@ -84,8 +98,10 @@ curl -fsS http://127.0.0.1:8080/health
 
 ### 失败
 
-- `503 database not configured`
-- `500 query failed`
+- `503 database_not_configured`
+- `500 query_failed`
+- `401 auth_required`
+- `429 rate_limited`
 
 ## `GET /api/v1/subscription-plans`
 
@@ -122,8 +138,10 @@ curl -fsS http://127.0.0.1:8080/health
 
 ### 失败
 
-- `503 database not configured`
-- `500 query failed`
+- `503 database_not_configured`
+- `500 query_failed`
+- `401 auth_required`
+- `429 rate_limited`
 
 ## `GET /api/v1/reports/latest`
 
@@ -155,9 +173,12 @@ curl -fsS http://127.0.0.1:8080/health
 
 ### 失败
 
-- `503 database not configured`
-- `404 latest report not found`
-- `500 query failed`
+- `503 database_not_configured`
+- `404 latest_report_not_found`
+- `500 query_failed`
+- `401 auth_required`
+- `429 rate_limited`
+
 
 ## `GET /api/v1/reports/latest/markdown`
 
@@ -170,8 +191,10 @@ curl -fsS http://127.0.0.1:8080/health
 
 ### 失败
 
-- `404 latest report not found`：数据库中没有符合条件的正式日报
-- `404 report artifact not found`：元数据存在，但落盘文件缺失
+- `404 latest_report_not_found`：数据库中没有符合条件的正式日报
+- `404 report_artifact_not_found`：元数据存在，但落盘文件缺失
+- `401 auth_required`
+- `429 rate_limited`
 
 ## `GET /api/v1/reports/latest/html`
 
@@ -184,22 +207,24 @@ curl -fsS http://127.0.0.1:8080/health
 
 ### 失败
 
-- `404 latest report not found`
-- `404 report artifact not found`
+- `404 latest_report_not_found`
+- `404 report_artifact_not_found`
+- `401 auth_required`
+- `429 rate_limited`
+
 
 ## 冒烟检查命令
 
 ```bash
 curl -fsS http://127.0.0.1:8080/health
-curl -fsS http://127.0.0.1:8080/api/v1/models | jq '.data | length'
-curl -fsS http://127.0.0.1:8080/api/v1/subscription-plans | jq '.data | length'
-curl -fsS http://127.0.0.1:8080/api/v1/reports/latest | jq '.data.reportDate'
-curl -fsS http://127.0.0.1:8080/api/v1/reports/latest/html > /tmp/latest_report.html
+curl -fsS -H "Authorization: Bearer $API_AUTH_TOKEN" http://127.0.0.1:8080/api/v1/models | jq '.data | length'
+curl -fsS -H "Authorization: Bearer $API_AUTH_TOKEN" http://127.0.0.1:8080/api/v1/subscription-plans | jq '.data | length'
+curl -fsS -H "Authorization: Bearer $API_AUTH_TOKEN" http://127.0.0.1:8080/api/v1/reports/latest | jq '.data.reportDate'
+curl -fsS -H "Authorization: Bearer $API_AUTH_TOKEN" http://127.0.0.1:8080/api/v1/reports/latest/html > /tmp/latest_report.html
 ```
 
-## 生产暴露建议
 
-- 在 Nginx / 网关上补齐访问控制、速率限制和超时配置
-- `/health` 仅暴露给负载均衡器和监控系统
+- 在公网暴露时至少配置 `API_AUTH_TOKEN` 或 `API_BASIC_AUTH_USER` / `API_BASIC_AUTH_PASS`
+- `/health` 仅暴露给负载均衡器、监控系统或私网来源
 - 如果前端与 API 同域部署，优先由 Nginx 转发 `/api/` 和 `/health`
-- 如果需要公网访问，建议至少加一层 Basic Auth、OIDC 或内网入口限制
+- 如需更强控制，继续在 Nginx / 网关上补齐 CIDR 白名单、OIDC、WAF 与更细粒度限流