439 lines
12 KiB
Markdown
439 lines
12 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/ # 错误码定义
|
||
│ ├── constants/ # 常量定义（业务常量、Redis Key 管理）
|
||
│ └── 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
|
||
|
||
### 常量和 Redis Key 管理
|
||
所有常量统一在 `pkg/constants/` 目录管理：
|
||
```go
|
||
// 业务常量
|
||
constants.SIMStatusActive
|
||
constants.SIMStatusInactive
|
||
|
||
// Redis Key 管理（统一使用 Key 生成函数）
|
||
constants.RedisSIMStatusKey(iccid) // sim:status:{iccid}
|
||
constants.RedisAgentCommissionKey(agentID) // agent:commission:{agentID}
|
||
constants.RedisTaskLockKey(taskName) // task:lock:{taskName}
|
||
|
||
// 使用示例
|
||
key := constants.RedisSIMStatusKey("898600...")
|
||
rdb.Set(ctx, key, status, time.Hour)
|
||
```
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 配置
|
||
编辑 `config/config.yaml` 配置数据库和 Redis 连接
|
||
|
||
### 启动 API 服务
|
||
```bash
|
||
go run cmd/api/main.go
|
||
```
|
||
|
||
### 启动 Worker 服务
|
||
```bash
|
||
go run cmd/worker/main.go
|
||
```
|
||
|
||
---
|
||
|
||
## 设计原则
|
||
|
||
- **简单实用**：不过度设计，够用就好
|
||
- **直接实现**：避免不必要的接口抽象
|
||
- **统一管理**：依赖集中初始化，避免参数传递
|
||
- **职责分离**：API 和 Worker 独立部署，便于扩展
|
||
|
||
---
|
||
|
||
## 开发流程 (Speckit)
|
||
|
||
本项目使用 Speckit 规范化功能开发流程，确保代码质量、测试覆盖和架构一致性。
|
||
|
||
### 项目宪章 (Constitution)
|
||
|
||
项目遵循 `.specify/memory/constitution.md` 定义的核心原则：
|
||
|
||
1. **技术栈遵守**：严格使用 Fiber + GORM + Viper + Zap + Asynq，禁止原生调用快捷方式
|
||
2. **代码质量标准**：遵循 Handler → Service → Store → Model 分层架构
|
||
3. **测试标准**：70%+ 测试覆盖率，核心业务 90%+
|
||
4. **用户体验一致性**：统一 JSON 响应格式、RESTful API、双语错误消息
|
||
5. **性能要求**：API P95 < 200ms，P99 < 500ms，合理使用批量操作和异步任务
|
||
|
||
详细原则和规则请参阅宪章文档。
|
||
|
||
### Speckit 命令使用
|
||
|
||
#### 1. 创建功能规范
|
||
|
||
```bash
|
||
/speckit.specify "功能描述"
|
||
```
|
||
|
||
**用途**：从自然语言描述创建结构化的功能规范文档
|
||
|
||
**输出**：`specs/###-feature-name/spec.md`
|
||
|
||
**包含内容**：
|
||
- 用户故事和测试场景（按优先级排序 P1/P2/P3）
|
||
- 功能需求（FR-001, FR-002...）
|
||
- 技术需求（基于宪章自动生成）
|
||
- 成功标准
|
||
|
||
**示例**：
|
||
```bash
|
||
/speckit.specify "实现代理商分佣计算和结算功能，支持多级代理商分佣规则"
|
||
```
|
||
|
||
---
|
||
|
||
#### 2. 明确规范细节
|
||
|
||
```bash
|
||
/speckit.clarify
|
||
```
|
||
|
||
**用途**：识别规范中的不明确区域，提出最多 5 个针对性问题并将答案编码回规范
|
||
|
||
**使用场景**：
|
||
- 功能需求模糊或有歧义
|
||
- 需要澄清技术实现细节
|
||
- 边界条件不清楚
|
||
|
||
**输出**：更新 `spec.md`，消除歧义和不确定性
|
||
|
||
---
|
||
|
||
#### 3. 生成实现计划
|
||
|
||
```bash
|
||
/speckit.plan
|
||
```
|
||
|
||
**用途**：基于功能规范执行完整的实现规划工作流
|
||
|
||
**输出**：`specs/###-feature-name/` 目录下生成：
|
||
- `plan.md` - 实现计划（技术上下文、宪章检查、项目结构）
|
||
- `research.md` - Phase 0 技术调研
|
||
- `data-model.md` - Phase 1 数据模型设计
|
||
- `quickstart.md` - Phase 1 快速开始指南
|
||
- `contracts/` - Phase 1 API 契约定义
|
||
|
||
**关键检查**：
|
||
- ✅ 宪章符合性检查（技术栈、架构、测试、性能）
|
||
- ✅ 项目结构规划（Go 模块组织）
|
||
- ✅ 复杂度跟踪和说明
|
||
|
||
---
|
||
|
||
#### 4. 生成任务列表
|
||
|
||
```bash
|
||
/speckit.tasks
|
||
```
|
||
|
||
**用途**：从设计文档生成依赖排序的可执行任务列表
|
||
|
||
**输入**：
|
||
- `spec.md`（必需 - 用户故事）
|
||
- `plan.md`（必需 - 技术规划）
|
||
- `research.md`、`data-model.md`、`contracts/`（可选）
|
||
|
||
**输出**：`specs/###-feature-name/tasks.md`
|
||
|
||
**任务组织**：
|
||
- Phase 1: Setup（项目初始化）
|
||
- Phase 2: Foundational（基础设施 - 阻塞所有用户故事）
|
||
- Phase 3+: 按用户故事优先级组织（US1/P1, US2/P2...）
|
||
- Phase N: Polish & Quality Gates（质量关卡）
|
||
|
||
**任务特性**：
|
||
- `[P]` 标记可并行执行的任务
|
||
- `[US1]` 标记任务所属用户故事
|
||
- 包含精确文件路径
|
||
- 包含依赖关系说明
|
||
|
||
---
|
||
|
||
#### 5. 执行实现
|
||
|
||
```bash
|
||
/speckit.implement
|
||
```
|
||
|
||
**用途**：执行 `tasks.md` 中定义的所有任务，完成功能实现
|
||
|
||
**执行流程**：
|
||
1. 按阶段顺序处理任务（Setup → Foundational → User Stories → Polish）
|
||
2. 每个用户故事独立实现和测试
|
||
3. 自动运行质量关卡检查
|
||
|
||
**质量关卡**（自动执行）：
|
||
- `go test ./...` - 所有测试通过
|
||
- `gofmt -l .` - 代码格式化
|
||
- `go vet ./...` - 静态检查
|
||
- `golangci-lint run` - 代码质量检查
|
||
- `go test -cover ./...` - 测试覆盖率验证
|
||
|
||
---
|
||
|
||
#### 6. 一致性分析
|
||
|
||
```bash
|
||
/speckit.analyze
|
||
```
|
||
|
||
**用途**：执行非破坏性的跨文档一致性和质量分析
|
||
|
||
**检查内容**：
|
||
- spec.md、plan.md、tasks.md 之间的一致性
|
||
- 宪章符合性验证
|
||
- 任务完整性和依赖正确性
|
||
- 测试覆盖计划是否充分
|
||
|
||
**使用时机**：
|
||
- 生成 tasks.md 之后
|
||
- 开始实现之前
|
||
- 发现文档不一致时
|
||
|
||
---
|
||
|
||
#### 7. 生成自定义检查清单
|
||
|
||
```bash
|
||
/speckit.checklist "检查项要求"
|
||
```
|
||
|
||
**用途**：为当前功能生成自定义检查清单
|
||
|
||
**示例**：
|
||
```bash
|
||
/speckit.checklist "生成代码审查清单，包括安全性、性能和 Fiber 最佳实践"
|
||
```
|
||
|
||
---
|
||
|
||
#### 8. 更新项目宪章
|
||
|
||
```bash
|
||
/speckit.constitution "宪章更新说明"
|
||
```
|
||
|
||
**用途**：创建或更新项目宪章，并保持所有依赖模板同步
|
||
|
||
**使用场景**：
|
||
- 首次建立项目开发原则
|
||
- 修订现有原则
|
||
- 添加新的质量标准
|
||
|
||
**自动同步**：
|
||
- 更新 `plan-template.md` 的宪章检查部分
|
||
- 更新 `spec-template.md` 的技术需求部分
|
||
- 更新 `tasks-template.md` 的质量关卡部分
|
||
|
||
---
|
||
|
||
### 完整开发工作流示例
|
||
|
||
```bash
|
||
# 1. 创建功能规范
|
||
/speckit.specify "实现 SIM 卡批量状态同步功能，支持定时任务和手动触发"
|
||
|
||
# 2. 明确模糊需求（如有必要）
|
||
/speckit.clarify
|
||
|
||
# 3. 生成实现计划（包含技术调研和设计）
|
||
/speckit.plan
|
||
|
||
# 4. 生成任务列表
|
||
/speckit.tasks
|
||
|
||
# 5. 再次分析一致性（推荐）
|
||
/speckit.analyze
|
||
|
||
# 6. 执行实现
|
||
/speckit.implement
|
||
|
||
# 7. 代码审查和合并
|
||
# - 验证宪章符合性
|
||
# - 确保所有测试通过
|
||
# - 检查代码覆盖率
|
||
```
|
||
|
||
---
|
||
|
||
### 最佳实践
|
||
|
||
#### 功能开发
|
||
- ✅ 总是从 `/speckit.specify` 开始，明确需求
|
||
- ✅ 使用 `/speckit.clarify` 消除歧义，避免返工
|
||
- ✅ 在 `/speckit.plan` 后检查宪章符合性
|
||
- ✅ 使用 `/speckit.analyze` 在实现前验证计划质量
|
||
|
||
#### 代码质量
|
||
- ✅ 严格遵循 Handler → Service → Store → Model 分层
|
||
- ✅ 所有业务逻辑必须有单元测试（90%+ 覆盖）
|
||
- ✅ 所有 API 端点必须有集成测试
|
||
- ✅ 使用 GORM 而不是 `database/sql`
|
||
- ✅ 使用 Fiber 而不是 `net/http`
|
||
- ✅ 使用 sonic 而不是 `encoding/json`
|
||
|
||
#### 测试
|
||
- ✅ 测试文件与源文件同目录（`*_test.go`）
|
||
- ✅ 使用 Go 标准 testing 包
|
||
- ✅ 测试独立可运行（使用 mock 或 testcontainers）
|
||
- ✅ 单元测试 < 100ms，集成测试 < 1s
|
||
|
||
#### 性能
|
||
- ✅ 批量操作使用 GORM 的批量方法
|
||
- ✅ 耗时操作使用 Asynq 异步任务
|
||
- ✅ 列表 API 必须分页（默认 20，最大 100）
|
||
- ✅ 确保数据库索引支持查询
|
||
|
||
#### API 设计
|
||
- ✅ 使用统一 JSON 响应格式（code/msg/data/timestamp）
|
||
- ✅ 错误消息中英文双语
|
||
- ✅ 时间字段使用 ISO 8601 格式
|
||
- ✅ 金额字段使用整数（分）
|
||
|
||
---
|
||
|
||
### 文档结构
|
||
|
||
```
|
||
.specify/
|
||
├── memory/
|
||
│ └── constitution.md # 项目宪章（开发核心原则）
|
||
└── templates/
|
||
├── spec-template.md # 功能规范模板
|
||
├── plan-template.md # 实现计划模板
|
||
├── tasks-template.md # 任务列表模板
|
||
└── checklist-template.md # 检查清单模板
|
||
|
||
specs/
|
||
└── ###-feature-name/ # 功能文档目录
|
||
├── spec.md # 功能规范
|
||
├── plan.md # 实现计划
|
||
├── research.md # 技术调研
|
||
├── data-model.md # 数据模型
|
||
├── quickstart.md # 快速开始
|
||
├── contracts/ # API 契约
|
||
└── tasks.md # 任务列表
|
||
```
|
||
|
||
---
|
||
|
||
### 常见问题
|
||
|
||
**Q: 为什么要使用 Speckit？**
|
||
A: Speckit 确保团队遵循统一的开发流程，减少沟通成本，提高代码质量和可维护性。
|
||
|
||
**Q: 可以跳过某些步骤吗？**
|
||
A: 不推荐。每个步骤都有明确目的，跳过可能导致需求不清、架构不合理或测试不足。
|
||
|
||
**Q: 如何处理紧急修复？**
|
||
A: 小型修复可以简化流程，但仍需遵循宪章原则（技术栈、测试、代码质量）。
|
||
|
||
**Q: 宪章可以修改吗？**
|
||
A: 可以，使用 `/speckit.constitution` 修改。修改需要团队共识，并会自动同步所有模板。
|
||
|
||
**Q: 测试覆盖率达不到 70% 怎么办？**
|
||
A: 核心业务逻辑必须达到 90%+。工具函数、简单的 getter/setter 可以适当放宽，但总体必须 > 70%。
|