171 lines
4.6 KiB
Markdown
Executable File
171 lines
4.6 KiB
Markdown
Executable File
# 过程方案vs事实方案
|
||
|
||
> 相关：[[规格驱动开发]]、[[上下文体系]]、[[Harness工程]]
|
||
|
||
## 定义
|
||
|
||
**过程方案**和**事实方案**是[[规格驱动开发]]中两种不同的规格管理方式。
|
||
|
||
- **过程方案（Plans）**：记录实现过程，每次新建文件，用完即弃
|
||
- **事实方案（Designs）**：记录系统真相，覆盖更新，长期维护
|
||
|
||
## 核心区别
|
||
|
||
| 维度 | 过程方案（Plans） | 事实方案（Designs） |
|
||
|------|------------------|-------------------|
|
||
| 目的 | 记录实现过程 | 记录当前状态 |
|
||
| 更新方式 | 追加新文件 | 覆盖更新 |
|
||
| 生命周期 | 短期（任务完成后归档） | 长期（持续维护） |
|
||
| 维护成本 | 低（不修改旧文件） | 高（必须保持最新） |
|
||
| 使用场景 | 任务执行、问题排查 | 新功能开发、架构决策 |
|
||
| 示例 | plan-2026-06-20-feature-x.md | database-schema.md |
|
||
|
||
## 过程方案（Plans）
|
||
|
||
### 特征
|
||
- 每次任务创建新文件
|
||
- 文件命名包含日期：`plan-YYYY-MM-DD-feature-name.md`
|
||
- 任务完成后移动到`archive/`目录
|
||
- 不修改旧文件，保留决策轨迹
|
||
|
||
### 内容结构
|
||
```markdown
|
||
# Plan: 实现用户注册功能
|
||
|
||
## 目标
|
||
实现用户注册API，支持邮箱验证
|
||
|
||
## 任务列表
|
||
- [ ] 1. 创建数据库表users
|
||
- [ ] 2. 实现POST /api/v1/users API
|
||
- [ ] 3. 实现邮箱验证逻辑
|
||
|
||
## 实现方案
|
||
1. 使用Flyway创建users表
|
||
2. Controller接收CreateUserCommand
|
||
3. AppService调用UserRepository保存
|
||
|
||
## 状态
|
||
- 开始时间：2026-06-20 10:00
|
||
- 预计完成：2026-06-20 12:00
|
||
- 实际完成：2026-06-20 11:30
|
||
|
||
## 问题记录
|
||
- 10:30 发现数据库连接池配置问题
|
||
- 11:00 邮箱服务超时，增加重试机制
|
||
```
|
||
|
||
### 最佳实践
|
||
- **命名规范**：`plan-YYYY-MM-DD-feature-name.md`
|
||
- **内容结构**：目标、方案、任务列表、状态、问题记录
|
||
- **归档策略**：任务完成后移动到`archive/`目录
|
||
|
||
## 事实方案（Designs）
|
||
|
||
### 特征
|
||
- 每次覆盖更新
|
||
- 文件命名使用功能名称：`database-schema.md`
|
||
- 必须保持最新状态
|
||
- 作为下次Plan的事实依据
|
||
|
||
### 内容结构
|
||
```markdown
|
||
# 数据库设计
|
||
|
||
## 概述
|
||
系统数据库设计，包含用户、角色、权限等表。
|
||
|
||
## users表
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | bigint | 主键 |
|
||
| username | varchar(50) | 用户名，唯一 |
|
||
| email | varchar(100) | 邮箱，唯一 |
|
||
| password | varchar(255) | 密码，加密存储 |
|
||
| status | tinyint(1) | 状态：0-禁用，1-启用 |
|
||
| created_at | timestamp | 创建时间 |
|
||
| updated_at | timestamp | 更新时间 |
|
||
|
||
## roles表
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | bigint | 主键 |
|
||
| name | varchar(20) | 角色名称 |
|
||
|
||
## 变更历史
|
||
- 2026-06-20：添加users表
|
||
- 2026-06-21：添加roles表
|
||
- 2026-06-22：添加user_roles关联表
|
||
```
|
||
|
||
### 最佳实践
|
||
- **命名规范**：使用功能名称，如`database-schema.md`
|
||
- **内容结构**：概述、详细设计、变更历史
|
||
- **更新策略**：每次变更必须更新文档，保持最新
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
docs/
|
||
├── standards/ # 标准规格（事实方案）
|
||
├── features/ # 需求规格（事实方案）
|
||
├── designs/ # 设计规格（事实方案）
|
||
├── plans/ # 计划规格（过程方案）
|
||
│ ├── archive/ # 归档的计划
|
||
│ └── plan-2026-06-20-feature-x.md
|
||
└── others/ # 架构决策、Release、测试用例等
|
||
```
|
||
|
||
## 使用策略
|
||
|
||
### 何时使用过程方案
|
||
- 任务执行过程记录
|
||
- 问题排查记录
|
||
- 决策轨迹记录
|
||
- 临时方案记录
|
||
|
||
### 何时使用事实方案
|
||
- 数据库设计
|
||
- API设计
|
||
- 架构设计
|
||
- 标准规范
|
||
- 需求规格
|
||
|
||
## 优势与局限
|
||
|
||
### 过程方案
|
||
**优势**：
|
||
- 维护成本低
|
||
- 保留决策轨迹
|
||
- 易于追溯历史
|
||
|
||
**局限**：
|
||
- 文件数量多
|
||
- 需要定期归档
|
||
- 不反映当前状态
|
||
|
||
### 事实方案
|
||
**优势**：
|
||
- 反映当前状态
|
||
- 单一真相来源
|
||
- 易于理解
|
||
|
||
**局限**：
|
||
- 维护成本高
|
||
- 需要持续更新
|
||
- 丢失历史信息
|
||
|
||
## 最佳实践
|
||
|
||
1. **明确区分**：清楚区分哪些是过程方案，哪些是事实方案
|
||
2. **定期归档**：过程方案定期归档到`archive/`目录
|
||
3. **保持最新**：事实方案必须保持最新状态
|
||
4. **变更历史**：事实方案记录变更历史
|
||
5. **关联引用**：Plans引用Designs，确保一致性
|
||
|
||
## 相关概念
|
||
|
||
- [[规格驱动开发]]：过程方案和事实方案是SDD的规格管理方式
|
||
- [[上下文体系]]：过程方案和事实方案是上下文体系的组成部分
|
||
- [[Harness工程]]：过程方案和事实方案是Harness的文档管理方式
|