xiaobai-review/tools/README.md

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.