# 君鸿卡管系统

## 系统简介

物联网卡 + 号卡全生命周期管理平台，支持代理商体系和分佣结算。

**技术栈**：Fiber + GORM + Viper + Zap + Lumberjack.v2 + Validator + sonic JSON + Asynq + PostgreSQL

**核心功能**：
- 物联网卡/号卡生命周期管理（开卡、激活、停机、复机、销户）
- 代理商层级管理和分佣结算
- 批量状态同步（卡状态、实名状态、流量使用情况）
- 与外部 Gateway 服务通过 RESTful API 交互

---

## 项目结构

```
junhong_cmp_fiber/
│
├── cmd/                          # 应用程序入口
│   ├── api/                      # HTTP API 服务
│   └── worker/                   # Asynq 异步任务 Worker
│
├── internal/                     # 私有业务代码
│   ├── handler/                  # HTTP 处理层
│   │   └── middleware/           # 中间件（认证、日志、恢复、验证）
│   ├── service/                  # 业务逻辑层（核心业务）
│   ├── store/                    # 数据访问层
│   │   └── postgres/             # PostgreSQL 实现
│   ├── model/                    # 数据模型（实体、DTO）
│   ├── task/                     # Asynq 任务定义和处理
│   ├── gateway/                  # Gateway 服务 HTTP 客户端
│   └── router/                   # 路由注册
│
├── pkg/                          # 公共工具库
│   ├── config/                   # 配置管理（Viper）
│   ├── logger/                   # 日志（Zap + Lumberjack）
│   ├── database/                 # 数据库初始化（PostgreSQL + Redis）
│   ├── queue/                    # 队列封装（Asynq）
│   ├── response/                 # 统一响应格式
│   ├── errors/                   # 错误码定义
│   └── validator/                # 验证器封装
│
├── config/                       # 配置文件（yaml）
├── migrations/                   # 数据库迁移文件
├── scripts/                      # 脚本工具
└── docs/                         # 文档
```

---

## 架构设计

### 分层架构
```
Handler (HTTP) → Service (业务逻辑) → Store (数据访问) → Model (数据模型)
```

### 双服务架构
- **API 服务**：处理 HTTP 请求，快速响应
- **Worker 服务**：处理异步任务（批量同步、分佣计算等），独立部署

### 核心模块
- **Service 层**：统一管理所有业务逻辑，支持跨模块调用
- **Store 层**：统一管理所有数据访问，支持事务
- **Task 层**：Asynq 任务处理器，支持定时任务和事件触发

---

## 开发规范

### 依赖注入
通过 `Service` 和 `Store` 结构体统一管理依赖：
```go
// 初始化
st := store.New(db)
svc := service.New(st, queueClient, logger)

// 使用
svc.SIM.Activate(...)
svc.Commission.Calculate(...)
```

### 事务处理
```go
store.Transaction(ctx, func(tx *store.Store) error {
    tx.SIM.UpdateStatus(...)
    tx.Commission.Create(...)
    return nil
})
```

### 异步任务
- 高频任务：批量状态同步、流量同步、实名检查
- 业务任务：分佣计算、生命周期变更通知
- 任务优先级：critical > default > low

---

## 快速开始

### 配置
编辑 `config/config.yaml` 配置数据库和 Redis 连接

### 启动 API 服务
```bash
go run cmd/api/main.go
```

### 启动 Worker 服务
```bash
go run cmd/worker/main.go
```

---

## 设计原则

- **简单实用**：不过度设计，够用就好
- **直接实现**：避免不必要的接口抽象
- **统一管理**：依赖集中初始化，避免参数传递
- **职责分离**：API 和 Worker 独立部署，便于扩展