Decision 决策文档模板

文档定位

Decision 决策文档用于记录项目中的关键设计取舍。

它重点回答：

为什么这样设计？
当时有哪些备选方案？
为什么不选其他方案？
这个决策带来了什么影响？
未来什么情况下可以重新评估？

Decision 文档的价值不是记录“做了什么”，而是记录“为什么这么做”。

很多项目后期维护困难，往往不是因为不知道代码现在是什么样，而是不知道当时为什么要这样设计。

适用场景

以下情况建议编写 Decision 文档：

• 新增表还是复用旧表

• 拆表还是宽表

• 同步还是异步

• 是否引入新组件

• 是否引入缓存

• 是否使用消息队列

• 是否改变接口模型

• 是否兼容历史数据

• 是否保留旧逻辑

• 是否重构核心模块

• 状态流转如何设计

• 数据来源如何选择

• 某个字段为什么不能删除

• 某个历史包袱为什么暂时保留

以下情况一般不需要单独写 Decision：

• 简单 bug 修复

• 简单字段调整

• 普通接口新增

• 没有明显取舍的小功能

文件命名建议

如果放在代码仓库中，建议命名为：

docs/decisions/yyyy-MM-dd-decision-title.md

示例：

docs/decisions/2026-06-11-etf-fund-flow-rank-use-independent-table.md
docs/decisions/2026-06-10-calendar-event-api-use-post.md

如果放在 MinDoc 中，可以按项目或模块归类：

项目档案 / ETF系统 / 技术决策 / ETF 资金异动榜使用独立表

模板

# 决策标题

## 状态

已决定 / 已废弃 / 已替换 / 待重新评估

## 关联信息

- 关联 Feature：
- 关联 PRD：
- 关联需求：
- 关联 Issue：
- 决策时间：
- 参与人员：
- 影响项目：

## 背景

说明当时遇到了什么问题。

可以包括：

- 当前系统现状
- 当前方案的问题
- 新需求带来的变化
- 数据、性能、维护、扩展方面的约束
- 为什么需要做这个决策

示例：

```text
系统需要新增 ETF 资金异动榜功能。
该功能需要按交易日保存历史榜单，但当前 ETF 基础信息表只表示 ETF 当前状态，没有交易日维度。
因此需要决定榜单数据是写入 ETF 基础信息表，还是独立建表保存。

决策

简洁说明最终决定。

示例：

ETF 资金异动榜使用独立表保存，不写入 ETF 基础信息表。
初期新增 etf_share_change_rank 表保存份额异动榜。
后续成交额异动榜可以独立建表或在接口层统一聚合。

文档边界

如果涉及表结构、接口、配置等容易变化的内容，可以说明文档边界。

示例：

本文档只记录设计决策和核心业务字段，不维护完整数据库 DDL。
实际表结构以 migration SQL、实体类、Mapper 和线上数据库为准。

约束条件

记录做决策时必须考虑的约束。

示例：

• 需要兼容历史数据。

• 不能影响旧接口。

• 数据源不稳定。

• 任务需要支持重复执行。

• 前端需要统一展示。

• 数据量未来可能增长。

• 当前阶段不引入新中间件。

备选方案

方案一：方案名称

说明方案内容。

优点：

1. xxx

2. xxx

3. xxx

缺点：

1. xxx

2. xxx

3. xxx

结论：

采用 不采用 暂不采用。

方案二：方案名称

说明方案内容。

优点：

1. xxx

2. xxx

3. xxx

缺点：

1. xxx

2. xxx

3. xxx

结论：

采用 不采用 暂不采用。

方案三：方案名称

说明方案内容。

优点：

1. xxx

2. xxx

3. xxx

缺点：

1. xxx

2. xxx

3. xxx

结论：

采用 不采用 暂不采用。

为什么选择当前方案

说明选择当前方案的核心原因。

建议写清楚：

• 当前方案解决了什么问题

• 相比其他方案更适合在哪里

• 当前阶段为什么这样做

• 这个方案的长期维护收益是什么

• 接受了哪些代价

示例：

ETF 基础信息表表达的是“某个 ETF 当前是什么”，而资金异动榜表达的是“某个 ETF 在某个交易日发生了什么变化”。

两者语义不同、生命周期不同、更新频率不同，因此不应混在同一张表中。

独立建表虽然会增加表数量，但可以更好地支持历史快照、重复执行、补数据和后续扩展。

影响范围

数据库

说明涉及哪些表，但不一定写完整 DDL。

示例：

新增 etf_share_change_rank 表，用于保存 ETF 份额异动榜。
后续可能新增 etf_amount_change_rank 表，用于保存成交额异动榜。

后端

说明影响哪些后端模块。

示例：

• 新增榜单生成任务。

• 新增榜单查询接口。

• 新增最近榜单交易日查询接口。

• 修改数据读取逻辑。

前端

说明影响哪些前端页面。

示例：

• 新增 ETF 资金异动榜页面。

• 新增榜单类型切换。

• 新增日期筛选。

• 新增空数据展示。

运维 / 数据

说明是否影响部署、任务、补数据、监控。

示例：

• 需要执行 SQL。

• 需要手动补跑历史数据。

• 需要监控任务执行结果。

• 后续需要增加任务失败告警。

代价和风险

记录当前方案带来的成本和风险。

示例：

• 表数量增加。

• 后端需要做一层统一接口适配。

• 后续跨榜单查询时需要额外聚合。

• 如果没有补数据工具，历史数据修复成本较高。

• 如果文档不维护，后续仍可能不清楚设计原因。

后续重新评估条件

说明未来什么情况下可以推翻或调整这个决策。

示例：

• 榜单类型大量增加。

• 多个榜单字段高度一致。

• 前端强依赖统一榜单模型。

• 数据量增长导致当前表结构查询性能不足。

• 需要建设统一指标宽表或数据仓库层。

• 当前方案维护成本超过收益。

最终结论

用简短文字再次总结决策。

示例：

ETF 资金异动榜不写入 ETF 基础信息表。
初期采用独立的 ETF 份额异动榜表保存数据。
后续成交额榜可以独立建表，接口层可以统一包装给前端。
该方案能保持数据语义清晰，降低不同数据源之间的耦合，并方便后续补数据、重算和扩展。

## 使用建议

Decision 文档不要写成大段技术论文。

最重要的是写清楚：

```text
背景
决策
备选方案
为什么选择当前方案
影响范围
代价和风险
重新评估条件

Decision 文档越早写越好，最好在关键方案确定时就记录，而不是上线很久以后再回忆。