# Module Map

## 2026-09-18 本机OHIP沙箱运行入口

`arr_web/local_ohip.py`将真实OHIP凭据来源与独立本机库/存储组合，使用固定酒店OHIPSB02；不会在启动/登录时查询酒店。管理面check-access核对应用/密钥元数据；权限状态控制按钮、任务提交及执行。`local_replay`仅增加可选下载控制包装，`local_xml_replay`增加页面提示/状态扩展点，原XML和模拟默认行为保持。实例位置及当前缺权见[证据](../50-evidence/topics/2026-09-18-arr-ohip-activation.md)。

New direct-data acquisition: `integrations/ohip/arr_data.py` exposes `ARRDataSource.fetch(date, request_id)` and CLI;
`data_client.py` owns eight fixed read operations, bounded retry/cache and raw response provenance. Output is private
`arr-ohip-data/v1` JSON for15 fields, no XML or Finance writes.41 new/150 scoped offline checks pass. Existing XML
collectors/executor remain separate; direct data-processing/Web consumption is implemented through DirectARRSource/DirectARRExecutor. [Guide](../../integrations/ohip/DATA_SOURCE.md).

`arr_web.arr_download_runtime` composes explicit source components with the same processing dependencies exposed by
`ProcessingInputRuntime`; source.json pins identity before queued dispatch. Standard `run.main(..., arr_source=...)`
uses ordered resource ownership; default CLI has no configured source. Queue owners wait for active work before
closing shared clients/owned DB. This is assembly, not actual-source acceptance. [Handoff](../../arr_web/ARR_DOWNLOAD_HANDOFF.md).

Local API simulation: `arr_web.local_api_simulation` composes `local_api_fixture` (derived fixture, local adapter and independent native baseline validator), `local_api_server` (authenticated loopback search/detail/rate) and existing v2 capture/executor with isolated replay infrastructure. Separate8874/cookie/state; no platform URL/key or default runtime activation. [Guide](../../arr_web/LOCAL_API_SIMULATION.md).

Standalone local replay: `arr_web.local_replay` composes `local_xml_replay` snapshot/executor/label wrapper and
`local_replay_database` owned socket-only PostgreSQL with existing processing, validation, queue and monthly services.
It is not imported by the standard run entry; [guide](../../arr_web/LOCAL_XML_REPLAY.md). Native fixture replay does
not implement the API source adapter. Private state lives outside the repository and booking simulator.

`integrations/ohip/room_calendar_evidence.py` inspects one previously authenticated room-calendar response with explicit
hotel/date/target IDs. Preserves missing/empty states and all room/move occurrences, never infers pagination or selects
anARR room. No network or runtime wiring; see [evidence](../50-evidence/topics/2026-09-17-arr-room-calendar-evidence.md).

ARR local acquisition now also includes `integrations/ohip/profile_supplement.py`: separately pinned profile enrichment
over a verified completev2 base, bounded outage gaps, ordered prior-pin replay/cache reuse and optional source preparation.
It does not change legacyv3 or activate the runtime executor. See [guide](../../integrations/ohip/profile-supplement.md).

| Path | Responsibility | Notes |
|---|---|---|
| `integrations/ohip/prepare_arr_source.py` | Integrated offline strict field candidates and gap diagnostics | Rechecks pinned v2/v3 field evidence, retains all16 fields/allrows, source/evidence hashes and private output; no report ordering, whitelist, dedup, XML or adapter/validator protocol |
| `integrations/ohip/collect_arr_named_day.py`, `profile_reader.py`, `audit_arr_named_day.py`, `capture_named_day_job.py` | Versioned v3 capture with bounded exact-ID primary-name summaries | Four operations, explicit profile budget, private successful-response cache with per-reservation identity/name validation, immutable replay/reuse; separate v2 contract, no native display equivalence or runtime wiring |
| `arr_web/arr_downloads.py` | Explicit single-day automatic-download task boundary | Injected accepted executor; private single-host SQLite/process lock; stable request/retry identity and unknown-outcome recovery. Default Web runtime remains unavailable. See `arr_web/ARR_DOWNLOAD_HANDOFF.md` |
| `arr_web/arr_download_handoff.py` | Strict frozen-delivery acknowledgement conversion | Checks expected job/delivery/package/date and acknowledged Finance version before Web success; preserves review/failure and rejects unknown receipts. No source adapter or runtime executor |
| `arr_web/arr_download_executor.py` | Explicit-date capture/adaptation/frozen-delivery orchestration | Defaultv2 or explicitv3/mandatory profilebudget; requires accepted adapter/independent mapping validator. Typed immutable request/version/acquisition bounds, full capture/policy comparison before delivery and pre-delivery package checkpoint; prepared recovery skips capture/adaptation. No credentials or default runtime wiring |
| `tests/local_postgres.py`, `tests/test_arr_download_postgres_integration.py` | Opt-in real SQL acceptance in owned disposable cluster | No external DSN; private Unix socket with TCP disabled, current008–018 schema, synthetic source/local objects and automatic shutdown/cleanup |
| `arr_web/preview.py` | Explicit local UI preview command | Loopback-only HTTP, actual assets plus visible preview label, empty history, unavailable services and all mutations rejected; isolated from production runtime/configuration |
| `integrations/ohip/arr_xml_contract.py`, `arr_xml.py`, `validate_arr_xml.py` | Explicit source-row processing XML serialization and independent comparison | Preserves exact fields and row/note/Trace order,25MiB handoff cap; no API candidate selection, native report reconstruction, mapping approval or runtime wiring |
| `integrations/ohip/source_facts_contract.py`, `source_facts.py`, `validate_source_facts.py` | Private per-record field evidence and independent raw-source verification | Explicit capturev2/v3; named evidencev2 independently joins raw Primary Profile identities/successful retry provenance, distinct unqueried state; old contract unchanged. All16 columns/context remain candidates, no business acceptance or Web adapter protocol |
| `integrations/ohip/compare_arr_sources.py` | Pinned v2/v3 API/native ARR comparison aid | Same-hotel/date guards, unique internal-ID pairs, bounded observations including v3 validated primary name exact/trimmed comparison; no fallback, source adapter or equivalence/Finance approval |
| `integrations/ohip/collect_arr_day.py`, `audit_arr_day.py`, `capture_day_job.py` | Explicit-date v2 search/detail/rate capture, pinned offline replay and local batch entry | Three equal system-supplied dates, exact request identity, independent price diagnostics; shared local job lifecycle, no source projection/runtime/Finance wiring |
| `integrations/ohip/rate_info.py` | Reservation/day effective-rate read | Published0.7 GET/POST contract, bounded private response capture, exact decimals and fail-closed candidates; used by v2, v1 remains unchanged |
| `integrations/ohip/processing_handoff.py` | Isolated frozen XML delivery primitive | Stable batch job, local processor/independent validation, pre-freeze intent pin and verified interrupted-ready recovery, exact artifact/envelope replay and optional expected capture/policy checks before writes; typed identity digests; explicitly injected dependencies only, no runtime wiring or API source-equivalence claim |
| `integrations/ohip/capture_job.py` | Local acquisition batch lifecycle | Exact canonical JSON identity, private atomic state, OS file lock, full-attempt retry and pinned completed reuse; not a production queue or Finance submission interface |
| `integrations/ohip/audit_arr_capture.py` | Offline capture integrity/protocol replay and candidate-field audit | Requires recorded manifest hash, verifies private original files, emits aggregate observations only; no network, source projection or business readiness claim |
| `integrations/ohip/collect_arr_source.py` | Isolated OHIP search/detail candidate capture | Private raw archive with pre-write cumulative byte limit/reserved failure footer, completeness/drift checks and bounded retries; no runtime imports, source projection or Finance/OSS integration. Candidate completeness is not report equivalence |
| `arr_web/auth.py` | Login credential verification and bounded attempt ledger | Environment-owned single-operator identity; dependency-free constant-time comparison; no secret logging |
| `arr_web/programmatic.py` | XML upload and manual-price finalization coordinator | Registers the validated browser basename separately from canonical `source.xml`; pure price misses create no Finance version, while a frozen manifest replays the original source for final commit |
| `arr_web/booking_uploads.py`, `booking_ingestion/excel.py` | Authenticated Booking source upload and bounded raw XLSX parsing | Parser 2.1 uses approved full-cell exact aliases for Tour Code/Group Code and hotel detail (including legacy Thai and current bilingual forms), latest-row cancellations and extracted room items with review state; coordinator/backend route contracts target drafts |
| `booking_ingestion/excel_postgres.py` | Earlier direct Booking full-source import/activation path | Its one-item immediate-accept implementation does not represent parser 2.1 review and must not be treated as the completed review repository |
| `booking_ingestion/excel_review.py`, `booking_ingestion/excel_review_postgres.py` | Editable extraction drafts and atomic reviewed-source activation | Single-operator repository uses advisory locking and a zero-pending gate; real PostgreSQL transaction/rollback acceptance passes; actor/reason/revision history is not implemented |
| `arr_web/processing_runtime.py` | PostgreSQL + OSS + processor composition | Active production processing composition |
| `arr_processing/local.py` | Bounded subprocess and output manifest extraction | Never exposes stdout/stderr |
| `arr_processing/policy.py` | Frozen processor/rule identity | Active v4 loader plus isolated legacy direct-MCP v3 compatibility projection |
| `arr_ingestion/validation.py` | Strict artifact/result validation | Dispatches v3/v4; independently replays review and frozen-manifest final results |
| `arr_ingestion/postgres.py` | Job/review lifecycle and atomic Finance commit | `recorded_review` has no Finance/outbox write; final success is the only activation boundary; four retries only for transient SQLSTATEs |
| `arr_storage/aliyun_oss_v2.py` | Encrypted/unversioned OSS adapter | Writes all objects private |
| `arr_web/downloads.py` | OSS daily/report + controlled local legacy download routing | Rechecks provider metadata, size and SHA-256 |
| `arr_web/job_trace.py` | Programmatic persisted-fact trace | No external trace store |
| `arr_web/app.py`, `arr_web/repository.py`, `arr_web/company_jobs.py` | Authenticated portal routes plus public H5 aggregate routes, paged history reads and read-only history-month discovery | Default-deny login gate protects the desktop/API/download surface; purpose-built `/api/public/h5/*` exposes only sanitized aggregate metrics; daily/monthly counts and rows share a repeatable-read snapshot; `/api/history-months` merges daily/monthly database counts with company job-state counts; company totals/slices share one lock |
| `arr_web/server.py` | Standard-library HTTP transport | Dispatches GET/POST/PATCH/DELETE with one bounded body reader; real socket tests cover review update/delete and missing/oversized lengths |
| `arr_web/static/login.html`, `login.css`, `login.js` | Responsive ARR login gateway | Labeled form, password visibility, generic inline failures, safe desktop/H5 return target and reduced-motion support |
| `arr_web/static/app.js`, `arr_web/static/i18n.js`, `arr_web/static/h5.js` | Authenticated desktop and anonymous-capable H5 client state, rendering, localization and polling | Desktop daily/monthly/company histories own independent viewing-month state and default to the latest non-empty month; needs-review status opens/focuses the paged privacy-safe price panel, finalization projects a generating upload state, and review controls/errors follow the shared Chinese/English/Thai catalog. H5 reads only public aggregate endpoints; session-expiry redirect and CSRF logout remain shared |
| `monthly_reports/worker.py` | Dedicated outbox consumer | Lease/reclaim, retry/dead-letter, success acknowledgement after activation |
| `monthly_reports/repository.py` | Monthly snapshot and publication repository | Derives scope from `ARRIVAL`; persists metadata/lineage/artifact identities |
| `monthly_reports/publishing.py` | Python/openpyxl monthly builder and atomic/OSS publisher | Reopens sheets, headers, row counts, semantic hash and exact row-relative `TOTAL PRICE` formulas |
| `monthly_reports/`, `company_reports/`, `channel_analytics/` | Downstream reports/BI | Consume accepted Finance facts |
| `database/012_monthly_report_publication.sql` | Additive metadata-only publication schema | Applied after immutable 008–011 baseline |
| `database/016_monthly_report_oss_artifacts.sql` | Monthly publication provider compatibility | Allows new OSS/S3 identities while retaining legacy local records |
| `database/017_daily_price_review.sql` | Daily missing-price review lifecycle | Applied to controlled `booking_test` on 2026-08-06 after exact 016 semantic verification and corrected up/down probe; adds protected case/item/event audit, `awaiting_review`, manual lineage and guarded rollback |
| `database/018_daily_review_manual_override_artifact.sql` | Frozen manual-manifest artifact compatibility | Applied as a forward-only correction after rollback probing; permits only `manual_override_json` in the existing artifact-kind constraint and refuses destructive rollback once such an immutable artifact exists |
| `database/014_booking_current_source_batch.sql` | Booking full-workbook current-source pointer and view scoping | Formally applied on 2026-07-31; batch 1 remains selected |
| `database/015_booking_excel_review_drafts.sql` | Item-level Booking extraction draft state | Formally applied and empty; basic latest-state review only, with no actor/reason/revision history and no DB-enforced zero-pending activation |
| `compose.yaml`, `deploy/` | Web-login + Caddy-HTTPS template and worker deployment boundary | Requires Web credentials for the desktop/operational surface; public H5 aggregate routes and `/healthz` remain anonymously reachable; no MCP port/domain/service |
| `tests/test_arr_programmatic.py` | Real success/failure vertical slices | Primary ARR2.0 acceptance proof |

Historical ARR1 compatibility modules and migrations remain for audit/tests but are not imported, installed or deployed
by the active ARR2.0 entrypoint.

## Last Updated

2026-09-16

## Direct data entry — 2026-09-18

Direct data modules: arr_web/arr_data_executor.py freezes/replays JSON delivery; arr_data_runtime.py composes source and queue; run.py exposes explicit three-option OHIP configuration; processor/validator share business normalization; migration019 adds ohip_json and result5 review. tests/direct_data_portal.py is an explicitly synthetic independent local page.