refactor: restructure project to modern Python layout, separate src, tests, docs, examples

2025-08-07 16:57:41 +08:00
commit 4cb6c4eab7
27 changed files with 2580 additions and 0 deletions
--- a/docs/requirements.md
+++ b/docs/requirements.md
@@ -0,0 +1,232 @@
+# Config-Man CLI 工具需求文档
+
+## 1. 项目概述
+
+### 1.1 项目背景
+开发一个Python CLI工具，用于管理存储在对象存储中的加密静态资源配置文件。该工具支持多版本管理，通过Cloudflare CDN进行分发，主要用于游戏应用的配置管理。
+
+### 1.2 项目目标
+- 简化多版本配置文件的查看和管理
+- 支持版本升级策略（建议更新和强制更新）
+- 确保配置文件的加密存储和CDN缓存同步
+- 提供直观的配置对比功能
+
+## 2. 系统架构
+
+### 2.1 存储架构
+```
+对象存储服务器
+├── ab/
+│   ├── 0_29/
+│   │   ├── androidconfig.json (加密)
+│   │   └── iosconfig.json (加密)
+│   ├── 0_30/
+│   │   ├── androidconfig.json (加密)
+│   │   └── iosconfig.json (加密)
+│   └── 1_00/
+│       ├── androidconfig.json (加密)
+│       └── iosconfig.json (加密)
+```
+
+### 2.2 技术栈
+- **开发语言**: Python 3.13+
+- **CLI框架**: Click 或 Typer
+- **存储同步**: rclone
+- **CDN服务**: Cloudflare
+- **文件加密**: AES-256
+- **配置格式**: JSON
+
+## 3. 功能需求
+
+### 3.1 功能1: 查看配置文件
+
+#### 3.1.1 功能描述
+对比显示对象存储和CDN中的配置内容，支持Android和iOS平台。
+
+#### 3.1.2 命令行格式
+```bash
+config-man view --version <版本号>
+```
+
+#### 3.1.3 参数说明
+- `--version`: 版本号，格式为 0.29, 0.30, 0.31 等
+
+#### 3.1.4 功能特性
+- 同时显示Android和iOS平台的配置文件
+- 对比对象存储中的内容和CDN中的内容
+- 使用表格格式漂亮地展示配置差异
+- 支持JSON格式化输出
+
+#### 3.1.5 输出示例
+```
+版本: 0.30
+平台: Android
+┌─────────────────┬─────────────────────┬─────────────────────┐
+│ 配置项          │ 对象存储内容        │ CDN内容             │
+├─────────────────┼─────────────────────┼─────────────────────┤
+│ Ver             │ 0.30.1abc123       │ 0.30.1abc123       │
+│ EventApiURL     │ https://...        │ https://...        │
+│ PlayFabTitle    │ B066F              │ B066F              │
+│ ...             │ ...                 │ ...                 │
+└─────────────────┴─────────────────────┴─────────────────────┘
+
+平台: iOS
+┌─────────────────┬─────────────────────┬─────────────────────┐
+│ 配置项          │ 对象存储内容        │ CDN内容             │
+├─────────────────┼─────────────────────┼─────────────────────┤
+│ Ver             │ 0.30.1def456       │ 0.30.1def456       │
+│ ...             │ ...                 │ ...                 │
+└─────────────────┴─────────────────────┴─────────────────────┘
+```
+
+### 3.2 功能2: 建议更新
+
+#### 3.2.1 功能描述
+在目标版本的配置文件中添加 `Ver_New` 属性，提示用户有新版本可用。
+
+#### 3.2.2 命令行格式
+```bash
+config-man suggest-update --platform <平台> --target-version <目标版本> --update-version <更新版本>
+```
+
+#### 3.2.3 参数说明
+- `--platform`: 平台类型，支持 android 或 ios
+- `--target-version`: 目标版本号，如 0.29
+- `--update-version`: 更新版本号，如 0.30
+
+#### 3.2.4 功能特性
+- 在目标版本配置中添加 `Ver_New` 属性
+- `Ver_New` 的值设为更新版本的 `Ver` 属性值
+- 自动加密并上传到对象存储
+- 自动刷新CDN缓存
+
+#### 3.2.5 配置变更示例
+```json
+// 修改前
+{
+  "Ver": "0.29.1abc123",
+  "EventApiURL": "https://n3backend.azurewebsites.net/",
+  "PlayFabTitle": "B066F"
+}
+
+// 修改后
+{
+  "Ver": "0.29.1abc123",
+  "Ver_New": "0.30.1def456",
+  "EventApiURL": "https://n3backend.azurewebsites.net/",
+  "PlayFabTitle": "B066F"
+}
+```
+
+### 3.3 功能3: 强制更新
+
+#### 3.3.1 功能描述
+直接更新目标版本的 `Ver` 属性，强制用户升级到新版本。
+
+#### 3.3.2 命令行格式
+```bash
+config-man force-update --platform <平台> --target-version <目标版本> --update-version <更新版本>
+```
+
+#### 3.3.3 参数说明
+- `--platform`: 平台类型，支持 android 或 ios
+- `--target-version`: 目标版本号，如 0.29
+- `--update-version`: 更新版本号，如 0.30
+
+#### 3.3.4 功能特性
+- 将目标版本的 `Ver` 属性值改为更新版本的 `Ver` 属性值
+- 自动加密并上传到对象存储
+- 自动刷新CDN缓存
+
+#### 3.3.5 配置变更示例
+```json
+// 修改前
+{
+  "Ver": "0.29.1abc123",
+  "EventApiURL": "https://n3backend.azurewebsites.net/",
+  "PlayFabTitle": "B066F"
+}
+
+// 修改后
+{
+  "Ver": "0.30.1def456",
+  "EventApiURL": "https://n3backend.azurewebsites.net/",
+  "PlayFabTitle": "B066F"
+}
+```
+
+## 4. 配置文件结构
+
+### 4.1 配置项说明
+```json
+{
+  "EventApiURL": "https://n3backend.azurewebsites.net/",
+  "Ver": "0.28.2ece920695",
+  "PlayFabTitle": "B066F",
+  "Google_Play_URL": "https://play.google.com/store/apps/details?id=com.arkgame.ft",
+  "APP_Store_URL": "https://apps.apple.com/us/app/id6505145935",
+  "HeartBeat": "60",
+  "RTMPid": "80000586",
+  "RTMServerEndpoint": "rtm-intl-frontgate.ilivedata.com:13321",
+  "RTMHmacSecret": "57047697437f4f2c97a835e8d9a53358",
+  "FuncUrl": "https://leaderboardcreate.azurewebsites.net",
+  "FuncKey": "R5kU45fNBRd52Eqp3tEqfpZqrbFw53uSSEo7wraUSqIfAzFuRmLm_w=="
+}
+```
+
+### 4.2 配置项分类
+- **API端点**: EventApiURL, FuncUrl
+- **版本信息**: Ver, Ver_New
+- **应用商店链接**: Google_Play_URL, APP_Store_URL
+- **实时通信**: RTMPid, RTMServerEndpoint, RTMHmacSecret
+- **功能配置**: PlayFabTitle, HeartBeat, FuncKey
+
+## 5. 技术要求
+
+### 5.1 安全要求
+- 配置文件在对象存储中加密存储
+- 支持AES-256加密算法
+- 加密密钥安全管理
+- 操作日志记录
+
+### 5.2 性能要求
+- 配置文件查看响应时间 < 3秒
+- 配置文件修改响应时间 < 5秒
+- CDN缓存刷新响应时间 < 10秒
+
+### 5.3 兼容性要求
+- 支持Python 3.13+
+- 支持Windows、macOS、Linux
+- 支持rclone命令行工具
+
+## 6. 错误处理
+
+### 6.1 常见错误场景
+- 版本号不存在
+- 平台类型错误
+- 网络连接失败
+- 文件加密/解密失败
+- CDN刷新失败
+
+### 6.2 错误处理策略
+- 提供清晰的错误信息
+- 支持重试机制
+- 记录详细的操作日志
+- 提供回滚功能
+
+## 7. 非功能性需求
+
+### 7.1 可用性
+- 提供清晰的命令行帮助信息
+- 支持命令自动补全
+- 提供详细的错误提示
+
+### 7.2 可维护性
+- 模块化设计
+- 完善的日志记录
+- 清晰的代码注释
+
+### 7.3 可扩展性
+- 支持新的配置文件格式
+- 支持新的存储后端
+- 支持新的CDN服务商