# Maintenance tools

Run these commands from the application root. This directory contains only active startup,
registry, and verification tools.

## Normal maintenance

- `powershell -ExecutionPolicy Bypass -File tools/start_local.ps1 [-Port 8797]`: start the
  local application in a hidden process and keep logs, the PID, and Python cache under
  `runtime/` instead of the source root.
- `python tools/verify_baseline.py`: all unit tests, registry checks, every frontend
  JavaScript syntax check, Git whitespace check, and read-only SQLite integrity check.
- `python tools/verify_baseline.py --e2e`: the same checks plus Playwright. The verifier owns
  the local static-server lifecycle so the command exits cleanly on Windows.
- `python tools/build_api_registry.py [--check]`: generate or verify
  `config/api.config.json` from `backend/http/dispatch.py` and the registered
  `backend/features/*/routes.py` owners.
- `python tools/build_architecture_inventory.py [--check]`: generate or verify
  `config/architecture-inventory.json` from the current source tree.
- `python tools/backfill_recent_snapshots.py --account <admin> [--lookback 60] [--dry-run]`:
  auditable recent trading-day dashboard snapshot backfill. See
  `docs/maintenance/行情历史补档.md`.
- `tools/update_from_main.sh` (deployed to the server as
  `~/xiaobai-build/update-from-main.sh`): the server-side update-and-build entry for
  the managed local worktree at `/opt/1panel/docker/compose/xiaobaifupan`. Fetches
  Gitea `main`, enforces branch/clean/fast-forward checks, builds a
  `main-<shortsha>` tagged image with the revision label, and verifies the label
  after the build. `tools/xiaobai-git` is the matching git wrapper for that
  worktree (`status`/`log`/`diff`).
- `bash tools/build_image.sh <commit> <tag>`: agent-grade entry that streams
  `git archive <commit>` to the deploy host over SSH (default
  `moxiaobai@192.168.200.11`), refuses tags that do not end with the commit
  short SHA, verifies the revision label after the build, and appends a record to
  `~/xiaobai-build/BUILD_LOG.tsv` on the host. Before building, it runs
  `tools/check_deploy_baseline.sh` so the candidate commit must contain the currently
  running container's Git revision as an ancestor.
- `bash tools/check_deploy_baseline.sh <commit> [--live-revision <sha>]`: deployment
  ancestor gate. Reads the live `org.opencontainers.image.revision` from the running
  `xiaobai-review` container (or `--live-revision` in tests), prints the live SHA,
  candidate SHA, file diff, and commits the candidate would drop, then exits if the
  live revision is not an ancestor of the candidate.

`verify_baseline.py` does not inspect a parent checkout or skip tests according to files outside
this application. Historical comparison scripts were retired after final standalone acceptance;
their results remain under `docs/migration/evidence/` and their source remains recoverable from
Git history.