Armor/KSP_project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add project handover guides

Browse Source
This commit is contained in:
Armor
2026-05-28 11:33:19 +08:00
parent e0c6e4876b
commit e6be6058a5
2 changed files with 1250 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
handover/ksp_wiki_handover.md
+691
View File
@@ -0,0 +1,691 @@
# KSP Wiki.js 工作流交接文档
最后更新：2026-05-28
本文档介绍 KSP Wiki 内容生产与 Wiki.js 发布工作流。后台项目本身、数据库模型和 Mission Ops 功能见 `handover/operation_hangar_handover.md`。
## 1. 这套工作流是什么
KSP Wiki 工作流用于把 KSP Operation Hangar 中整理出的航天器设定、任务记录和运营数据，转化为 Wiki.js 上的百科条目。它不是单纯写 Markdown，而是一套从设定讨论、本地 HTML 编写、图片资产上传、页面发布、缓存刷新到前台验证的完整流程。
当前主要维护对象包括：
- 航天飞机条目：秃鹫、回声、进取。
- 星际探索母舰条目：羲和、万星源 / Stellaria。
- 航天器图片资产。
- Wiki.js 页面 CSS、页面 JS 和图片点击放大 lightbox。
核心原则：
- 本地 HTML 是事实来源，先在仓库内修改，再发布到 Wiki.js。
- 发布必须通过脚本走 Wiki.js GraphQL `pages.update`/`pages.create`，并执行 render/flushCache。
- 发布后必须做前台验证，不只看数据库。
- 涉及临时 `manage:system` 权限时必须先向用户确认，并确保脚本结束后移除。
- 不打印 `.env`、密码、JWT 或数据库连接串。
## 2. 本地内容文件
主要 Wiki HTML 位于 `data/wiki/`：
| 文件 | 语言 | 页面 |
| --- | --- | --- |
| `data/wiki/vulture_shuttle_zh.html` | zh | 秃鹫航天飞机 |
| `data/wiki/vulture_shuttle_en.html` | en | Vulture Shuttle |
| `data/wiki/echo_shuttle_zh.html` | zh | 回声级航天飞机 |
| `data/wiki/echo_shuttle_en.html` | en | Echo Shuttle |
| `data/wiki/enterprise_shuttle_zh.html` | zh | 进取级航天飞机 |
| `data/wiki/enterprise_shuttle_en.html` | en | Enterprise Shuttle |
| `data/wiki/xihe_mothership_zh.html` | zh | 羲和级星际探索母舰 |
| `data/wiki/xihe_mothership_en.html` | en | Xihe-class interplanetary exploration mothership |
| `data/wiki/wanxingyuan_mothership_zh.html` | zh | 万星源级星际探索母舰 |
| `data/wiki/stellaria_mothership_en.html` | en | Stellaria-class interplanetary exploration mothership |
根目录还有早期/参考文件：
- `vulture_shuttle.md`：秃鹫中文长稿参考。
- `vulture_shuttle_html_test.html`：早期 HTML 测试稿。
图片和资源通常位于 `data/KSP/` 下的 wiki 上传目录，例如：
- `data/KSP/wiki-upload/`
- `data/KSP/wiki-upload-echo-current/`
- `data/KSP/wiki-upload-enterprise-current/`
- `data/KSP/wiki-upload-png/`
- `data/KSP/wiki-embed-current/`
## 3. 当前已经完成的内容
### 3.1 航天飞机页面
已完成并发布的主要页面：
| 页面 | Locale | 已知 Page ID | 路径 |
| --- | --- | --- | --- |
| 秃鹫航天飞机 | zh | 18 | `home/Space_Shuttles/Vulture_Shuttle` |
| Vulture Shuttle | en | 21 | `home/Space_Shuttles/Vulture_Shuttle` |
| 回声级航天飞机 | zh | 8 | `home/Space_Shuttles/Echo_Shuttle` |
| Echo Shuttle | en | 22 | `home/Space_Shuttles/Echo_Shuttle` |
| 进取级航天飞机 | zh | 7 | `home/Space_Shuttles/Enterprise_Shuttle` |
| Enterprise Shuttle | en | 23 | `home/Space_Shuttles/Enterprise_Shuttle` |
内容状态：
- Vulture 中文页已扩展为大型百科条目，包含设计、系统组成、任务剖面、运用历史、飞行次数、安全事件、机队、成本和技术参数。
- Vulture 英文页已修正旧稿措辞，去掉 `English draft`、`local Chinese article` 等草稿痕迹，并补齐 Xihe/Stellaria 互链。
- Echo/Enterprise 中文页已扩写到 Vulture 级别的丰富度，包含背景、设计需求、系统组成、推进、电源、整备、任务剖面、母舰支援、运用历史、机队编号、安全事件、经济性和评价。
- Echo/Enterprise 中文页当前有本地润色版，用户要求先本地保存，暂不发布云端。
### 3.2 母舰页面
已完成并发布的主要页面：
| 页面 | Locale | 已知 Page ID | 路径 |
| --- | --- | --- | --- |
| 羲和级星际探索母舰 | zh | 13 | `home/Exploration_Motherships/Xihe/XH-01` 或相关 Xihe 路径 |
| Xihe-class interplanetary exploration mothership | en | 24 | `home/Exploration_Motherships/Xihe` |
| 万星源级星际探索母舰 | zh | 15 | `home/Exploration_Motherships/Stellaria` |
| Stellaria-class interplanetary exploration mothership | en | 25 | `home/Exploration_Motherships/Stellaria` |
关键设定：
- XH-02 是太白 / Taibai。
- XH-03 是常曦 / Changxi，不是 Zhuque。
- Stellaria 是万星源级英文名。
- ST-01 与 ST-02 是万星源级早期高速度增量构型。
- 当前中文统一 ST-02 为“万星源NEXT号（ST-02）”。
### 3.3 术语和设定统一
已清理过的错误或旧稿词：
- `English draft`
- `local Chinese article`
- `XH-03 Zhuque`
- `Zhuque` / `朱雀`
- `克里斯滕号（ST-02）`
当前推荐术语：
| 中文 | 英文 | 说明 |
| --- | --- | --- |
| 秃鹫航天飞机 | Vulture Shuttle | 重载航天飞机主线 |
| 秃鹫航天飞机改进乙型 | Vulture Shuttle Block 2 | 高能推进重载干线 |
| 回声级航天飞机 | Echo Shuttle | 母舰随舰摆渡航天飞机 |
| 进取级航天飞机 | Enterprise Shuttle | 中型客货运输与母舰近程支援 |
| 羲和级星际探索母舰 | Xihe-class interplanetary exploration mothership | 第一代探索母舰 |
| 万星源级星际探索母舰 | Stellaria-class interplanetary exploration mothership | 后续大型探索母舰 |
| 摆渡航天飞机 | ferry shuttle | 母舰目标系统末端运输载具 |
## 4. 从 brainstorming 到 HTML 的写作流程
Wiki 条目通常按以下顺序生产：
1. 与用户确认设定定位。
2. 建立条目骨架。
3. 从 KSP Operation Hangar 后台读取任务日志和运营上下文。
4. 写本地 HTML。
5. 本地润色和术语一致性扫描。
6. 用户确认。
7. 发布到 Wiki.js。
8. 前台验证。
### 4.1 Brainstorming 阶段
先确认页面的百科定位，而不是直接堆设定。例如 Echo 与 Enterprise 的分工：
- Echo：随舰远征、双艇互备、大气天体探索、卫星间摆渡、小型样品和应急撤离。
- Enterprise：中型节点、25 吨级货运、22 人短期运输、母舰建造/改装/补给、返港卸载。
- Vulture Block 2：重载地月干线，不是 Echo/Enterprise 的简单替代。
写作时先确定：
- 它属于哪一代技术路线。
- 与前代或并行型号的关系。
- 在航天运输体系中的层级。
- 不承担哪些任务。
- 与任务日志中的运营记录如何对应。
### 4.2 HTML 结构
本地 HTML 通常包含：
```html
<style>
...页面 CSS...
</style>
<article class="mw-parser-output wiki-article">
<h1>...</h1>
<table class="infobox">...</table>
<nav class="toc">...</nav>
...正文...
</article>
<script>
...lightbox JS...
</script>
```
发布时使用 `--extract-style-to-script-css` 和 `--extract-script-to-script-js`，脚本会把第一个 `<style>` 提取到 Wiki.js 页面 CSS，把第一个 `<script>` 提取到页面 JS。
注意：`scriptJs` 必须保留完整 `<script>...</script>` 包裹。Wiki.js 会把它原样注入页面 body。
### 4.3 常用条目章节
航天飞机页面建议包含：
- 导语。
- 背景与发展。
- 设计需求与方案取舍。
- 设计。
- 推进与电源。
- 地面设施与整备。
- 任务剖面。
- 星际探索母舰支援。
- 运营与任务分工。
- 与相关型号的关系。
- 运用历史。
- 机队与编号。
- 安全与飞行事件。
- 成本与经济性。
- 技术参数。
- 评价。
- 图片。
- 相关条目。
母舰页面建议包含：
- 导语。
- 发展背景。
- 设计。
- 推进、电源、生命保障。
- Ferry shuttles and external berthing。
- 任务运营体系。
- 建造与服役。
- 安全与运行约束。
- 舰队与后续发展。
- 技术参数。
- 相关条目。
### 4.4 文风要求
中文稿应尽量接近百科风格：
- 使用“该级”“该型号”“该系统”代替过多“它”。
- 少用“因此、事实上、本质上、可以说、最适合、发现空位”等解释腔。
- 以定位、任务、约束、适用场景和限制组织内容。
- 不写“本文”“本稿”“英文草稿”“中文文章”等编辑过程词。
- 避免口语化转折，如“不是 A，而是 B”反复出现。
## 5. 如何从 KSP Operation Hangar 读取日志和运营上下文
Wiki 内容中的任务史、母舰定位和运营流程应尽量来自后台数据库或后台页面，不只凭设定脑补。
### 5.1 数据来源
后台相关模型：
- `Asset`
- `AssetLogEntry`
- `AssetStateNode`
导入脚本：
```powershell
python scripts/import_log_book.py
```
该脚本读取 `log_book.xlsx`，将每个资产 sheet 导入数据库。导入后可在后台查看：
- `/assets`
- `/assets/<asset_id>`
- `/missions`
- `/mission-preview/status-board`
- `/mission-preview/location-board`
- `/mission-preview/timeline`
### 5.2 后台页面读取方式
常用读取路径：
- `/assets`：看资产清单、当前状态、未来事件。
- `/assets/<uuid>`：看单个资产全部日志和 State Nodes。
- `/missions`：按 mission label 分组。
- `/mission-preview/timeline`：按模拟时间看状态区间与事件节点。
- `/mission-preview/status-board`：看当前状态分组。
- `/mission-preview/location-board`：看地点/区域分组。
撰写 Wiki 时，先在这些页面确认：
- 资产名称和编号。
- 任务时间窗口。
- 任务地点。
- 任务标签。
- 当前/未来状态。
- 是否存在 State Nodes 细节。
### 5.3 代码层读取方式
如果需要在 Flask 环境中直接查数据，可使用应用上下文与 SQLAlchemy 模型。示例只展示方法，不包含任何凭据：
```python
from app import create_app
from app.extensions import db
from app.models import Asset
app = create_app()
with app.app_context():
assets = Asset.query.order_by(Asset.name.asc()).all()
for asset in assets:
print(asset.name, asset.asset_type, len(asset.log_entries))
```
注意：查询真实数据库前确认 `.env` 指向正确的 `PGDATABASE`。不要把真实查询结果中的敏感配置、账号或连接串写入文档。
### 5.4 当前从后台继承到 Wiki 的典型设定
- XH-02 Taibai：火星一号补给转移。
- XH-03 Changxi：星港木星中继部署改装。
- ST-01 / ST-02：万星源级早期高速度增量构型。
- Echo：母舰常用随舰摆渡航天飞机，可两艘外部停泊。
- Enterprise：母舰建造、改装、补给和近程接驳，不作为标准远征 ferry shuttle。
## 6. Wiki.js 配置读取方式
Wiki 发布脚本读取根目录 `.env`，不是 `.env.example`。示例键名在 `.env.example` 中。
### 6.1 Wiki.js 数据库配置
`scripts/wiki_update_page.py` 的 `connect_info()` 会读取：
```text
PGHOST
PGPORT
PGUSER
PGPASSWORD
WIKIDATABASE 或 PGDATABASE
```
优先使用 `WIKIDATABASE`，若不存在则退回 `PGDATABASE`。
这意味着同一个 `.env` 可以同时服务后台数据库和 Wiki 数据库，但要特别注意不要把后台业务库和 Wiki.js 库混淆。
### 6.2 Wiki.js 登录配置
发布脚本读取：
```text
wiki_useremail
wiki_username
wiki_password
```
脚本会依次尝试 `wiki_useremail`、`wiki_username` 登录 Wiki.js GraphQL，成功后得到 JWT。脚本输出只显示 `token_received=True/False`，不要打印 JWT。
### 6.3 Wiki URL
默认 Wiki URL：
```text
http://192.168.195.241:38353
```
也可通过环境变量或参数指定：
```text
WIKI_URL=http://...
--wiki-url http://...
```
## 7. 页面发布脚本
核心脚本：`scripts/wiki_update_page.py`
功能：
- 从 `.env` 读取 Wiki.js DB 和登录信息。
- 解析本地 HTML/Markdown。
- 提取 `<style>` 到页面 CSS。
- 提取 `<script>` 到页面 JS。
- 保留现有 tags。
- 检查 Page Rule 是否匹配页面路径。
- 通过 GraphQL 执行 `pages.update` 或 `pages.create`。
- 调用 `pages.render`。
- 调用 `pages.flushCache`。
- 前台 HTTP GET 验证 must/must_not 文本。
- 如使用 `--temporary-manage-system`，结束后自动移除权限。
常用发布命令模板：
```powershell
python scripts/wiki_update_page.py `
--path home/Space_Shuttles/Echo_Shuttle `
--content-file data/wiki/echo_shuttle_zh.html `
--locale zh `
--title "回声级航天飞机" `
--description "全可重复使用轻型航天飞机" `
--editor markdown `
--create-if-missing `
--extract-style-to-script-css `
--extract-script-to-script-js `
--temporary-manage-system `
--must-contain "回声级航天飞机" `
--must-not-contain "English draft" `
--must-not-contain "Zhuque"
```
发布前必须确认：
- 用户同意发布。
- 用户同意临时 `manage:system` 权限。
- 本地 HTML 已通过结构检查。
- must/must_not 包含足够关键文本。
### 7.1 关键参数说明
| 参数 | 说明 |
| --- | --- |
| `--path` | Wiki.js 页面路径，不带 locale |
| `--content-file` | 本地 HTML/Markdown 文件 |
| `--locale` | `zh` 或 `en` |
| `--title` | Wiki 页面标题 |
| `--description` | Wiki 页面描述 |
| `--editor` | 通常用 `markdown` |
| `--create-if-missing` | 页面不存在时创建 |
| `--extract-style-to-script-css` | 提取 `<style>` 到页面 CSS |
| `--extract-script-to-script-js` | 提取 `<script>` 到页面 JS |
| `--temporary-manage-system` | 临时授予 render/flush 所需系统权限 |
| `--must-contain` | 前台必须存在的文本，可重复 |
| `--must-not-contain` | 前台不得存在的文本，可重复 |
### 7.2 权限流程
Wiki.js 发布涉及两层权限：
1. 用户组 permissions。
2. Page Rule roles。
`wiki_update_page.py` 会检查匹配 Page Rule 是否有：
```text
write:pages
manage:pages
```
`pages.render` 和 `pages.flushCache` 需要 `manage:system`。如果用户授权，使用：
```text
--temporary-manage-system
```
脚本会在 finally 中移除该权限。发布后要看输出是否有：
```text
temporary_manage_system_removed=True
```
## 8. 图片资产上传和验证
核心脚本：`scripts/wiki_upload_assets.py`
用途：上传图片到 Wiki.js，并验证 URL 可访问。
示例：
```powershell
python scripts/wiki_upload_assets.py `
--source-dir data/KSP/wiki-upload-echo-current `
--file echo_mk2_cross_section.png `
--folder-slug echo `
--skip-existing
```
常用 folder slug：
| slug | 用途 | 已知文件夹 ID |
| --- | --- | --- |
| `enterprise` | Enterprise 图片 | 1 |
| `echo` | Echo 图片 | 2 |
| `vulture` | Vulture 图片 | 4 |
验证原则：
- 上传后必须用 HTTP GET 验证。
- 不要只用 HEAD。
- 不要只查 Wiki.js DB。
- 需要确认 HTTP 200 和 `Content-Type: image/*`。
已知资产问题：Wiki.js disk storage target 的 `config.path` 曾为空，导致资产 URL 500。修复方式是把 disk path 设置为：
```text
/wiki/data/storage
```
然后执行 storage dump。该操作属于系统级维护，需要临时 `manage:system` 并在完成后移除。
## 9. Lightbox 工作流
相关脚本：
- `scripts/wiki_apply_image_lightbox.py`
- `scripts/wiki_verify_lightbox.py`
### 9.1 注入 Lightbox
`wiki_apply_image_lightbox.py` 会处理 6 个航天飞机页面：
- Vulture zh/en。
- Echo zh/en。
- Enterprise zh/en。
它查找：
```html
<img data-wiki-asset="...">
```
并注入统一 CSS/JS，使图片点击后出现放大预览。
### 9.2 验证 Lightbox
运行：
```powershell
python scripts/wiki_verify_lightbox.py
```
验证步骤：
- 打开页面。
- 检查 article 是否安装 lightbox。
- 点击第一张 `img[data-wiki-asset]`。
- 检查 `.wiki-image-lightbox` 显示。
- 检查 preview image 和 caption。
- 按 Escape 关闭。
## 10. 资产清理与应急嵌图
### 10.1 清理错放资产
脚本：`scripts/wiki_cleanup_misplaced_assets.py`
用途：删除误放到 `/vulture` 下的 Echo/Enterprise 图片。
Dry-run：
```powershell
python scripts/wiki_cleanup_misplaced_assets.py
```
执行：
```powershell
python scripts/wiki_cleanup_misplaced_assets.py --delete
```
验证：
```powershell
python scripts/wiki_verify_asset_cleanup.py
```
验证内容：
- `/vulture/echo_*` 和 `/vulture/enterprise_*` 不再存在。
- `/echo/...` 和 `/enterprise/...` 正常返回 image。
- `automation` 组不保留 `manage:system`。
### 10.2 应急 base64 图片嵌入
脚本：`scripts/wiki_embed_image_fallbacks.py`
用途：当 Wiki.js 资产服务异常时，把图片转为 data URI 临时嵌入 HTML。
嵌入：
```powershell
python scripts/wiki_embed_image_fallbacks.py `
--embed-dir data/KSP/wiki-embed-current `
--max-dimension 1600 `
--quality 82
```
恢复为资产 URL：
```powershell
python scripts/wiki_embed_image_fallbacks.py --restore-asset-src
```
应急嵌图不是常规发布方式，只在资产服务异常时使用。
## 11. 本地验证清单
发布前至少检查：
```powershell
# 诊断 HTML 文件
# 在 VS Code 中看 Problems，或调用 get_errors
# 风险词搜索
rg "English draft|local Chinese article|Zhuque|朱雀|克里斯滕" data/wiki
# 结构检查
rg "<article|</article>|<script>|</script>" data/wiki/echo_shuttle_zh.html
```
常见 must_not：
```text
English draft
local Chinese article
Zhuque
朱雀
克里斯滕
TODO
placeholder
```
常见 must_contain：
```text
回声级航天飞机
进取级航天飞机
秃鹫航天飞机
XH-03 常曦
万星源NEXT号（ST-02）
Stellaria-class interplanetary exploration mothership
```
## 12. 发布后验证清单
发布脚本自带前台验证，但最好再做一次独立验证：
- 打开带 cache-bust 的前台 URL。
- 确认新段落存在。
- 确认旧词不存在。
- 确认图片显示。
- 点击图片测试 lightbox。
- 确认页面目录、信息框和表格结构正常。
如果工具返回旧内容，但发布脚本显示成功，可用直接 HTTP cache-bust 验证。之前曾出现网页抓取工具返回缓存片段，而真实前台已经更新的情况。
## 13. 常见失败与处理
### 13.1 `PageUpdateForbidden`
原因：
- 用户组权限不足。
- Page Rule 没有命中路径。
- Page Rule 缺 `write:pages` 或 `manage:pages`。
处理：
- 先检查 Wiki.js Groups / Page Rules。
- 如需脚本修补，必须先问用户，再使用 `--patch-page-rule`。
### 13.2 `Forbidden` during render/flush
原因：缺少 `manage:system`。
处理：
- 先问用户。
- 使用 `--temporary-manage-system`。
- 检查输出是否移除权限。
### 13.3 页面更新但前台不变
处理顺序：
1. 确认 `pages.update` 成功。
2. 确认 `pages.render` 成功。
3. 确认 `pages.flushCache` 成功。
4. 用 cache-bust URL 访问。
5. 必要时重启 Wiki.js 容器。
### 13.4 图片 500
可能原因：storage target `disk` 的 `config.path` 为空或存储 dump 不完整。
处理：
- 修复 disk storage path。
- 执行 storage dump。
- 用 GET 验证资产。
### 13.5 Windows PowerShell 中文编码问题
复杂中文命令不要直接写长 here-string。优先：
- 把中文写在 UTF-8 文件中，由脚本读取。
- 或减少命令行中文。
- 避免输出 `.env` 和 token。
## 14. 当前待办
### 内容待办
- 用户当前要求：Echo/Enterprise 中文 HTML 已本地再润色，先不发布，等待用户审阅。
- Echo/Enterprise 英文页可能需要按中文新版再次同步扩写。
- Vulture 英文页仍比中文短很多，后续可按中文结构扩写。
- 母舰页面后续可补充更多图片资产。
### 工程待办
- 为 Wiki 发布命令沉淀更短的 Make/PowerShell wrapper。
- 给 HTML 结构检查写自动脚本。
- 为风险词建立固定检查清单。
- 给 Wiki 页面与本地文件建立 manifest，记录 path、locale、page id、title、description、content-file。
- 将 `LOG_BOOK_ASSET_SPECS` 与 Wiki 内容中资产名称做一致性校验。
## 15. 新人接手建议
1. 先读本文件，再读 `handover/operation_hangar_handover.md`。
2. 打开 `data/wiki/echo_shuttle_zh.html` 和 `data/wiki/enterprise_shuttle_zh.html`，理解当前中文百科风格。
3. 在后台 `/assets`、`/missions`、`/mission-preview/timeline` 查任务日志和模拟时间状态。
4. 修改本地 HTML，不直接改 Wiki.js 数据库。
5. 本地检查 HTML 结构、风险词和图片路径。
6. 发布前向用户确认，尤其是临时 `manage:system`。
7. 使用 `wiki_update_page.py` 发布。
8. 发布后检查 `pages.update`、`pages.render`、`pages.flushCache`、frontend must/must_not。
9. 独立打开前台页面验证内容和图片。
10. 确认临时权限已经移除。
handover/operation_hangar_handover.md
+559
View File
@@ -0,0 +1,559 @@
# KSP Operation Hangar 交接文档
最后更新：2026-05-28
本文档介绍 KSP Operation Hangar 后台项目本身，不包含 Wiki.js 页面生产、图片资产上传、Wiki 发布脚本和 KSP_wiki 内容维护。Wiki 相关工作流见 `handover/ksp_wiki_handover.md`。
## 1. 项目定位
KSP Operation Hangar 是一个 Flask + SQLAlchemy 的 KSP 数据整理与任务运营后台。项目最初用于把 Excel 工作簿中的发动机、通信部件、燃料箱和载具成本数据导入数据库，随后扩展出任务资产、资产日志、状态节点和 Mission Ops 预览页面。
项目的主要目标是：
- 将分散的 KSP Excel 数据转为可查询、可编辑、可导入的数据库记录。
- 提供 Web 后台管理 Engine、Communication、Tank、Vehicle Cost 等资料。
- 提供 Fuel Converter 工具和 API，支持燃料体积与质量换算。
- 管理任务资产、任务日志和状态节点，用于构建任务运营视图。
- 通过 Mission Ops 页面按模拟时间查看任务状态、地点分布、未来事件和时间线。
当前项目更接近个人/小团队内部管理后台，不是面向公网的完整生产系统。鉴权、审计、自动化测试和正式权限隔离尚未完成。
## 2. 代码结构总览
```text
KSP_Project/
├── main.py
├── app/
│ ├── __init__.py
│ ├── config.py
│ ├── extensions.py
│ ├── models.py
│ ├── routes/
│ │ ├── api.py
│ │ └── web.py
│ ├── services/
│ │ ├── fuel_conversion.py
│ │ ├── log_book_importer.py
│ │ ├── workbook_importer.py
│ │ └── workbook_inspector.py
│ ├── static/
│ │ └── styles.css
│ └── templates/
├── migrations/
│ └── versions/
├── scripts/
│ ├── import_log_book.py
│ ├── import_workbook.py
│ └── inspect_workbook.py
├── prototypes/
│ └── mission-ops/
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── .env.example
```
非后台范围说明：
- `data/wiki/`、`data/KSP/wiki-*`、`scripts/wiki_*.py`、根目录 `vulture_shuttle*.html/md` 属于 Wiki 工作流，见另一份交接文档。
- `prototypes/mission-ops/` 是早期静态 Mission Ops 原型，虽然不是正式 Flask 页面，但可作为 UI 设计参考。
## 3. 运行入口与应用初始化
### 3.1 入口文件
入口是 `main.py`：
- 调用 `app.create_app()` 创建 Flask app。
- 本地直接运行时监听 `0.0.0.0:APP_PORT`。
- 当 `APP_ENV=development` 时启用 Flask debug。
常用本地命令：
```powershell
pip install -r requirements.txt
python main.py
```
默认访问地址：
```text
http://127.0.0.1:8000/
```
### 3.2 Flask app factory
`app/__init__.py` 中的 `create_app()` 负责：
- 创建 Flask 应用。
- 加载 `app.config.Config`。
- 初始化 `db` 与 `migrate`。
- 注册 `web_bp` 和 `api_bp`。
- 注册 Jinja filter：`fmt_decimal`。
`fmt_decimal` 用于在模板中格式化 Decimal，默认保留 4 位并去掉尾随零。
### 3.3 扩展对象
`app/extensions.py` 定义全局扩展对象：
- `db = SQLAlchemy()`
- `migrate = Migrate()`
不要在模型或路由中重新创建扩展实例，统一从 `app.extensions` 导入。
## 4. 依赖
`requirements.txt` 当前依赖：
```text
Flask>=3.1,<4.0
Flask-SQLAlchemy>=3.1,<4.0
Flask-Migrate>=4.0,<5.0
python-dotenv>=1.0,<2.0
psycopg[binary]>=3.2,<4.0
openpyxl>=3.1,<4.0
gunicorn>=23.0,<24.0
```
用途说明：
- Flask：Web 框架。
- Flask-SQLAlchemy：ORM。
- Flask-Migrate：Alembic 迁移集成。
- python-dotenv：读取 `.env`。
- psycopg：PostgreSQL 驱动。
- openpyxl：读取 Excel 工作簿。
- gunicorn：容器/生产运行 WSGI server。
## 5. 配置读取方式
### 5.1 配置入口
配置逻辑在 `app/config.py`。
启动时会执行：
```python
load_dotenv(BASE_DIR / ".env")
```
也就是说，项目根目录的 `.env` 是运行时真实配置来源；`.env.example` 只提供安全示例，不包含真实凭据。
### 5.2 数据库连接
`_build_database_uri()` 读取下列变量：
```text
PGHOST
PGPORT
PGUSER
PGPASSWORD
PGDATABASE
```
如果这些变量全部存在，则拼接 PostgreSQL URI：
```text
postgresql+psycopg://<user>:<password>@<host>:<port>/<database>
```
如果任一 PostgreSQL 配置缺失，则回退到本地 SQLite：
```text
instance/ksp.sqlite3
```
注意：生产或 NAS 部署应使用 PostgreSQL。SQLite 主要用于临时本地开发。
### 5.3 应用配置项
`Config` 支持的主要变量：
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `APP_ENV` | `development` | 控制 debug 等环境行为 |
| `APP_PORT` | `8000` | 本地 Flask 启动端口，也被 docker-compose 用作宿主机端口 |
| `APP_SECRET_KEY` | `development-only-secret-key` | Flask session secret |
| `PROJECT_TITLE` | `KSP Data Hangar` | 页面标题/项目展示名 |
| `WORKBOOK_PATH` | `KSP Engine Tweak Chart.xlsx` | 默认 KSP Excel 工作簿路径 |
| `SQLALCHEMY_ECHO` | `false` | 是否输出 SQL 日志 |
`.env.example` 还包含 Wiki.js 相关变量，但后台应用本身只依赖 `PGDATABASE`，不直接使用 `WIKIDATABASE` 或 Wiki 登录信息。
## 6. 数据模型
模型位于 `app/models.py`。所有核心表使用 UUID 主键；多数模型继承 `TimestampMixin`，提供 `created_at` 和 `updated_at`。
### 6.1 基础数据模型
| 模型 | 表 | 用途 |
| --- | --- | --- |
| `EngineFamily` | `engine_families` | 发动机家族/基础型号 |
| `EngineVariant` | `engine_variants` | 发动机配置项，如燃料、环境、推力、比冲等 |
| `CommunicationPart` | `communication_parts` | 通信部件、天线类型、范围、功耗等 |
| `TankSpec` | `tank_specs` | 燃料箱质量、湿重、干重、体积与质量比 |
| `VehicleCost` | `vehicle_costs` | 载具发射成本或价格数据 |
发动机数据注意事项：
- 源 Excel 中 `Engine + Config Name` 不是可靠唯一键。
- 早期巡检发现 48 组 `Engine + Config Name` 冲突。
- 即使加入 Fuel Type，仍有 19 组冲突。
- 因此数据库采用 UUID 主键，自然键只用于展示、筛选和告警。
### 6.2 任务资产模型
| 模型 | 表 | 用途 |
| --- | --- | --- |
| `Asset` | `assets` | 任务资产，例如母舰、航天飞机、站点、基地 |
| `AssetLogEntry` | `asset_log_entries` | 资产日志，支持事件点与状态区间 |
| `AssetStateNode` | `asset_state_nodes` | 状态区间内的时间节点和细节说明 |
任务运营页面主要基于这三张表构建：
- 当前状态。
- 未来事件。
- 任务标签和地点分组。
- 状态板、地点板和时间线。
`Asset.is_retired` 用于排除退役资产。
## 7. 数据迁移
迁移目录：`migrations/versions/`
当前有 6 个迁移：
| 文件 | 作用 |
| --- | --- |
| `f1fa035d3afe_initial_schema.py` | 初始 schema |
| `6c2a57f2b1e9_add_asset_log_tables.py` | 增加资产日志表 |
| `f4f0c9c9426e_add_asset_state_nodes.py` | 增加状态节点表 |
| `8bbf69ea2013_add_retired_flag_to_assets.py` | 增加资产退役标记 |
| `0f1b9bb2156c_add_detail_to_asset_state_nodes.py` | 状态节点增加 detail 字段 |
| `83be4d38636d_expand_communication_range_precision.py` | 扩展通信距离精度 |
常用命令：
```powershell
python -m flask --app main:app db upgrade
```
创建新迁移：
```powershell
python -m flask --app main:app db migrate -m "message"
python -m flask --app main:app db upgrade
```
如果是首次初始化且没有 `migrations/`，才需要：
```powershell
python -m flask --app main:app db init
```
## 8. Web 后台功能
Web 路由在 `app/routes/web.py`，蓝图名称为 `web_bp`。
### 8.1 Dashboard 与工具
| 路径 | 用途 |
| --- | --- |
| `/` | Dashboard，展示项目模块与数据冲突统计 |
| `/fuel-converter` | 燃料体积/质量换算页面 |
Dashboard 当前展示的冲突数固定为：
- `duplicate_conflicts=48`
- `duplicate_conflicts_with_fuel=19`
### 8.2 Engine Catalog
| 路径 | 用途 |
| --- | --- |
| `/engines` | 发动机列表、搜索、筛选、排序、分页 |
| `/engines/new` | 新建发动机及初始配置 |
| `/engines/<uuid>` | 发动机详情 |
| `/engines/<uuid>/edit` | 编辑发动机家族和配置项 |
| `/engines/<uuid>/variants/add` | 添加配置项 |
| `/engines/<uuid>/variants/<uuid>/delete` | 删除配置项 |
| `/engines/<uuid>/delete` | 删除发动机家族 |
相关模板：
- `engine_list.html`
- `engine_create.html`
- `engine_detail.html`
- `engine_edit.html`
### 8.3 Communication / Tank / Vehicle
这三类资源使用类似 CRUD 模式：
| 资源 | 列表 | 新建 | 编辑 | 删除 |
| --- | --- | --- | --- | --- |
| Communication | `/communications` | `/communications/new` | `/communications/<uuid>/edit` | `/communications/<uuid>/delete` |
| Tank | `/tanks` | `/tanks/new` | `/tanks/<uuid>/edit` | `/tanks/<uuid>/delete` |
| Vehicle | `/vehicles` | `/vehicles/new` | `/vehicles/<uuid>/edit` | `/vehicles/<uuid>/delete` |
这些页面共用 `resource_edit.html` 做新增/编辑表单。
### 8.4 Mission Assets
| 路径 | 用途 |
| --- | --- |
| `/assets` | 任务资产目录，支持模拟时间、搜索、筛选、排序、分页 |
| `/assets/new` | 新建任务资产 |
| `/assets/<uuid>` | 资产详情、日志列表、未来事件 |
| `/assets/<uuid>/edit` | 编辑资产 |
| `/assets/<uuid>/delete` | 删除资产及日志 |
| `/assets/import-log-book` | 从 `log_book.xlsx` 导入资产日志 |
| `/assets/<uuid>/entries/new` | 新增资产日志条目 |
| `/assets/<uuid>/entries/<uuid>/edit` | 编辑资产日志条目与 State Nodes |
| `/assets/<uuid>/entries/<uuid>/delete` | 删除资产日志条目 |
任务日志支持两类记录：
- `event`：单点事件。
- `state`：状态区间，可带多个 `AssetStateNode`。
资产详情页会根据模拟时间计算：
- 当前状态。
- 当前地点。
- 活跃/计划/历史状态。
- 未来事件，包括未来日志事件和未来 State Nodes。
### 8.5 Mission Ops 页面
Mission Ops 页面基于数据库中的 Asset/AssetLogEntry/AssetStateNode 实时构建，而不是静态原型。
| 路径 | 用途 |
| --- | --- |
| `/missions` | 按 mission label 分组的任务列表 |
| `/mission-preview` | 重定向到状态板 |
| `/mission-preview/status-board` | 状态板，按运行状态分组 |
| `/mission-preview/location-board` | 地点板，按地区/地点分组 |
| `/mission-preview/asset-log` | 重定向到资产列表 |
| `/mission-preview/timeline` | 时间线视图，支持 scale、范围、资产筛选 |
核心构建函数包括：
- `_load_assets_with_logs()`
- `_build_asset_snapshot()`
- `_build_mission_board_rows()`
- `_build_status_board_groups()`
- `_build_location_board_groups()`
- `_build_timeline_rows()`
时间线支持自动或手动范围、按 day/month/year 等 scale 展示，并计算 state segments 与 event nodes。
## 9. API
API 路由在 `app/routes/api.py`，蓝图路径前缀为 `/api/v1`。
| 路径 | 方法 | 用途 |
| --- | --- | --- |
| `/api/v1/health` | GET | 健康检查，返回 `status=ok` |
| `/api/v1/fuel-converter/fuels` | GET | 返回燃料密度因子 |
| `/api/v1/fuel-converter/convert` | GET/POST | 燃料体积/质量换算 |
Fuel Converter 的业务逻辑在 `app/services/fuel_conversion.py`。
## 10. 服务层与导入脚本
### 10.1 Fuel conversion
文件：`app/services/fuel_conversion.py`
主要能力：
- `list_fuel_factors()`：列出燃料密度因子。
- `convert_value(mode, raw_value)`：在体积与质量之间换算。
实现使用 `Decimal`，避免浮点误差。
### 10.2 Workbook importer
文件：`app/services/workbook_importer.py`
导入对象：
- Engine Database。
- Communication。
- Tank Chart。
- KSP Vehicle Cost。
入口脚本：
```powershell
python scripts/import_workbook.py
python scripts/import_workbook.py --replace
python scripts/import_workbook.py --path "path/to/workbook.xlsx"
```
`--replace` 会清空导入相关表并重新导入。对真实数据库执行前应确认备份。
### 10.3 Workbook inspector
文件：`app/services/workbook_inspector.py`
入口脚本：
```powershell
python scripts/inspect_workbook.py
python scripts/inspect_workbook.py --path "path/to/workbook.xlsx"
```
用途：
- 列出工作表和行数。
- 检查 Engine Database 表头。
- 汇总 Work Env 枚举。
- 统计自然键冲突。
- 分析字段稳定性。
### 10.4 Log book importer
文件：`app/services/log_book_importer.py`
入口脚本：
```powershell
python scripts/import_log_book.py
python scripts/import_log_book.py --path "path/to/log_book.xlsx"
```
导入逻辑：
- 默认读取 `log_book.xlsx`。
- 忽略 `Overview` 和 `Model` sheet。
- 每个 sheet 对应一个 Asset。
- 按日期行解析事件与状态。
- 创建或更新 `Asset`、`AssetLogEntry`。
- 通过 `LOG_BOOK_ASSET_SPECS` 补充已知资产类型和初始信息。
当前 `LOG_BOOK_ASSET_SPECS` 仍有硬编码，需要随新资产扩展。
## 11. 模板与前端
模板目录：`app/templates/`
主要模板：
- `base.html`：页面外壳。
- `dashboard.html`：首页。
- `fuel_converter.html`：燃料换算工具。
- `engine_*.html`：发动机 CRUD。
- `communication_list.html`、`tank_list.html`、`vehicle_list.html`：基础资源列表。
- `asset_list.html`、`asset_detail.html`、`asset_entry_form.html`：任务资产与日志。
- `mission_list.html`：任务标签列表。
- `mission_status_board_preview.html`：状态板。
- `mission_location_board_preview.html`：地点板。
- `mission_timeline_preview.html`：时间线。
常用 partial：
- `_datetime_picker_field.html`
- `_mission_ops_tabs.html`
- `_mission_preview_controls.html`
- `_mission_preview_header.html`
- `_mission_upcoming_events.html`
静态样式：`app/static/styles.css`。
当前前端为后台工具风格，未引入大型前端框架。
## 12. Docker 与部署
### 12.1 Dockerfile
`Dockerfile` 使用 `python:3.12-slim`，安装 `requirements.txt`，复制项目文件，默认运行：
```text
gunicorn --bind 0.0.0.0:8000 main:app
```
### 12.2 docker-compose
`docker-compose.yml` 定义 `web` 服务：
- `env_file: .env`
- 宿主机端口：`${APP_PORT:-8000}`
- 容器端口：`8000`
- restart policy：`unless-stopped`
启动：
```powershell
docker compose up --build
```
## 13. 当前已完成内容
- Flask app factory 与配置系统。
- PostgreSQL/SQLite 数据库连接。
- Alembic/Flask-Migrate 迁移体系。
- Engine/Communication/Tank/Vehicle 基础数据模型与 CRUD。
- Workbook 巡检和导入。
- Fuel Converter 页面与 API。
- Asset/AssetLogEntry/AssetStateNode 任务资产模型。
- Log Book 导入。
- Asset 详情页、日志编辑、State Nodes 编辑。
- Mission list、状态板、地点板、时间线页面。
- 未来事件展示与可跳转编辑。
- 表单验证错误弹窗和提交值保留。
- Dockerfile 与 docker-compose。
## 14. 已知问题与后续 TODO
### 14.1 数据和导入
- Engine 自然键冲突仍需人工理解和治理。
- `LOG_BOOK_ASSET_SPECS` 是硬编码，新增资产时需要扩展或改为配置化。
- Workbook 导入缺少自动化测试和导入报告导出。
- 大规模重导入前需要备份，尤其是 `--replace`。
### 14.2 后台功能
- 缺少用户登录、权限控制和审计日志。
- CRUD 操作没有软删除和恢复机制。
- Mission Ops 当前以读取资产日志为主，缺少更完整的任务计划/排程实体。
- Mission labels、state labels 等多值字段仍是文本拆分，未来可规范化成表。
- 资产关系、母舰/随舰载具关系仍未建成结构化模型。
### 14.3 前端体验
- 样式仍集中在单一 CSS 文件。
- 前端表单校验较少，主要依赖后端验证。
- Mission Ops 时间线在数据量很大时可能需要性能优化。
- 原型目录中的静态页面应定期与正式 Flask 页面同步或归档。
### 14.4 工程质量
- 缺少 pytest 或其他自动化测试。
- 缺少 CI。
- 缺少 lint/format 固定流程。
- 缺少导入脚本的 dry-run 模式。
- 缺少数据库备份/恢复文档。
## 15. 新人接手建议
1. 先阅读 `app/config.py`、`app/__init__.py`、`app/models.py`，理解配置、初始化和数据模型。
2. 本地创建 `.env`，只使用示例键名，不提交真实凭据。
3. 执行 `python -m flask --app main:app db upgrade`，确认 schema 到最新。
4. 用 `python scripts/inspect_workbook.py` 了解 Excel 源数据质量。
5. 用 `python scripts/import_workbook.py` 导入基础数据。
6. 用 `python scripts/import_log_book.py` 导入任务资产日志。
7. 打开 `/assets`、`/missions`、`/mission-preview/timeline`，确认任务运营页面能从数据库生成内容。
8. 开发新功能时优先复用 `web.py` 里的表单解析、分页、时间处理和 Mission Ops 构建函数。
## 16. 安全注意事项
- 不要提交 `.env`。
- 不要在日志或终端输出真实数据库密码。
- 写路径验证前优先使用临时记录，避免污染真实任务数据。
- 使用 `--replace` 导入前先确认数据库备份。
- Docker 生产部署前应更换 `APP_SECRET_KEY`，并补齐鉴权机制。