420 lines
9.3 KiB
Markdown
420 lines
9.3 KiB
Markdown
# 🚀 GUI客户端自动化版本管理系统
|
||
|
||
## 📋 概述
|
||
|
||
**与后端完全一致的版本管理系统** - 直接连接PostgreSQL数据库
|
||
|
||
- ✅ **直接数据库操作** - 与后端使用相同方式（PostgreSQL）
|
||
- ✅ **完全一致** - 相同的表、相同的字段、相同的逻辑
|
||
- ✅ **极简设计** - 无需API，配置一次，永久生效
|
||
- ✅ **全自动** - 提交代码即可，自动版本递增
|
||
|
||
---
|
||
|
||
## 🎯 核心特性
|
||
|
||
### 存储方式（与后端完全一致）
|
||
|
||
```
|
||
后端Django GUI客户端
|
||
↓ ↓
|
||
Django ORM psycopg2
|
||
↓ ↓
|
||
└──────────┬──────────────────┘
|
||
↓
|
||
PostgreSQL
|
||
web_versionhistory表
|
||
```
|
||
|
||
| 特性 | 后端 | GUI |
|
||
|------|------|-----|
|
||
| **操作方式** | Django ORM | psycopg2（SQL） |
|
||
| **数据库** | PostgreSQL (8.155.9.53) | **相同** |
|
||
| **表名** | web_versionhistory | **相同** |
|
||
| **版本类型** | "Web端" | "水滴智能通讯插件" |
|
||
|
||
---
|
||
|
||
## 🚀 快速开始（2步）
|
||
|
||
### 1️⃣ 安装依赖
|
||
|
||
```bash
|
||
pip install psycopg2-binary
|
||
```
|
||
|
||
### 2️⃣ 提交代码
|
||
|
||
```bash
|
||
# 新增功能（MINOR版本）
|
||
git commit -m "[minor] 新增拼多多平台支持"
|
||
|
||
# 修复Bug（PATCH版本）
|
||
git commit -m "[patch] 修复京东连接超时"
|
||
|
||
# 重大变更（MAJOR版本）
|
||
git commit -m "[major] 重构WebSocket架构"
|
||
|
||
# 推送触发自动版本发布
|
||
git push origin main
|
||
```
|
||
|
||
**就这么简单！** 🎉
|
||
|
||
---
|
||
|
||
## 📖 版本号规则
|
||
|
||
采用**语义化版本**（Semantic Versioning）：`MAJOR.MINOR.PATCH`
|
||
|
||
| 版本类型 | 说明 | 示例 |
|
||
|---------|------|------|
|
||
| `MAJOR` | 重大架构变更 | 1.0.0 → 2.0.0 |
|
||
| `MINOR` | 新增功能 | 1.0.0 → 1.1.0 |
|
||
| `PATCH` | Bug修复、优化 | 1.0.0 → 1.0.1 |
|
||
|
||
---
|
||
|
||
## 🔍 Commit Message 关键词
|
||
|
||
### 手动标记（优先级最高）
|
||
|
||
```bash
|
||
git commit -m "[major] 重构WebSocket通信架构"
|
||
git commit -m "[minor] 新增拼多多平台支持"
|
||
git commit -m "[patch] 修复京东连接超时问题"
|
||
```
|
||
|
||
### 自动识别关键词
|
||
|
||
**MAJOR**: `重构`, `refactor`, `架构`, `breaking`
|
||
**MINOR**: `新增`, `add`, `feature`, `功能`, `实现`
|
||
**PATCH**: `修复`, `fix`, `bug`, `优化`, `调整`
|
||
|
||
---
|
||
|
||
## 📁 文件结构
|
||
|
||
```
|
||
shuidrop_gui/
|
||
├── .gitea/
|
||
│ ├── workflows/
|
||
│ │ └── gui-version-release.yml # CI/CD工作流
|
||
│ ├── scripts/
|
||
│ │ ├── gui_version_creator.py # ⭐ 核心：版本创建器（直接数据库）
|
||
│ │ ├── view_version_history.py # 版本历史查看
|
||
│ │ └── init_version_system.py # 系统初始化
|
||
│ └── README.md # 本文档
|
||
├── version_history.json # 版本历史本地备份
|
||
├── config.py # 包含 APP_VERSION
|
||
└── VERSION_MANAGEMENT_GUIDE.md # 快速入门指南
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠️ 常用命令
|
||
|
||
### 查看版本历史
|
||
|
||
```bash
|
||
# 查看最近10个版本
|
||
python .gitea/scripts/view_version_history.py --list
|
||
|
||
# 查看最新版本
|
||
python .gitea/scripts/view_version_history.py --latest
|
||
|
||
# 查看特定版本详情
|
||
python .gitea/scripts/view_version_history.py --detail 1.2.3
|
||
|
||
# 导出更新日志
|
||
python .gitea/scripts/view_version_history.py --export
|
||
```
|
||
|
||
### 本地测试
|
||
|
||
```bash
|
||
# 设置数据库连接
|
||
export DB_HOST=8.155.9.53
|
||
export DB_PORT=5400
|
||
export DB_NAME=ai_web
|
||
export DB_USER=user_emKCAb
|
||
export DB_PASSWORD=password_ee2iQ3
|
||
|
||
# 运行版本创建脚本
|
||
python .gitea/scripts/gui_version_creator.py
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 版本创建流程
|
||
|
||
```
|
||
提交代码
|
||
↓
|
||
git push origin main
|
||
↓
|
||
Gitea Actions触发
|
||
↓
|
||
gui_version_creator.py
|
||
↓
|
||
┌────────────────────────────────┐
|
||
│ 1. 连接PostgreSQL数据库 │
|
||
│ (8.155.9.53:5400/ai_web) │
|
||
│ 2. 查询最新版本 │
|
||
│ SELECT version FROM ... │
|
||
│ 3. 分析commit message │
|
||
│ 识别版本类型 │
|
||
│ 4. 计算新版本号 │
|
||
│ 1.0.5 → 1.1.0 │
|
||
│ 5. 插入数据库 │
|
||
│ INSERT INTO web_versionhistory...│
|
||
│ 6. 保存本地JSON备份 │
|
||
│ 7. 更新config.py │
|
||
│ APP_VERSION = "1.1.0" │
|
||
└────────────────────────────────┘
|
||
↓
|
||
完成！
|
||
```
|
||
|
||
---
|
||
|
||
## 💾 存储策略
|
||
|
||
### 主要存储：PostgreSQL数据库
|
||
|
||
```sql
|
||
-- web_versionhistory表（与后端共用）
|
||
INSERT INTO web_versionhistory (
|
||
version, -- "1.1.0"
|
||
type, -- "水滴智能通讯插件"
|
||
content, -- commit message
|
||
download_url, -- 下载地址
|
||
release_time, -- 发布时间
|
||
is_delete -- FALSE
|
||
) VALUES (...);
|
||
```
|
||
|
||
### 备份存储：本地JSON
|
||
|
||
```json
|
||
// version_history.json（快速查询/离线使用）
|
||
[
|
||
{
|
||
"version": "1.1.0",
|
||
"update_type": "minor",
|
||
"content": "新增拼多多平台支持",
|
||
"author": "张三",
|
||
"release_time": "2025-10-09 14:30:00",
|
||
"stats": {
|
||
"files_changed": 5,
|
||
"lines_added": 234,
|
||
"lines_deleted": 56
|
||
}
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ CI/CD配置
|
||
|
||
### 触发条件
|
||
|
||
- **分支**: `main`
|
||
- **事件**: `push`
|
||
|
||
### 环境变量（已配置好）
|
||
|
||
```yaml
|
||
env:
|
||
DB_HOST: 8.155.9.53 # 数据库主机
|
||
DB_PORT: 5400 # 端口
|
||
DB_NAME: ai_web # 数据库名
|
||
DB_USER: user_emKCAb # 用户名
|
||
DB_PASSWORD: password_ee2iQ3 # 密码
|
||
```
|
||
|
||
**这些配置与后端完全一致！**
|
||
|
||
### 执行步骤
|
||
|
||
1. 📦 检出代码
|
||
2. 🐍 设置Python环境
|
||
3. 📦 安装依赖（psycopg2-binary）
|
||
4. 🏷️ 创建版本记录（直接数据库操作）
|
||
5. 📦 自动打包（可选）
|
||
|
||
---
|
||
|
||
## 📊 版本历史格式
|
||
|
||
### PostgreSQL数据库（主要）
|
||
|
||
```sql
|
||
-- 与后端共享web_versionhistory表
|
||
SELECT * FROM web_versionhistory
|
||
WHERE type = '水滴智能通讯插件'
|
||
ORDER BY release_time DESC;
|
||
```
|
||
|
||
### 本地JSON备份
|
||
|
||
```json
|
||
[
|
||
{
|
||
"version": "1.1.0",
|
||
"update_type": "minor",
|
||
"content": "新增拼多多平台支持",
|
||
"author": "张三",
|
||
"commit_hash": "abc123def456...",
|
||
"release_time": "2025-10-09 14:30:00",
|
||
"stats": {...}
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 常见问题
|
||
|
||
### Q: 为什么不用API？
|
||
|
||
**A**: 直接数据库操作的优势：
|
||
- ✅ 与后端存储方式完全一致
|
||
- ✅ 无需后端开发接口
|
||
- ✅ 更简单、更可靠
|
||
- ✅ 减少中间层故障点
|
||
|
||
### Q: 数据库连接失败怎么办？
|
||
|
||
**A**: 不影响使用！
|
||
- ✅ 本地JSON备份仍会保存
|
||
- ✅ config.py仍会更新
|
||
- ✅ 后续可手动同步数据库
|
||
|
||
### Q: 如何跳过版本发布？
|
||
|
||
**A**: 在commit message中添加 `[skip ci]`：
|
||
```bash
|
||
git commit -m "更新文档 [skip ci]"
|
||
```
|
||
|
||
### Q: 如何验证版本记录？
|
||
|
||
**A**:
|
||
```bash
|
||
# 方式1: 查看本地备份
|
||
python .gitea/scripts/view_version_history.py --latest
|
||
|
||
# 方式2: 查询数据库
|
||
psql -h 8.155.9.53 -p 5400 -U user_emKCAb -d ai_web \
|
||
-c "SELECT * FROM web_versionhistory WHERE type='水滴智能通讯插件' LIMIT 5;"
|
||
```
|
||
|
||
---
|
||
|
||
## 🎓 学习资源
|
||
|
||
### 1. 查看快速入门指南
|
||
|
||
```bash
|
||
cat VERSION_MANAGEMENT_GUIDE.md
|
||
```
|
||
|
||
### 2. 查看实施说明
|
||
|
||
```bash
|
||
cat IMPLEMENTATION_NOTES.md
|
||
```
|
||
|
||
### 3. 初始化系统
|
||
|
||
```bash
|
||
python .gitea/scripts/init_version_system.py
|
||
```
|
||
|
||
---
|
||
|
||
## 📞 完整示例
|
||
|
||
### 场景：新增拼多多平台支持
|
||
|
||
```bash
|
||
# 1. 开发功能
|
||
# 修改: Utils/Pdd/PddUtils.py, config.py 等
|
||
|
||
# 2. 提交代码
|
||
git commit -m "[minor] 新增拼多多平台支持，实现消息收发和自动重连"
|
||
git push origin main
|
||
```
|
||
|
||
**自动执行**：
|
||
1. Gitea Actions检测push
|
||
2. 连接PostgreSQL数据库
|
||
3. 查询最新版本: `1.0.5`
|
||
4. 版本递增: `1.0.5` → `1.1.0`
|
||
5. **插入数据库**: `INSERT INTO web_versionhistory ...`
|
||
6. 保存本地备份: `version_history.json`
|
||
7. 更新配置: `APP_VERSION = "1.1.0"`
|
||
|
||
**验证结果**：
|
||
```bash
|
||
$ python .gitea/scripts/view_version_history.py --latest
|
||
|
||
🏷️ 最新版本: v1.1.0
|
||
📅 发布时间: 2025-10-09 14:30:00
|
||
👤 发布者: 张三
|
||
📝 内容: 新增拼多多平台支持，实现消息收发和自动重连
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 核心优势
|
||
|
||
### 1. 与后端完全一致
|
||
- ✅ 相同的数据库（PostgreSQL）
|
||
- ✅ 相同的表（web_versionhistory）
|
||
- ✅ 相同的字段结构
|
||
- ✅ 相同的时间处理逻辑
|
||
|
||
### 2. 极简设计
|
||
- ✅ 只需安装1个依赖（psycopg2-binary）
|
||
- ✅ 无需后端开发API
|
||
- ✅ 配置一次，永久生效
|
||
|
||
### 3. 全自动
|
||
- ✅ 提交代码自动触发
|
||
- ✅ 自动版本递增
|
||
- ✅ 自动更新配置
|
||
|
||
### 4. 双重保障
|
||
- ✅ PostgreSQL数据库（主要）
|
||
- ✅ 本地JSON备份（保底）
|
||
|
||
---
|
||
|
||
## 🚀 下一步行动
|
||
|
||
```bash
|
||
# 1. 安装依赖（必需）
|
||
pip install psycopg2-binary
|
||
|
||
# 2. 初始化系统（推荐）
|
||
python .gitea/scripts/init_version_system.py
|
||
|
||
# 3. 测试提交
|
||
git commit -m "[patch] 测试版本管理系统"
|
||
git push origin main
|
||
|
||
# 4. 验证结果
|
||
python .gitea/scripts/view_version_history.py --latest
|
||
```
|
||
|
||
---
|
||
|
||
**恭喜！** 🎉 你现在拥有了一套**与后端完全一致**的自动化版本管理系统！
|
||
|
||
**版本**: 3.0（最终版）
|
||
**最后更新**: 2025-10-09
|
||
**核心特点**: 直接PostgreSQL数据库操作，与后端完全一致
|