# 本机接口模拟与 ARR 按钮联调

2026-09-17。本机采集全链路已通过：按钮 → 日期查询/分页 → 预订详情/当日价 → ARR处理XML →
独立核验 → 日报 → 隔离Finance入库 → 自动月报/文件下载。它与8873原文件重放是两个独立实例。
Oracle实际来源的完整ARR验收仍未完成，默认`arr_web.run`不因此启用。

## 当前实例与结果

2026-09-17录制准备：用户认可交互后要求清空测试数据，现8874日报/月报/队列均为0，统计为空且按钮可用。
6次历史试跑及关联数据已冷备份至实例内`recording-backup-20260917-155725`，原9/15模拟源、账号密码保留。
页面已登录留在日报页；请勿主动再提交测试，以免破坏录像起点。
[清理证据与恢复边界](../.project-docs/50-evidence/topics/2026-09-17-arr-recording-cleanup.md)。
以下为清理之前的联调验收记录，数量不代表当前页面。

按钮任务已补充实际联调：无数据日期现在提示后可改选；9/15双击仅新增一批，刷新和同编号重发不重复。
按钮联调当时保留两次主动运行的日报/事件/月报（144条分类记录），当时最新月报为report_id=2，旧版本保留。
下面“一次完整采集”和“一个有效版本”描述单次运行及当前有效结果，不表示只有一条历史。
5项新增提交逻辑测试、34项回归及本轮浏览器/SQL/文件检查通过；完整证据见
[按钮联调记录](../.project-docs/50-evidence/topics/2026-09-17-arr-button-api-integration.md)。

- 页面：`http://127.0.0.1:8874/`，侧边浏览器已打开并登录。
- 私有目录：`/Users/chillishark/Downloads/arr-api-simulation-fvlfmt4y`。
- 唯一源日期：`2026-09-15`；From、To、有效价查询日均取系统传入的这个日期。
- 原文件：准确的`res_detail_71054429.XML`，72条；独立冻结副本的摘要
  `5c87ab6f2483b2244e98e47bb792080ef4aca9036568638842116b246ac97438`。
- 一次完整采集152个本机HTTP请求：8次搜索（20条/页，4页加完整复查）、72次详情、72次日价。
- 当前处理结果61保留、11费率排除，0重复/校验失败/价格未匹配；一个有效日报版本和一个已发布月报版本。
- 日报除按用户要求清空的Trace列外，其余单元格与原文件重放结果完全一致；月报61个金额公式通过检查。
- 服务完整停止/重启、重新登录、任务回显及两个文件下载通过；仍只有一个版本/事件/月报和72条分类记录。

## 按钮对接

沿用[单日下载HTTP契约](ARR_DOWNLOAD_HANDOFF.md)，开发服务指向8874。与8873有独立会话Cookie
`arr_api_simulation_session`；凭据只保存在该实例`login.json`。现有登录、CSRF和同源规则继续生效，
不将密码放入前端代码，也不开放跨域直连。服务重启会使内存登录会话失效，重新登录即可，业务任务保留。

1. `GET /api/arr-downloads`确认`ready=true`，同时检查`environment=local-api-simulation`、
   `source_kind=local_api_simulation`、`oracle_connected=false`和`default_date=2026-09-15`。
2. `POST /api/arr-downloads`提交`{"report_date":"2026-09-15","request_id":"32位小写十六进制"}`，带`X-ARR-CSRF`。
   202表示排队；其他源日期409且不创建任务。From/To/日价日期不会根据运行当天重算。
3. `GET /api/arr-downloads/{request_id}`查看任务；成功后按返回`job_id`下载日报。
4. `POST /api/arr-downloads/{request_id}/retry`沿用原任务恢复。未知提交结果也保留原交付身份。
5. `GET /api/download/daily?job_id=...`；月报异步生成，通过`GET /api/monthly-runs?month=2026-09`
   获取实际`report_id`后请求`GET /api/download/monthly?report_id=...`。

同一request_id重复提交不创建第二份Finance版本；新request_id表示用户主动重跑，允许新日报版本。
浏览器文件名带`LOCAL-API-SIMULATION-`，响应头有`X-ARR-Environment: local-api-simulation`。

## 模拟范围与实际来源的区别

本机酒店服务仅接受三种已接采集器的接口形状：

| 操作 | 本机接口 |
|---|---|
| searchHotelReservations | POST /api/v1/reservations/searches |
| getReservation | GET /api/v1/reservations/{local-id} |
| searchRateInfo | POST /api/v1/reservations/rate-info/searches |

该内层服务绑定127.0.0.1动态端口与临时随机密钥，只有本实例采集器使用；按钮使用稳定的8874外层接口。
不读取平台密钥，不允许外部baseURL，不使用代理或跳转，不提供酒店写入或模拟故障配置HTTP入口。
正常日志不输出原始请求/响应。故障注入只供本地测试进程调用。

`simulation-data.json`是独立派生数据，`fixture/source.xml`始终是未修改的基准。酒店ID、预订ID、状态及
最后修改时间明确为合成值。原币种THB保留；金额通过十进制JSON数传递。姓名、公司、显示房号、团号、
产品、房型标签与报表顺序存放在`__localARRReport`，**不伪装成已确认的Oracle映射**。
备注保留原XML的所有预订备注文本/顺序；模拟为GEN/RESERVATION，但不能据此证明Oracle备注顺序。
Trace按用户要求空列表，原文件中的Trace原样保留在基准内。

采集器使用既有v2归档/回放协议；归档中的旧service_url/application_id描述平台契约命名空间，
不能作为实际联网来源证据。此实例每个成功响应都包含`__localSimulation`来源摘要，适配契约以
`local-api-simulation/v1-`开头；实例清单、HTTP计数和下载标签共同明确全部请求仅发生在本机。
归档的report_equivalence_verified/finance_ready仍为false，不能拿本轮模拟验收替代Oracle真实报表验收。

独立核验器重新读取原始XML，逐字段/备注/顺序比较生成的处理XML；只接受明确的日期/数字规范化、合成ID
和无Trace选择。后续处理器另行负责白名单、去重、价格及入库验证，模拟服务不提前过滤记录。

## 创建与重启

```sh
.venv/bin/python -m arr_web.local_api_simulation init \
  --parent /Users/chillishark/Downloads \
  --xml /Users/chillishark/Downloads/res_detail_71054429.XML \
  --expected-sha256 5c87ab6f2483b2244e98e47bb792080ef4aca9036568638842116b246ac97438 \
  --report-date 2026-09-15

.venv/bin/python -m arr_web.local_api_simulation serve \
  --root /Users/chillishark/Downloads/arr-api-simulation-fvlfmt4y --port 8874
```

现有实例已在运行，不要重复启动同目录服务。停止前核对`server-process.json`对应PID的完整命令，确认是
这个实例后SIGTERM；等待进程和自有数据库完全退出再重启。保留原目录，不重新init，不重置数据库。
与原文件重放复用受控基础设施：新0700私有目录、0600业务文件、独立Unix socket PostgreSQL、每次核对
data_directory、排除环境DSN、不接现有同名库。原文件重放入口拒绝打开带simulation.json的实例。
每批上限2000条、100页，每页20条。修改源、模拟清单、派生数据或处理规则时拒绝原实例复用。

验证：9项新增测试（其中1项真实SQL及重启）与82项相关测试，共91项通过；实际72条数据、浏览器桌面/
390px视口、刷新与整机服务重启验收通过。`acceptance-summary.json`、`browser-verification.json`、
`http-counts-before-restart.json`和截图在私有实例目录。浏览器检查使用
`tests/browser/arr_local_xml_replay.cjs`并显式设`ARR_LOCAL_TEST_MODE=local-api-simulation`。
本轮没有修改预订项目模拟酒店、生产服务、平台凭据或授权，没有调用酒店平台业务接口。