AI规范准则生成 README.md初始化

2025-11-10 15:48:47 +08:00
parent eb8a759d4d
commit 2413baf945
5 changed files with 456 additions and 60 deletions
--- a/READEME.md
+++ b/READEME.md
@@ -0,0 +1,124 @@
+# 君鸿卡管系统
+
+## 系统简介
+
+物联网卡 + 号卡全生命周期管理平台，支持代理商体系和分佣结算。
+
+**技术栈**：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 独立部署，便于扩展