# 天猫卡密工作区管理

<cite>
**本文档引用文件**  
- [workspace.go](file://api/card_info_t_mall_game/v1/workspace.go)
- [sync.go](file://api/card_info_t_mall_game/v1/sync.go)
- [card_info_t_mall_game_v1_t_mall_game_data_sync.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_data_sync.go)
- [card_info_t_mall_game_v1_t_mall_game_daily_order_summary.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_daily_order_summary.go)
- [card_info_t_mall_game_v1_t_mall_game_stats.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_stats.go)
- [card_t_mall_game_work_space.go](file://internal/model/card_t_mall_game_work_space.go)
</cite>

## 目录
1. [简介](#简介)
2. [工作区管理API概览](#工作区管理api概览)
3. [数据同步接口](#数据同步接口)
4. [状态监控接口](#状态监控接口)
5. [配置管理接口](#配置管理接口)
6. [架构设计与数据隔离](#架构设计与数据隔离)
7. [错误处理与安全考虑](#错误处理与安全考虑)
8. [管理端实现指南](#管理端实现指南)
9. [性能优化建议](#性能优化建议)
10. [实际使用示例](#实际使用示例)

## 简介
本文档详细介绍了天猫卡密工作区管理系统的API接口，涵盖数据同步、配置管理、状态监控等核心功能。系统通过RESTful API提供工作区创建、数据同步、状态查询等端点，支持大规模卡密订单的高效处理与监控。文档详细说明了各接口的HTTP方法、URL模式、请求/响应模式和认证机制，并提供实际使用场景示例。

## 工作区管理API概览
天猫卡密工作区管理API提供了一套完整的接口，用于管理工作区的生命周期、数据同步和状态监控。API基于GoFrame框架构建，采用模块化设计，主要功能包括工作区数据同步、订单统计、状态查询等。

```mermaid
graph TB
subgraph "API接口层"
A[数据同步接口]
B[状态监控接口]
C[配置管理接口]
end
subgraph "服务层"
D[订单服务]
E[账户服务]
F[店铺服务]
end
subgraph "数据层"
G[订单数据]
H[账户数据]
I[店铺数据]
J[历史数据]
end
A --> D
B --> D
C --> D
D --> G
D --> H
D --> I
D --> J
```

**图示来源**  
- [card_info_t_mall_game_v1_t_mall_game_data_sync.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_data_sync.go)
- [card_info_t_mall_game_v1_t_mall_game_daily_order_summary.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_daily_order_summary.go)

## 数据同步接口
数据同步接口用于实时同步天猫卡密工作区的订单、账户、店铺等数据，确保系统数据的及时性和一致性。

### 数据同步端点
- **URL**: `/recharge/tMallGame/data/sync`
- **HTTP方法**: POST
- **功能**: 同步指定渠道在指定时间范围内的所有相关数据

#### 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| channelName | string | 是 | 渠道名称 |
| duration | int | 是 | 同步时长（秒） |

#### 响应数据结构
同步接口返回包含以下数据集合的响应：
- 订单数据（OrderData）
- 账户数据（AccountData）
- 店铺数据（ShopData）
- 订单历史数据（OrderHistory）
- 店铺历史数据（ShopHistory）

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API网关"
participant Controller as "控制器"
participant DAO as "数据访问层"
Client->>API : POST /recharge/tMallGame/data/sync
API->>Controller : 转发请求
Controller->>DAO : 查询订单数据
DAO-->>Controller : 返回订单数据
Controller->>DAO : 查询关联账户数据
DAO-->>Controller : 返回账户数据
Controller->>DAO : 查询关联店铺数据
DAO-->>Controller : 返回店铺数据
Controller->>DAO : 查询订单历史数据
DAO-->>Controller : 返回订单历史数据
Controller->>DAO : 查询店铺历史数据
DAO-->>Controller : 返回店铺历史数据
Controller-->>API : 组装完整响应
API-->>Client : 返回同步数据
```

**图示来源**  
- [sync.go](file://api/card_info_t_mall_game/v1/sync.go)
- [card_info_t_mall_game_v1_t_mall_game_data_sync.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_data_sync.go)

**本节来源**  
- [sync.go](file://api/card_info_t_mall_game/v1/sync.go)
- [card_info_t_mall_game_v1_t_mall_game_data_sync.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_data_sync.go)

## 状态监控接口
状态监控接口提供工作区的实时状态和统计信息，支持运营监控和数据分析。

### 每日订单统计接口
- **URL**: `/recharge/tMallGame/workspace/orderSummary`
- **HTTP方法**: GET
- **功能**: 获取每日订单统计信息

#### 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| channelName | string | 否 | 渠道名称 |
| callbackType | RechargeTMallGameCallBackType | 否 | 回调类型 |

#### 响应数据结构
```json
{
  "total": 100,
  "list": [
    {
      "count": 20,
      "succeedCount": 18,
      "succeedAmount": 1800.00,
      "amount": 2000.00,
      "rate": 0.9,
      "date": "2024-01-01"
    }
  ]
}
```

### 基本统计信息接口
- **URL**: `/recharge/tMallGame/workspace/stats`
- **HTTP方法**: GET
- **功能**: 获取工作区基本统计信息

#### 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| channelName | string | 是 | 渠道名称 |

#### 响应数据结构
```json
{
  "totalCount": 1000,
  "totalSucceedCount": 950,
  "totalAmount": 95000.00,
  "totalSucceedAmount": 90250.00,
  "todayCount": 50,
  "todaySucceedCount": 48,
  "todayAmount": 4800.00,
  "todaySucceedAmount": 4560.00,
  "totalRate": 0.95,
  "todayRate": 0.96
}
```

```mermaid
flowchart TD
Start([获取状态监控数据]) --> ValidateInput["验证输入参数"]
ValidateInput --> InputValid{"参数有效?"}
InputValid --> |否| ReturnError["返回参数错误"]
InputValid --> |是| QueryStats["查询统计信息"]
QueryStats --> StatsResult{"查询成功?"}
StatsResult --> |否| HandleError["处理查询错误"]
StatsResult --> |是| FormatResponse["格式化响应数据"]
FormatResponse --> ReturnResult["返回统计结果"]
HandleError --> ReturnError
ReturnError --> End([结束])
ReturnResult --> End
```

**图示来源**  
- [workspace.go](file://api/card_info_t_mall_game/v1/workspace.go)
- [card_info_t_mall_game_v1_t_mall_game_daily_order_summary.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_daily_order_summary.go)
- [card_info_t_mall_game_v1_t_mall_game_stats.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_stats.go)

**本节来源**  
- [workspace.go](file://api/card_info_t_mall_game/v1/workspace.go)
- [card_info_t_mall_game_v1_t_mall_game_daily_order_summary.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_daily_order_summary.go)
- [card_info_t_mall_game_v1_t_mall_game_stats.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_stats.go)

## 配置管理接口
配置管理接口用于管理工作区的运行参数和业务配置，确保系统能够适应不同的业务需求。

### 配置获取接口
- **URL**: `/recharge/tMallGame/account/authorize/getKey`
- **HTTP方法**: GET
- **功能**: 获取天猫游戏配置信息

#### 响应数据结构
```json
{
  "code": "appKey",
  "redirectUri": "https://callback.example.com"
}
```

### 账户状态切换接口
- **URL**: `/recharge/tMallGame/account/toggle`
- **HTTP方法**: POST
- **功能**: 切换账户状态（启用/禁用）

#### 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | string | 是 | 账户ID |
| status | int | 是 | 状态（1:启用, 0:禁用） |

**本节来源**  
- [card_info_t_mall_game_v1_t_mall_game_account_authorize_get_key.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_authorize_get_key.go)
- [card_info_t_mall_game_v1_t_mall_game_account_toggle.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_toggle.go)

## 架构设计与数据隔离
天猫卡密工作区管理系统采用分层架构设计，确保系统的可维护性和可扩展性。

### 分层架构
系统采用典型的三层架构：
1. **API接口层**: 提供RESTful API接口
2. **服务层**: 实现业务逻辑处理
3. **数据层**: 负责数据持久化和访问

### 数据隔离机制
系统通过以下机制实现数据隔离：
- **渠道隔离**: 不同渠道的数据通过channelName字段进行隔离
- **时间范围隔离**: 数据同步通过时间戳范围进行隔离
- **关联查询隔离**: 通过外键关联确保数据一致性

```mermaid
erDiagram
ORDER {
string order_no PK
string account_id FK
string channel_name
float amount
int status
datetime created_at
datetime updated_at
}
ACCOUNT {
string id PK
string account_number UK
string channel_name
int status
datetime created_at
datetime updated_at
}
SHOP {
string order_no PK, FK
string t_mall_order_no
datetime end_time
datetime created_at
datetime updated_at
}
ORDER_HISTORY {
int id PK
string order_no FK
int status
datetime created_at
datetime updated_at
}
SHOP_HISTORY {
int id PK
int shop_id FK
string status
datetime created_at
datetime updated_at
}
ORDER ||--o{ ACCOUNT : "belongs to"
ORDER ||--o{ SHOP : "has"
ORDER ||--o{ ORDER_HISTORY : "has"
ORDER_HISTORY ||--o{ SHOP_HISTORY : "has"
```

**图示来源**  
- [card_info_t_mall_game_v1_t_mall_game_data_sync.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_data_sync.go)
- [card_t_mall_game_work_space.go](file://internal/model/card_t_mall_game_work_space.go)

## 错误处理与安全考虑
系统实现了完善的错误处理和安全机制，确保系统的稳定性和安全性。

### 错误处理策略
- **统一错误包装**: 使用errHandler.WrapError统一包装错误
- **错误码体系**: 基于gcode.Code体系定义错误码
- **日志记录**: 关键操作和错误信息记录到日志

### 安全考虑
- **参数验证**: 所有输入参数进行严格验证
- **缓存保护**: 使用gmlock确保缓存操作的线程安全
- **敏感信息保护**: 关键配置信息从配置中心获取

**本节来源**  
- [card_info_t_mall_game_v1_t_mall_game_data_sync.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_data_sync.go)
- [card_info_t_mall_game_v1_t_mall_game_account_get_one_random.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_get_one_random.go)

## 管理端实现指南
管理端实现应遵循以下指南，确保系统的稳定性和性能。

### 实现要点
1. **异步处理**: 大规模数据同步采用异步处理模式
2. **批量操作**: 尽量使用批量查询和更新操作
3. **缓存策略**: 合理使用缓存减少数据库压力
4. **锁机制**: 使用gmlock确保关键操作的线程安全

### 最佳实践
- **分页查询**: 大数据量查询使用分页
- **连接池**: 使用数据库连接池提高性能
- **监控告警**: 关键接口添加监控和告警

**本节来源**  
- [card_info_t_mall_game_v1_t_mall_game_data_sync.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_data_sync.go)
- [card_info_t_mall_game_v1_t_mall_game_account_get_one_random.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_get_one_random.go)

## 性能优化建议
针对大规模数据同步场景，提出以下性能优化建议。

### 查询优化
- **索引优化**: 在channelName、updatedAt等常用查询字段上建立索引
- **批量查询**: 使用WhereIn一次性查询关联数据
- **时间范围查询**: 使用时间戳范围限制查询数据量

### 缓存优化
- **热点数据缓存**: 将频繁访问的数据缓存到Redis
- **缓存预热**: 在高峰期前预热常用数据
- **缓存失效策略**: 设置合理的缓存失效时间

### 并发优化
- **并发控制**: 根据系统负载调整并发度
- **连接池配置**: 优化数据库连接池大小
- **资源监控**: 实时监控系统资源使用情况

**本节来源**  
- [card_info_t_mall_game_v1_t_mall_game_data_sync.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_data_sync.go)

## 实际使用示例
以下是天猫卡密工作区管理API的实际使用示例。

### 工作区数据同步示例
```bash
curl -X POST \
  http://api.example.com/recharge/tMallGame/data/sync \
  -H 'Content-Type: application/json' \
  -d '{
    "channelName": "channel_001",
    "duration": 300
  }'
```

### 状态监控查询示例
```bash
curl -X GET \
  "http://api.example.com/recharge/tMallGame/workspace/stats?channelName=channel_001" \
  -H 'Content-Type: application/json'
```

### 配置更新示例
```bash
curl -X POST \
  http://api.example.com/recharge/tMallGame/account/toggle \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "account_001",
    "status": 1
  }'
```

**本节来源**  
- [sync.go](file://api/card_info_t_mall_game/v1/sync.go)
- [workspace.go](file://api/card_info_t_mall_game/v1/workspace.go)
- [card_info_t_mall_game_v1_t_mall_game_account_toggle.go](file://internal/controller/card_info_t_mall_game/card_info_t_mall_game_v1_t_mall_game_account_toggle.go)