君鸿卡管系统

系统简介

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

技术栈：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 结构体统一管理依赖：

// 初始化
st := store.New(db)
svc := service.New(st, queueClient, logger)

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

事务处理

store.Transaction(ctx, func(tx *store.Store) error {
    tx.SIM.UpdateStatus(...)
    tx.Commission.Create(...)
    return nil
})

异步任务

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

快速开始

配置

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

启动 API 服务

go run cmd/api/main.go

启动 Worker 服务

go run cmd/worker/main.go

设计原则

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

3.7 KiB Raw Blame History Unescape Escape