# 工作流清单

> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。

---

## 任务分类

| 类型 | 特征 | 处理方式 |
|---|---|---|
| **简单修复** | 查询、解释、小范围修改、影响面低、用户已给出明确方式 | 直接处理，完成后验证并归档检查 |
| **旧模块修复** | 已有框架模块的 bug 修复、逻辑补全、局部优化 | 读取模块文档，分析影响范围后修复，验证并归档 |
| **Spec 任务** | 新增框架模块、调整架构/目录/依赖、批量修改迁移 | 走 OpenSpec 流程 |

---

## 简单修复流程

1. 确认任务范围。
2. 读取相关模块文档。
3. 直接修改。
4. 验证（如可运行测试、检查链接、预览 Markdown）。
5. 执行归档检查。
6. 简短说明结果。

---

## 旧模块修复流程

1. 定位已有模块文档和相关内容。
2. 简短分析影响范围和风险。
3. 直接修复。
4. 验证。
5. 按 [50-归档规则.md](50-归档规则.md) 同步相关模块文档。

---

## Spec 任务流程

大需求 / 新模块统一走 OpenSpec：

1. 分析目标、影响范围、风险和依赖。
2. 给出 2-3 个方案。
3. 用户确认后创建 OpenSpec change。
4. 生成 `proposal.md`、`design.md`、`tasks.md`。
5. 实现。
6. 验证。
7. 归档并同步文档。

详见 [60-新特性工作流.md](60-新特性工作流.md)。

---

## 开发流程

### 1. 文档学习

根据任务类型阅读对应模块文档：

| 任务类型 | 必读文档 |
|---------|---------|
| UI 开发 | [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md) |
| UI 界面设计 | [UI 界面拼接设计指南](../modules/frameworks/UI窗口系统/界面拼接.md) |
| 相机控制 | [相机系统](../modules/frameworks/相机系统/README.md) |
| 实体开发 | [实体系统](../modules/frameworks/实体系统/README.md) |
| 事件使用 | [事件系统](../modules/frameworks/事件系统/README.md) |
| 资源加载 | [资源管理](../modules/frameworks/资源管理/README.md) |

### 2. 需求分析

1. 明确需求：理解业务需求，确定需要实现的功能。
2. 评估复杂度：判断是否需要核心库支持或扩展。
3. 设计方案：规划代码结构和调用关系。

### 3. 代码编写

1. 在 `GameFunction/` 下按职责创建模块目录。
2. 遵循编码规范，使用核心库提供的 API。
3. 在 Unity 中测试功能正确性。

### 4. 代码审查

1. 自我检查：检查是否符合规范，是否有潜在问题。
2. 团队审查：提交代码进行团队审查。
3. 修复问题：根据审查意见修改代码。

### 5. 集成测试

1. 模块测试：测试单个模块功能。
2. 集成测试：测试模块间交互。
3. 回归测试：确保不影响现有功能。

---

## 文档变更联动检查

修改任何文档前，确认它是否被其他文档引用：

- 模块文档变更 → 同步检查模块索引、模块登记规则、架构说明。
- 架构/目录变更 → 同步检查模块索引、相关模块 README、架构说明。
- 规则文件变更 → 同步检查 `rules/项目规则入口.md`、`ai/AI接入入口.md`、`AGENTS.md`、`CLAUDE.md`、`RULES.md`。
- spec/change 完成 → 同步更新相关模块 progress.md，并建立 `specs/openspec/` 归档。

---

## 提交前检查

### 提交信息格式

推荐格式：

```text
[模块][类型]: 简短描述

- 详细说明 1
- 详细说明 2
```

类型：`feat`、`fix`、`docs`、`refactor`、`test`、`chore`。

模块名示例：`framework`、`entity`、`ui`、`event`、`resource`、`docs`、`rules`、`hooks`。

示例：

```text
[entity][docs]: 补充实体池索引机制说明

- 添加 onlyid -> entity 映射说明
- 补充 HFBasicPool/HFEnemyPool/HFHumanityPool 边界
```

> **历史格式说明**：早期文档使用 `【操作原因】具体操作内容`（如 `【修复】xxx`）。该格式已弃用，新提交统一使用 `[module][type]: description`。

### 分支管理

| 分支名称 | 用途 |
|----------|------|
| `master` | 主分支，稳定版本 |
| `develop` | 开发分支，日常开发 |
| `feature/*` | 功能分支，开发新功能 |
| `bugfix/*` | Bug 修复分支 |

### Git 操作原则

- 执行 Git 操作前确认当前操作路径是否正确。
- 遵循项目既定的分支策略。
- 使用语义化提交信息，清晰描述更改内容。
- 重要功能提交前建议先创建分支进行测试。
- 开发完成后及时推送到远程仓库。

### 提交前检查项

- [ ] 文档链接可点击且指向正确。
- [ ] 文档关联表已更新。
- [ ] 模块索引已同步（如新增/拆分了模块）。
- [ ] 无拼写或明显格式错误。
- [ ] 未引入外部项目专属内容。
- [ ] 业务参考内容只出现在 `business-reference/` 下。

---

## 新增内容流程

### 新增框架模块

1. 在 [模块索引](../modules/模块索引.md) 中登记。
2. 创建 `modules/frameworks/<module>.md`；复杂模块可拆分为 `modules/frameworks/<module>/README.md` 加子文档。
3. 在 [架构说明](10-架构说明.md) 中补充依赖方向。
4. 更新相关模块的文档关联表。

### 新增编辑器工具

1. 在 [模块索引](../modules/模块索引.md) 中登记。
2. 创建 `modules/editor-tools/<tool>.md` 或补充汇总文档。
3. 说明使用入口、生成输出、依赖项。

### 新增业务参考

1. 放入 `business-reference/<project>/`。
2. 不进入 `modules/模块索引.md` 主索引。
3. 在 `business-reference/<project>/业务框架映射接口.md` 中补充映射关系。

---

## 生成/构建流程

若项目使用 StrayFog 框架配套的生成工具：

- 优先修改源表、proto 或 schema，而不是生成输出。
- 生成后检查输出目录，确认变更符合预期。
- 缺失的生成步骤记录到对应模块文档。

---

## 文档关联

> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

| 文档 | 关联原因 |
|---|---|
| [rules/项目规则入口.md](项目规则入口.md) | 工作流清单是项目规则入口索引的关键规则 |
| [rules/50-归档规则.md](50-归档规则.md) | 归档规则与工作流清单互相引用 |
| [rules/60-新特性工作流.md](60-新特性工作流.md) | 新特性工作流是工作流清单的延伸 |
| [rules/20-开发规则.md](20-开发规则.md) | 提交格式与开发规则互相引用 |
| [modules/模块索引.md](../modules/模块索引.md) | 新增模块登记需同步模块索引 |
| [hooks/commit-check.ps1](../hooks/commit-check.ps1) | 提交检查脚本需与本文件格式一致 |