81 lines
3.6 KiB
Markdown
81 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
|
|
```powershell
|
|
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
|