变更日志维护
概览
创建并维护结构化的变更日志，记录项目的所有重大变更，遵循行业最佳实践，如Keep a Changelog和语义化版本控制。
何时使用
- 版本历史文档
- 发布说明生成
- 重大变更跟踪
- 迁移指南创建
- 弃用通知
- 安全补丁文档
- 功能公告
- 错误修复跟踪
CHANGELOG.md 模板
# 变更日志
本项目的所有重大变更都将记录在此文件中。
格式基于[Keep a Changelog](https://keepachangelog.com/en/1.0.0/)，
并且本项目遵循[语义化版本控制](https://semver.org/spec/v2.0.0.html)。
## [未发布]
### 新增
- 新增功能或能力
- 可以有多个项目
### 变更
- 现有功能的变更
- 功能工作方式的更新
### 弃用
- 将在即将发布的版本中移除的功能
- 包括移除的时间表
### 移除
- 已移除的功能
- 之前弃用的功能
### 修复
- 错误修复
- 安全补丁
### 安全
- 已修复的安全漏洞
- 重要的安全更新
## [2.1.0] - 2025-01-15
### 新增
- 为GitHub和Google添加了OAuth2认证支持
- 新的仪表板小部件系统，用于可定制的布局
- 批量操作API，用于处理多个记录
- 支持自定义模板的Excel导出功能
- 所有页面支持暗色模式主题
- 支持实时通知的WebSocket
- 与现有REST端点一起的GraphQL API
- 支持10种新语言的国际化
- 西班牙语、法语、德语、意大利语、葡萄牙语
- 日语、韩语、中文（简体/繁体）、阿拉伯语
### 变更
- 更新了带有改进布局和性能的个人资料页面
- 从REST迁移到GraphQL作为主要API端点
- 改进了错误消息，提供更多上下文和建议
- 重构认证系统以提高安全性
- 更新到最新版本的依赖
- React 18.2.0 → 19.0.0
- Node.js 16.x → 18.x（最低所需版本）
- PostgreSQL 13 → 14
- 将默认分页从20更改为50个项目
- 改进了搜索算法，结果速度提高3倍
### 弃用
- REST API v1端点（将在v3.0.0中移除）
- 使用GraphQL API或REST API v2代替
- 迁移指南：[docs/migration-v1-to-v2.md](docs/migration-v1-to-v2.md)
- 旧的认证令牌（将在2025-06-01之前移除）
- 替换为JWT令牌
- `config.json`中的旧配置格式
- 使用`config.yaml`中的新YAML格式
### 移除
- 移除了弃用的`/api/users/list`端点
- 使用`/api/v2/users`代替
- 移除了对Internet Explorer 11的支持
- 最低浏览器版本：Chrome 90+、Firefox 88+、Safari 14+、Edge 90+
- 移除了jQuery依赖（现在使用纯JavaScript）
- 移除了旧的仪表板小部件（被新的小部件系统替换）
### 修复
- 修复了导致重复收费的订单处理中的竞态条件
- 受影响版本：2.0.0 - 2.0.5
- 问题：[#1234](https://github.com/user/repo/issues/1234)
- 修复了WebSocket连接中的内存泄漏
- 修复了日期选择器中不正确的时区处理
- 修复了CSV导出不包括所有列的问题
- 修复了表单提交中的CSRF漏洞（CVE-2025-12345）
- 修复了导航菜单中的可访问性问题
- 现在完全可通过键盘导航
- 屏幕阅读器友好
- 修复了iPad Pro上的移动响应问题
- 修复了搜索中的SQL注入漏洞（CVE-2025-12346）
- **安全影响**：高
- **受影响版本**：2.0.0 - 2.0.9
- **推荐操作**：立即升级
### 安全
- **CRITICAL**: 修复了用户搜索中的SQL注入（CVE-2025-12346）
- 影响：允许未经授权的数据库访问
- 受影响：v2.0.0到v2.0.9
- 操作：立即升级到v2.1.0
- 修复了评论渲染中的XSS漏洞（CVE-2025-12347）
- 更新了所有已知安全漏洞的依赖
- 在所有API端点上实施了速率限制
- 为所有表单添加了CSRF保护
- 启用了内容安全策略头
## [2.0.5] - 2025-01-08
### 修复
- 热修复：导致导出功能数据丢失的关键错误
- 修复了LDAP集成中的认证问题
- 解决了大数据集的性能下降问题
### 安全
- 修补了认证绕过漏洞（CVE-2025-12344）
## [2.0.0] - 2025-01-01
### 新增
- 完整的UI重新设计，现代外观和感觉
- 新的REST API v2，性能更好
- 用户角色和权限系统
- 所有管理操作的审计日志
- 电子邮件模板定制
- 双因素认证（2FA）
- API速率限制
- 数据库备份自动化
### 变更
- **BREAKING**: 从XML更改为JSON的API响应格式
- 所有API消费者必须更新他们的集成
- 查看迁移指南：[docs/api-v1-to-v2.md](docs/api-v1-to-v2.md)
- **BREAKING**: 重命名数据库表以保持一致性
- `user` → `users`
- `order` → `orders`
- 运行迁移脚本：`npm run migrate:v2`
- **BREAKING**: 从基于会话的认证更改为JWT
- 现有的会话将被使无效
- 用户需要重新登录
- 改进了数据库查询性能，提高了50%
- 更新了Node.js的最低版本到16.x
### 移除
- **BREAKING**: 移除了对Node.js 12和14的支持
- **BREAKING**: 移除了弃用的配置选项
- `USE_OLD_AUTH` - 使用JWT认证
- `LEGACY_MODE` - 不再支持
### 迁移指南
**从v1.x到v2.0：**
1. 更新Node.js到16或更高版本
2. 更新您的API集成：
```javascript
// 旧版（v1）
fetch('/api/users/list')
.then(res => res.text())
.then(xml => parseXML(xml));
// 新版（v2）
fetch('/api/v2/users')
.then(res => res.json())
.then(data => console.log(data));
- 运行数据库迁移：
npm run migrate:v2 - 更新环境变量：
# 移除 USE_OLD_AUTH=true LEGACY_MODE=true # 添加 JWT_SECRET=your-secret-key JWT_EXPIRES_IN=7d
1.5.2 - 2024-12-15
修复
- 修复了用户列表页面的分页错误
- 解决了报告中的时区问题
- 修复了电子邮件通知延迟
1.5.0 - 2024-12-01
新增
- 新的报告仪表板
- 用户配置文件的自定义字段
- 集成的Webhook支持
变更
- 改进了搜索性能
- 更新了UI组件库
1.0.0 - 2024-10-01
新增
- 初始发布
- 用户管理
- 基本API
- 认证和授权
- 数据库迁移
- 单元和集成测试
## 发布说明模板
```markdown
# 发布说明 - 版本 2.1.0
**发布日期：** 2025年1月15日
**下载：** [v2.1.0](https://github.com/user/repo/releases/tag/v2.1.0)
## 🎉 亮点
- **OAuth2认证**：使用GitHub和Google登录
- **GraphQL API**：新的GraphQL端点与REST API一起
- **暗色模式**：所有页面支持完整的暗色模式
- **实时通知**：WebSocket驱动的实时更新
- **10种新语言**：扩展的国际化支持
## 📦 新增内容
### OAuth2认证
您现在可以使用GitHub或Google账户登录。在设置>认证中配置OAuth。
```javascript
// 在您的配置中启用OAuth
{
"auth": {
"providers": ["github", "google"],
"github": {
"clientId": "your-client-id",
"clientSecret": "your-client-secret"
}
}
}
GraphQL API
使用GraphQL访问您的数据，进行更有效的查询：
query GetUser {
user(id: "123") {
id
name
email
orders {
id
total
items {
product {
name
price
}
}
}
}
}
端点： https://api.example.com/graphql
文档： GraphQL API文档
暗色模式
在设置>外观中启用暗色模式，或使用系统首选项。
🔧 改进
- 3倍更快的搜索：改进的搜索算法
- 更好的错误消息：更有帮助的错误消息和建议
- 增强的性能：页面加载速度提高50%
- 移动改进：更好的平板电脑响应设计
🐛 错误修复
- 修复了订单处理中的竞态条件
- 修复了WebSocket连接中的内存泄漏
- 修复了日期选择器中的时区处理
- 修复了导航中的可访问性问题
🔒 安全更新
- CRITICAL: 修复了SQL注入漏洞（CVE-2025-12346）
- 影响：高 - 允许未经授权的数据库访问
- 操作：如果您使用的是v2.0.0 - v2.0.9，请立即升级
- 修复了评论渲染中的XSS漏洞（CVE-2025-12347）
- 更新了带有安全补丁的依赖
📋 重大变更
弃用的API（在v3.0.0中移除）
以下REST API v1端点已被弃用，将在v3.0.0中移除：
| 旧端点 | 新端点 | 迁移指南 |
|---|---|---|
/api/users/list |
/api/v2/users |
链接 |
/api/products/search |
/api/v2/products?q= |
链接 |
时间表：这些端点将继续工作，直到2025年6月。
更新的依赖
- Node.js：最低版本现在是18.x（之前是16.x）
- React：升级到19.0.0
- PostgreSQL：最低版本现在是14（之前是13）
📖 文档
🔄 升级
从v2.0.x
# 首先备份您的数据库
pg_dump your_database > backup.sql
# 拉取最新版本
git pull origin main
# 安装依赖
npm install
# 运行迁移
npm run migrate
# 重新启动应用程序
npm start
从v1.x
请参阅v1到v2迁移指南以获取详细的升级说明。
🙏 贡献者
感谢所有使此版本成为可能的贡献者：
- @contributor1 - OAuth2实现
- @contributor2 - GraphQL API
- @contributor3 - 暗色模式
- @contributor4 - 性能改进
📞 支持
- 问题：GitHub问题
- 讨论：GitHub讨论
- 文档：docs.example.com
- 电子邮件：support@example.com
🔜 接下来是什么？
v2.2.0中即将推出：
- 高级分析仪表板
- 插件系统以扩展性
- 移动应用（iOS和Android）
- 改进的团队协作功能
敬请期待！
## 语义化版本控制指南
版本：MAJOR.MINOR.PATCH
MAJOR版本：不兼容的API变更 MINOR版本：添加功能（向后兼容） PATCH版本：向后兼容的错误修复
示例：
- 1.0.0 → 1.0.1：错误修复
- 1.0.1 → 1.1.0：新功能（向后兼容）
- 1.1.0 → 2.0.0：重大变更
## 最佳实践
### ✅ 执行
- 遵循Keep a Changelog格式
- 使用语义化版本控制
- 突出记录重大变更
- 包括迁移指南
- 链接到相关的问题/PR
- 分类变更（新增、变更、修复等）
- 在单独的部分中包括安全修复
- 所有发布都包括日期（YYYY-MM-DD格式）
- 链接到发布标签
- 记录弃用和时间表
- 包括升级说明
- 提及贡献者
### ❌ 不要
- 跳过记录重大变更
- 发布前忘记更新变更日志
- 在一个类别中混合多种类型
- 使用模糊的描述
- 省略发布日期
- 忘记语义化版本控制
- 隐藏安全问题
## 资源
- [Keep a Changelog](https://keepachangelog.com/)
- [Semantic Versioning](https://semver.org/)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Release Drafter](https://github.com/release-drafter/release-drafter)