# ARR Web Portal

The portal exposes four surfaces:

- 日报处理：XML upload, remote processing status, ARR validation and database result;
- 月报处理：ordinary program generation from current database facts;
- 渠道 BI：live read-only aggregation from current retained facts;
- 渠道使用情况：company ten-day report jobs.

## Current database model

`arr_web.repository.PostgresPortalRepository` reads migration 008 relations:

- `ingestion.processing_runs` / `ingestion.artifacts` for daily history and artifacts;
- `finance.daily_versions` / `finance.current_daily_versions` for validated dates;
- `finance.v_active_daily_facts` and current channel metrics through `channel_analytics`.

There are no database `report_versions`. The monthly-runs read endpoint exposes a source-ready monthly projection (dates, channels and row count) and does not claim an XLSX artifact. Generated monthly files live in the controlled publishing/OSS layer.

## Local run

```bash
PYTHONPYCACHEPREFIX=/private/tmp/arr-web-pyc \
.venv/bin/python -m arr_web.run \
  --host 127.0.0.1 \
  --port 8765 \
  --db-config /path/to/private/booking-test-db.env \
  --enable-processing \
  --enable-agent-writeback \
  --enable-monthly-generation \
  --enable-company-reports \
  --node-binary /absolute/path/to/node \
  --artifact-tool-module /absolute/path/to/artifact_tool.mjs
```

- Desktop: `http://127.0.0.1:8765/`
- H5: `http://127.0.0.1:8765/h5`
- Health: `http://127.0.0.1:8765/api/health`

The active test target is the controlled `<ARR_DB_HOST>:5432/booking_test`. The old `booking-test-lan-db.env` is retained only for temporary rollback checks and should not receive new writes.

`--enable-processing` is also fail-closed. It reports `processing_ready=true`
only when PostgreSQL, the guarded OSS uploader and the Open Agent client all
initialize; the dispatched message contains one `fetch_oss_file` attachment
descriptor and no OSS credential.

`--enable-agent-writeback` is fail-closed. `GET /api/health` reports
`agent_writeback_ready=true` only after the current processor policy, PostgreSQL
state/repository, independent HMAC verifier, Aliyun OSS backend and controlled
output reader all initialize successfully. Missing or incompatible deployment
configuration keeps the callback route unavailable instead of accepting an
unverified result.

The local LaunchAgent wrapper optionally loads
`/path/to/private/agent-writeback.env`. It refuses a symlink,
non-regular file, foreign owner or permissions other than `0600`; no real
secret belongs in this repository or `.env.example`.

Local secrets use the macOS Keychain account `arr-web`. The launcher maps the
OSS key ID/secret and the Agent Open API key from their dedicated service names
into process environment variables; the callback HMAC remains an independent
Keychain item. At present the launchd label and launcher/log paths still use
the historical project location even though the process runs this repository;
that deployment-path cleanup is separate from application readiness.

## Security

- Browsers never receive a PostgreSQL DSN or OSS credential.
- Read transactions are repeatable-read/read-only and reject any database other than `booking_test`.
- Writes use same-origin session/CSRF; machine result callbacks use signed result verification.
- Downloads are resolved from server-owned artifact identity, then rechecked for path, type, size and SHA-256.
- Production needs dedicated reader/writer roles and a provider-backed private OSS reader; the current test database owner and local fixture reader are not production configuration.

## API

- `GET /api/session`
- `GET /api/health`
- `GET|POST /api/jobs`
- `GET|POST /api/monthly-runs`
- `GET /api/months`
- `GET /api/analytics`
- `GET /api/h5/months` (legacy H5 raw compatibility)
- `GET /api/monthly/{month_key}/analytics` (analytics 1.2 raw compatibility)
- `GET /api/channel-detail`
- `GET|POST /api/company-reports/jobs`
- `POST /api/integrations/super-agent/results`

The machine callback accepts the canonical signed body described in
[`AGENT_WRITEBACK_CONTRACT.md`](../AGENT_WRITEBACK_CONTRACT.md). HTTP `200`
means that the delivery is committed (or is an identical idempotent replay),
not merely that the remote Agent Run reported `success`.

## Verification

```bash
PYTHONPYCACHEPREFIX=/private/tmp/arr-web-pyc \
python3 -m unittest tests.test_arr_web_repository_schema tests.test_arr_web -v
```

The full fake-transport end-to-end suite remains privacy-safe and uses synthetic identifiers only.