dev

2026-05-18 20:02:16 +08:00
parent 1565c4735f
commit 74cf99289f
14 changed files with 2250 additions and 237 deletions
@@ -0,0 +1,225 @@
+# Frontend 装备流派/职业分支/打造阶段 完整交互与布局设计文档
+
+## 1. 分析范围与假设
+
+- 分析范围仅覆盖 frontend。
+- 目标模块包含：装备、技能、打造、角色信息、计算结果展示。
+- 术语固定：装备流派、职业分支、打造阶段。
+- 输出重点：交互链路、分列布局、结果渲染、代码定位证据。
+
+入口证据：
+- frontend/src/router/index.ts:13
+- frontend/src/router/index.ts:22
+- frontend/src/router/index.ts:34
+- frontend/src/router/index.ts:40
+
+## 2. 模块清单与职责映射
+
+### 2.1 路由与页面
+
+- 角色主容器页：frontend/src/pages/Character/Index.vue:1
+- 装备页：frontend/src/pages/Character/EquipmentDictionary/Index.vue:1
+- 技能页：frontend/src/pages/Character/Skill/index.vue:1
+- 打造页：frontend/src/pages/Character/Forge/index.vue:1
+- 结果页：frontend/src/pages/Character/Result/Index.vue:1
+
+### 2.2 状态管理
+
+- 配置与计算入口：frontend/src/stores/config.ts:45
+- 角色信息与职业上下文：frontend/src/stores/info.ts:9
+- 角色创建与职业参数接入：frontend/src/stores/info.ts:165
+
+### 2.3 API 与结果类型
+
+- 计算结果结构定义：frontend/src/api/calc/type.ts:1
+- 计算请求触发：frontend/src/stores/config.ts:236
+
+## 3. 交互链路分解（装备流派/职业分支/打造阶段）
+
+### 3.1 装备流派链路
+
+1. 触发动作：点击装备图标。
+   - 证据：frontend/src/pages/Character/EquipmentDictionary/Index.vue:67
+2. 状态变化：调用 chooseEqu 更新 config.equips。
+   - 证据：frontend/src/stores/config.ts:243
+3. 请求与计算：watch config 变化后执行 result.execute -> api.calc。
+   - 证据：frontend/src/pages/Character/Index.vue:61
+   - 证据：frontend/src/pages/Character/Index.vue:70
+   - 证据：frontend/src/stores/config.ts:236
+4. 结果渲染：Info 与 Skill/BufferSkill 刷新。
+   - 证据：frontend/src/pages/Character/Result/Index.vue:25
+   - 证据：frontend/src/pages/Character/Result/Index.vue:35
+   - 证据：frontend/src/pages/Character/Result/Index.vue:40
+
+说明：当前“装备流派”主要通过装备组合隐式形成，未见独立流派枚举模型。
+
+### 3.2 职业分支链路
+
+1. 触发动作：路由 alter 参数进入职业上下文。
+   - 证据：frontend/src/router/index.ts:13
+2. 状态变化：createCharacter(alter) 加载职业信息与配置。
+   - 证据：frontend/src/stores/info.ts:165
+3. 请求与计算：技能加点/定制写入 config.skills，触发重算。
+   - 证据：frontend/src/pages/Character/Skill/index.vue:23
+   - 证据：frontend/src/pages/Character/Skill/index.vue:32
+   - 证据：frontend/src/pages/Character/Skill/index.vue:41
+   - 证据：frontend/src/pages/Character/Index.vue:61
+4. 结果渲染：根据 buffer 分支渲染输出职业或辅助职业结果。
+   - 证据：frontend/src/pages/Character/Result/Index.vue:35
+   - 证据：frontend/src/pages/Character/Result/Index.vue:40
+
+说明：当前“职业分支”语义主要依赖路由 alter 与角色数据，无单独分支选择器。
+
+### 3.3 打造阶段链路
+
+1. 触发动作：在打造页切换装备/誓约/时装/徽章并录入参数。
+   - 证据：frontend/src/pages/Character/Forge/index.vue:5
+   - 证据：frontend/src/pages/Character/Forge/index.vue:6
+   - 证据：frontend/src/pages/Character/Forge/index.vue:7
+   - 证据：frontend/src/pages/Character/Forge/index.vue:8
+   - 证据：frontend/src/pages/Character/Forge/index.vue:30
+2. 状态变化：reinforce、upgrade 等字段写入 equips。
+   - 证据：frontend/src/stores/config.ts:21
+   - 证据：frontend/src/stores/config.ts:26
+3. 请求与计算：配置变化统一触发 execute 与 calc。
+   - 证据：frontend/src/pages/Character/Index.vue:61
+   - 证据：frontend/src/stores/config.ts:236
+4. 结果渲染：计算结果映射到 info 与 skills 区域。
+   - 证据：frontend/src/api/calc/type.ts:3
+   - 证据：frontend/src/api/calc/type.ts:4
+   - 证据：frontend/src/pages/Character/Result/Index.vue:25
+   - 证据：frontend/src/pages/Character/Result/Index.vue:35
+
+说明：当前“打造阶段”以数值字段组合表达，未见显式阶段枚举。
+
+## 4. 页面布局与分列展示逻辑
+
+### 4.1 页面骨架
+
+- 顶部：装备设置/技能设置/打造设置页签。
+  - 证据：frontend/src/pages/Character/Index.vue:4
+- 中部：content 为 flex 双列结构。
+  - 左列：RouterView 承载配置页面。
+  - 右列：Result 承载结果面板。
+  - 证据：frontend/src/pages/Character/Index.vue:10
+  - 证据：frontend/src/pages/Character/Index.vue:15
+  - 证据：frontend/src/pages/Character/Index.vue:18
+- 底部：系统奶、组队、导入按钮。
+  - 证据：frontend/src/pages/Character/Index.vue:21
+
+### 4.2 分列与联动
+
+- 主列联动：左侧输入变化驱动右侧结果更新。
+  - 证据：frontend/src/pages/Character/Index.vue:61
+  - 证据：frontend/src/pages/Character/Index.vue:70
+- 结果区二级分列：Info 与 Skill/BufferSkill 并排。
+  - 证据：frontend/src/pages/Character/Result/Index.vue:1
+- 装备页分列：装备列表区 + 右侧信息区（基础/套装/誓约）。
+  - 证据：frontend/src/pages/Character/EquipmentDictionary/Index.vue:1
+- 技能页分列：技能树主区 + 技能详情侧浮层。
+  - 证据：frontend/src/pages/Character/Skill/index.vue:1
+  - 证据：frontend/src/pages/Character/Skill/index.vue:58
+
+## 5. 角色信息与计算结果展示逻辑
+
+### 5.1 数据源
+
+- 角色基础数据：frontend/src/stores/info.ts:9
+- 技能与装备源：frontend/src/stores/info.ts:21
+- 计算输入配置：frontend/src/stores/config.ts:45
+- 计算结果结构（skills/info/buffer）：frontend/src/api/calc/type.ts:3
+- 角色信息项结构：frontend/src/api/calc/type.ts:27
+
+### 5.2 渲染链路
+
+1. 输入端：装备、技能、打造等写入 config。
+2. 计算端：result.execute 调用 calc，返回 IResult。
+   - 证据：frontend/src/stores/config.ts:260
+   - 证据：frontend/src/stores/config.ts:236
+3. 展示端：
+   - 角色信息由 Info 消费 result.state.info。
+     - 证据：frontend/src/pages/Character/Result/Index.vue:25
+   - 结果明细由 Skill/BufferSkill 消费 result.state.skills。
+     - 证据：frontend/src/pages/Character/Result/Index.vue:35
+     - 证据：frontend/src/pages/Character/Result/Index.vue:40
+
+## 6. 证据索引（按路由/store/API/页面组件分类）
+
+### 路由
+- frontend/src/router/index.ts:13
+- frontend/src/router/index.ts:22
+- frontend/src/router/index.ts:34
+- frontend/src/router/index.ts:40
+
+### Store
+- frontend/src/stores/config.ts:21
+- frontend/src/stores/config.ts:26
+- frontend/src/stores/config.ts:45
+- frontend/src/stores/config.ts:236
+- frontend/src/stores/config.ts:243
+- frontend/src/stores/config.ts:260
+- frontend/src/stores/info.ts:9
+- frontend/src/stores/info.ts:21
+- frontend/src/stores/info.ts:165
+
+### API
+- frontend/src/api/calc/type.ts:3
+- frontend/src/api/calc/type.ts:4
+- frontend/src/api/calc/type.ts:10
+- frontend/src/api/calc/type.ts:27
+
+### 页面组件
+- frontend/src/pages/Character/Index.vue:4
+- frontend/src/pages/Character/Index.vue:15
+- frontend/src/pages/Character/Index.vue:18
+- frontend/src/pages/Character/Index.vue:61
+- frontend/src/pages/Character/Index.vue:70
+- frontend/src/pages/Character/EquipmentDictionary/Index.vue:13
+- frontend/src/pages/Character/EquipmentDictionary/Index.vue:21
+- frontend/src/pages/Character/EquipmentDictionary/Index.vue:30
+- frontend/src/pages/Character/EquipmentDictionary/Index.vue:33
+- frontend/src/pages/Character/EquipmentDictionary/Index.vue:38
+- frontend/src/pages/Character/EquipmentDictionary/Index.vue:67
+- frontend/src/pages/Character/Skill/index.vue:10
+- frontend/src/pages/Character/Skill/index.vue:18
+- frontend/src/pages/Character/Skill/index.vue:23
+- frontend/src/pages/Character/Skill/index.vue:32
+- frontend/src/pages/Character/Skill/index.vue:41
+- frontend/src/pages/Character/Forge/index.vue:5
+- frontend/src/pages/Character/Forge/index.vue:6
+- frontend/src/pages/Character/Forge/index.vue:7
+- frontend/src/pages/Character/Forge/index.vue:8
+- frontend/src/pages/Character/Forge/index.vue:30
+- frontend/src/pages/Character/Result/Index.vue:25
+- frontend/src/pages/Character/Result/Index.vue:35
+- frontend/src/pages/Character/Result/Index.vue:40
+
+## 7. 问题清单与优先级改造建议
+
+### P0
+
+1. 装备流派缺少显式数据模型与入口。
+- 影响：流派复用、分享、回放能力弱。
+- 建议：新增流派实体（名称、标签、约束、快照），并在装备页增加流派管理入口。
+
+2. 职业分支语义依赖路由参数，缺少可视化分支状态。
+- 影响：评审和调试容易混淆当前分支上下文。
+- 建议：在角色页头部补充职业与分支状态条。
+
+### P1
+
+1. 打造阶段没有统一阶段语义层。
+- 影响：规则解释成本高，阶段对比困难。
+- 建议：建立阶段映射（阶段名 -> 字段集合），并在打造页展示阶段摘要。
+
+2. 结果展示缺少标准化加载态/错误态反馈。
+- 影响：请求延迟或失败时可解释性不足。
+- 建议：结果区增加执行中、失败重试、最近成功时间。
+
+### P2
+
+1. 多模块分列宽度与信息密度策略存在差异。
+- 建议：统一主次列比例与标题层级规范。
+
+2. 证据索引依赖人工维护。
+- 建议：后续补充自动化证据采集脚本，降低维护成本。