KSP_project/reference/ksp_admin_user_journey.md

name, description, metadata

name	description	metadata
ksp-admin-user-journey	Current-state and ideal-state User Journey for the KSP管理后台 admin panel	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 表:

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持久化)