# 🚀 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数据库操作，与后端完全一致
