# ARR 看板与 API 数据库交接

更新时间：2026-07-28  
目标项目：仓库根目录

## 1. 当前结论

`arr_web`、渠道 BI、渠道明细、月报生成源和公司报表源已适配 ARR MVP v1 数据库。看板不再依赖旧 `report_versions` 或本地 `dashboard.json` 作为业务事实源。

测试数据库：

- `<ARR_DB_HOST>:5432/booking_test`（远程测试库）
- 本机受控配置：`/path/to/private/booking-test-db.env`

旧 `<LEGACY_DB_HOST>:5433/booking_test` 和 `/path/to/private/booking-test-lan-db.env` 只作为临时回退，不再作为默认应用数据源。

## 2. 安全架构

```text
浏览器/手机 H5
  → ARR 后端 API
  → 只读 PostgreSQL 连接
  → current + retained 视图
```

数据库地址、用户名和密码只能保存在后端 Secret/受控配置中。浏览器 JavaScript 不连接 PostgreSQL，不读取 env 文件，也不接收 DSN。

生产应给 API 创建独立只读账号；当前 `<TEST_DB_OWNER>` 是测试库 owner，并非生产只读账号。

## 3. 页面数据源

| 页面/功能 | 后端数据源 |
|---|---|
| 日报处理记录 | `ingestion.processing_runs` + `finance.daily_versions` + 工件身份 |
| 可用月份 | `finance.current_daily_versions` |
| 渠道 BI | `finance.v_active_daily_facts` + `finance.daily_channel_metrics` |
| 渠道明细 | `finance.v_active_daily_facts` |
| 月报生成 | `monthly_reports` 查询 current facts |
| 公司 10 日报表 | `company_reports` 查询 Finance facts + booking room items |

`arr_web/repository.py` 已改用 `ingestion.processing_runs`、`ingestion.artifacts`、`finance.daily_versions` 和 current facts；旧 `finance.processing_jobs`、`booking.file_objects`、`finance.report_versions` 引用已移除。

## 4. BI 固定口径

- 售出房数：`sum(NO_OF_ROOMS)`
- 总价：`sum(TOTAL PRICE)`，不能再次乘房数或晚数
- 间夜：`sum(NIGHTS × NO_OF_ROOMS)`
- 房型：`ROOM_CATEGORY_LABEL`，空值显示为未标注房型
- 渠道：`channel_key`，顺序来自 current daily channel metrics
- 业务范围：只包含 current daily version 中 outcome 为 retained 的记录

渠道明细公开字段限制为日期、晚数、房数、公司、rate code、房型、real price 和 total price；不要向 BI 返回姓名、确认号、房号、备注、trace、source coordinates 或 OSS object key。

## 5. 月报版本含义

最新业务决策是不在 PostgreSQL 重复保存月报行或 `report_versions`。

- `GET /api/monthly-runs` 当前返回该月份“数据库数据源已就绪”的投影，包含截止日、渠道数和行数；
- 它不伪造数据库月报工件，因此 `artifact_sha256` 为空；
- `POST /api/monthly-runs` 由普通程序生成 XLSX，并在发布前再次核对 current daily pins；
- 生成文件可保存在私有 OSS/受控输出目录，但不是数据库业务事实；
- 旧 `GET /api/download/monthly?report_id=...` 没有 report-version 记录可解析，会返回未找到。

如果产品后续需要“历史月报下载列表”，应单独增加轻量 OSS 生成工件目录/接口，不要恢复重复的月报行表。

## 6. API

当前主要路由：

- `GET /api/session`
- `GET /api/health`
- `GET /api/jobs?month=YYYY-MM`
- `POST /api/jobs`
- `GET /api/monthly-runs?month=YYYY-MM`
- `POST /api/monthly-runs`
- `GET /api/months`
- `GET /api/analytics?month=YYYY-MM`
- `GET /api/h5/months`（旧 H5 月份索引兼容，raw response）
- `GET /api/monthly/{month_key}/analytics`（旧 H5 analytics 1.2 兼容，raw response）
- `GET /api/channel-detail?month=YYYY-MM&worksheet=...`
- `GET /api/company-reports/jobs`
- `POST /api/company-reports/jobs`
- `POST /api/integrations/super-agent/results`

所有公开响应必须 `no-store`；写请求使用同源 session/CSRF，Agent 回写使用机器验签而不是浏览器 CSRF。

## 7. 本机启动

```bash
PYTHONPYCACHEPREFIX=/private/tmp/arr-web-pyc \
.venv/bin/python -m arr_web.run \
  --host 127.0.0.1 \
  --port 8765 \
  --db-config /path/to/private/booking-test-db.env \
  --enable-processing \
  --enable-agent-writeback \
  --enable-monthly-generation \
  --enable-company-reports \
  --node-binary /absolute/path/to/node \
  --artifact-tool-module /absolute/path/to/artifact_tool.mjs
```

地址：桌面 `http://127.0.0.1:8765/`，手机 `http://127.0.0.1:8765/h5`，健康检查 `http://127.0.0.1:8765/api/health`。

启动时后端会检查目标数据库为 `booking_test`。当前代码的 read transactions 使用 REPEATABLE READ READ ONLY 和超时门禁。`processing_ready=true` 表示“XML 上传 OSS 并提交 Agent”已装配；`agent_writeback_ready=true` 表示“签名结果回调、OSS 重取与数据库落库”已装配。任一缺失时对应入口 fail-closed。

## 8. 已验收状态

对远程测试库的真实只读验收：

- 看板：2026-07，1 个渠道、1 条 retained；
- 渠道明细：1 行；
- Web 日报列表：1 条 accepted/succeeded；
- 月度数据源投影：1 条、1 行、无数据库月报工件；
- 月报生成源：1 行；
- QBD 公司报表源：1 行，Booking Room 为 `【DBL】1`。

这是一组合成流程 fixture，不是真实业务规模。

## 9. 给看板对话的提示词

```text
请先完整读取 FRONTEND_HANDOFF.md 和
DATABASE_CONVERSATION_HANDOFF.md。

看板只能通过 ARR 后端只读查询 <ARR_DB_HOST>:5432/booking_test；本机配置是
/path/to/private/booking-test-db.env，绝不能把账号或 DSN 放进前端。
BI 使用 channel_analytics/current + retained facts，不再查询 report_versions 或 dashboard.json。
不要改数据库写模型；若需要新的聚合接口，先复用现有只读 repository 和隐私字段白名单。
```

## 10. 生产缺口

生产前仍需创建最小权限 reader/writer、将 Agent Profile 开启 Open API 并发布、注入正式 OSS 与独立 HMAC、让 Super Agent runtime 调用已实现的签名回写 adapter，并做一笔无隐私竖切和权限/隐私测试。输入已按现有 `fetch_oss_file` 使用的 `oss_attachments` 契约生成，但未发布的 Profile 仍不能由 ARR key 调用。当前远程地址用于测试，不代表已经确定为生产地址。