# 技术设计文档输出模板

本模板定义需求分析 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. **阶段适配**：原型阶段允许简化描述，批量生产阶段需要完整覆盖所有章节