update

2026-05-08 15:16:04 +08:00
parent 042b626ccb
commit 507fb9789a
71 changed files with 14944 additions and 0 deletions
@@ -0,0 +1,105 @@
+# 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，原始自然键只保留做展示和导入告警
+
+## 本地运行
+
+1. 复制 .env.example 到 .env，并填写真实 PG 连接信息
+2. 安装依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+3. 启动开发服务器
+
+```bash
+python main.py
+```
+
+4. 打开以下地址
+
+- 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
+
+## 初始化数据库
+
+```bash
+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。
+
+## 巡检工作簿
+
+```bash
+python scripts/inspect_workbook.py
+```
+
+这个脚本会输出：
+
+- 工作表列表与行数
+- Engine Database 表头
+- Work Env 枚举值
+- 自然键冲突统计
+- 字段稳定性分析
+
+## 导入工作簿
+
+```bash
+python scripts/import_workbook.py
+```
+
+如果需要覆盖数据库中已有的导入数据：
+
+```bash
+python scripts/import_workbook.py --replace
+```
+
+导入脚本会处理：
+
+- Engine Database
+- Communication
+- Tank Chart
+- KSP Vehicle Cost
+
+## Docker 运行
+
+```bash
+docker compose up --build
+```
+
+应用默认监听容器内 8000 端口，宿主机端口取决于 APP_PORT。
+
+## 关于 .env
+
+- 根目录已经补上 .gitignore，避免后续再次提交 .env
+- 如果 .env 已经在 Git 索引里，.gitignore 不会自动取消跟踪，需要你本地手动把它移出索引后再提交
+
+## 下一步建议
+
+1. 把 Communication、Tank、Vehicle Cost 的页面也补成 CRUD
+2. 为导入脚本增加增量更新和冲突报告导出
+3. 增加筛选、分页和排序
+4. 补上数据库迁移和导入的自动化测试