20 KiB
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. 系统全景
┌──────────────────────────────┐
│ 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 登录与访问边界
- 桌面门户、详细健康信息、业务 API、上传、任务日志和下载默认需要登录。
- 登录账号和密码只从
ARR_WEB_USERNAME、ARR_WEB_PASSWORD注入；缺少任一变量时 Web 拒绝启动。 - 会话由服务端保存，Cookie 使用
HttpOnly和SameSite=Strict；HTTPS 环境必须启用--secure-cookies。 - 所有已登录写操作还需要 CSRF token。
- 公共例外只有 H5 页面及其专用聚合接口和无详情
/healthz；公共投影不返回源哈希、对象键或运营元数据。
3.2 Opera XML → 日报 → Finance
- 浏览器上传 Opera
RES_DETAILXML。 - ARR 校验文件名、内容和大小，将源文件保存为私有不可变 OSS 对象。
- 固定版本处理器在隔离临时目录运行，生成日报 XLSX、结果 JSON、结构化 JSON，或者正式失败/缺价复核结果。
- 独立验证器校验 Schema、SHA-256、字节数、MIME、行数、业务恒等式和日报重放结果。
- 验证成功后，ARR 在一个数据库事务中写入并激活 Finance 日版本，同时创建
arr.daily_version_committedoutbox 事件。 - 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 → 自动月报
- 独立
monthly_reports.worker使用租约和FOR UPDATE SKIP LOCKED领取arr.daily_version_committed。 - worker 从该 Finance 版本实际保留的
ARRIVAL推导受影响月份。 - “更新至”日期取当前月报快照中最大的
ARRIVAL，不使用 XML 文件名或服务器时间推测。 - 程序以 repeatable-read 快照生成 XLSX 和
result.json，重新打开并校验工作簿。 - 每个数据行的
TOTAL PRICE必须是 Excel 公式：REAL PRICE × NIGHTS × NO_OF_ROOMS，当前布局形如=R2*C2*G2。 - 两份工件写入 OSS、登记并激活后，outbox 才标记
published；相同快照重放不会重复发布。
月报页面只显示持久化发布记录，并在页面可见时轮询更新。用户无需手工选择月报月份或点击生成。
3.5 Booking Excel → 公司渠道明细
- 操作员上传完整原始
.xlsx；解析器只接受同一表头行上的两类已批准完整表头。 - 表头经过 Unicode、大小写、空白和标点归一化后仍需整格精确匹配，不做文件名、月份、工作表名、包含词或模糊匹配。
- 提取结果先进入草稿。自动识别和人工记录均可编辑或删除；pending 项不计入有效 Booking 房量。
- 草稿必须零 pending 且至少保留一条确认记录，才能原子激活为新的当前完整来源。
- 激活是整表替换，不是静默追加；打开的草稿会阻止创建新的公司报表任务。
- 公司报表从当前 Finance 事实读取价格与入住信息，用规范化完整 Group Code 关联当前 Booking 房型数量。
- 没有 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/ |
Web 路由、登录会话、上传、复核、任务日志、下载、页面和运行时装配 |
arr_processing/ |
固定处理器执行、版本/规则身份、运行策略与处理回执 |
arr_ingestion/ |
交付契约、独立验证、生命周期与 Finance 原子入库 |
arr_storage/ |
私有不可变对象存储、OSS 适配、工件身份与安全物化 |
booking_ingestion/ |
Booking Excel 解析、草稿复核和当前来源激活 |
monthly_reports/ |
月报快照、生成、校验、发布和独立 worker |
company_reports/ |
五家公司渠道明细的生成、校验和发布 |
channel_analytics/ |
当前 Finance 事实的只读 BI 投影 |
database/ |
PostgreSQL 基线、增量迁移、回滚保护和应用记录 |
tests/ |
单元、契约、迁移、Web、工作簿和竖切回归测试 |
deploy/ |
Caddy、Compose 环境样例与生产部署说明 |
.project-docs/ |
项目定位、ADR、架构、业务规则、工作日志、证据和遗留项 |
历史 Agent/MCP 兼容模块仍为审计和旧测试保留，但不属于 ARR 2.0 的生产 XML 主入口。
5. 环境要求与配置
基础依赖
- Python 3.12；
- PostgreSQL 15+，且目标数据库必须名为
booking_test； - 满足区域、加密、ACL 和 versioning 约束的阿里云 OSS；
- 生产部署建议使用 Docker Compose、Caddy 和独立进程管理器。
安装本地依赖：
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 聚合处理、入库、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.local、deploy/.env.production、数据库配置文件或真实 Secret。
6. 本地运行
将 .env.local 中的配置安全注入当前 shell 后，启动完整 Web 能力：
.venv/bin/python -m arr_web.run \
--host 127.0.0.1 \
--port 8765 \
--enable-processing \
--enable-monthly-generation \
--enable-company-reports
另开一个终端启动自动月报 worker：
.venv/bin/python -m monthly_reports.worker \
--output-root /absolute/path/to/ARR2.0/outputs/monthly_reports
如果不是通过环境变量提供数据库，可使用受控文件：
.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 加 009–018 增量迁移。应用迁移前必须：
- 确认连接数据库名称严格为
booking_test； - 备份并保存 schema/data manifest；
- 校验迁移 SHA-256；
- 在恢复副本或外层回滚事务中先做 up/down 探针；
- 按迁移依赖顺序发布，不改写已应用迁移。
017 增加日报缺价复核生命周期，018 增加冻结人工清单工件类型。一旦存在 review case、人工 lineage 或冻结清单，对应 down migration 会主动拒绝破坏性回滚。详细步骤见 deploy/README.md 和 database/APPLIED_MIGRATIONS.md。
8. 测试与质量门禁
运行全量测试：
.venv/bin/python -m unittest discover -s tests -p 'test_*.py' -v
常用聚焦验证：
.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、容器编排器或同等级工具持续守护。
部署前：
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 探针：
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。
10. 运行观测与故障定位
建议按以下顺序定位：
/healthz是否返回 200；- 登录后的
/api/health中 database、processing、download、company report 和 Booking source readiness； - PostgreSQL 任务/attempt/delivery/Finance/outbox 终态；
- OSS 工件的对象身份、大小、MIME 和 SHA-256；
- monthly worker 是否存活，以及 outbox 的
pending、publishing、dead数量； - 公司报表
.web-jobs状态与最终 OSS 发布结果。
不要从一个成功 HTTP 响应推断整个链路完成。日报成功需要 Finance 原子提交；月报成功需要两份工件登记并激活；公司报表成功需要每家公司发布结果完成。
常见边界：
needs_review：纯缺价，等待人工填写，不是失败；failed：确定性业务/Schema/身份错误，不能靠盲目重试修复；- 基础设施错误：允许按既定上限重试，但不得绕过独立验证；
- 月报未更新：先查成功日报对应 outbox 和 worker，再查页面刷新；
- 公司报表缺少
Booking Room：先区分无 Group Code、未匹配 Booking 与真正的 Finance 数据错误。
11. 安全、隐私与幂等要求
- 所有 ARR 新写 OSS 对象显式使用 private ACL；拒绝
public-read-writebucket 和启用/暂停的 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/30-worklog/current-state.md。不要仅依据本文日期判断生产状态。
13. 新成员交接清单
- 阅读本文件和根
README.md。 - 阅读 项目定位、系统总览、业务规则 和 决策索引。
- 确认当前分支、远端、工作树和最近提交，不覆盖未提交改动。
- 从 Secret 管理器获得运行配置，不向对话、日志或仓库复制真实值。
- 在隔离
booking_test与测试 OSS 前缀上完成健康检查和自动化测试。 - 对任何迁移、真实上传、Booking 激活、人工价格确认或生产重启单独取得授权。
- 发布后验证数据库权威状态、OSS 哈希、下载、worker 和页面，而不是只看进程存在。
- 更新
.project-docs的当前状态、任务历史、证据与遗留项。