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. 安全架构

浏览器/手机 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/public/h5/months（匿名 H5 月份索引，只读聚合字段）
GET /api/public/h5/analytics?month=YYYY-MM（匿名 H5 看板，只读聚合字段；不含 source hash/运营元数据）
GET /api/channel-detail?month=YYYY-MM&worksheet=...
GET /api/company-reports/jobs
POST /api/company-reports/jobs
POST /api/integrations/super-agent/results

匿名公开范围仅限 H5 页面/资源、上述两个 /api/public/h5/* 聚合接口和 /healthz；桌面、通用/旧版 H5 接口、任务、详情健康、下载和写请求仍需 session/CSRF。所有公开响应必须 no-store；Agent 回写使用机器验签而不是浏览器 CSRF。

7. 本机启动

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

地址：桌面 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. 给看板对话的提示词

请先完整读取 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 调用。当前远程地址用于测试，不代表已经确定为生产地址。

6.3 KiB Raw Blame History Unescape Escape