353 lines
20 KiB
Markdown
353 lines
20 KiB
Markdown
# ARR 2.0 项目说明与交接指南
|
||
|
||
> 文档基线：2026-09-06。本文说明仓库当前代码的职责、架构、运行方式和交接边界。生产环境是否已经运行同一版本，必须通过发布记录、进程启动时间、健康检查和受控验收单独确认。
|
||
|
||
## 1. 项目概述
|
||
|
||
ARR 2.0 是面向酒店 Finance 团队的 Opera 数据接入与报表自动化系统。系统接收 Opera `RES_DETAIL` XML 和 Booking 原始 Excel，在固定规则下完成解析、校验、数据库提交、月报发布、公司渠道明细生成与渠道 BI 展示。
|
||
|
||
项目的核心原则是：业务用户只提供源文件，内部处理参数由系统从已提交的业务事实中推导。生产 XML 主链由 ARR 自身的确定性程序完成，不依赖 Agent、MCP、Prompt 或公开源文件 URL。
|
||
|
||
### 主要使用者
|
||
|
||
- 酒店 Finance 操作员：登录、上传 XML、处理缺价复核、下载日报与月报。
|
||
- 公司渠道报表操作员：上传 Booking Excel、核对房型、生成公司渠道明细。
|
||
- BI 使用者：查看按月份、公司、渠道和房型汇总的数据。
|
||
- 运维与开发人员：维护 PostgreSQL、OSS、Web、月报 worker 和部署环境。
|
||
|
||
### 项目不做什么
|
||
|
||
- 不让业务用户手工输入月报年份、月份或“更新至”日期。
|
||
- 不让月报程序再次解析 XML、执行白名单、去重、定价或公司匹配。
|
||
- 不把真实登录凭据、数据库 DSN、OSS Secret 或住客隐私写入仓库、日志或浏览器响应。
|
||
- 不把远端 Agent/MCP 的成功响应当作 Finance 已提交；ARR 2.0 的生产 XML 主链不使用该路径。
|
||
|
||
## 2. 系统全景
|
||
|
||
```text
|
||
┌──────────────────────────────┐
|
||
│ ARR Web / Caddy │
|
||
│ 登录、上传、复核、下载、BI │
|
||
└──────────────┬───────────────┘
|
||
│
|
||
┌─────────────────────────┼─────────────────────────┐
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
Opera RES_DETAIL XML Booking 原始 Excel 只读查询/下载
|
||
│ │ │
|
||
▼ ▼ │
|
||
固定处理器 + 独立验证器 提取草稿 + 人工核对 │
|
||
│ │ │
|
||
▼ ▼ │
|
||
Finance 原子版本提交 当前 Booking 完整来源 │
|
||
│ │ │
|
||
├──────────────┬──────────┴──────────────┐ │
|
||
▼ ▼ ▼ │
|
||
outbox 月报事件 渠道 BI 公司渠道明细任务 │
|
||
│ │ │
|
||
▼ ▼ │
|
||
独立 monthly worker Python/openpyxl │
|
||
│ │ │
|
||
└───────────────┬────────────────────────┘ │
|
||
▼ │
|
||
私有 OSS 报表工件 ◄───────────────────────────┘
|
||
```
|
||
|
||
### 权威状态与存储职责
|
||
|
||
| 层 | 权威内容 |
|
||
|---|---|
|
||
| PostgreSQL | 任务、处理尝试、复核生命周期、Finance 当前事实、Booking 当前来源、outbox、月报发布元数据 |
|
||
| OSS | 源文件、日报、月报、公司报表、结果 JSON 与冻结人工价格清单等不可变工件 |
|
||
| Web | 登录会话、CSRF、上传与复核入口、只读查询、受控下载和页面交互 |
|
||
| monthly worker | 领取成功提交后的 outbox 事件，生成并发布月报 |
|
||
| `outputs/` | staging、历史本地兼容缓存和公司任务 `.web-jobs` 状态；不是新报表的最终权威存储 |
|
||
|
||
## 3. 核心业务流程
|
||
|
||
### 3.1 登录与访问边界
|
||
|
||
1. 桌面门户、详细健康信息、业务 API、上传、任务日志和下载默认需要登录。
|
||
2. 登录账号和密码只从 `ARR_WEB_USERNAME`、`ARR_WEB_PASSWORD` 注入；缺少任一变量时 Web 拒绝启动。
|
||
3. 会话由服务端保存，Cookie 使用 `HttpOnly` 和 `SameSite=Strict`；HTTPS 环境必须启用 `--secure-cookies`。
|
||
4. 所有已登录写操作还需要 CSRF token。
|
||
5. 公共例外只有 H5 页面及其专用聚合接口和无详情 `/healthz`；公共投影不返回源哈希、对象键或运营元数据。
|
||
|
||
### 3.2 Opera XML → 日报 → Finance
|
||
|
||
1. 浏览器上传 Opera `RES_DETAIL` XML。
|
||
2. ARR 校验文件名、内容和大小，将源文件保存为私有不可变 OSS 对象。
|
||
3. 固定版本处理器在隔离临时目录运行，生成日报 XLSX、结果 JSON、结构化 JSON，或者正式失败/缺价复核结果。
|
||
4. 独立验证器校验 Schema、SHA-256、字节数、MIME、行数、业务恒等式和日报重放结果。
|
||
5. 验证成功后，ARR 在一个数据库事务中写入并激活 Finance 日版本，同时创建 `arr.daily_version_committed` outbox 事件。
|
||
6. PostgreSQL 终态是成功与否的权威；HTTP 或控制台输出不能替代数据库提交证据。
|
||
|
||
上传接口为了兼容页面仍返回 HTTP `202`，但响应时初始处理已经收敛到 `succeeded`、`needs_review` 或 `failed`。
|
||
|
||
### 3.3 纯缺价人工复核
|
||
|
||
只有非空错误集合全部为 `PRICE_UNMATCHED` 时，任务才进入人工复核：
|
||
|
||
- 初始阶段不生成可下载日报，不写 Finance 版本，也不创建失败事件或月报事件。
|
||
- 操作员只能为已验证的“公司 + Rate Code + Opera price”键填写非负整数，显式 `0` 合法。
|
||
- 数据库存为精确两位小数，冻结清单把整数规范化为如 `0.00` 的文本。
|
||
- 确认生成时，系统将清单绑定到 job、case、源文件 SHA、业务日期、处理器/规则身份和完整键集合。
|
||
- 系统重新物化原 XML，用同一固定处理器重放并独立验证；只有最终重放成功才提交 Finance 和 outbox。
|
||
- 基础设施错误保留冻结清单以便重试；确定性错误关闭任务。开放 case 遇到处理器或规则版本变化时，应取消后重新上传。
|
||
|
||
### 3.4 Finance → 自动月报
|
||
|
||
1. 独立 `monthly_reports.worker` 使用租约和 `FOR UPDATE SKIP LOCKED` 领取 `arr.daily_version_committed`。
|
||
2. worker 从该 Finance 版本实际保留的 `ARRIVAL` 推导受影响月份。
|
||
3. “更新至”日期取当前月报快照中最大的 `ARRIVAL`，不使用 XML 文件名或服务器时间推测。
|
||
4. 程序以 repeatable-read 快照生成 XLSX 和 `result.json`，重新打开并校验工作簿。
|
||
5. 每个数据行的 `TOTAL PRICE` 必须是 Excel 公式：`REAL PRICE × NIGHTS × NO_OF_ROOMS`，当前布局形如 `=R2*C2*G2`。
|
||
6. 两份工件写入 OSS、登记并激活后，outbox 才标记 `published`；相同快照重放不会重复发布。
|
||
|
||
月报页面只显示持久化发布记录，并在页面可见时轮询更新。用户无需手工选择月报月份或点击生成。
|
||
|
||
### 3.5 Booking Excel → 公司渠道明细
|
||
|
||
1. 操作员上传完整原始 `.xlsx`；解析器只接受同一表头行上的两类已批准完整表头。
|
||
2. 表头经过 Unicode、大小写、空白和标点归一化后仍需整格精确匹配，不做文件名、月份、工作表名、包含词或模糊匹配。
|
||
3. 提取结果先进入草稿。自动识别和人工记录均可编辑或删除；pending 项不计入有效 Booking 房量。
|
||
4. 草稿必须零 pending 且至少保留一条确认记录，才能原子激活为新的当前完整来源。
|
||
5. 激活是整表替换，不是静默追加；打开的草稿会阻止创建新的公司报表任务。
|
||
6. 公司报表从当前 Finance 事实读取价格与入住信息，用规范化完整 Group Code 关联当前 Booking 房型数量。
|
||
7. 没有 Group Code 或找不到 Booking 房型时，Finance 行仍保留，`Booking Room` 留空；这不是报表失败。
|
||
|
||
当前支持 `LianTai`、`QBD`、`DY-AI-Easy-KB`、`FengRun` 和 `HanaTour` 五家公司。公司报表由 Python/openpyxl 生成，无公式；`Total Booking Price` 直接使用 Finance 的 `TOTAL PRICE`。
|
||
|
||
### 3.6 渠道 BI
|
||
|
||
渠道 BI 直接读取当前 Finance 日事实，不读取月报工作簿。聚合口径包括：
|
||
|
||
- sold rooms：`sum(NO_OF_ROOMS)`；
|
||
- total price：`sum(TOTAL PRICE)`，不再次相乘；
|
||
- room nights：`sum(NIGHTS × NO_OF_ROOMS)`；
|
||
- 数据范围：同一当前版本快照中的最小/最大 `ARRIVAL`。
|
||
|
||
公开 H5 只提供去隐私的聚合数据；详情接口不返回住客姓名、确认号、房号、备注、对象键、凭据或处理 trace。
|
||
|
||
## 4. 代码模块
|
||
|
||
| 路径 | 职责 |
|
||
|---|---|
|
||
| [`arr_web/`](arr_web/) | Web 路由、登录会话、上传、复核、任务日志、下载、页面和运行时装配 |
|
||
| [`arr_processing/`](arr_processing/) | 固定处理器执行、版本/规则身份、运行策略与处理回执 |
|
||
| [`arr_ingestion/`](arr_ingestion/) | 交付契约、独立验证、生命周期与 Finance 原子入库 |
|
||
| [`arr_storage/`](arr_storage/) | 私有不可变对象存储、OSS 适配、工件身份与安全物化 |
|
||
| [`booking_ingestion/`](booking_ingestion/) | Booking Excel 解析、草稿复核和当前来源激活 |
|
||
| [`monthly_reports/`](monthly_reports/) | 月报快照、生成、校验、发布和独立 worker |
|
||
| [`company_reports/`](company_reports/) | 五家公司渠道明细的生成、校验和发布 |
|
||
| [`channel_analytics/`](channel_analytics/) | 当前 Finance 事实的只读 BI 投影 |
|
||
| [`database/`](database/) | PostgreSQL 基线、增量迁移、回滚保护和应用记录 |
|
||
| [`tests/`](tests/) | 单元、契约、迁移、Web、工作簿和竖切回归测试 |
|
||
| [`deploy/`](deploy/) | Caddy、Compose 环境样例与生产部署说明 |
|
||
| [`.project-docs/`](.project-docs/) | 项目定位、ADR、架构、业务规则、工作日志、证据和遗留项 |
|
||
|
||
历史 Agent/MCP 兼容模块仍为审计和旧测试保留，但不属于 ARR 2.0 的生产 XML 主入口。
|
||
|
||
## 5. 环境要求与配置
|
||
|
||
### 基础依赖
|
||
|
||
- Python 3.12；
|
||
- PostgreSQL 15+，且目标数据库必须名为 `booking_test`；
|
||
- 满足区域、加密、ACL 和 versioning 约束的阿里云 OSS；
|
||
- 生产部署建议使用 Docker Compose、Caddy 和独立进程管理器。
|
||
|
||
安装本地依赖：
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
.venv/bin/python -m pip install --upgrade pip
|
||
.venv/bin/python -m pip install -r requirements.txt
|
||
cp .env.example .env.local
|
||
```
|
||
|
||
根 [`requirements.txt`](requirements.txt) 聚合处理、入库、OSS 和月报依赖。公司报表、Booking 与历史兼容路径另有分模块 requirements 文件，Docker 构建会复制并安装根聚合依赖。
|
||
|
||
### 关键环境变量
|
||
|
||
| 变量 | 用途 |
|
||
|---|---|
|
||
| `ARR_WEB_USERNAME` / `ARR_WEB_PASSWORD` | Finance 操作员登录；密码至少 12 位，生产必须使用独立长随机值 |
|
||
| `ARR_DATABASE_URL` | 主数据库连接，必须指向 `booking_test` |
|
||
| `MONTHLY_REPORT_DATABASE_URL` | 可选月报角色覆盖，默认回退到 `ARR_DATABASE_URL` |
|
||
| `DASHBOARD_DATABASE_URL` | 可选 BI 只读角色覆盖，默认回退到 `ARR_DATABASE_URL` |
|
||
| `ARR_OBJECT_PREFIX` | ARR OSS 对象前缀 |
|
||
| `ARR_OSS_REGION` / `ARR_OSS_ENDPOINT` / `ARR_OSS_BUCKET` | OSS 区域、端点和 bucket |
|
||
| `OSS_ACCESS_KEY_ID` / `OSS_ACCESS_KEY_SECRET` / `OSS_SESSION_TOKEN` | OSS SDK 凭据；优先使用 RAM 角色或 STS 注入 |
|
||
|
||
以 [`.env.example`](.env.example) 为唯一公开样例。不要提交 `.env.local`、`deploy/.env.production`、数据库配置文件或真实 Secret。
|
||
|
||
## 6. 本地运行
|
||
|
||
将 `.env.local` 中的配置安全注入当前 shell 后，启动完整 Web 能力：
|
||
|
||
```bash
|
||
.venv/bin/python -m arr_web.run \
|
||
--host 127.0.0.1 \
|
||
--port 8765 \
|
||
--enable-processing \
|
||
--enable-monthly-generation \
|
||
--enable-company-reports
|
||
```
|
||
|
||
另开一个终端启动自动月报 worker：
|
||
|
||
```bash
|
||
.venv/bin/python -m monthly_reports.worker \
|
||
--output-root /absolute/path/to/ARR2.0/outputs/monthly_reports
|
||
```
|
||
|
||
如果不是通过环境变量提供数据库，可使用受控文件：
|
||
|
||
```bash
|
||
.venv/bin/python -m monthly_reports.worker \
|
||
--db-config /absolute/path/to/booking-test-db.env \
|
||
--output-root /absolute/path/to/ARR2.0/outputs/monthly_reports
|
||
```
|
||
|
||
访问 `http://127.0.0.1:8765`。登录后查看 `/api/health` 的详细 readiness；容器和外部探针只使用无详情 `/healthz`。
|
||
|
||
`--enable-monthly-generation` 打开的是 Web 内部受控恢复入口，不替代独立 worker。日常自动月报仍以 outbox + worker 为唯一主流程。
|
||
|
||
## 7. 数据库与迁移
|
||
|
||
当前权威结构为 [`database/008_arr_mvp_v1_rebuild.sql`](database/008_arr_mvp_v1_rebuild.sql) 加 009–018 增量迁移。应用迁移前必须：
|
||
|
||
1. 确认连接数据库名称严格为 `booking_test`；
|
||
2. 备份并保存 schema/data manifest；
|
||
3. 校验迁移 SHA-256；
|
||
4. 在恢复副本或外层回滚事务中先做 up/down 探针；
|
||
5. 按迁移依赖顺序发布，不改写已应用迁移。
|
||
|
||
017 增加日报缺价复核生命周期，018 增加冻结人工清单工件类型。一旦存在 review case、人工 lineage 或冻结清单，对应 down migration 会主动拒绝破坏性回滚。详细步骤见 [`deploy/README.md`](deploy/README.md) 和 [`database/APPLIED_MIGRATIONS.md`](database/APPLIED_MIGRATIONS.md)。
|
||
|
||
## 8. 测试与质量门禁
|
||
|
||
运行全量测试：
|
||
|
||
```bash
|
||
.venv/bin/python -m unittest discover -s tests -p 'test_*.py' -v
|
||
```
|
||
|
||
常用聚焦验证：
|
||
|
||
```bash
|
||
.venv/bin/python -m unittest tests.test_arr_programmatic -v
|
||
.venv/bin/python -m unittest discover -s tests -p 'test_arr_web*.py' -v
|
||
.venv/bin/python -m unittest discover -s tests -p 'test_company_reports*.py' -v
|
||
```
|
||
|
||
交付前至少检查：
|
||
|
||
- `git diff --check` 无空白或冲突标记问题；
|
||
- Markdown 内部链接存在；
|
||
- Web 和 worker CLI 可加载 `--help`；
|
||
- 关键竖切测试覆盖成功、待复核、失败、重试和幂等边界；
|
||
- 生成的 XLSX 被重新打开校验，月报公式引用同一行正确字段；
|
||
- `.project-docs` 的 planning gate 和 post-task documentation gate 通过。
|
||
|
||
涉及数据库或真实文件的验收应使用无 PII 测试数据和可回滚事务；任何真实 Booking 来源激活、人工定价确认或生产上传都需要业务操作员明确授权。
|
||
|
||
## 9. 生产部署
|
||
|
||
当前 Compose 模板包含 `web` 和 `caddy`：
|
||
|
||
- Web 负责应用登录、XML 处理、公司报表和下载；
|
||
- Caddy 负责 HTTPS；
|
||
- 月报 worker 是独立无端口进程，必须由 systemd、容器编排器或同等级工具持续守护。
|
||
|
||
部署前：
|
||
|
||
```bash
|
||
cp deploy/.env.production.example deploy/.env.production
|
||
chmod 600 deploy/.env.production
|
||
docker compose --env-file deploy/.env.production config --quiet
|
||
docker compose --env-file deploy/.env.production build web
|
||
docker compose --env-file deploy/.env.production up -d
|
||
```
|
||
|
||
单次 worker 探针：
|
||
|
||
```bash
|
||
docker compose --env-file deploy/.env.production run --rm web \
|
||
python -m monthly_reports.worker \
|
||
--once \
|
||
--output-root /app/outputs/monthly_reports
|
||
```
|
||
|
||
部署验收应覆盖登录/退出、健康状态、无 PII XML 竖切、纯缺价隔离、Finance 唯一 active 版本、outbox、月报公式、OSS 下载哈希，以及业务失败不触发月报。完整发布和回退步骤见 [`deploy/README.md`](deploy/README.md)。
|
||
|
||
## 10. 运行观测与故障定位
|
||
|
||
建议按以下顺序定位：
|
||
|
||
1. `/healthz` 是否返回 200；
|
||
2. 登录后的 `/api/health` 中 database、processing、download、company report 和 Booking source readiness；
|
||
3. PostgreSQL 任务/attempt/delivery/Finance/outbox 终态；
|
||
4. OSS 工件的对象身份、大小、MIME 和 SHA-256；
|
||
5. monthly worker 是否存活，以及 outbox 的 `pending`、`publishing`、`dead` 数量；
|
||
6. 公司报表 `.web-jobs` 状态与最终 OSS 发布结果。
|
||
|
||
不要从一个成功 HTTP 响应推断整个链路完成。日报成功需要 Finance 原子提交；月报成功需要两份工件登记并激活；公司报表成功需要每家公司发布结果完成。
|
||
|
||
常见边界：
|
||
|
||
- `needs_review`：纯缺价，等待人工填写，不是失败；
|
||
- `failed`：确定性业务/Schema/身份错误，不能靠盲目重试修复；
|
||
- 基础设施错误：允许按既定上限重试，但不得绕过独立验证；
|
||
- 月报未更新：先查成功日报对应 outbox 和 worker，再查页面刷新；
|
||
- 公司报表缺少 `Booking Room`：先区分无 Group Code、未匹配 Booking 与真正的 Finance 数据错误。
|
||
|
||
## 11. 安全、隐私与幂等要求
|
||
|
||
- 所有 ARR 新写 OSS 对象显式使用 private ACL；拒绝 `public-read-write` bucket 和启用/暂停的 versioning。
|
||
- 用户文件名只作为受控显示信息，不能进入 OSS 对象键。
|
||
- 临时处理目录在请求结束后清理；下载前重新校验路径/对象身份、大小和哈希。
|
||
- 日报价格复核只保存规范化价格键、聚合影响、revision 和前后价格，不保存住客姓名、备注或原始 trace。
|
||
- 同一 delivery 精确重放幂等；相同 ID 下字节变化必须冲突。
|
||
- 相同月报/公司报表语义快照复用权威发布物；不因 XLSX ZIP 元数据变化重复发布。
|
||
- 只有可识别的 PostgreSQL 瞬时并发错误可以做有界事务重试，业务或验证错误不重试。
|
||
|
||
## 12. 当前状态与交接注意事项
|
||
|
||
仓库内的实现、生产部署和业务验收是三个不同状态。交接时应特别核对：
|
||
|
||
- 本地 Daily 行交互与 Booking 双语表头兼容修改是否已发布到目标生产实例；
|
||
- Web 与 monthly worker 是否由可重启、可监控的持久 supervisor 管理；
|
||
- 真实 Booking 完整工作簿的上传、人工核对和整表激活是否已获业务授权并完成；
|
||
- 日报人工价格 case 是否由操作员确认了正确任务和正确价格后再重试；
|
||
- 生产登录密码是否已使用与用户名不同的高强度随机值；
|
||
- worker heartbeat、结构化日志、队列积压和 dead event 告警是否已补齐。
|
||
|
||
这些事项会随任务推进变化。权威开放项请查阅 [`.project-docs/90-maintenance/stale-items.md`](.project-docs/90-maintenance/stale-items.md)，当前工作焦点查阅 [`.project-docs/30-worklog/current-state.md`](.project-docs/30-worklog/current-state.md)。不要仅依据本文日期判断生产状态。
|
||
|
||
## 13. 新成员交接清单
|
||
|
||
1. 阅读本文件和根 [`README.md`](README.md)。
|
||
2. 阅读 [项目定位](.project-docs/00-brief/project-positioning.md)、[系统总览](.project-docs/20-architecture/system-overview.md)、[业务规则](.project-docs/40-domain/business-rules.md) 和 [决策索引](.project-docs/10-decisions/decision-index.md)。
|
||
3. 确认当前分支、远端、工作树和最近提交，不覆盖未提交改动。
|
||
4. 从 Secret 管理器获得运行配置，不向对话、日志或仓库复制真实值。
|
||
5. 在隔离 `booking_test` 与测试 OSS 前缀上完成健康检查和自动化测试。
|
||
6. 对任何迁移、真实上传、Booking 激活、人工价格确认或生产重启单独取得授权。
|
||
7. 发布后验证数据库权威状态、OSS 哈希、下载、worker 和页面，而不是只看进程存在。
|
||
8. 更新 `.project-docs` 的当前状态、任务历史、证据与遗留项。
|
||
|
||
## 14. 相关文档
|
||
|
||
- [根 README：快速启动与当前主链](README.md)
|
||
- [Web 接口与登录边界](arr_web/README.md)
|
||
- [验证后入库边界](arr_ingestion/README.md)
|
||
- [对象存储约束](arr_storage/README.md)
|
||
- [自动月报](monthly_reports/README.md)
|
||
- [公司渠道明细](company_reports/README.md)
|
||
- [渠道 BI](channel_analytics/README.md)
|
||
- [生产部署](deploy/README.md)
|
||
- [数据库 Schema 字典](DATABASE_SCHEMA_DICTIONARY.md)
|
||
- [项目决策索引](.project-docs/10-decisions/decision-index.md)
|
||
- [项目当前状态](.project-docs/30-worklog/current-state.md)
|