Feature 功能档案模板

文档定位

Feature 功能档案用于记录一个功能最终在系统中是如何落地的。

它不是产品需求文档，也不是纯技术设计文档。

它重点回答：

这个功能最终做成了什么样？
系统怎么实现？
涉及哪些接口、页面、表、任务？
如何测试和上线？
后续维护时需要注意什么？

Feature 文档的核心价值是：让后续维护者快速理解一个功能的实现全貌，而不是只能从代码里反推。

适用场景

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

• 新增一个较完整的功能

• 新增页面或核心接口

• 新增定时任务

• 新增或修改重要表结构

• 修改核心业务流程

• 引入新的数据来源

• 存在上线步骤、补数据、兼容逻辑

• 功能后续可能继续扩展

以下情况一般不需要单独写 Feature 文档：

• 简单 bug 修复

• 简单文案调整

• 简单样式调整

• 非核心字段调整

• 临时测试代码

• 非业务核心的小重构

文件命名建议

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

docs/features/yyyy-MM-dd-feature-name.md

示例：

docs/features/2026-06-11-etf-fund-flow-rank.md
docs/features/2026-06-10-finance-calendar.md
docs/features/2026-06-05-etf-same-index-compare.md

如果放在 MinDoc 中，可以按业务模块归类：

项目档案 / ETF系统 / 功能历史 / ETF 资金异动榜

模板

# 功能名称

## 状态

开发中 / 已完成 / 已废弃 / 已替换

## 关联信息

- PRD：
- 原型：
- 需求负责人：
- 开发负责人：
- 测试负责人：
- 分支：
- 上线版本：
- 上线时间：

## 背景

说明为什么要做这个功能。

可以包括：

- 原来系统有什么问题
- 用户或业务有什么诉求
- 当前流程有什么不足
- 为什么现在需要做

## 目标

说明这个功能要解决什么问题。

示例：

1. 支持用户查看 xxx。
2. 支持后台配置 xxx。
3. 支持按日期查询 xxx。
4. 支持后续扩展 xxx。

## 非目标

说明这个功能本阶段明确不做什么。

示例：

1. 本阶段不做实时统计。
2. 本阶段不支持导出。
3. 本阶段不改造历史数据。
4. 本阶段不支持多租户配置。

非目标很重要，可以避免后续误以为“为什么没做”。

## 功能说明

从系统最终实现角度描述这个功能。

可以包括：

- 用户如何进入这个功能
- 页面展示什么
- 用户可以执行哪些操作
- 后端如何提供数据
- 数据如何生成
- 是否有任务、消息、缓存、第三方接口

## 业务规则

记录对实现有影响的业务规则。

示例：

- 默认展示最近一个有数据的交易日。
- 非交易日可能没有数据。
- 状态为已审核的数据不允许再次修改。
- 任务重复执行时应覆盖更新，不应重复插入。

## 与需求文档的差异

| 项目 | PRD 原始要求 | 最终实现 | 原因 |
|---|---|---|---|
| 默认日期 | 默认当天 | 默认最近一个有数据的日期 | 非交易日当天可能无数据 |
| 数据口径 | 真实资金流入 | 初期使用份额变化近似表示 | 暂无真实资金净流入数据 |

如果最终实现和 PRD 完全一致，可以写：

```text
暂无差异。

前端改动

新增页面

修改页面

主要交互

说明前端关键交互：

• 页面初始化逻辑

• 查询条件

• 表格字段

• 按钮操作

• 弹窗逻辑

• 空数据展示

• 异常提示

后端改动

新增接口

修改接口

核心类

数据库设计

说明：本文档中的字段只描述业务含义，不作为最终 DDL 定义。实际表结构以数据库 migration 脚本、实体类、Mapper 和线上数据库为准。

相关表

核心字段

关键约束

• xxx 字段不能重复。

• 同一业务编号只允许一条有效记录。

• 任务重复执行时不能重复插入。

• 已完成状态不允许回退。

表结构来源

真实表结构以数据库脚本为准。

示例：

src/main/resources/db/migration/
docs/sql/

数据来源

说明数据来自哪里：

• 用户录入

• 定时任务抓取

• 第三方接口

• 其他业务表

• 文件导入

• 消息队列

示例：

核心流程

可以用文字说明，也可以用简单列表。

示例：

1. 定时任务抓取原始数据。
2. 系统读取最近交易日数据。
3. 系统查询历史交易日数据。
4. 计算变化值。
5. 生成榜单记录。
6. 前端查询榜单数据。

计算逻辑

如果功能涉及计算，需要写清楚核心公式和边界情况。

示例：

share_change_1d = current_trade_date_share - previous_trade_date_share

边界情况：

• 历史数据为空时，变化值为空。

• 分母为 0 时，变化比例为空。

• 非交易日不生成榜单。

定时任务

如果有定时任务，记录：

需要说明：

• 什么时候执行

• 是否支持重复执行

• 是否支持补跑

• 失败后如何处理

• 是否需要告警

缓存设计

如果有缓存，记录：

• 缓存 key

• 缓存内容

• 过期时间

• 什么时候刷新

• 什么时候删除

如果没有缓存，可以写：

本功能暂不使用缓存。

权限设计

如果涉及权限，记录：

• 哪些角色可以访问

• 哪些角色可以操作

• 是否需要数据权限

• 是否需要菜单权限

• 是否需要按钮权限

如果没有特殊权限，可以写：

沿用系统现有权限模型，无特殊权限设计。

上线步骤

示例：

1. 执行数据库脚本。
2. 发布后端服务。
3. 发布前端页面。
4. 执行一次初始化任务。
5. 检查数据是否生成。
6. 检查页面是否正常展示。
7. 检查日志是否有异常。

回滚方案

说明如果上线失败如何回滚。

示例：

• 回滚前端版本。

• 回滚后端版本。

• 新增表可以保留。

• 新增字段不影响旧逻辑。

• 如果已生成错误数据，需要执行清理脚本。

测试点

正常场景

• 能正常查询数据。

• 能正常新增数据。

• 能正常修改数据。

• 能正常展示页面。

边界场景

• 空数据。

• 重复提交。

• 非交易日。

• 历史数据缺失。

• 分页最后一页。

• 异常状态。

异常场景

• 第三方接口失败。

• 数据源为空。

• 参数非法。

• 权限不足。

• 任务重复执行。

风险点

记录后续维护时需要注意的问题。

示例：

• 数据源不稳定可能导致榜单缺失。

• 历史数据缺失会影响计算结果。

• 任务重复执行必须保证幂等。

• 文档字段说明和实际表结构不一致时，以数据库脚本和代码为准。

后续计划

记录本阶段未做但后续可能扩展的内容。

示例：

1. 增加导出功能。

2. 增加趋势图。

3. 增加补数据功能。

4. 增加任务失败告警。

5. 增加更多查询条件。
   

   javascripttypescripthtmlcssshellpythongolangjavacc++c#phprubyswiftkotlinscalarustdartelixirhaskellluaperlrsql

   
   ## 使用建议
   
   Feature 文档不追求事无巨细，重点是留下后续维护需要的上下文。
   
   最重要的是写清楚：
   
   ```text
   背景
   目标
   最终实现
   核心规则
   影响范围
   上线步骤
   测试点
   风险点
   后续计划