chore: add reference docs, scripts, tests, demo, prototypes

- Reference docs: known issues, user journey, location redesign, mission merge plan - Scripts: fill_location_state, merge_missions, migrate_location, migrate_state - Tests: e2e test suite, asset entries unit tests - Demo: location board, hifi prototypes, test screenshots - Data backup: asset log entries and state nodes - Update .gitignore Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-01 15:29:47 +08:00
parent f4909765af
commit e1d601a774
190 changed files with 11464 additions and 0 deletions
@@ -0,0 +1,183 @@
+---
+name: ksp-admin-user-journey
+description: "Current-state and ideal-state User Journey for the KSP管理后台 admin panel"
+metadata:
+  type: project
+---
+
+# KSP管理后台 — User Journey
+
+## 版本
+
+- **v1 (current)**: 2026-05-30, based on codebase audit of 32 routes, 25 templates
+- **v2 (ideal)**: in design — sidebar + topbar layout, live mission overview as homepage
+
+## 当前系统架构
+
+```
+KSP管理后台 (32 routes, 25 templates)
+├── 📊 仪表盘 (/) — 硬编码静态指标
+├── 🔧 零件参考库
+│   ├── 引擎目录 (/engines) — CRUD + 变体管理
+│   ├── 通信部件 (/communications) — CRUD
+│   ├── 燃料箱规格 (/tanks) — CRUD
+│   └── 载具成本 (/vehicles) — CRUD
+├── 🚀 任务运营 (核心)
+│   ├── 状态看板 (/mission-preview/status-board)
+│   ├── 地点看板 (/mission-preview/location-board)
+│   ├── 任务列表 (/missions)
+│   ├── 任务资产 (/assets) — 资产CRUD + 日志条目CRUD
+│   └── 时间线 (/mission-preview/timeline)
+├── 🔧 工具
+│   └── 燃料换算 (/fuel-converter)
+└── 📡 API (/api/v1/*)
+```
+
+## 当前 User Journey (v1)
+
+### Journey 1: 查看任务态势
+1. 打开首页 → 看到硬编码静态指标 (Tracked Assets: 14, Active Missions: 6)
+2. 点「任务运营」→ 进入 `/mission-preview/status-board`
+3. 看到按状态分组的资产卡片
+4. 顶部有模拟时间显示和编辑表单
+5. 改时间 → Apply Time → 页面刷新
+
+### Journey 2: 管理资产日志
+1. 从状态看板点资产 → `/assets/<uuid>`
+2. 看到: 当前快照, 未来事件, 日志条目表格(分页)
+3. [新增状态区间] → 表单(start_at, end_at, title, state_label, location, note)
+4. [新增事件点] → 表单(at_time, title, location, note)
+5. 提交 → 回到资产详情
+
+### Journey 3: 全局时间线
+1. 任务运营 → 时间线标签
+2. 甘特图风格, 按日/月/年缩放
+3. 状态区间为色条, 事件为节点
+
+### Journey 4: 零件参考
+1. 顶部导航 → 引擎目录/通信部件/燃料箱/载具成本
+2. 表格列表(搜索, 排序, 筛选) → 详情 → 编辑
+
+## 当前 UX 痛点
+
+1. 首页硬编码假数据, 无运营价值
+2. 导航扁平, 8个同级项, 无主次
+3. URL中 `/mission-preview/` 暗示"预览", 实际是正式功能
+4. 两套并行看板(status/location)各自独立
+5. 模拟时间藏在页面头部, 视觉权重不足
+6. 资产CRUD需4层导航
+7. 零件库与任务系统无关联
+8. 无面包屑, 操作后丢失上下文
+9. 视觉风格简陋, 无设计系统
+
+## 理想 User Journey (v2) — 设计决策
+
+### 已确认的设计决策
+- **首页**: 实时任务态势总览(整合状态看板 + 即将发生事件 + 关键指标)
+- **导航**: 侧边栏(功能导航) + 顶部栏(全局控制)
+- **零件库**: 降级为"数据中心"二级模块
+
+### 理想布局
+```
+┌──────────────────────────────────────────────────┐
+│ 顶部栏: [Logo]              🕐 2060-08-11 [编辑] │
+├────────────┬─────────────────────────────────────┤
+│ 侧边栏     │  内容区                            │
+│            │                                    │
+│ 🏠 任务总览│  关键指标 | 状态看板 | 30天事件     │
+│ 📋 任务运营│                                    │
+│   ├ 资产   │                                    │
+│   ├ 列表   │                                    │
+│   └ 时间线 │                                    │
+│ 📊 数据中心│                                    │
+│   ├ 引擎   │                                    │
+│   ├ 通信   │                                    │
+│   ├ 燃料箱 │                                    │
+│   └ 载具   │                                    │
+│ 🔧 工具    │                                    │
+└────────────┴─────────────────────────────────────┘
+```
+
+### 理想 Journey 概览
+1. 打开系统 → 任务总览(实时指标 + 状态看板 + 30天事件)
+2. 调整时间 → 顶部栏编辑 → 全局刷新 → 写入DB
+3. 管理资产 → 侧边栏进资产列表 → 搜索筛选 → 详情 → 编辑日志
+4. 时间线 → 侧边栏直接进入, 缩放/筛选
+5. 参考数据 → 侧边栏数据中心展开 → 各CRUD表格
+
+---
+
+## Asset 面板 — 功能缺口 (v1 → v2 扩展)
+
+### 数据库变更
+新增 `docking_events` 表:
+```sql
+CREATE TABLE docking_events (
+    id UUID PRIMARY KEY,
+    parent_asset_id UUID REFERENCES assets(id),
+    child_asset_id UUID NULL REFERENCES assets(id),
+    child_label VARCHAR(255) NULL,  -- 当对接非追踪Asset时使用
+    docked_at TIMESTAMPTZ NOT NULL,
+    undocked_at TIMESTAMPTZ NULL,   -- NULL = 仍在对接中
+    dock_note TEXT NULL,
+    undock_note TEXT NULL,
+    created_at TIMESTAMPTZ NOT NULL,
+    updated_at TIMESTAMPTZ NOT NULL
+);
+```
+
+### 新增功能
+
+#### 1. 对接载具面板
+- 显示当前模拟时间下已对接的载具列表
+- 每个载具: 名称(链接) / 对接时间 / 备注 / [移除]按钮
+- 查询: `WHERE docked_at <= sim_time AND (undocked_at IS NULL OR undocked_at > sim_time)`
+
+#### 2. "对接到了哪个 Asset" 面板
+- 当前 Asset 作为子方对接到的父方 Asset
+- 同样基于 docking_events 查询
+
+#### 3. 新增对接流程
+输入:
+- 对接时间 (默认=模拟时间)
+- 对接载具 (两种分支)
+  - A: 选择已有Asset
+  - B: 输入字符串
+- 备注信息 (可选)
+
+保存逻辑:
+- **A (selected asset)**:
+  - 对**双方Asset**执行:
+    - 查找覆盖对接时间的日志区间
+    - 若存在: 在该日志下新增 state node ("X 对接到 Y", detail=备注, at=对接时间)
+    - 若不存在: 新建以对接时间为起始、end_at=NULL的日志区间 + state node
+- **B (string)**:
+  - 仅对**当前Asset**执行上述操作
+  - state node title 为 "Echo Shuttle 对接到 <当前Asset名称>"
+
+#### 4. 移除对接流程
+输入:
+- 分离时间 (默认=模拟时间)
+- 备注信息 (可选)
+
+保存逻辑:
+- 对**有 selected asset 记录的对接**:
+  - 查找 docked_at 等于对接时间、undocked_at=NULL 的日志
+  - 若存在: 新增分离 state node，设置日志 end_at = 分离时间
+  - 若不存在: 查找覆盖分离时间的日志 → 新增 state node
+  - 若仍不存在: 新建 event point 记录分离
+- 对**字符串记录的对接**:
+  - 仅对当前Asset执行上述操作
+
+#### 5. 位置快速编辑
+- 当前位置从日志派生，仅做展示
+- 新增快速编辑入口，直接修改最新活跃日志的 location 字段
+
+### 当前Asset面板已有功能 (保留)
+- Asset名称/类别/日志数量/当前状态/当前任务
+- 日志列表(分页+筛选)
+- 未来事件列表
+- 新增 event point / 状态区间
+- 编辑日志条目
+- 修改Asset名称/类别/退役状态
+- 全局时间调节 (DB持久化)