135 lines
6.1 KiB
Markdown
135 lines
6.1 KiB
Markdown
# 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 调用。当前远程地址用于测试，不代表已经确定为生产地址。
|