ARR-2.0-0918/.project-docs/20-architecture/module-map.md

Module Map

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

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

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.

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.

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.

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. 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.

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.

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.