docs(review): P-008交互系统程序设计质量门审查通过+美术调研+工作流完善

- P-008 交互系统技术设计审查通过,审查记录 docs/plans/reviews/P-008-review.md
- D-001 关卡执行案审查通过,审查记录 docs/plans/reviews/D-001-review.md
- 新增 AI 美术调研参考图(我的暑假/放学后少年/真实场景/美术风格)
- 新增关卡执行案、白模搭建指南和搭建报告
- 完善工作流技能:质量门审查、Agent记忆、需求分析
- 更新交互系统和角色控制系统技术设计文档
- 清理过时参考文档
This commit is contained in:
2026-06-07 01:54:02 +08:00
parent dec183ff02
commit 8011cb6472
276 changed files with 5630 additions and 1633 deletions
@@ -0,0 +1,337 @@
# 技术设计文档输出模板
本模板定义需求分析 8 步流程产出的技术设计文档的标准结构。所有技术设计文档必须遵循此模板。
---
## 模板
```markdown
# <系统名称> 技术设计文档(<版本号> <阶段>)
> 任务ID: <任务编号>
> 对应执行案: `<执行案文件路径>`
> 关联系统: <上游/下游/平行系统列表>
> 阶段: 原型 / 批量生产 / 测试
> 日期: <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. **阶段适配**:原型阶段允许简化描述,批量生产阶段需要完整覆盖所有章节