75 lines
6.0 KiB
Markdown
75 lines
6.0 KiB
Markdown
# ARR 2.0 Web
|
||
|
||
2026-09-18：[直接数据入口](DIRECT_DATA_ENTRY.md)已接通日期按钮、日报、复核和月报；独立本机模拟8875，未查询实际Oracle。
|
||
|
||
2026-09-17：[本机接口模拟全流程及按钮联调](LOCAL_API_SIMULATION.md)已在独立8874验证；[原文件重放](LOCAL_XML_REPLAY.md)8873保留。两个入口均明确未连接Oracle，不改变默认运行配置。
|
||
|
||
按钮已完成真实浏览器联调（单日、重复点击、刷新、日报/月报下载），并修复模拟源日期不存在时无法改选的问题。
|
||
提交/未知结果身份保护的离线测试：`node --test tests/javascript/arr_download_submission.cjs`，不连接服务或数据库。
|
||
|
||
后端受控装配已支持`main(argv, arr_source=CapturedARRSource(...))`，共享现有处理依赖并按顺序关闭工作线程/存储。
|
||
默认启动仍未配置真实来源；接入和目录绑定要求见[受控启动装配](ARR_DOWNLOAD_HANDOFF.md#受控启动装配2026-09-17)。
|
||
相关独立测试：`.venv/bin/python -m unittest tests.test_arr_download_runtime`。
|
||
|
||
## 本地页面预览
|
||
|
||
不要直接打开 `arr_web/static/index.html`：`file://` 无法提供页面依赖的 `/assets` 和 `/api`。
|
||
在项目根目录运行 `.venv/bin/python -m arr_web.preview`，然后打开
|
||
[本地只读预览](http://127.0.0.1:8872/)。可用 `--port` 修改端口，退出进程即停止预览。
|
||
|
||
预览只监听本机回环地址，显示真实页面和明确的预览标识，历史为空，所有业务写操作均拒绝。
|
||
它不读取生产配置、连接数据库/OSS/OHIP 或启动下载；生产启动和登录方式不受影响。
|
||
|
||
真实 PostgreSQL 事务联调可单独运行：
|
||
|
||
```sh
|
||
ARR_TEST_LOCAL_POSTGRES=1 .venv/bin/python -m unittest -v tests.test_arr_download_postgres_integration
|
||
```
|
||
|
||
需要本机 `initdb`、`pg_ctl` 和 `psycopg`。测试自行创建私有临时集群，关闭 TCP 监听，使用合成来源和本地对象存储，
|
||
仅在该新集群应用现有008–019迁移；结束时停止并删除。它不接受外部 DSN 或既有数据库配置；未显式启用时跳过。
|
||
|
||
下载卡片的浏览器重连测试可运行 `node --test tests/browser/arr_download_reconnection.cjs`。
|
||
需要本机 Playwright/Chromium 和项目 `.venv`；可用 `ARR_TEST_PLAYWRIGHT_MODULE` 指定 Playwright 模块绝对路径，
|
||
`ARR_TEST_CHROMIUM` 指定本机浏览器可执行文件。测试自行启动并关闭空数据、只读的回环预览，下载接口响应全部合成，
|
||
覆盖首次断网、日期/任务恢复、服务恢复、隐藏暂停和请求合并，不连接真实酒店或业务数据库。
|
||
|
||
Web 层提供固定页面和审计友好的 API。生产 XML 写路径为：
|
||
|
||
`POST /api/jobs` → `ProgrammaticUploadCoordinator` → 固定处理器 → `DeliveryValidator` → PostgreSQL 原子提交。
|
||
|
||
主要接口：
|
||
|
||
- `GET /login`、`POST /api/login`、`POST /api/logout`
|
||
- `GET /api/session`
|
||
- `GET /api/health`
|
||
- `GET` / `POST /api/arr-downloads`、`GET /api/arr-downloads/{request_id}`、`POST /api/arr-downloads/{request_id}/retry`：单日自动下载任务；[接入契约与当前未就绪边界](ARR_DOWNLOAD_HANDOFF.md)
|
||
- `GET /healthz`：仅供容器读取的无详情 readiness 探针
|
||
- `POST /api/jobs`
|
||
- `GET /api/jobs`
|
||
- `GET /api/jobs/{job_id}/trace`
|
||
- `GET /api/download/daily`
|
||
- `GET /api/monthly-runs?month=YYYY-MM`：读取已持久化的月报版本
|
||
- `GET /api/download/monthly?report_id=...`：下载登记为 active/superseded 的月报并复核路径、大小和 SHA-256
|
||
- `POST /api/company-reports/source`：上传并提取原始 Booking XLSX，先创建复核草稿
|
||
- `GET /api/company-reports/source/draft`：分页读取当前复核草稿
|
||
- `PATCH`/`DELETE /api/company-reports/source/draft/items/{id}`：人工保存房型/数量或删除记录
|
||
- `DELETE /api/company-reports/source/draft/items`：在同一事务中批量删除最多 50 条所选记录
|
||
- `DELETE /api/company-reports/source/draft`、`POST /api/company-reports/source/draft/activate`：放弃草稿或在零待人工时原子启用
|
||
- BI 与公司报表接口
|
||
|
||
ARR 2.0 不注册 `/api/integrations/super-agent/results`。访问旧回调地址返回 `404 ROUTE_NOT_FOUND`。
|
||
|
||
除登录静态资源、`POST /api/login` 和 `/healthz` 外，页面、API、上传与下载均要求应用登录。Web 进程从 `ARR_WEB_USERNAME` / `ARR_WEB_PASSWORD` 读取 Finance 操作员凭据；缺失时启动失败。会话 cookie 为 `HttpOnly`、`SameSite=Strict`，HTTPS 部署必须启用 `--secure-cookies`。Caddy 仅终结 HTTPS，不再使用浏览器原生 Basic Auth。
|
||
|
||
`--enable-processing` 只有在数据库、OSS、固定处理器和独立验证器全部初始化成功时才使 `processing_ready=true`。上传处理是同步终态边界：HTTP 保持 `202` 兼容页面，但响应前已经完成验证/入库或记录失败。
|
||
|
||
日报历史中的“文件”显示浏览器上传的 XML basename，自动数据来源显示“接口获取”。内部源工件分别规范化为 `source.xml` 和 `source.json`，不会暴露到这两个用户界面；迁移前的历史任务没有可还原的上传名，页面显示 `—`。
|
||
|
||
月报主页面没有月份、截止日、手动生成或手动刷新控件。日报提交成功后，独立 `monthly_reports.worker` 消费 outbox 事件；它从数据库内纳入数据的最新 `ARRIVAL` 派生“更新至”。月报页可见时每四秒自动读取 `reporting.monthly_runs`，新版本发布后直接新增；页面隐藏或离开该页时停止轮询，恢复时立即读取。Web 内部 POST 生成端点只作为显式启用的受控恢复入口，不属于用户主流程。
|
||
|
||
公司渠道明细的 Booking XLSX 使用“提取 → 人工核对 → 整表启用”边界。上传只写私有源工件和
|
||
`booking.extraction_*` 草稿；自动/人工记录都能编辑或删除，待人工项目不会进入有效房量。只有草稿不存在
|
||
待人工项目且至少保留一条确认记录时，后端才在一个事务中生成 accepted Booking 批次并切换
|
||
`booking.current_source_batch`。打开草稿期间禁止创建新的公司渠道明细任务。
|