release-note-db-migration

name	release-note-db-migration
description	为 Best-AI-Trader 生成或审阅 release note。适用于用户要求写发布说明、版本说明、升级说明或回滚说明；默认范围是上次 release 到当前 main，尤其关注数据库字段变更。仅数据库表字段变更需要输出“数据库迁移的升级和回滚”章节；删除表只给 DROP，新建表无需单独说明。

Release Note 生成

目标

生成面向发布人员的 release note，重点写清楚本次发布改了什么、影响什么、如何升级、如何回滚、如何验证。只有存在数据库表字段变更时才输出数据库迁移章节，不展开实现细节。

输出结构

最终输出必须是完整 Markdown 文档，可直接复制为 release note；除非需要在正文之外提醒发布人员确认范围，否则不要在 Markdown 正文前后追加解释性文字。

默认使用这个结构；如果没有数据库表字段变更，省略 ## 数据库迁移的升级和回滚 章节：

# Release Note

## 变更摘要

## 变更范围

## 影响范围

## 数据库迁移的升级和回滚

## 升级步骤

## 回滚步骤

## 验证清单

写作规则

• 标题必须固定为 # Release Note；不要在标题后追加版本号、提交范围、冒号或其他说明。
• 变更摘要：用 3-6 条 bullet 概括用户可感知或运维需要关注的变化。
• 变更范围：写清楚本次 release note 覆盖从上次 release 到当前 main 的变更；如果上次 release 标签不明确，正文只标成 <LAST_RELEASE> 占位符。
• 影响范围：写受影响的后端服务、前端页面、异步任务、数据源、配置或部署组件。
• 数据库迁移的升级和回滚：仅在存在数据库表字段变更时输出；只写简短摘要和两行命令，不解释字段设计细节。删除表只需要给 DROP TABLE，新建表不需要单独说明，会随应用自动创建。
• 升级步骤：简短写应用升级命令；如果存在数据库表字段变更，先写执行数据库升级命令，再写应用升级命令。
• 回滚步骤：简短写先手动把镜像版本改回目标版本，再执行应用升级命令；如果存在数据库表字段变更，先写执行数据库回滚命令。
• 验证清单：列出 3-6 条发布后检查项。

范围判断

默认按上次 release 到当前 main 生成 release note。生成前必须先拉取远端最新 tag/release（例如执行 git fetch --tags），再优先使用拉取后可见的最新 release tag、版本 tag 或用户指定的上次 release 点作为比对基线；如果能够确定上次 release tag，直接在正文写范围，不要额外写“请确认上一个 release tag”之类的提醒。如果无法确定，不要猜测，正文使用 <LAST_RELEASE>..main 占位；需要提醒发布人员确认时，把提醒放在 release note 正文之外。

数据库迁移章节

只有存在数据库表字段变更时才输出 ## 数据库迁移的升级和回滚 章节。没有字段变更时，不输出该章节，也不要写“字段变更：无”。

表级变更规则：

• 删除表：如需迁移说明，只给 DROP TABLE ...;，不要展开字段说明。
• 新建表：不需要单独说明数据库迁移，应用会自动创建。

## 数据库迁移的升级和回滚 章节保持简短：

## 数据库迁移的升级和回滚

- 字段变更：<一句话概括>
- 升级命令：
```bash
docker compose exec -T postgres psql -U <DB_USER> -d <DB_NAME> -c "<UPGRADE_SQL>"
```
- 回滚命令：
```bash
docker compose exec -T postgres psql -U <DB_USER> -d <DB_NAME> -c "<ROLLBACK_SQL>"
```

约束：

• 两条 Docker 命令使用字符串 SQL：psql -c "<SQL字符串>"。
• 两条 Docker 命令必须分别用三反引号 bash 代码块包裹。
• 不使用 -f SQL 文件路径。
• 不写数据库备份命令。
• 不在数据库章节展开字段类型、nullable、默认值、索引细节或迁移原理，除非用户明确要求。
• 不确定数据库名、用户、SQL 字符串时使用占位符，不编造。

顺序要求

存在数据库表字段变更时，release note 必须表达这两个顺序：

• 升级：先完成数据库升级，再升级应用。
• 回滚：先完成数据库回滚，再回滚应用。

不要把应用容器升级或回滚命令写进数据库章节。升级/回滚步骤默认只写：

docker compose pull
docker compose up -d --force-recreate

回滚步骤必须先说明：手动把镜像版本改回目标回滚版本，再执行上述两条命令。