KSP_project/CLAUDE.md

KSP 管理后台 (KSP Management Backend)

• Note: you should always refer the user as Doctor Armor. It is non-negotiable.

Flask-based admin panel for a fictional space simulation universe.

Project overview

• Backend: Flask (app factory pattern), SQLAlchemy + PostgreSQL
• Frontend: Jinja2 templates, vanilla JS, custom CSS (dark theme default)
• Wiki: Wiki.js instance at http://192.168.195.241:38353, pages published via scripts/wiki_update_page.py
• Simulation time: 2060-03-12 09:00 UTC (DB-backed, no URL param)

Running the app

cd "d:/My Coding Project/KSP_Project"
PYTHONPATH="d:/My Coding Project/KSP_Project" python -m flask run --host=0.0.0.0 --port=9000 --debug

Use cmd //c "taskkill /f /im python.exe" to kill running Flask processes on Windows.

Key directories

Directory	Purpose
app/routes/	Flask blueprints (web.py, api.py)
app/templates/	Jinja2 templates
app/static/	CSS, JS
app/models.py	SQLAlchemy models
data/wiki/	Local HTML copies of Wiki.js pages
scripts/	One-off utilities, wiki publishing
migrations/	Alembic DB migrations

Wiki publishing

Edit the local HTML file in data/wiki/, then publish:

python scripts/wiki_update_page.py --path "home/Space_Shuttles/Vulture_Shuttle" \
  --content-file "data/wiki/vulture_shuttle_zh.html" --locale "zh" \
  --extract-style-to-script-css --extract-script-to-script-js --temporary-manage-system

Add --create-if-missing for new pages. HTML files use <style> blocks (extracted to page CSS) and wiki-infobox table patterns. Images use <div class="image-placeholder"> when the actual render is not yet available.

Mission gallery release gate (mandatory)

• Mission gallery interaction is provided only by scripts/wiki_mission_gallery_runtime.js, published with scripts/wiki_publish_mission_gallery_runtime.py. Do not put gallery JavaScript in page scriptJs or inline <script> blocks.
• After any gallery content, CSS, runtime, or publishing change, run both commands below. A gallery release is incomplete if either command fails or if screenshots were not visually inspected:

py -3.12 -m pytest tests/test_mission_galleries.py -q -p no:cacheprovider
py -3.12 scripts/wiki_verify_mission_galleries.py --screenshot-dir output/playwright/mission-gallery-e2e

• The E2E gate must cover every mission gallery, not a sample. See docs/wiki-mission-gallery-quality-gate.md for the incident root cause and checklist.

Database

• PostgreSQL is authoritative for mission logs and timelines
• Excel files (log_book.xlsx, Timeline.xlsx) are reference only, not data sources
• Use _default_simulation_time() in web.py for the canonical sim time

Naming conventions

• ST-01 = 万星源号 (Wanxingyuan / Stellaria), lead ship of Stellaria-class
• ST-02 = 克丽斯腾号 (Kristen), second Stellaria-class ship
• Star Port Station = 星港空间站 (LEO orbital shipyard, home port for motherships)
• Star Ring Station = 星环空间站 (separate station, do not confuse with Star Port)
• Xihe-class = 羲和级 (XH-01 through XH-04)
• Stellaria-class = 万星源级 (ST-01 through ST-04)
• Vulture Shuttle = 秃鹫航天飞机, ThunderHawk Shuttle = 雷鹰航天飞机
• Solar Shuttle = 金乌 (JW-01/02/03)
• Vulture Block 1.5 (VS-06/VS-07) did NOT participate in mothership construction; after conversion they built Star Port Station

Commit style

• Conventional commit prefixes: feat:, fix:, docs:, refactor:, chore:
• Co-Authored-By trailer on all commits
• Chinese for wiki/docs commits, English for code commits