# 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服务商