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