12 KiB
12 KiB
君鸿卡管系统
系统简介
物联网卡 + 号卡全生命周期管理平台，支持代理商体系和分佣结算。
技术栈：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 结构体统一管理依赖：
// 初始化
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
常量和 Redis Key 管理
所有常量统一在 pkg/constants/ 目录管理：
// 业务常量
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 服务
go run cmd/api/main.go
启动 Worker 服务
go run cmd/worker/main.go
设计原则
- 简单实用：不过度设计，够用就好
- 直接实现：避免不必要的接口抽象
- 统一管理：依赖集中初始化，避免参数传递
- 职责分离：API 和 Worker 独立部署，便于扩展
开发流程 (Speckit)
本项目使用 Speckit 规范化功能开发流程，确保代码质量、测试覆盖和架构一致性。
项目宪章 (Constitution)
项目遵循 .specify/memory/constitution.md 定义的核心原则：
- 技术栈遵守：严格使用 Fiber + GORM + Viper + Zap + Asynq，禁止原生调用快捷方式
- 代码质量标准：遵循 Handler → Service → Store → Model 分层架构
- 测试标准：70%+ 测试覆盖率，核心业务 90%+
- 用户体验一致性：统一 JSON 响应格式、RESTful API、双语错误消息
- 性能要求：API P95 < 200ms，P99 < 500ms，合理使用批量操作和异步任务
详细原则和规则请参阅宪章文档。
Speckit 命令使用
1. 创建功能规范
/speckit.specify "功能描述"
用途：从自然语言描述创建结构化的功能规范文档
输出：specs/###-feature-name/spec.md
包含内容：
- 用户故事和测试场景（按优先级排序 P1/P2/P3）
- 功能需求（FR-001, FR-002...）
- 技术需求（基于宪章自动生成）
- 成功标准
示例：
/speckit.specify "实现代理商分佣计算和结算功能，支持多级代理商分佣规则"
2. 明确规范细节
/speckit.clarify
用途：识别规范中的不明确区域，提出最多 5 个针对性问题并将答案编码回规范
使用场景：
- 功能需求模糊或有歧义
- 需要澄清技术实现细节
- 边界条件不清楚
输出：更新 spec.md，消除歧义和不确定性
3. 生成实现计划
/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. 生成任务列表
/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. 执行实现
/speckit.implement
用途：执行 tasks.md 中定义的所有任务，完成功能实现
执行流程：
- 按阶段顺序处理任务（Setup → Foundational → User Stories → Polish）
- 每个用户故事独立实现和测试
- 自动运行质量关卡检查
质量关卡（自动执行）：
go test ./...- 所有测试通过gofmt -l .- 代码格式化go vet ./...- 静态检查golangci-lint run- 代码质量检查go test -cover ./...- 测试覆盖率验证
6. 一致性分析
/speckit.analyze
用途：执行非破坏性的跨文档一致性和质量分析
检查内容：
- spec.md、plan.md、tasks.md 之间的一致性
- 宪章符合性验证
- 任务完整性和依赖正确性
- 测试覆盖计划是否充分
使用时机：
- 生成 tasks.md 之后
- 开始实现之前
- 发现文档不一致时
7. 生成自定义检查清单
/speckit.checklist "检查项要求"
用途：为当前功能生成自定义检查清单
示例：
/speckit.checklist "生成代码审查清单，包括安全性、性能和 Fiber 最佳实践"
8. 更新项目宪章
/speckit.constitution "宪章更新说明"
用途：创建或更新项目宪章，并保持所有依赖模板同步
使用场景：
- 首次建立项目开发原则
- 修订现有原则
- 添加新的质量标准
自动同步：
- 更新
plan-template.md的宪章检查部分 - 更新
spec-template.md的技术需求部分 - 更新
tasks-template.md的质量关卡部分
完整开发工作流示例
# 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%。