40 lines
3.2 KiB
Markdown
40 lines
3.2 KiB
Markdown
# ARR 2.0 Web
|
||
|
||
Web 层提供固定页面和审计友好的 API。生产 XML 写路径为：
|
||
|
||
`POST /api/jobs` → `ProgrammaticUploadCoordinator` → 固定处理器 → `DeliveryValidator` → PostgreSQL 原子提交。
|
||
|
||
主要接口：
|
||
|
||
- `GET /login`、`POST /api/login`、`POST /api/logout`
|
||
- `GET /api/session`
|
||
- `GET /api/health`
|
||
- `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`，不会暴露到这两个用户界面；迁移前的历史任务没有可还原的上传名，页面显示 `—`。
|
||
|
||
月报主页面没有月份、截止日、手动生成或手动刷新控件。日报提交成功后，独立 `monthly_reports.worker` 消费 outbox 事件；它从数据库内纳入数据的最新 `ARRIVAL` 派生“更新至”。月报页可见时每四秒自动读取 `reporting.monthly_runs`，新版本发布后直接新增；页面隐藏或离开该页时停止轮询，恢复时立即读取。Web 内部 POST 生成端点只作为显式启用的受控恢复入口，不属于用户主流程。
|
||
|
||
公司渠道明细的 Booking XLSX 使用“提取 → 人工核对 → 整表启用”边界。上传只写私有源工件和
|
||
`booking.extraction_*` 草稿；自动/人工记录都能编辑或删除，待人工项目不会进入有效房量。只有草稿不存在
|
||
待人工项目且至少保留一条确认记录时，后端才在一个事务中生成 accepted Booking 批次并切换
|
||
`booking.current_source_batch`。打开草稿期间禁止创建新的公司渠道明细任务。
|