starmen1265
0f96b79dba
两阶段流水线：搭建指南Markdown → JSON → UE5 Actor - 解析器：4种表格变体+范围展开+坐标表达式计算 - 配置：37种BSP资产映射+13种材质+7区域定义 - 验证：265个Actor全部通过，0错误 - Builder：UE5 Python API自动放置Actor+材质+Outliner - 报告：自动生成搭建报告Markdown Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
338 lines
8.4 KiB
Markdown
338 lines
8.4 KiB
Markdown
# 技术设计文档输出模板
|
||
|
||
本模板定义需求分析 8 步流程产出的技术设计文档的标准结构。所有技术设计文档必须遵循此模板。
|
||
|
||
---
|
||
|
||
## 模板
|
||
|
||
```markdown
|
||
# <系统名称> 技术设计文档（<版本号> <阶段>）
|
||
|
||
> 任务ID: <任务编号>
|
||
> 对应执行案: `docs/design/<stage>/<系统名>-执行案.md`
|
||
> 关联系统: <上游/下游/平行系统列表>
|
||
> 阶段: 原型 / 批量生产 / 测试
|
||
> 日期: <YYYY-MM-DD>
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
<系统的一句话定位>。<系统在当前版本中要做什么、不做什么>。
|
||
|
||
**实现复杂度**：低 / 中 / 中-高 / 高
|
||
**预估工期**：<X-Y 天>
|
||
**新增/修改代码量**：约 <XXX-YYY> 行 C++ + <N> 个 UMG 蓝图
|
||
|
||
---
|
||
|
||
## 1. 需求功能点罗列
|
||
|
||
将执行文档中所有行为规则逐一列出，按实现方式分类。
|
||
|
||
### UE 内置功能
|
||
|
||
以下功能点直接使用 UE5 引擎内置能力，无需或仅需极少量自定义代码：
|
||
|
||
| 功能点 | 使用的 UE 内置能力 | 对应行为规则 | 备注 |
|
||
|--------|-------------------|-------------|------|
|
||
| <功能描述> | <如：SpringArm Camera Lag、Enhanced Input、CMC 参数、SetViewTargetWithBlend 等> | <执行案条目编号> | <配置说明> |
|
||
|
||
### 自定义实现
|
||
|
||
以下功能点需要编写自定义 C++ / 蓝图代码：
|
||
|
||
| 功能点 | 实现方式概述 | 对应行为规则 | 预估复杂度 |
|
||
|--------|-------------|-------------|-----------|
|
||
| <功能描述> | <如：新建 UActorComponent 管理状态机、自定义 UI Widget 等> | <执行案条目编号> | 低/中/高 |
|
||
|
||
> **分类原则**：如果 UE 内置能力能覆盖 80% 以上的需求且行为一致，归为"UE 内置"。需要自定义状态管理、跨系统协调或特殊逻辑的归为"自定义实现"。
|
||
|
||
---
|
||
|
||
## 2. 功能领域图
|
||
|
||
展示当前系统由哪些功能模块组成，以及模块之间的关系。注意：此处只关注功能领域和领域之间的关系，不细分到类级别。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
subgraph <层名1>
|
||
<模块A>[<模块A名称>]
|
||
<模块B>[<模块B名称>]
|
||
end
|
||
|
||
subgraph <层名2>
|
||
<模块C>[<模块C名称>]
|
||
end
|
||
|
||
<模块A> -->|<交互说明>| <模块C>
|
||
<模块B> -.->|<事件通知>| <模块C>
|
||
```
|
||
|
||
### 模块职责说明
|
||
|
||
| 模块 | 职责 | 关键输入 | 关键输出 |
|
||
|------|------|---------|---------|
|
||
| <模块名> | <一句话描述> | <从哪接收什么> | <向谁发送什么> |
|
||
|
||
---
|
||
|
||
## 3. 类设计图
|
||
|
||
将功能领域图细化为具体的类设计。展示每个类的关键数据成员、关键接口，以及类之间的关系类型。
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class <类名> {
|
||
<可见性><数据成员/接口>
|
||
}
|
||
|
||
<类A> *-- <类B> : <关系说明>
|
||
<类C> ..|> <接口D> : <关系说明>
|
||
```
|
||
|
||
### 关系类型说明
|
||
|
||
| 关系类型 | 含义 | 本项目中的体现 |
|
||
|---------|------|--------------|
|
||
| 继承 `<\|--` | 子类继承父类 | Actor/Component 继承 |
|
||
| 实现 `..\|>` | 实现接口 | UInterface 实现 |
|
||
| 组合 `*--` | 生命周期绑定 | Character 持有 Component |
|
||
| 聚合 `o--` | 引用但非拥有 | 引用其他 Actor/Component |
|
||
| 依赖 `..>` | 临时使用 | 方法参数、局部变量 |
|
||
|
||
### 新增类
|
||
|
||
| 类名 | 类型 | 职责 | 位置 |
|
||
|------|------|------|------|
|
||
| <UE5类名> | <UActorComponent / UInterface / AActor 等> | <一句话职责> | <Source/ 子目录> |
|
||
|
||
### 修改类
|
||
|
||
| 类名 | 修改内容 |
|
||
|------|---------|
|
||
| <已有类名> | <新增成员/接口/修改逻辑> |
|
||
|
||
### 新增蓝图
|
||
|
||
| 蓝图名 | 类型 | 用途 |
|
||
|--------|------|------|
|
||
| <BP_前缀名称> | <UMG Widget / Actor Blueprint 等> | <用途说明> |
|
||
|
||
---
|
||
|
||
## 4. 时序图（仅复杂特性）
|
||
|
||
> ⚠️ 条件性章节：仅当特性涉及 3+ 个系统协调，或有条件分支/循环流程时才需要绘制。
|
||
> 简单特性（如纯参数配置、单系统内部逻辑）跳过此章节。
|
||
|
||
### <特性名称> 时序图
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
autonumber
|
||
participant <别名1> as <中文名1>
|
||
participant <别名2> as <中文名2>
|
||
|
||
<别名1>->><别名2>: <消息描述>
|
||
activate <别名2>
|
||
<别名2>-->><别名1>: <返回描述>
|
||
deactivate <别名2>
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 核心数据结构
|
||
|
||
### 枚举
|
||
|
||
```cpp
|
||
UENUM(BlueprintType)
|
||
enum class E<EnumName> : uint8
|
||
{
|
||
<Value1>, // <中文说明>
|
||
<Value2>, // <中文说明>
|
||
};
|
||
```
|
||
|
||
### 配置数据结构
|
||
|
||
```cpp
|
||
USTRUCT(BlueprintType)
|
||
struct F<StructName>
|
||
{
|
||
GENERATED_BODY()
|
||
|
||
// <分组说明>
|
||
UPROPERTY(EditAnywhere, BlueprintReadWrite)
|
||
<Type> <PropertyName> = <DefaultValue>; // <中文说明>
|
||
};
|
||
```
|
||
|
||
### 类关键数据定义
|
||
|
||
```cpp
|
||
UCLASS()
|
||
class U<ClassName> : public U<ParentClass>
|
||
{
|
||
GENERATED_BODY()
|
||
|
||
// === 配置参数（构造函数设置默认值） ===
|
||
UPROPERTY(EditAnywhere, Category="<Category>")
|
||
<Type> <Property> = <Default>; // <说明>
|
||
|
||
// === 运行时状态 ===
|
||
<Type> <Property>; // <说明>
|
||
|
||
// === 关键接口 ===
|
||
UFUNCTION(BlueprintCallable)
|
||
void <MethodName>(<Params>); // <说明>
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 行为规则 → 实现方案映射
|
||
|
||
对执行文档中每条行为规则，逐一说明实现方案。复杂接口使用鲁棒图/流程图/伪代码描述。
|
||
|
||
### 一、<规则分组标题>
|
||
|
||
#### <规则编号>. <规则简述>
|
||
|
||
**实现**：<一句话概述实现方式>
|
||
|
||
```cpp
|
||
// 关键代码片段
|
||
```
|
||
|
||
**可调参数**：<参数名>, <范围/默认值>
|
||
|
||
---
|
||
|
||
#### <复杂接口名称>（复杂接口描述）
|
||
|
||
> ⚠️ 条性章节：仅当接口有 5+ 个决策分支或协调多个子系统状态时才需要。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start([入口]) --> Check{判断?}
|
||
Check -->|条件A| ActionA[执行A]
|
||
Check -->|条件B| ActionB[执行B]
|
||
ActionA --> End([结束])
|
||
ActionB --> End
|
||
```
|
||
|
||
或使用伪代码：
|
||
|
||
```
|
||
function <InterfaceName>(<params>):
|
||
1. <步骤1：前置检查>
|
||
2. <步骤2：状态更新>
|
||
3. <步骤3：根据类型分发>
|
||
- 类型A → <处理A>
|
||
- 类型B → <处理B>
|
||
4. <步骤4：后续通知>
|
||
5. <步骤5：状态清理>
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 美术资源需求
|
||
|
||
| 资源类型 | 名称 | 数量 | 规格 | 触发时机/用途 |
|
||
|----------|------|------|------|---------------|
|
||
| <3D模型/动画/UI/2D图标/音效> | <名称> | <数量> | <尺寸/格式/时长> | <何时使用> |
|
||
|
||
> v0.1 原型阶段允许占位资源，但类型和数量必须明确。
|
||
|
||
---
|
||
|
||
## 8. 技术风险与注意事项
|
||
|
||
| 风险 | 等级 | 说明 | 缓解措施 |
|
||
|------|------|------|---------|
|
||
| <风险描述> | 🔴高/🟡中/🟢低 | <详细说明> | <如何应对> |
|
||
|
||
### 注意事项
|
||
|
||
1. **<注意事项标题>**：<详细说明>
|
||
|
||
---
|
||
|
||
## 9. 数据流
|
||
|
||
### 配置参数流
|
||
|
||
```
|
||
<数据来源> → <加载方式> → <使用位置>
|
||
```
|
||
|
||
### 运行时状态流
|
||
|
||
```
|
||
<输入源> → <处理系统> → <输出/通知>
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 可调参数汇总
|
||
|
||
| 参数 | C++ 属性 | 默认值 | 位置 |
|
||
|------|---------|--------|------|
|
||
| <中文参数名> | `<PropertyName>` | <值> | <构造函数/BeginPlay/DataAsset> |
|
||
|
||
---
|
||
|
||
## 11. 文件结构
|
||
|
||
```
|
||
Source/ChildHood/
|
||
├── <模块目录>/
|
||
│ ├── <文件名>.h/.cpp # <说明>
|
||
│ └── <文件名>.h/.cpp # <说明>
|
||
└── <其他目录>/
|
||
└── <文件名>.h/.cpp # <修改说明>
|
||
|
||
Content/
|
||
├── Blueprints/
|
||
│ └── <蓝图名> # <说明>
|
||
├── UI/
|
||
│ └── <Widget名> # <说明>
|
||
└── Data/
|
||
└── <DataAsset名> # <说明>
|
||
```
|
||
|
||
---
|
||
|
||
## 工期预估与实现拆分
|
||
|
||
### 工作量估算
|
||
|
||
| 维度 | 估算 |
|
||
|------|------|
|
||
| 总工期 | <X-Y 天> |
|
||
| 新增 C++ 代码 | <XXX-YYY 行> |
|
||
| 新增蓝图 | <N 个> |
|
||
| 实现复杂度 | <低/中/高> |
|
||
|
||
### 实现拆分建议
|
||
|
||
供步骤⑥（程序实现）参考的推荐拆分方式，每个子任务可独立验证：
|
||
|
||
| 子任务 | 内容 | 预估时间 | 依赖 | 验证方式 |
|
||
|--------|------|---------|------|---------|
|
||
| <子任务名> | <具体内容> | <时间> | <依赖其他子任务> | <如何验证完成> |
|
||
```
|
||
|
||
---
|
||
|
||
## 使用说明
|
||
|
||
1. **替换所有 `<...>` 占位符**为实际内容
|
||
2. **条件性章节**（第 4 节时序图、第 6 节复杂接口描述）：根据复杂度判定决定是否包含
|
||
3. **Mermaid 图表**：在 markdown 渲染器中会自动生成可视化图表
|
||
4. **保持一一映射**：每条执行文档行为规则都必须在第 6 节有对应实现方案
|
||
5. **阶段适配**：原型阶段允许简化描述，批量生产阶段需要完整覆盖所有章节
|