ArmorandClaude Opus 4.7
e1d601a774
- 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>
184 lines
7.0 KiB
Markdown
184 lines
7.0 KiB
Markdown
---
|
|
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持久化)
|