# 君鸿卡管系统

## 系统简介

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

**技术栈**：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%。