ArmorandClaude
ac2578ca8b
The wiki_update_page.py script had a bug where extract_script_to_script_js used match.group(0) (including <script> tags) instead of group(1) (pure JS). This caused Wiki.js to render page JS as escaped HTML text rather than executing it. Since Wiki.js markdown editor strips iframes and only the markdown editor is enabled, the topology diagram is now linked via a prominent button that opens the interactive topology viewer in a new tab. Co-Authored-By: Claude <noreply@anthropic.com>
KSP Data Hangar
这是当前项目的第一版可运行骨架，目标是把 Excel 中的 KSP 数据逐步整理为可导入、可管理、可检索的 Flask 应用。
当前已落地
- Flask 应用骨架，包含网页路由和 JSON API
- SQLAlchemy 数据模型，覆盖 Engine、Communication、Tank、Vehicle Cost
- Engine 列表页、详情页、编辑页
- Fuel Chart 的前端工具页和 API 接口
- Excel 巡检脚本，用来核对工作簿结构和候选唯一键冲突
- Excel 导入脚本与导入服务
- Dockerfile 与 docker-compose 基线
关键建模结论
- 不能把 Engine + Config Name 当成数据库硬唯一键
- 当前源数据里有 48 组 Engine + Config Name 冲突
- 即使补上 Fuel Type，仍然还有 19 组冲突
- 因此数据库主键采用 UUID，原始自然键只保留做展示和导入告警
本地运行
- 复制 .env.example 到 .env，并填写真实 PG 连接信息
- 安装依赖
pip install -r requirements.txt
- 启动开发服务器
python main.py
- 打开以下地址
- http://127.0.0.1:8000/
- http://127.0.0.1:8000/engines
- http://127.0.0.1:8000/fuel-converter
- http://127.0.0.1:8000/api/v1/health
初始化数据库
python -m flask --app main:app db init
python -m flask --app main:app db migrate -m "initial schema"
python -m flask --app main:app db upgrade
如果仓库里已经有 migrations 目录，只需要执行最后一条 upgrade。
巡检工作簿
python scripts/inspect_workbook.py
这个脚本会输出：
- 工作表列表与行数
- Engine Database 表头
- Work Env 枚举值
- 自然键冲突统计
- 字段稳定性分析
导入工作簿
python scripts/import_workbook.py
如果需要覆盖数据库中已有的导入数据：
python scripts/import_workbook.py --replace
导入脚本会处理：
- Engine Database
- Communication
- Tank Chart
- KSP Vehicle Cost
Docker 运行
docker compose up --build
应用默认监听容器内 8000 端口，宿主机端口取决于 APP_PORT。
关于 .env
- 根目录已经补上 .gitignore，避免后续再次提交 .env
- 如果 .env 已经在 Git 索引里，.gitignore 不会自动取消跟踪，需要你本地手动把它移出索引后再提交
Wiki.js 资产与页面发布记录
Wiki.js 页面发布使用 scripts/wiki_update_page.py，图片上传使用 scripts/wiki_upload_assets.py。发布 HTML 页面时，页面内 <style> 应通过 --extract-style-to-script-css 写入 Wiki.js 页面 CSS；页面内 <script> 应通过 --extract-script-to-script-js 写入页面 JS。Wiki.js 会把 scriptJs 原样注入页面 body，因此发布脚本会保留完整 <script>...</script> 包裹。
曾出现所有图片 URL 返回 500 Internal Server Error，但数据库 assets / assetData 中记录和二进制数据都存在的情况。根因是 Wiki.js 的 storage target disk 被启用，但 config.path 为空；Wiki.js 的 Local File System storage 要求绝对路径，空路径会导致资产服务读取/缓存文件路径异常。修复方式是通过 Wiki.js GraphQL storage.updateTargets 将 disk 的路径设为绝对目录 /wiki/data/storage，随后执行 storage.executeAction(targetKey: "disk", handler: "dump")，并在操作前后临时授予/移除 manage:system。
验证图片时不要只用 HEAD 或只查数据库。应实际 GET 资产 URL，并确认 HTTP 200、Content-Type 为 image/*。上传脚本现在默认会做真实 GET 验证，例如：
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
如果 Echo / Enterprise 图片误传到 /vulture，先 dry-run 查看目标，再通过官方 assets.deleteAsset 删除错放资源。清理脚本只匹配 /vulture 下文件名以 echo_ 或 enterprise_ 开头的资产，并在操作后移除临时系统权限：
py scripts/wiki_cleanup_misplaced_assets.py
py scripts/wiki_cleanup_misplaced_assets.py --delete
py scripts/wiki_verify_asset_cleanup.py
六个航天飞机页面的图片点击放大由 scripts/wiki_apply_image_lightbox.py 统一注入，发布后可用以下脚本做浏览器级验证：
py scripts/wiki_verify_lightbox.py
下一步建议
- 把 Communication、Tank、Vehicle Cost 的页面也补成 CRUD
- 为导入脚本增加增量更新和冲突报告导出
- 增加筛选、分页和排序
- 补上数据库迁移和导入的自动化测试