ChildHood/.claude/skills/requirements-analysis/references/output-template.md

技术设计文档输出模板

本模板定义需求分析 8 步流程产出的技术设计文档的标准结构。所有技术设计文档必须遵循此模板。

---

模板

# <系统名称> 技术设计文档（<版本号>）

> 任务ID: <任务编号>
> 对应执行案: `docs/design/<系统名>-执行案.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. 类设计图

将功能领域图细化为具体的类设计。展示每个类的关键数据成员、关键接口，以及类之间的关系类型。

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+ 个系统协调，或有条件分支/循环流程时才需要绘制。 简单特性（如纯参数配置、单系统内部逻辑）跳过此章节。

<特性名称> 时序图

sequenceDiagram
    autonumber
    participant <别名1> as <中文名1>
    participant <别名2> as <中文名2>

    <别名1>->><别名2>: <消息描述>
    activate <别名2>
    <别名2>-->><别名1>: <返回描述>
    deactivate <别名2>

---

5. 核心数据结构

枚举

UENUM(BlueprintType)
enum class E<EnumName> : uint8
{
    <Value1>,  // <中文说明>
    <Value2>,  // <中文说明>
};

配置数据结构

USTRUCT(BlueprintType)
struct F<StructName>
{
    GENERATED_BODY()

    // <分组说明>
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    <Type> <PropertyName> = <DefaultValue>;  // <中文说明>
};

类关键数据定义

UCLASS()
class U<ClassName> : public U<ParentClass>
{
    GENERATED_BODY()

    // === 配置参数（构造函数设置默认值） ===
    UPROPERTY(EditAnywhere, Category="<Category>")
    <Type> <Property> = <Default>;  // <说明>

    // === 运行时状态 ===
    <Type> <Property>;  // <说明>

    // === 关键接口 ===
    UFUNCTION(BlueprintCallable)
    void <MethodName>(<Params>);  // <说明>
};

---

6. 行为规则 → 实现方案映射

对执行文档中每条行为规则，逐一说明实现方案。复杂接口使用鲁棒图/流程图/伪代码描述。

一、<规则分组标题>

<规则编号>. <规则简述>

实现：<一句话概述实现方式>

// 关键代码片段

可调参数：<参数名>, <范围/默认值>

---

<复杂接口名称>（复杂接口描述）

⚠️ 条性章节：仅当接口有 5+ 个决策分支或协调多个子系统状态时才需要。

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图标/音效>	<名称>	<数量>	<尺寸/格式/时长>	<何时使用>

类型和数量必须明确，允许占位资源。

---

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. **完整覆盖**：所有章节需按模板结构填写，条件性章节按复杂度判定