# Deployment checklist

Hugging Face Space type: Docker, preferably Private while testing.

Required Space Secrets:
- `ZAI_API_KEY`（智谱 API key；启动脚本会映射给官方 Codex CLI）
- `CODEWHALE_RUNTIME_TOKEN`

Recommended Space Secret:
- `HF_TOKEN` with read access to any private/restricted fisheries Dataset used
  by the Space. The two default public repositories can be read without a token.

Required Space Variable:
- `MARINE_API_URL`

For the school deployment, keep `MARINE_API_URL=http://127.0.0.1:8000` and set
`MARINE_PROXY_UPSTREAM_URL=http://127.0.0.1:8000`. The fixed ngrok web domain
continues to point to port 7861; requests sent to `/marine/...` are forwarded
to the local Marine API. On Hugging Face, set `MARINE_API_URL` to the public
web URL with the `/marine` suffix, for example:
`https://subway-unbiased-barcode.ngrok-free.dev/marine`.

When the school network cannot reach Hugging Face, set these school-only
variables so fisheries inventory and downloads use the local mirror:
- `LOCAL_SQUID_DATA_ROOT=/data0/zqyan/squid_data/raw`
- `LOCAL_TUNA_DATA_ROOT=/data0/zqyan/tuna_data/raw`

Optional Space Variables:
- `HF_SQUID_DATASET_REPO` (default `globalsquiddatabase/squid_dataset`)
- `HF_TUNA_DATASET_REPO` (default `globalsquiddatabase/Tuna-Fisheries-Dataset`)
- `HF_SQUID_DATASET_REVISION` and `HF_TUNA_DATASET_REVISION` (optional approved
  commit SHAs; otherwise each repository's current SHA is resolved and cached)
- `PUBLIC_BASE_URL` (normally inferred from `SPACE_HOST`)
- `HF_FISHERIES_MAX_CSV_BYTES` and `HF_FISHERIES_MAX_ZIP_BYTES`

The current temporary Marine API URL can be used for the first smoke test.
Later replace the Quick Tunnel with a fixed Named Tunnel URL.

After the Space is Running:
1. Open `/mobile` if the root does not redirect there.
2. Test Ocean status: `检查我的海洋数据服务器，并告诉我三个数据中心状态。`
3. Test a real fisheries CSV read/export:
   `实际读取 current/sprfmo_effort.csv，报告字段、记录数、缺失、重复并导出 CSV。`
4. Test Tuna routing and export:
   `只查询 Tuna-Fisheries-Dataset，查找并读取 ICCAT/EFFDIS_LL2000-2024.csv，报告真实字段、记录数、缺失和重复并导出 CSV。`
   Expected exports: filtered raw detail, exact-deduplicated detail and annual
   summary. ICCAT `YearC` must be reported as the year field.
5. Expected model-visible tools include
   `mcp_marine_fisheries_analyze_export`.
6. Open the returned `/api/fisheries/download/{token}` URL and confirm the CSV
   downloads successfully.

Next server phase:
- add `/query`
- add `/subset`
- add `/download/{token}`
- add job/update APIs
Then extend `marine_mcp.py` with corresponding tools.

## v3.4.0 deployment stability

- `VERSION` is the single application version source.
- Only root `app.html` is served; do not re-create `templates/app.html`.
- `scripts/preflight.py` runs automatically from `start.sh` and fails fast if Space metadata or the frontend entry is inconsistent.
- For durable user favorites and project-package downloads, attach Hugging Face Persistent Storage and set:
  - `USER_STATE_ROOT=/data/squid_user_state`
  - `PROJECT_PACKAGE_ROOT=/data/squid_project_packages`