4.6 KiB
Executable File
4.6 KiB
Executable File
过程方案vs事实方案
定义
过程方案和事实方案是规格驱动开发中两种不同的规格管理方式。
- 过程方案（Plans）：记录实现过程，每次新建文件，用完即弃
- 事实方案（Designs）：记录系统真相，覆盖更新，长期维护
核心区别
| 维度 | 过程方案（Plans） | 事实方案（Designs） |
|---|---|---|
| 目的 | 记录实现过程 | 记录当前状态 |
| 更新方式 | 追加新文件 | 覆盖更新 |
| 生命周期 | 短期（任务完成后归档） | 长期（持续维护） |
| 维护成本 | 低（不修改旧文件） | 高（必须保持最新） |
| 使用场景 | 任务执行、问题排查 | 新功能开发、架构决策 |
| 示例 | plan-2026-06-20-feature-x.md | database-schema.md |
过程方案（Plans）
特征
- 每次任务创建新文件
- 文件命名包含日期：
plan-YYYY-MM-DD-feature-name.md - 任务完成后移动到
archive/目录 - 不修改旧文件，保留决策轨迹
内容结构
# 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的事实依据
内容结构
# 数据库设计
## 概述
系统数据库设计，包含用户、角色、权限等表。
## 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设计
- 架构设计
- 标准规范
- 需求规格
优势与局限
过程方案
优势：
- 维护成本低
- 保留决策轨迹
- 易于追溯历史
局限：
- 文件数量多
- 需要定期归档
- 不反映当前状态
事实方案
优势：
- 反映当前状态
- 单一真相来源
- 易于理解
局限：
- 维护成本高
- 需要持续更新
- 丢失历史信息
最佳实践
- 明确区分：清楚区分哪些是过程方案，哪些是事实方案
- 定期归档：过程方案定期归档到
archive/目录 - 保持最新：事实方案必须保持最新状态
- 变更历史：事实方案记录变更历史
- 关联引用：Plans引用Designs，确保一致性