125 lines
3.7 KiB
Markdown
125 lines
3.7 KiB
Markdown
# 君鸿卡管系统
|
||
|
||
## 系统简介
|
||
|
||
物联网卡 + 号卡全生命周期管理平台，支持代理商体系和分佣结算。
|
||
|
||
**技术栈**：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 独立部署，便于扩展
|