From e9df1e7dedad6082b99b0fb4431161cd799464d0 Mon Sep 17 00:00:00 2001 From: huang Date: Thu, 9 Apr 2026 10:50:46 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20IoT=E5=8D=A1=E6=96=B0=E5=A2=9E=E7=BB=91?= =?UTF-8?q?=E5=AE=9A=E8=AE=BE=E5=A4=87=E8=99=9A=E6=8B=9F=E5=8F=B7=E5=BF=AB?= =?UTF-8?q?=E7=85=A7=E5=AD=97=E6=AE=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - tb_iot_card 新增 device_virtual_no 字段，存储绑定设备的虚拟号快照 - 列表/详情接口响应新增 device_virtual_no 字段 - 列表接口 is_standalone 改为可选参数（不传返回全部卡） - 移除列表接口 virtual_no 查询参数 - 绑卡/解绑时同步更新 device_virtual_no 快照 - 设备导入时批量写入 device_virtual_no 快照 - 归档 feat-iot-card-device-virtual-no 变更提案 Co-Authored-By: Claude Sonnet 4.6 --- .mcp.json | 20 +- CLAUDE.md | 726 ++---------------- internal/model/dto/iot_card_dto.go | 3 +- internal/model/iot_card.go | 1 + internal/service/device/binding.go | 20 + internal/service/iot_card/service.go | 5 +- internal/store/postgres/iot_card_store.go | 35 +- internal/task/device_import.go | 8 + ...add_device_virtual_no_to_iot_card.down.sql | 1 + ...0_add_device_virtual_no_to_iot_card.up.sql | 13 + .../.openspec.yaml | 2 + .../design.md | 92 +++ .../proposal.md | 42 + .../specs/iot-card-device-snapshot/spec.md | 59 ++ .../tasks.md | 39 + .../specs/iot-card-device-snapshot/spec.md | 59 ++ 16 files changed, 421 insertions(+), 704 deletions(-) create mode 100644 migrations/000110_add_device_virtual_no_to_iot_card.down.sql create mode 100644 migrations/000110_add_device_virtual_no_to_iot_card.up.sql create mode 100644 openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/.openspec.yaml create mode 100644 openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/design.md create mode 100644 openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/proposal.md create mode 100644 openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/specs/iot-card-device-snapshot/spec.md create mode 100644 openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/tasks.md create mode 100644 openspec/specs/iot-card-device-snapshot/spec.md diff --git a/.mcp.json b/.mcp.json index 2f75365..a81f618 100644 --- a/.mcp.json +++ b/.mcp.json @@ -1,19 +1,15 @@ { "mcpServers": { "postgres": { - "command": "docker", + "command": "npx", "args": [ - "run", - "-i", - "--rm", - "-e", - "DATABASE_URI", - "crystaldba/postgres-mcp", - "--access-mode=restricted" - ], - "env": { - "DATABASE_URI": "postgresql://erp_pgsql:erp_2025@cxd.whcxd.cn:16159/junhong_cmp_test?sslmode=disable" - } + "-y", + "@bytebase/dbhub@latest", + "--transport", + "stdio", + "--config", + ".config/dbhub.toml" + ] } } } \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index a52bb78..d14e7d7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,6 +18,10 @@ | 数据库迁移 | `db-migration` | 迁移命令、文件规范、执行流程、失败处理 | | 维护规范文档 | `doc-management` | 规范文档流程和维护规则 | | 调试 bug / 排查异常 | `systematic-debugging` | 四阶段根因分析流程、逐层诊断、场景速查表 | +| 编写 Go 代码注释/文档注释 | `comment-standards` | 包/结构体/接口/函数/内联注释完整规范与示例 | +| 创建涉及接口的 OpenSpec 提案 | `openspec-api-contract` | 探索阶段引导清单、提案必填章节与完成标准 | + +--- ### ⚠️ 新增 Handler 时必须同步更新文档生成器 @@ -111,150 +115,13 @@ Handler → Service → Store → Model ### 注释规范 -#### 基本原则 +- **所有注释使用中文**，导出符号必须有文档注释（包、函数、类型、接口、常量） +- 复杂逻辑解释"为什么"而非"做了什么"，禁止废话注释（复述代码本身） +- Handler 方法注释必须包含 HTTP 方法和路径（`// Create 创建账号` + `// POST /api/admin/accounts`） +- 未导出函数：< 15 行可省略，≥ 15 行或非显而易见算法必须注释 +- 修改代码时必须同步更新注释，过时注释比没有注释更有害 -- **所有注释使用中文**（与语言要求一致） -- **导出符号必须有文档注释**（包、函数、方法、类型、接口、常量、变量） -- **复杂逻辑必须有实现注释**（解释"为什么"，而不是"做了什么"） -- **禁止废话注释**（不要用注释复述代码本身） -- **修改代码时必须同步更新注释**（过时的注释比没有注释更有害） - -#### 包注释 - -每个包的入口文件（通常是主文件或 `doc.go`）必须有包注释： - -```go -// Package account 提供账号管理的业务逻辑服务 -// 包含账号创建、修改、删除、权限分配等功能 -package account -``` - -#### 结构体注释 - -所有导出结构体必须有文档注释，说明该结构体代表什么： - -```go -// Service 账号业务服务 -// 负责账号的 CRUD、角色分配、密码管理等业务逻辑 -type Service struct { - store *Store - auditService AuditServiceInterface -} -``` - -#### 接口注释 - -导出接口必须注释接口用途，每个方法必须说明契约： - -```go -// PermissionChecker 权限检查器接口 -// 用于查询用户的权限列表 -type PermissionChecker interface { - // CheckPermission 检查用户是否拥有指定权限 - // userID: 用户ID - // permCode: 权限编码（格式: module:action） - // platform: 端口类型 (all/web/h5) - CheckPermission(ctx context.Context, userID uint, permCode string, platform string) (bool, error) -} -``` - -#### 函数和方法注释 - -导出函数/方法必须以函数名开头，说明功能： - -```go -// Create 创建账号 -// POST /api/admin/accounts -func (h *AccountHandler) Create(c *fiber.Ctx) error { -``` - -**复杂方法**（超过 30 行或包含复杂业务逻辑）必须额外说明实现思路： - -```go -// ActivateByRealname 首次实名激活套餐 -// 当用户完成实名认证后，自动激活处于"囤货待实名"状态的套餐： -// 1. 查找该卡所有 status=3（待实名激活）的套餐 -// 2. 按创建时间排序，第一个主套餐立即激活（status=1） -// 3. 其余主套餐进入排队状态（status=4） -// 4. 加油包如果绑定了已激活的主套餐则一并激活 -func (s *UsageService) ActivateByRealname(ctx context.Context, cardID uint) error { -``` - -#### 未导出符号的注释 - -未导出（小写）的函数/方法： - -- **简单逻辑**（< 15 行）：可以不加注释 -- **复杂逻辑**（≥ 15 行）或 **非显而易见的算法**：必须加注释 - -```go -// buildPermissionTree 递归构建权限树 -// 采用 map 索引 + 单次遍历算法，时间复杂度 O(n) -func (s *Service) buildPermissionTree(permissions []*model.Permission) []*dto.PermissionTreeNode { -``` - -#### 内联注释（实现逻辑注释） - -以下场景**必须**添加内联注释： - -| 场景 | 要求 | -|------|------| -| 复杂条件判断 | 解释判断的业务含义 | -| 多步骤业务流程 | 用编号注释标明每一步 | -| 非显而易见的设计决策 | 解释"为什么这样做"而不是"做了什么" | -| 缓存/事务/并发处理 | 说明策略和原因 | -| 临时方案/兼容逻辑 | 标注 TODO 或说明背景 | - -**✅ 好的内联注释（解释为什么）**： - -```go -// 使用 Redis 分布式锁防止并发重复创建，锁超时 10 秒 -if !s.acquireLock(ctx, lockKey, 10*time.Second) { - return errors.New(errors.CodeTooManyRequests, "操作过于频繁，请稍后重试") -} - -// 先冻结佣金再扣款，保证资金安全（失败时佣金自动解冻） -if err := s.freezeCommission(ctx, tx, orderID); err != nil { - return err -} -``` - -**❌ 废话注释（禁止）**： - -```go -// 获取用户ID ← 禁止：代码本身已经很清楚 -userID := middleware.GetUserIDFromContext(ctx) - -// 创建账号 ← 禁止：变量名已说明意图 -account := &model.Account{} - -// 返回错误 ← 禁止：return err 不需要注释 -return err -``` - -#### 常量和枚举注释 - -分组常量必须有组注释，每个值必须有行内注释： - -```go -// 用户类型常量 -const ( - UserTypeSuperAdmin = 1 // 超级管理员 - UserTypePlatform = 2 // 平台用户 - UserTypeAgent = 3 // 代理账号 - UserTypeEnterprise = 4 // 企业账号 -) -``` - -#### Handler 层特殊要求 - -Handler 方法的注释必须包含 HTTP 方法和路径： - -```go -// Create 创建账号 -// POST /api/admin/accounts -func (h *AccountHandler) Create(c *fiber.Ctx) error { -``` +**详细规范与示例**：见 `comment-standards` skill ### Go 代码风格 @@ -292,35 +159,9 @@ func (h *AccountHandler) Create(c *fiber.Ctx) error { ## ⚠️ 测试禁令（强制执行） -**本项目不使用任何形式的自动化测试代码。** - -**绝对禁止：** - -- ❌ **禁止编写单元测试** - 无论任何场景 -- ❌ **禁止编写集成测试** - 无论任何场景 -- ❌ **禁止编写验收测试** - 无论任何场景 -- ❌ **禁止编写流程测试** - 无论任何场景 -- ❌ **禁止编写 E2E 测试** - 无论任何场景 -- ❌ **禁止创建 `*_test.go` 文件** - 除非用户明确要求 -- ❌ **禁止在任务中包含测试相关工作** - 规划和实现均不涉及测试 -- ❌ **禁止在文档中提及测试要求** - 规范、设计文档均不讨论测试 - -**唯一例外：** - -- ✅ **仅当用户明确要求**时才编写测试代码 -- ✅ 用户必须主动说明"请写测试"或"需要测试" - -**原因说明：** - -- 业务系统的正确性通过人工验证和生产环境监控保证 -- 测试代码的维护成本高于价值 -- 快速迭代优先于测试覆盖率 - -**替代方案：** - -- 使用 PostgreSQL MCP 工具手动验证数据 -- 使用 Postman/curl 手动测试 API -- 依赖生产环境日志和监控发现问题 +**本项目禁止任何形式的自动化测试**（单元/集成/E2E/`*_test.go` 文件），规划和文档中也不讨论测试。 +**唯一例外**：用户明确说"请写测试"时。 +**替代验证**：PostgreSQL MCP 手动验证数据、Postman/curl 手动测试 API。 ## 性能要求 @@ -395,198 +236,58 @@ func (h *AccountHandler) Create(c *fiber.Ctx) error { ### 越权防护规范 -**适用场景**：任何涉及跨用户、跨店铺、跨企业的资源访问 +**三层防护机制**（基础设施已就绪，无需自建）： +1. **路由层中间件**：粗粒度拦截（如企业账号禁止访问账号管理） +2. **Service 层业务检查**：`middleware.CanManageShop()` / `middleware.CanManageEnterprise()` 细粒度验证；示例见 `internal/service/account/service.go` +3. **GORM Callback 自动过滤**：代理按店铺层级、企业按企业ID，已自动应用无需手动调用 -**三层防护机制**： - -1. **路由层中间件**（粗粒度拦截） - - 用于明显的权限限制（如企业账号禁止访问账号管理） - - 示例： - - ```go - group.Use(func(c *fiber.Ctx) error { - userType := middleware.GetUserTypeFromContext(c.UserContext()) - if userType == constants.UserTypeEnterprise { - return errors.New(errors.CodeForbidden, "无权限访问账号管理功能") - } - return c.Next() - }) - ``` - -2. **Service 层业务检查**（细粒度验证） - - 使用 `middleware.CanManageShop(ctx, targetShopID, shopStore)` 验证店铺权限 - - 使用 `middleware.CanManageEnterprise(ctx, targetEnterpriseID, enterpriseStore, shopStore)` 验证企业权限 - - 类型级权限检查（如代理不能创建平台账号） - - 示例见 `internal/service/account/service.go` - -3. **GORM Callback 自动过滤**（兜底） - - 已有实现，自动应用到所有查询 - - 代理用户：`WHERE shop_id IN (自己店铺+下级店铺)` - - 企业用户：`WHERE enterprise_id = 当前企业ID` - - 无需手动调用 - -**统一错误返回**： - -- 越权访问统一返回：`errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")` -- 不区分"不存在"和"无权限"，防止信息泄露 +统一错误返回：`errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")`（不区分"不存在"与"无权限"，防止信息泄露） ### 幂等性规范 -**适用场景**：任何可能被重复触发的写操作 - -#### 必须实现幂等性的场景 - -| 场景 | 原因 | 实现策略 | -|------|------|----------| -| 订单创建 | 用户双击、网络重试 | Redis 业务键防重 + 分布式锁 | -| 支付回调 | 第三方平台重复通知 | 状态条件更新（`WHERE status = pending`） | -| 钱包扣款/充值 | 并发请求、消息重投 | 乐观锁（version 字段）+ 状态条件更新 | -| 套餐激活 | 异步任务重试 | Redis 分布式锁 + 已存在记录检查 | -| 异步任务处理 | Asynq 自动重试 | Redis 任务锁（`RedisTaskLockKey`） | -| 佣金计算 | 支付成功后触发 | 幂等任务入队 + 状态检查 | - -#### 不需要幂等性的场景 - -- 纯查询接口（GET 请求天然幂等） -- 管理后台的配置修改（低频操作，人为确认） -- 日志记录、审计记录（允许重复写入） - -#### 实现策略选择 - -根据场景特征选择合适的策略： - -**策略 1：状态条件更新（首选，适用于有明确状态流转的操作）** +写操作按场景选择策略： +- **状态流转操作** → 状态条件更新（首选） +- **创建类操作（无状态可依赖）** → Redis 业务键防重 + 分布式锁（三层检测） +- **余额/库存数值更新** → 乐观锁（`version` 字段） ```go -// 通过 WHERE 条件确保只有预期状态才能更新，RowsAffected == 0 说明已被处理 +// 策略1示例（首选）：通过 WHERE 条件确保幂等，RowsAffected=0 说明已被处理 result := tx.Model(&model.Order{}). Where("id = ? AND payment_status = ?", orderID, model.PaymentStatusPending). Updates(map[string]any{"payment_status": model.PaymentStatusPaid}) - -if result.RowsAffected == 0 { - // 已被处理，检查当前状态决定返回成功还是错误 -} +if result.RowsAffected == 0 { /* 已处理，检查当前状态 */ } ``` -**策略 2：Redis 业务键防重 + 分布式锁（适用于创建类操作，无状态可依赖）** +- Redis Key 定义在 `pkg/constants/redis.go`，分布式锁必须用 `defer` 释放 +- 参考实现：`internal/service/order/service.go` + +### 异步任务载荷规范（Asynq） + +**必须遵守：** + +- ✅ 调用 `queueClient.EnqueueTask()` 时，`payload` 必须传入 **struct 或 map** +- ❌ **禁止传入 `[]byte`**：`EnqueueTask` 内部统一调用 `sonic.Marshal`，若传入 `[]byte` 会被 base64 编码成字符串，Handler 反序列化时类型不匹配直接崩溃 ```go -// 业务键 = 唯一标识请求意图的组合字段 -// 示例：order:create:{buyer_type}:{buyer_id}:{carrier_type}:{carrier_id}:{sorted_package_ids} -idempotencyKey := buildBusinessKey(...) -redisKey := constants.RedisXxxIdempotencyKey(idempotencyKey) +// ✅ 正确：传 struct +queueClient.EnqueueTask(ctx, constants.TaskTypeXxx, MyPayload{OrderID: id}) -// 第 1 层：Redis GET 快速检测 -val, err := s.redis.Get(ctx, redisKey).Result() -if err == nil && val != "" { - return existingResult // 已创建，直接返回 -} - -// 第 2 层：分布式锁防止并发 -lockKey := constants.RedisXxxLockKey(resourceType, resourceID) -locked, _ := s.redis.SetNX(ctx, lockKey, time.Now().String(), lockTTL).Result() -if !locked { - return errors.New(errors.CodeTooManyRequests, "操作进行中，请勿重复提交") -} -defer s.redis.Del(ctx, lockKey) - -// 第 3 层：加锁后二次检测 -val, err = s.redis.Get(ctx, redisKey).Result() -if err == nil && val != "" { - return existingResult -} - -// 执行业务逻辑... - -// 成功后标记 -s.redis.Set(ctx, redisKey, resultID, idempotencyTTL) +// ❌ 错误：预先序列化后传 []byte（二次 Marshal → base64 编码） +payloadBytes, _ := sonic.Marshal(MyPayload{OrderID: id}) +queueClient.EnqueueTask(ctx, constants.TaskTypeXxx, payloadBytes) ``` -**策略 3：乐观锁（适用于余额、库存等数值更新）** +直接用 `asynq.NewTask` 入队时（绕过 `EnqueueTask`）才需要自己 Marshal。 -```go -result := tx.Model(&model.Wallet{}). - Where("id = ? AND balance >= ? AND version = ?", walletID, amount, currentVersion). - Updates(map[string]any{ - "balance": gorm.Expr("balance - ?", amount), - "version": gorm.Expr("version + 1"), - }) -if result.RowsAffected == 0 { - return errors.New(errors.CodeInsufficientBalance, "余额不足或并发冲突") -} -``` - -#### Redis Key 命名规范 - -幂等性相关的 Redis Key 统一在 `pkg/constants/redis.go` 定义： - -```go -// 幂等性检测键：Redis{Module}IdempotencyKey — TTL 通常 3~5 分钟 -func RedisOrderIdempotencyKey(businessKey string) string - -// 分布式锁键：Redis{Module}{Action}LockKey — TTL 通常 10~30 秒 -func RedisOrderCreateLockKey(carrierType string, carrierID uint) string -``` - -#### 现有幂等性实现参考 - -| 模块 | 文件 | 策略 | -|------|------|------| -| 订单创建 | `internal/service/order/service.go` → `Create()` | 策略 2：Redis 业务键 + 分布式锁 | -| 钱包支付 | `internal/service/order/service.go` → `WalletPay()` | 策略 1：状态条件更新 | -| 支付回调 | `internal/service/order/service.go` → `HandlePaymentCallback()` | 策略 1：状态条件更新 | -| 套餐激活 | `internal/service/package/activation_service.go` → `ActivateQueuedPackage()` | 策略 2（简化版）：Redis 分布式锁 | -| 钱包扣款 | `internal/service/order/service.go` → `WalletPay()` | 策略 3：乐观锁（version 字段） | +--- ### 审计日志规范 **适用场景**：任何敏感操作（账号管理、权限变更、数据删除等） -**使用方式**： - -1. **Service 层集成审计日志**： - - ```go - type Service struct { - store *Store - auditService AuditServiceInterface - } - - func (s *Service) SensitiveOperation(ctx context.Context, ...) error { - // 1. 执行业务操作 - err := s.store.DoSomething(ctx, ...) - if err != nil { - return err - } - - // 2. 记录审计日志（异步） - s.auditService.LogOperation(ctx, &model.OperationLog{ - OperatorID: middleware.GetUserIDFromContext(ctx), - OperationType: "operation_type", - OperationDesc: "操作描述", - BeforeData: beforeData, // 变更前数据 - AfterData: afterData, // 变更后数据 - RequestID: middleware.GetRequestIDFromContext(ctx), - IPAddress: middleware.GetIPFromContext(ctx), - UserAgent: middleware.GetUserAgentFromContext(ctx), - }) - - return nil - } - ``` - -2. **审计日志字段说明**： - - `operator_id`, `operator_type`, `operator_name`: 操作人信息（必填） - - `target_*`: 目标资源信息（可选） - - `operation_type`: 操作类型（create/update/delete/assign_roles等） - - `operation_desc`: 操作描述（中文，便于查看） - - `before_data`, `after_data`: 变更数据（JSON 格式） - - `request_id`, `ip_address`, `user_agent`: 请求上下文 - -3. **异步写入**： - - 审计日志使用 Goroutine 异步写入 - - 写入失败不影响业务操作 - - 失败时记录 Error 日志，包含完整审计信息 +- Service 层注入 `auditService AuditServiceInterface`，操作成功后调用 `LogOperation()` +- 必填字段：`OperatorID`、`OperationType`、`OperationDesc`、`BeforeData`、`AfterData` +- 异步写入（Goroutine），写入失败不影响业务，失败时记录 Error 日志 **示例参考**：`internal/service/account/service.go` @@ -608,343 +309,4 @@ func RedisOrderCreateLockKey(carrierType string, carrierID uint) string > "我注意到任务 2.1 和 2.2 可以合并为一步完成，是否可以这样优化？" > "任务 3.1 在当前实现中可能不需要，是否可以跳过？" -**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md` - -# English Learning Mode - - The user is learning English through practical use. Apply these rules in every conversation: - - 1. **Always respond in Chinese** — regardless of whether the user writes in English or Chinese. - - 2. **When the user writes in English**, append a one-line correction at the end of your response in this format: - → `[natural version of what they wrote]` - No explanation needed — just the corrected phrase. - - 3. **When the user mixes Chinese into English** (e.g., "I want to 实现 dark mode"), translate the Chinese word/phrase inline and continue naturally. Do not make a - big deal of it. - - 4. **Never interrupt the flow** to give grammar lessons. Corrections are silent and brief — the user's focus is on the task, not the language. - - -## Project - -**君鸿卡管系统** - -物联网卡（IoT SIM）+ 号卡 + 设备全生命周期管理平台，支持多级代理商体系和分佣结算。平台以 B 端代理商为核心分销渠道，兼顾 C 端个人客户和企业客户，覆盖从卡/设备采购、分配、激活、套餐购买到佣金结算的完整业务链路。当前处于 MVP 阶段，核心功能模块已完成，目标是修复所有已知业务链路断点、补全缺失功能，将系统调整至可生产上线状态。 - -**Core Value:** **业务链路完整可用**——代理能采购分配卡/设备，C端客户能充值购包激活套餐，佣金能正确计算并可提现。这条主链路必须端到端跑通。 - -### Constraints - -- **Tech Stack**: 严格使用 Fiber v2 + GORM + Asynq + PostgreSQL + Redis，不引入替代框架 -- **No Tests**: 项目不写自动化测试，人工验收（rg + go build + DBHub + 日志） -- **Language**: 所有注释/日志/错误消息/文档使用中文，变量/函数名使用英文 -- **No Foreign Keys**: 禁止数据库外键约束，关联通过 ID 字段在代码层维护 -- **方案 E 风险**: 流量体系改革涉及 DB 迁移 + Redis 架构，必须低峰期发布，单独规划 - - - -## Technology Stack - -## Languages -- Go 1.25.x - 应用代码、API、Worker、OpenAPI 生成和基础设施脚本，依据 `go.mod`、`cmd/api/main.go`、`cmd/worker/main.go`、`cmd/gendocs/main.go` -- YAML - 配置与部署编排，见 `pkg/config/defaults/config.yaml`、`docker-compose.prod.yml`、`.gitea/workflows/deploy.yaml` -- Dockerfile - API/Worker 容器构建，见 `Dockerfile.api`、`Dockerfile.worker` -- Makefile - 本地构建、文档生成、迁移命令，见 `Makefile` -## Runtime -- Go runtime；API 服务基于 Fiber HTTP 服务器，见 `cmd/api/main.go` -- 独立 Worker 进程处理异步任务与调度，见 `cmd/worker/main.go` -- 生产容器基础镜像为 Alpine，构建镜像使用 Go 1.25.6 Alpine，见 `Dockerfile.api`、`Dockerfile.worker` -- Go Modules，见 `go.mod` -- Lockfile: `go.sum` present -## Frameworks -- Fiber v2.52.9 - HTTP 框架与路由宿主，见 `go.mod`、`cmd/api/main.go` -- GORM v1.31.1 + `gorm.io/driver/postgres` v1.6.0 - PostgreSQL ORM 与连接层，见 `go.mod`、`pkg/database/postgres.go` -- Viper v1.21.0 - 嵌入式默认配置 + 环境变量覆盖，见 `go.mod`、`pkg/config/loader.go` -- Asynq v0.25.1 - 任务提交、Worker 消费、定时任务，见 `go.mod`、`pkg/queue/client.go`、`pkg/queue/server.go`、`cmd/worker/main.go` -- sonic v1.14.2 - Fiber JSON 编解码与任务载荷序列化，见 `go.mod`、`cmd/api/main.go`、`pkg/queue/client.go` -- validator/v10 v10.28.0 - DTO 校验依赖，见 `go.mod` -- zap v1.27.1 - 应用日志与 SQL 日志，见 `go.mod`、`pkg/logger/logger.go`、`pkg/database/postgres.go` -- lumberjack.v2 v2.2.1 - 日志轮转，见 `go.mod`、`pkg/logger/logger.go` -- swaggest/openapi-go v0.2.60 - OpenAPI 3.0.3 文档生成，见 `go.mod`、`pkg/openapi/generator.go` -## Build / Dev / Deploy -- `Makefile` 定义 `build`、`run`、`run-worker`、`docs`、`migrate-*` 目标，见 `Makefile` -- API 与 Worker 使用多阶段 Docker 构建，编译产物分别来自 `./cmd/api` 与 `./cmd/worker`，见 `Dockerfile.api`、`Dockerfile.worker` -- 生产编排使用 Docker Compose，运行 `api` 与 `worker` 两个服务，见 `docker-compose.prod.yml` -- Gitea Actions 工作流构建镜像、推送私有镜像仓库并在主分支执行 `docker compose up -d`，见 `.gitea/workflows/deploy.yaml` -- API 启动时会生成 `logs/openapi.yaml`，见 `cmd/api/main.go`、`cmd/api/docs.go` -- 手动文档命令 `make docs` 运行 `cmd/gendocs/main.go`，输出 `docs/admin-openapi.yaml`，见 `Makefile`、`cmd/gendocs/main.go` -## Storage, Data, Messaging -- PostgreSQL 是唯一检测到的主数据库；连接、连接池、GORM logger、Ping 校验位于 `pkg/database/postgres.go` -- Redis 用于认证、缓存、队列后端、限流存储和配置缓存，见 `pkg/database/redis.go`、`cmd/api/main.go`、`internal/service/wechat_config/service.go` -- Asynq 直接复用 Redis 连接配置作为消息后端，见 `pkg/queue/client.go`、`pkg/queue/server.go` -- Worker 内注册订单超时、告警检查、数据清理等调度任务，见 `cmd/worker/main.go` -- S3 兼容对象存储通过 AWS SDK v1 实现，支持上传、下载、预签名 URL、临时文件下载，见 `pkg/storage/s3.go`、`pkg/storage/service.go` -## Configuration -- 默认配置从嵌入文件 `pkg/config/defaults/config.yaml` 读取，见 `pkg/config/embedded.go` -- 运行时使用 `JUNHONG_` 前缀环境变量覆盖，见 `pkg/config/loader.go` -- 必填配置校验包括数据库、Redis、JWT，见 `pkg/config/config.go` -- 服务与超时：`server.*`，见 `pkg/config/config.go` -- PostgreSQL：`database.*`，见 `pkg/config/config.go` -- Redis：`redis.*`，见 `pkg/config/config.go` -- Asynq：`queue.*`，见 `pkg/config/config.go` -- 日志：`logging.*`，见 `pkg/config/config.go` -- 短信：`sms.*`，见 `pkg/config/config.go` -- 对象存储：`storage.*`，见 `pkg/config/config.go` -- 外部 Gateway：`gateway.*`，见 `pkg/config/config.go` -- 微信公众号/小程序/支付配置不走 Viper 主配置，业务侧从数据库表 `tb_wechat_config` 读取并缓存到 Redis，见 `internal/model/wechat_config.go`、`internal/service/wechat_config/service.go`、`pkg/wechat/config.go` -## Logging & Observability -- `pkg/logger/logger.go` 初始化 app/access 双 logger；生产模式写 JSON，开发模式 app logger 同时输出控制台 -- `pkg/logger/middleware.go` 记录 method、path、query、status、duration、request_id、ip、user_agent、user_id、请求/响应 body -- `pkg/database/postgres.go` 自定义 GORM logger，记录错误、慢查询和普通 SQL trace -- `Dockerfile.api` 与 `docker-compose.prod.yml` 均通过 `GET /health` 做容器健康检查 -## Notable Dependencies -- `github.com/gofiber/fiber/v2` - API 服务核心框架，见 `go.mod`、`cmd/api/main.go` -- `github.com/google/uuid` - 请求 ID 生成，见 `cmd/api/main.go` -- `gorm.io/gorm`、`gorm.io/driver/postgres` - ORM 与 PostgreSQL 驱动，见 `go.mod`、`pkg/database/postgres.go` -- `github.com/redis/go-redis/v9` - Redis 客户端，见 `go.mod`、`pkg/database/redis.go` -- `github.com/hibiken/asynq` - 队列与调度器，见 `go.mod`、`pkg/queue/*.go`、`cmd/worker/main.go` -- `github.com/bytedance/sonic` - JSON 编解码，见 `cmd/api/main.go`、`pkg/queue/client.go` -- `github.com/xuri/excelize/v2` - Excel 导入处理依赖，见 `go.mod`; 任务消费方在 `internal/task/iot_card_import.go`、`internal/task/device_import.go` 调用 Excel 解析 -- `github.com/ArtisanCloud/PowerWeChat/v3` - 微信公众号与微信支付 SDK，见 `go.mod`、`pkg/wechat/official_account.go`、`pkg/wechat/payment.go` -- `github.com/aws/aws-sdk-go` - S3 兼容对象存储客户端，见 `go.mod`、`pkg/storage/s3.go` -## Platform Requirements -- 需要 PostgreSQL、Redis、JWT 密钥与 `JUNHONG_` 环境变量；`config.Load()` 在启动时强校验，见 `pkg/config/config.go` -- `make docs` 需要 Go 环境；`migrate-*` 目标需要系统安装 `migrate` 命令，见 `Makefile` -- 目标运行形态是 Docker 化 API + Worker 双进程部署，见 `Dockerfile.api`、`Dockerfile.worker`、`docker-compose.prod.yml` -- 镜像发布到私有仓库 `registry.boss160.cn`，见 `.gitea/workflows/deploy.yaml` -## Evidence -- `go.mod` -- `README.md` -- `cmd/api/main.go` -- `cmd/api/docs.go` -- `cmd/worker/main.go` -- `cmd/gendocs/main.go` -- `pkg/config/config.go` -- `pkg/config/loader.go` -- `pkg/config/embedded.go` -- `pkg/config/defaults/config.yaml` -- `pkg/database/postgres.go` -- `pkg/database/redis.go` -- `pkg/queue/client.go` -- `pkg/queue/server.go` -- `pkg/queue/handler.go` -- `pkg/logger/logger.go` -- `pkg/logger/middleware.go` -- `pkg/openapi/generator.go` -- `pkg/openapi/handlers.go` -- `pkg/storage/s3.go` -- `pkg/storage/service.go` -- `pkg/wechat/config.go` -- `pkg/wechat/official_account.go` -- `pkg/wechat/payment.go` -- `pkg/sms/client.go` -- `internal/gateway/client.go` -- `Makefile` -- `Dockerfile.api` -- `Dockerfile.worker` -- `docker-compose.prod.yml` -- `.gitea/workflows/deploy.yaml` - - - -## Conventions - -## Naming Patterns -- Go 源码使用 `snake_case.go` 或按领域拆分的普通小写命名；路由文件按模块命名放在 `internal/routes/*.go`，Handler 按域放在 `internal/handler/admin/*.go`、`internal/handler/auth/*.go`、`internal/handler/app/*.go`。 -- OpenAPI 与规范文档使用明确用途命名，例如 `docs/api-documentation-guide.md`、`docs/admin-openapi.yaml`、`cmd/api/docs.go`、`cmd/gendocs/main.go`。 -- 规范脚本使用动词前缀命名，例如 `scripts/check-all.sh`、`scripts/check-service-errors.sh`、`scripts/check-comment-paths.sh`、`scripts/verify_migration/main.go`。 -- 导出函数/方法使用 Go 的 `PascalCase`，例如 `NewAccountHandler()`、`Create()`、`Success()`、`RedisOrderIdempotencyKey()`，证据见 `internal/handler/admin/account.go`、`pkg/response/response.go`、`pkg/constants/redis.go`。 -- 未导出帮助函数使用 `camelCase`，例如 `generateOpenAPIDocs()`、`generateAdminDocs()`、`handleError()`、`safeLogWithLevel()`，证据见 `cmd/api/docs.go`、`cmd/gendocs/main.go`、`pkg/errors/handler.go`。 -- 局部变量使用英文 `camelCase`，例如 `outputPath`、`httpStatus`、`roleID`、`groupPath`，证据见 `cmd/api/docs.go`、`pkg/errors/handler.go`、`internal/handler/admin/account.go`。 -- 错误变量统一使用 `err`，成功返回数据常用业务名，例如 `account`、`accounts`、`roles`，证据见 `internal/handler/admin/account.go`。 -- 结构体和接口使用 `PascalCase`，接口语义化命名，配合 `-er` 后缀规则；项目规范明确要求接口名使用 `-er`，见 `AGENTS.md`。 -- 路由文档元数据类型使用语义名，如 `RouteSpec`、`FileUploadField`，证据见 `internal/routes/registry.go`。 -## Code Style -- 使用 `gofmt`；项目在 `AGENTS.md` 明确要求“使用 gofmt 格式化”。 -- 代码风格遵循 Go 惯用法，避免 Java 式过度抽象；证据见 `AGENTS.md` 的“Go 惯用法 vs Java 风格”。 -- 仓库未检测到 `.golangci.yml`、`golangci-lint`、`eslint`、`prettier` 之类自动 lint 配置；当前质量门主要依赖 shell 脚本和人工审查。 -- `scripts/check-service-errors.sh`：扫描 `internal/service/**/*.go` 中的 `fmt.Errorf`，要求改用 `errors.New()` / `errors.Wrap()`。 -- `scripts/check-comment-paths.sh`：扫描 `internal/handler/` 中残留的 `/api/v1` 注释，要求改成真实路径 `/api/admin`、`/api/h5`、`/api/c/v1`。 -- `scripts/check-all.sh`：串行执行以上两个检查。 -- 当前仓库与脚本规则存在冲突：`internal/service/polling/alert_service.go` 仍存在 4 处 `fmt.Errorf(...)`，按 `scripts/check-service-errors.sh` 的规则属于违规现状。 -## Language & Comment Requirements -- 用户可见内容、日志、注释、文档、提交信息都使用中文；变量名、函数名、类型名使用英文，证据见 `AGENTS.md` 的“语言要求”。 -- 导出包、结构体、接口、函数、方法、常量、变量必须有中文文档注释，证据见 `AGENTS.md`。 -- Handler 方法注释必须包含 HTTP 方法与真实路径；实际示例见 `internal/handler/admin/account.go`、`internal/handler/callback/payment.go`。 -- 注释解释“为什么”，不要复述代码；复杂逻辑必须有实现注释，证据见 `AGENTS.md`。 -- 常量必须带中文注释；实际示例见 `pkg/constants/constants.go`、`pkg/constants/redis.go`。 -## Import Organization -- 多数组件按“标准库 → 项目包/第三方包”分组，并保留空行分隔，证据见 `internal/handler/admin/account.go`、`pkg/errors/handler.go`、`cmd/gendocs/main.go`。 -- 项目使用完整 module import path，未体现短别名路径；必要时用语义别名，例如 `apphandler`、`accountService`，证据见 `cmd/gendocs/main.go`、`internal/handler/admin/account.go`。 -- 未检测到 TS/JS 式路径别名；Go 代码通过 module path `github.com/break/junhong_cmp_fiber/...` 引用。 -## Layering Rules -- 必须遵循 `Handler → Service → Store → Model`，证据见 `AGENTS.md` 与 `README.md`。 -- Handler 只做参数解析、上下文读取、调用 service、返回统一响应；示例见 `internal/handler/admin/account.go`。 -- Service 承载业务逻辑，并向下调用 Store；项目规范在 `AGENTS.md` 明确禁止在 Handler 中写业务逻辑。 -- Store 负责数据访问和事务；规范说明见 `AGENTS.md`、`README.md`。 -- Model/DTO 定义请求、响应和持久化结构；OpenAPI 文档也依赖 DTO 元数据，证据见 `docs/api-documentation-guide.md`。 -## Error Handling -- 所有错误码与应用错误类型集中在 `pkg/errors/`，证据见 `pkg/errors/codes.go`、`pkg/errors/errors.go`、`pkg/errors/handler.go`、`AGENTS.md`。 -- Handler 层不要把底层错误直接暴露给客户端；参数校验失败统一返回 `errors.New(errors.CodeInvalidParam)` 或其中文变体，证据见 `AGENTS.md`、`internal/handler/admin/account.go`。 -- Service 层对外不要返回 `fmt.Errorf(...)`，要返回 `errors.New(...)` 或 `errors.Wrap(...)`；脚本 `scripts/check-service-errors.sh` 专门检查这一点。 -- 全局错误处理使用 `pkg/errors/handler.go` 的 `SafeErrorHandler()` / `handleError()`，统一输出 `{code, data, msg, timestamp}`，并按错误码映射 HTTP 状态码与日志级别。 -- 5xx 响应统一走通用中文消息，避免泄露敏感信息，证据见 `pkg/errors/handler.go`。 -- `pkg/errors/codes.go` 定义 1000-1999 客户端错误、2000-2999 服务端错误。 -- `pkg/errors/codes.go` 在 `init()` 校验全部错误码都必须映射消息，新增错误码时要同步维护 `allErrorCodes` 和 `errorMessages`。 -## Response Format -- 所有 API 成功响应统一使用 `pkg/response/response.go`：`{code, data, msg, timestamp}`。 -- `Success()` 返回 `msg: "success"`；`SuccessWithMessage()` 允许覆盖消息；`SuccessWithPagination()` 将分页数据包进 `PaginationData`。 -- Handler 成功路径直接调用 `response.Success()` / `response.SuccessWithPagination()`；实际示例见 `internal/handler/admin/account.go`、`internal/handler/admin/iot_card.go`、`internal/handler/admin/shop.go`。 -- 错误路径直接 `return err` 交给全局 ErrorHandler，不在 Handler 内手动拼接 JSON，证据见 `internal/handler/admin/account.go`、`pkg/errors/handler.go`。 -## Constant Management -- 所有常量统一放在 `pkg/constants/`，证据见 `AGENTS.md` 与 `pkg/constants/constants.go`、`pkg/constants/redis.go`。 -- 禁止硬编码字符串与 magic numbers；公共业务值放进 `pkg/constants/constants.go`。 -- Redis Key 必须通过函数生成，而不是手写字符串，命名格式使用 `Redis{Module}{Purpose}Key(...)`，证据见 `pkg/constants/redis.go` 与 `AGENTS.md`。 -- 常量要配中文注释；`pkg/constants/constants.go` 中的用户类型、任务类型、分页上限、默认管理员信息都按此方式组织。 -## API / OpenAPI Conventions -- 所有 HTTP 路由都应在 `internal/routes/*.go` 中通过 `Register()` 注册，不要直接 `router.Get/Post/...`，证据见 `docs/api-documentation-guide.md`、`internal/routes/registry.go`。 -- `Register()` 同时负责 Fiber 路由注册和 OpenAPI 生成；当 `doc != nil` 时，会把 `/:id` 转为 OpenAPI 的 `/{id}`，证据见 `internal/routes/registry.go`。 -- 每个接口需要提供中文 `Summary`，可选 Markdown `Description`，并声明 `Input`、`Output`、`Tags`、`Auth`；证据见 `internal/routes/registry.go`、`docs/api-documentation-guide.md`。 -- DTO 字段必须使用 `description` 标签，不依赖行尾注释；枚举字段要在 `description` 中列出可选值，证据见 `docs/api-documentation-guide.md`。 -- 新增 Handler 时，除业务接线外，还必须同步更新 `internal/bootstrap/types.go`、`internal/bootstrap/handlers.go`、`internal/routes/admin.go`、`cmd/api/docs.go`、`cmd/gendocs/main.go`，证据见 `docs/api-documentation-guide.md` 与 `AGENTS.md`。 -- 文档生成命令使用 `go run cmd/gendocs/main.go` 或 `make docs`；代码证据见 `cmd/gendocs/main.go`、`Makefile`。 -## Documentation Expectations -- 每个功能应在 `docs/{feature-id}/` 创建总结文档，并同步更新 `README.md`，证据见 `AGENTS.md`。 -- 文档和说明统一使用中文。 -- API 文档规范集中在 `docs/api-documentation-guide.md`；开发总规范集中在 `AGENTS.md`。 -- `README.md` 仍保留旧的自动化测试与覆盖率章节、旧项目结构中的 `tests/` 目录描述、以及“CI/CD 自动执行检查”的表述。 -- 当前仓库未发现任何 `*_test.go` 文件，也未发现 `tests/` 目录内容；因此后续文档和执行应优先遵循 `AGENTS.md` 的现行规则，而不是 `README.md` 中这些过期段落。 -## Operational Scripts -- `bash scripts/check-service-errors.sh`：检查 Service 层是否违规使用 `fmt.Errorf`。 -- `bash scripts/check-comment-paths.sh`：检查 Handler 注释路径是否残留 `/api/v1`。 -- `bash scripts/check-all.sh`：运行上述两个检查。 -- `make docs` → `go run cmd/gendocs/main.go`，用于生成 `docs/admin-openapi.yaml`，证据见 `Makefile`、`cmd/gendocs/main.go`。 -- `go run scripts/verify_migration/main.go`：这是一个面向数据库迁移结果的人工验证脚本，会直接连接数据库并查询字段，不是自动测试框架，证据见 `scripts/verify_migration/main.go`。 -- `Makefile` 的 `test` 目标仍定义为 `go test -v ./...`，但这反映的是旧工具入口，不代表当前团队允许自动化测试。 -## Module Design -- 构造函数使用 `NewXxx...`，例如 `NewAccountHandler()`、`NewGenerator()`。 -- Handler、response、errors、constants 都以小包单职责方式导出少量明确入口，证据见 `internal/handler/admin/account.go`、`pkg/response/response.go`、`pkg/errors/errors.go`。 -- 未检测到 JS/TS 式 barrel file；Go 通过包目录与导出符号组织模块。 -## Prescriptive Summary -- 写新 Handler 时：在 `internal/handler/...` 保持中文注释 + 英文标识符，只解析请求并调用 Service，成功统一走 `pkg/response/response.go`，失败直接返回 `error`。 -- 写新业务错误时：先在 `pkg/errors/codes.go` 注册错误码与中文消息，再用 `errors.New()` / `errors.Wrap()`。 -- 写新常量或 Redis Key 时：放入 `pkg/constants/`，并补中文注释与 Key 生成函数。 -- 写新 API 时：在 `internal/routes/*.go` 用 `Register()` + `RouteSpec` 注册，并同步更新 `cmd/api/docs.go` 与 `cmd/gendocs/main.go` 的文档 Handler 装配。 -- 运行规范检查时：优先使用 `scripts/check-*.sh` 与 `make docs`；不要把 `README.md` 中的测试/覆盖率描述当成当前执行标准。 - - - -## Architecture - -## Pattern Overview -- HTTP 入口与异步任务入口分离：`cmd/api/main.go` 负责 Fiber API，`cmd/worker/main.go` 负责 Asynq Worker 与轮询调度。 -- 依赖集中在 `internal/bootstrap/` 组装，再分发给 `internal/routes/`、`internal/handler/`、`internal/task/`。 -- 数据访问主要走 `internal/store/postgres/*.go`，模型与 DTO 分别位于 `internal/model/*.go` 与 `internal/model/dto/*.go`。 -- 路由注册统一经过 `internal/routes/registry.go` 的 `Register()`，同时驱动 Fiber 路由与 OpenAPI 元数据。 -- 多租户与权限控制主要依赖认证上下文 + Store 层显式过滤函数，而不是数据库外键或 ORM 关联。 -## Layers -- Purpose: 进程启动、基础设施初始化、依赖装配、生命周期管理。 -- Location: `cmd/api/main.go`, `cmd/worker/main.go`, `internal/bootstrap/*.go` -- Contains: 配置加载、日志、数据库、Redis、队列、对象存储、Gateway 客户端、Bootstrap 编排。 -- Depends on: `pkg/config`, `pkg/database`, `pkg/logger`, `pkg/queue`, `pkg/storage`, `internal/bootstrap` -- Used by: 整个应用进程。 -- Purpose: 路由域划分、认证挂载、HTTP 入参与响应封装、OpenAPI 文档注册。 -- Location: `internal/routes/*.go`, `internal/handler/**/*.go` -- Contains: `RegisterRoutesWithDoc()` 总入口、Admin/Auth/Personal 域路由、Fiber Handler。 -- Depends on: `internal/bootstrap.Handlers`, `internal/bootstrap.Middlewares`, `pkg/openapi`, `pkg/response` -- Used by: `cmd/api/main.go` -- Purpose: 业务规则、权限判断、事务编排、幂等、异步任务提交、跨模块协作。 -- Location: `internal/service/**/*.go` -- Contains: 账号、订单、套餐、轮询、设备、卡、认证、充值、佣金等服务。 -- Depends on: `internal/store/postgres`, `pkg/errors`, `pkg/middleware`, `pkg/queue`, `pkg/wechat`, `gorm.DB`, `redis.Client` -- Used by: Handler 层、Worker Bootstrap、Task Handler。 -- Purpose: SQL 查询、分页、显式数据权限过滤、缓存辅助、事务基础能力。 -- Location: `internal/store/store.go`, `internal/store/options.go`, `internal/store/postgres/*.go` -- Contains: 每个聚合的 PostgreSQL Store，例如 `internal/store/postgres/account_store.go`, `internal/store/postgres/order_store.go`。 -- Depends on: `gorm`, `redis`, `pkg/middleware/data_scope.go` -- Used by: Service 层、部分 Handler 组装期专用读模型。 -- Purpose: 持久化模型、DTO、常量化状态值、表名映射。 -- Location: `internal/model/*.go`, `internal/model/dto/*.go` -- Contains: `model.Account`, `model.Order`, `model.Shop`, `model.PollingConfig` 以及请求/响应 DTO。 -- Depends on: GORM tags、标准库类型。 -- Used by: Store、Service、Handler、OpenAPI 生成。 -- Purpose: Asynq 任务处理、轮询调度、定时任务、批处理导入。 -- Location: `internal/task/*.go`, `internal/polling/*.go`, `pkg/queue/*.go` -- Contains: `pkg/queue/handler.go` 任务注册器、`internal/task/polling_handler.go`、`internal/task/order_expire.go`、`internal/polling/scheduler.go`。 -- Depends on: Worker bootstrap 产出的 stores/services、Redis、Asynq、Gateway。 -- Used by: `cmd/worker/main.go` -## Data Flow -- HTTP 侧状态主要放在 PostgreSQL；请求态身份与数据权限范围放在 `context.Context`。 -- 高速状态、Token、轮询队列、并发信号量、下级店铺缓存放在 Redis，如 `pkg/auth/token.go`、`internal/polling/scheduler.go`、`internal/store/postgres/shop_store.go`。 -- 异步处理采用 Redis-backed Asynq 队列，由 `pkg/queue/client.go` 提交、`pkg/queue/server.go` 消费。 -## Key Abstractions -- Purpose: 启动期依赖编排结果。 -- Examples: `internal/bootstrap/bootstrap.go`, `internal/bootstrap/worker.go` -- Pattern: 显式依赖注入，不使用外部 DI 框架。 -- Purpose: 路由注册时的装配清单。 -- Examples: `internal/bootstrap/types.go`, `internal/bootstrap/handlers.go`, `internal/bootstrap/middlewares.go` -- Pattern: 结构体聚合所有已构造的 Handler 与 Middleware。 -- Purpose: 单次声明同时完成真实路由注册和 OpenAPI 元数据注册。 -- Examples: `internal/routes/registry.go`, `internal/routes/account.go`, `internal/routes/personal.go` -- Pattern: 代码即文档，DTO 驱动文档生成。 -- Purpose: Store 通用分页与排序选项。 -- Examples: `internal/store/options.go`, `internal/service/account/service.go`, `internal/service/order/service.go` -- Pattern: Service 先构造查询选项，再下传到 Store。 -- Purpose: 承载用户身份与可管理店铺范围，并在 Store 查询时执行过滤。 -- Examples: `pkg/middleware/auth.go`, `pkg/middleware/data_scope.go`, `internal/store/postgres/shop_store.go` -- Pattern: 中间件预计算 `SubordinateShopIDs`，Store 按字段类型显式调用 `ApplyShopFilter` / `ApplyEnterpriseFilter` / `ApplySellerShopFilter`。 -## Entry Points -- Location: `cmd/api/main.go` -- Triggers: `go run cmd/api/main.go`、API 容器启动。 -- Responsibilities: 加载配置、初始化基础设施、执行 `bootstrap.Bootstrap()`、创建 Fiber、注册中间件和路由、生成运行时 OpenAPI 文件 `logs/openapi.yaml`。 -- Location: `cmd/worker/main.go` -- Triggers: `go run cmd/worker/main.go`、Worker 容器启动。 -- Responsibilities: 初始化 Worker 依赖、执行 `bootstrap.BootstrapWorker()`、启动 Asynq Worker、启动轮询调度器和 Asynq Scheduler、优雅关闭。 -- Location: `cmd/gendocs/main.go` -- Triggers: 手动执行文档生成。 -- Responsibilities: 通过 `openapi.BuildDocHandlers()` + `routes.RegisterRoutesWithDoc()` 输出 `docs/admin-openapi.yaml`。 -## Routing Strategy -- `/api/auth`：统一后台/H5 认证，见 `internal/routes/auth.go` -- `/api/admin`：管理后台业务域，见 `internal/routes/admin.go` -- `/api/c/v1`：个人客户端域，见 `internal/routes/personal.go` -- `/api/callback`：支付回调，无认证，见 `internal/routes/order.go` 与 `internal/handler/callback/payment.go` -- 所有 HTTP 接口使用 `internal/routes/registry.go` 的 `Register()`，文档规范见 `docs/api-documentation-guide.md`。 -- `internal/routes/admin.go` 以 handler 是否为 `nil` 决定是否挂载模块，便于文档生成和裁剪。 -- `internal/routes/personal.go` 明确区分公开路由与认证路由，并依赖注册顺序确保公开接口不被 `Use()` 拦截。 -## Error Handling -- Handler 层只做参数解析与转发，返回 `pkg/errors` 中的 `AppError`，如 `internal/handler/admin/account.go`。 -- Service 层封装业务错误，不直接向外泄露底层错误文本，如 `internal/service/account/service.go`、`internal/service/order/service.go`。 -- Worker 任务记录结构化日志，并将可重试与不可重试逻辑写在处理器内部，如 `internal/task/order_expire.go`、`internal/task/polling_handler.go`。 -## Cross-Cutting Concerns -- `pkg/logger/logger.go` 初始化 App/Access 日志；`pkg/logger/middleware.go` 记录完整请求/响应摘要。 -- Fiber `BodyParser` / `QueryParser` + `validator.v10`，示例见 `internal/handler/auth/handler.go`。 -- 后台/H5 使用 Redis Token + `pkg/middleware/auth.go`；个人客户使用单独中间件，由 `internal/bootstrap/middlewares.go` 创建。 -- 路由元数据写在 `RouteSpec`；文档生成器依赖 `cmd/api/docs.go`、`cmd/gendocs/main.go`、`pkg/openapi/handlers.go` 三处手工维护 Handler 清单。 -- 模型显式声明 `TableName()` 与字段列名，如 `internal/model/account.go`, `internal/model/order.go`, `internal/model/shop.go`。 -- 数据库结构通过 `migrations/*.sql` 管理，`pkg/database/postgres.go` 明确禁用自动建表。 -## Architectural Deviations -- `README.md` 与 `openspec/config.yaml` 多处描述“GORM Callback 自动注入数据权限过滤”，但当前 `internal/bootstrap/bootstrap.go` 第 67 行明确写明“数据权限过滤已移至 Store 层显式调用 ApplyXxxFilter 函数”。当前保留的 GORM Callback 只有 `pkg/gorm/callback.go` 中的创建人/更新人自动填充。 -- `internal/bootstrap/handlers.go` 为客户端场景直接新建多个 Store 和一个 `client_order` Service，而不是完全只消费 `services` 聚合；这说明 Handler 装配阶段存在读模型/适配层级的额外拼装。 -- `internal/task/polling_handler.go` 在首次实名激活流程中先构造 Asynq 任务，但实际通过 Redis List `RPush` 提交，文件内注释明确写出“实际应该通过依赖注入 asynq.Client”；这是 Worker 流程中的特殊机制与待收敛点。 - - - -## GSD Workflow Enforcement - -Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync. - -Use these entry points: -- `/gsd:quick` for small fixes, doc updates, and ad-hoc tasks -- `/gsd:debug` for investigation and bug fixing -- `/gsd:execute-phase` for planned phase work - -Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it. - - - -## Developer Profile - -> Profile not yet configured. Run `/gsd:profile-user` to generate your developer profile. -> This section is managed by `generate-claude-profile` -- do not edit manually. - +**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md` \ No newline at end of file diff --git a/internal/model/dto/iot_card_dto.go b/internal/model/dto/iot_card_dto.go index 9c6d779..0bc6083 100644 --- a/internal/model/dto/iot_card_dto.go +++ b/internal/model/dto/iot_card_dto.go @@ -11,7 +11,7 @@ type ListStandaloneIotCardRequest struct { SeriesID *uint `json:"series_id" query:"series_id" description:"套餐系列ID"` ICCID string `json:"iccid" query:"iccid" validate:"omitempty,max=20" maxLength:"20" description:"ICCID(模糊查询)"` MSISDN string `json:"msisdn" query:"msisdn" validate:"omitempty,max=20" maxLength:"20" description:"卡接入号(模糊查询)"` - VirtualNo string `json:"virtual_no" query:"virtual_no" validate:"omitempty,max=50" maxLength:"50" description:"虚拟号(模糊查询)"` + IsStandalone *bool `json:"is_standalone" query:"is_standalone" description:"是否为独立卡(true:仅返回未绑定设备的卡, false:仅返回已绑定设备的卡, 不传:返回全部)"` BatchNo string `json:"batch_no" query:"batch_no" validate:"omitempty,max=100" maxLength:"100" description:"批次号"` PackageID *uint `json:"package_id" query:"package_id" description:"套餐ID"` IsDistributed *bool `json:"is_distributed" query:"is_distributed" description:"是否已分销 (true:已分销, false:未分销)"` @@ -50,6 +50,7 @@ type StandaloneIotCardResponse struct { SeriesName string `json:"series_name" description:"套餐系列名称"` FirstCommissionPaid bool `json:"first_commission_paid" description:"一次性佣金是否已发放"` AccumulatedRecharge int64 `json:"accumulated_recharge" description:"累计充值金额(分)"` + DeviceVirtualNo string `json:"device_virtual_no" description:"绑定设备的虚拟号（未绑定时为空字符串）"` CreatedAt time.Time `json:"created_at" description:"创建时间"` UpdatedAt time.Time `json:"updated_at" description:"更新时间"` } diff --git a/internal/model/iot_card.go b/internal/model/iot_card.go index b4d77d0..16f318f 100644 --- a/internal/model/iot_card.go +++ b/internal/model/iot_card.go @@ -53,6 +53,7 @@ type IotCard struct { Generation int `gorm:"column:generation;type:int;not null;default:1;comment:资产世代编号" json:"generation"` IsStandalone bool `gorm:"column:is_standalone;type:boolean;default:true;not null;comment:是否为独立卡(未绑定设备) 由触发器自动维护" json:"is_standalone"` VirtualNo string `gorm:"column:virtual_no;type:varchar(50);uniqueIndex:idx_iot_card_virtual_no,where:deleted_at IS NULL AND virtual_no IS NOT NULL AND virtual_no <> '';comment:虚拟号(可选，非空时全局唯一)" json:"virtual_no,omitempty"` + DeviceVirtualNo string `gorm:"column:device_virtual_no;type:varchar(100);not null;default:'';comment:绑定设备的虚拟号快照(未绑定时为空字符串)" json:"device_virtual_no"` LastGatewayReadingMB float64 `gorm:"column:last_gateway_reading_mb;type:float;not null;default:0;comment:上次轮询时网关返回的流量读数(MB)" json:"last_gateway_reading_mb"` } diff --git a/internal/service/device/binding.go b/internal/service/device/binding.go index 619f2db..1ed464e 100644 --- a/internal/service/device/binding.go +++ b/internal/service/device/binding.go @@ -6,6 +6,8 @@ import ( "github.com/break/junhong_cmp_fiber/internal/model" "github.com/break/junhong_cmp_fiber/internal/model/dto" "github.com/break/junhong_cmp_fiber/pkg/errors" + "github.com/break/junhong_cmp_fiber/pkg/logger" + "go.uber.org/zap" "gorm.io/gorm" ) @@ -115,6 +117,15 @@ func (s *Service) BindCard(ctx context.Context, deviceID uint, req *dto.BindCard return nil, err } + // 异步快照维护：更新卡上的设备虚拟号，失败不阻断主流程 + if updateErr := s.iotCardStore.UpdateDeviceVirtualNo(ctx, card.ID, device.VirtualNo); updateErr != nil { + logger.GetAppLogger().Warn("更新卡的设备虚拟号快照失败", + zap.Uint("card_id", card.ID), + zap.Uint("device_id", device.ID), + zap.Error(updateErr), + ) + } + return &dto.BindCardToDeviceResponse{ BindingID: binding.ID, Message: "绑定成功", @@ -142,6 +153,15 @@ func (s *Service) UnbindCard(ctx context.Context, deviceID uint, cardID uint) (* return nil, err } + // 解绑后清空卡的设备虚拟号快照，失败不阻断主流程 + if updateErr := s.iotCardStore.UpdateDeviceVirtualNo(ctx, cardID, ""); updateErr != nil { + logger.GetAppLogger().Warn("清空卡的设备虚拟号快照失败", + zap.Uint("card_id", cardID), + zap.Uint("device_id", deviceID), + zap.Error(updateErr), + ) + } + return &dto.UnbindCardFromDeviceResponse{ Message: "解绑成功", }, nil diff --git a/internal/service/iot_card/service.go b/internal/service/iot_card/service.go index 0535288..483a3ec 100644 --- a/internal/service/iot_card/service.go +++ b/internal/service/iot_card/service.go @@ -124,8 +124,8 @@ func (s *Service) ListStandalone(ctx context.Context, req *dto.ListStandaloneIot if req.MSISDN != "" { filters["msisdn"] = req.MSISDN } - if req.VirtualNo != "" { - filters["virtual_no"] = req.VirtualNo + if req.IsStandalone != nil { + filters["is_standalone"] = req.IsStandalone } if req.BatchNo != "" { filters["batch_no"] = req.BatchNo @@ -279,6 +279,7 @@ func (s *Service) toStandaloneResponse(card *model.IotCard, shopMap map[uint]str SeriesID: card.SeriesID, FirstCommissionPaid: card.FirstCommissionPaid, AccumulatedRecharge: card.AccumulatedRecharge, + DeviceVirtualNo: card.DeviceVirtualNo, CreatedAt: card.CreatedAt, UpdatedAt: card.UpdatedAt, } diff --git a/internal/store/postgres/iot_card_store.go b/internal/store/postgres/iot_card_store.go index c4a6f20..fb9f5c4 100644 --- a/internal/store/postgres/iot_card_store.go +++ b/internal/store/postgres/iot_card_store.go @@ -271,8 +271,7 @@ func (s *IotCardStore) ListStandalone(ctx context.Context, opts *store.QueryOpti func (s *IotCardStore) listStandaloneTwoPhase(ctx context.Context, opts *store.QueryOptions, filters map[string]any) ([]*model.IotCard, int64, error) { var total int64 - query := s.db.WithContext(ctx).Model(&model.IotCard{}). - Where("is_standalone = true") + query := s.db.WithContext(ctx).Model(&model.IotCard{}) // 应用数据权限过滤 query = middleware.ApplyShopFilter(ctx, query) query = s.applyStandaloneFilters(ctx, query, filters) @@ -333,8 +332,7 @@ func (s *IotCardStore) listStandaloneDefault(ctx context.Context, opts *store.Qu var cards []*model.IotCard var total int64 - query := s.db.WithContext(ctx).Model(&model.IotCard{}). - Where("is_standalone = true") + query := s.db.WithContext(ctx).Model(&model.IotCard{}) // 应用数据权限过滤 query = middleware.ApplyShopFilter(ctx, query) query = s.applyStandaloneFilters(ctx, query, filters) @@ -395,7 +393,7 @@ func (s *IotCardStore) listStandaloneParallel(ctx context.Context, opts *store.Q defer wg.Done() q := s.db.WithContext(ctx).Model(&model.IotCard{}). - Where("is_standalone = true AND deleted_at IS NULL AND shop_id = ?", sid) + Where("deleted_at IS NULL AND shop_id = ?", sid) q = s.applyStandaloneFilters(ctx, q, filters) var cards []*model.IotCard @@ -410,7 +408,7 @@ func (s *IotCardStore) listStandaloneParallel(ctx context.Context, opts *store.Q var count int64 if !hasCachedTotal { countQ := s.db.WithContext(ctx).Model(&model.IotCard{}). - Where("is_standalone = true AND deleted_at IS NULL AND shop_id = ?", sid) + Where("deleted_at IS NULL AND shop_id = ?", sid) countQ = s.applyStandaloneFilters(ctx, countQ, filters) if err := countQ.Count(&count).Error; err != nil { results[idx] = shopResult{err: err} @@ -609,9 +607,14 @@ func (s *IotCardStore) listStandaloneParallelTwoPhase(ctx context.Context, opts } // applyStandaloneFilters 应用独立卡列表的通用过滤条件 -// 注意：不包含 is_standalone、shop_id、deleted_at 条件（由调用方控制） +// 注意：不包含 shop_id、deleted_at 条件（由调用方控制） // 也不包含 subordinate_shop_ids（仅用于路由选择，不作为查询条件） +// is_standalone 仅在 filters["is_standalone"] 非 nil 时拼接（不传则不过滤） func (s *IotCardStore) applyStandaloneFilters(ctx context.Context, query *gorm.DB, filters map[string]any) *gorm.DB { + // is_standalone 为可选过滤条件，仅在明确传入时应用 + if isStandalone, ok := filters["is_standalone"].(*bool); ok && isStandalone != nil { + query = query.Where("is_standalone = ?", *isStandalone) + } // 子查询无需数据权限过滤（在不同表上执行） if status, ok := filters["status"].(int); ok && status > 0 { @@ -823,6 +826,24 @@ func (s *IotCardStore) GetByIDsWithEnterpriseFilter(ctx context.Context, cardIDs return cards, nil } +// UpdateDeviceVirtualNo 更新卡的设备虚拟号快照 +// 绑定设备时写入 virtual_no，解绑时写入空字符串 +func (s *IotCardStore) UpdateDeviceVirtualNo(ctx context.Context, cardID uint, deviceVirtualNo string) error { + return s.db.WithContext(ctx).Model(&model.IotCard{}). + Where("id = ?", cardID). + Update("device_virtual_no", deviceVirtualNo).Error +} + +// BatchUpdateDeviceVirtualNo 批量更新卡的设备虚拟号快照（设备导入时使用） +func (s *IotCardStore) BatchUpdateDeviceVirtualNo(ctx context.Context, cardIDs []uint, deviceVirtualNo string) error { + if len(cardIDs) == 0 { + return nil + } + return s.db.WithContext(ctx).Model(&model.IotCard{}). + Where("id IN ?", cardIDs). + Update("device_virtual_no", deviceVirtualNo).Error +} + // BatchUpdateSeriesID 批量更新卡的套餐系列ID // 用于批量设置或清除卡与套餐系列的关联关系 func (s *IotCardStore) BatchUpdateSeriesID(ctx context.Context, cardIDs []uint, seriesID *uint) error { diff --git a/internal/task/device_import.go b/internal/task/device_import.go index 1ad77fc..943bb01 100644 --- a/internal/task/device_import.go +++ b/internal/task/device_import.go @@ -276,6 +276,7 @@ func (h *DeviceImportHandler) processBatch(ctx context.Context, task *model.Devi err := h.db.Transaction(func(tx *gorm.DB) error { txDeviceStore := postgres.NewDeviceStore(tx, nil) txBindingStore := postgres.NewDeviceSimBindingStore(tx, nil) + txIotCardStore := postgres.NewIotCardStore(tx, nil) device := &model.Device{ VirtualNo: row.VirtualNo, @@ -314,6 +315,13 @@ func (h *DeviceImportHandler) processBatch(ctx context.Context, task *model.Devi } } + // 批量更新卡的设备虚拟号快照（与绑定记录在同一事务中执行） + if len(validCardIDs) > 0 { + if err := txIotCardStore.BatchUpdateDeviceVirtualNo(ctx, validCardIDs, device.VirtualNo); err != nil { + return err + } + } + txWalletStore := postgres.NewAssetWalletStore(tx, nil) deviceWallet := &model.AssetWallet{ ResourceType: constants.AssetWalletResourceTypeDevice, diff --git a/migrations/000110_add_device_virtual_no_to_iot_card.down.sql b/migrations/000110_add_device_virtual_no_to_iot_card.down.sql new file mode 100644 index 0000000..1c80ca9 --- /dev/null +++ b/migrations/000110_add_device_virtual_no_to_iot_card.down.sql @@ -0,0 +1 @@ +ALTER TABLE tb_iot_card DROP COLUMN IF EXISTS device_virtual_no; diff --git a/migrations/000110_add_device_virtual_no_to_iot_card.up.sql b/migrations/000110_add_device_virtual_no_to_iot_card.up.sql new file mode 100644 index 0000000..0ab59fe --- /dev/null +++ b/migrations/000110_add_device_virtual_no_to_iot_card.up.sql @@ -0,0 +1,13 @@ +-- 新增设备虚拟号快照列 +ALTER TABLE tb_iot_card + ADD COLUMN IF NOT EXISTS device_virtual_no VARCHAR(100) NOT NULL DEFAULT ''; + +-- 回填现有已绑定卡的设备虚拟号 +UPDATE tb_iot_card c +SET device_virtual_no = d.virtual_no +FROM tb_device_sim_binding b +JOIN tb_device d ON d.id = b.device_id +WHERE b.iot_card_id = c.id + AND b.bind_status = 1 + AND b.deleted_at IS NULL + AND d.deleted_at IS NULL; diff --git a/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/.openspec.yaml b/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/.openspec.yaml new file mode 100644 index 0000000..98d7681 --- /dev/null +++ b/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-09 diff --git a/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/design.md b/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/design.md new file mode 100644 index 0000000..84fae36 --- /dev/null +++ b/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/design.md @@ -0,0 +1,92 @@ +## Context + +当前 `tb_iot_card` 表有 `is_standalone` 物化列（由 DB 触发器维护），`ListStandalone` 查询硬编码 `WHERE is_standalone = true`，导致绑定设备的卡不可见。设备表 `tb_device` 有 `virtual_no` 字段，设备与卡的绑定关系存于 `tb_device_sim_binding`。 + +`is_standalone` 的引入背景是：30M 行表上 `NOT EXISTS` 子查询造成 9s+ 延迟，物化为布尔列后降至 <500ms。本次新增 `device_virtual_no` 采用相同的物化快照思路，避免 JOIN `tb_device_sim_binding` + `tb_device` 带来的性能回退。 + +## Goals / Non-Goals + +**Goals:** +- 列表/详情接口展示绑定设备的 IoT 卡 +- 列表/详情响应新增 `device_virtual_no` 字段 +- `is_standalone` 作为可选查询参数（不传返回全部卡） +- 移除列表接口的 `virtual_no` 查询参数 +- 绑定/解绑/设备导入时同步维护 `device_virtual_no` 快照 + +**Non-Goals:** +- 修改路由名称（保持 `/api/admin/iot-cards/standalone`） +- 改变已绑定设备的卡不可单独分配/回收的限制 +- 支持通过设备虚拟号搜索卡（`device_virtual_no` 不作为搜索条件） +- 使用 DB 触发器维护 `device_virtual_no`（应用层维护） + +## Decisions + +### 决策 1：快照字段存在 `tb_iot_card`，由应用层维护 + +**选择：** 在 `tb_iot_card` 新增 `device_virtual_no VARCHAR(100) NOT NULL DEFAULT ''`，应用层在 BindCard / UnbindCard / device_import 时写入/清空。 + +**备选方案：** +- **DB 触发器**：`is_standalone` 使用触发器因为纯粹基于 `tb_device_sim_binding` 状态，`device_virtual_no` 需要跨表读 `tb_device.virtual_no`，触发器可以做但调试难度高、出错难追溯。 +- **每次 JOIN 查询**：不引入新列，查询时 JOIN。百万级数据下分页列表性能不可接受，违背 `is_standalone` 的设计初衷。 + +**结论：** 应用层快照，写入路径明确（3 处），可读性和可维护性优于触发器。 + +### 决策 2：`is_standalone` 改为可选过滤参数，Store 层支持 + +**选择：** `ListStandaloneIotCardRequest` 新增 `IsStandalone *bool`，Store 层 `ListStandalone` 仅在非 nil 时加条件，不传则不过滤。 + +**理由：** 最小改动，前端可按需传 `is_standalone=true` 保留原有"只看独立卡"场景。 + +### 决策 3：写入时机覆盖全部 3 个入口 + +| 入口 | 文件 | 操作 | +|------|------|------| +| `BindCard` | `internal/service/device/binding.go` | 事务外：`UPDATE tb_iot_card SET device_virtual_no = ? WHERE id = ?` | +| `UnbindCard` | `internal/service/device/binding.go` | 事务外：`UPDATE tb_iot_card SET device_virtual_no = '' WHERE id = ?` | +| 设备导入 | `internal/task/device_import.go` | 事务内：批量 `UPDATE tb_iot_card SET device_virtual_no = ? WHERE id IN (?)` | + +**说明：** BindCard / UnbindCard 中更新卡字段无需在事务内（绑定记录已提交），失败仅影响展示字段，不影响业务一致性；设备导入在事务内批量更新效率更高。 + +### 决策 4：Store 层新增 `UpdateDeviceVirtualNo` 方法 + +在 `IotCardStore` 新增： +```go +// UpdateDeviceVirtualNo 更新卡的设备虚拟号快照 +func (s *IotCardStore) UpdateDeviceVirtualNo(ctx context.Context, cardID uint, deviceVirtualNo string) error +// BatchUpdateDeviceVirtualNo 批量更新卡的设备虚拟号快照（设备导入时使用） +func (s *IotCardStore) BatchUpdateDeviceVirtualNo(ctx context.Context, cardIDs []uint, deviceVirtualNo string) error +``` + +Device Service 需要注入 `IotCardStore`（目前已有），通过该方法更新，不直接操作 GORM。 + +## Risks / Trade-offs + +**[快照不一致]** 极端情况下（写 BindCard 成功但更新 `device_virtual_no` 失败）会出现短暂不一致。 +→ 缓解：日志记录失败，不 panic；最终一致性由运维工具或重新触发绑定修复。实际概率极低（同一进程内两次 DB 写入）。 + +**[历史数据回填]** 迁移 SQL 执行期间可能短暂锁表（大表 UPDATE）。 +→ 缓解：使用 `UPDATE ... WHERE device_virtual_no = ''` 分批或一次性（数据量视实际情况），低峰期执行。 + +**[Device Service 依赖 IotCardStore]** device binding.go 需要调用 IotCardStore 方法，形成跨 Service 包的 Store 依赖。 +→ 接受：当前 `device.Service` 已注入 `iotCardStore`（用于绑定验证），添加新方法调用不引入新依赖。 + +## Migration Plan + +1. 执行新迁移：`ALTER TABLE tb_iot_card ADD COLUMN device_virtual_no VARCHAR(100) NOT NULL DEFAULT ''` +2. 回填数据： + ```sql + UPDATE tb_iot_card c + SET device_virtual_no = d.virtual_no + FROM tb_device_sim_binding b + JOIN tb_device d ON d.id = b.device_id + WHERE b.iot_card_id = c.id + AND b.bind_status = 1 + AND b.deleted_at IS NULL + AND d.deleted_at IS NULL; + ``` +3. 部署新代码（BindCard / UnbindCard / device_import 均写入快照） +4. 回滚：删除列即可（`ALTER TABLE tb_iot_card DROP COLUMN device_virtual_no`），代码回滚到旧版本 + +## Open Questions + +无。所有关键决策已在探索阶段与用户确认。 diff --git a/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/proposal.md b/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/proposal.md new file mode 100644 index 0000000..37a13d1 --- /dev/null +++ b/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/proposal.md @@ -0,0 +1,42 @@ +## Why + +`/api/admin/iot-cards/standalone` 当前使用硬编码 `WHERE is_standalone = true` 过滤，导致已绑定设备的 IoT 卡完全不可见。运营人员无法在卡管列表中看到这些卡，也无法通过列表查询某张卡目前归属于哪台设备，造成管理盲区。 + +## What Changes + +- **移除硬编码 `is_standalone = true` 过滤**：`is_standalone` 改为可选查询参数，不传时返回全部卡（含绑定设备的卡） +- **移除 `virtual_no` 列表过滤参数**：不再支持按卡虚拟号模糊搜索 +- **新增 `device_virtual_no` 冗余快照字段**：在 `tb_iot_card` 表新增 `device_virtual_no` 列，记录当前绑定设备的虚拟号（无绑定时为空字符串） +- **响应新增 `device_virtual_no` 字段**：列表和详情接口均返回对应的设备虚拟号 +- **写入时机快照**：BindCard / UnbindCard / 设备导入（device_import）时同步写入或清空该字段 + +## Capabilities + +### New Capabilities + +- `iot-card-device-snapshot`：IoT 卡列表展示绑定设备虚拟号的能力——包括 `device_virtual_no` 快照字段的数据库维护、列表/详情响应扩展、以及 `is_standalone` 可选过滤。 + +### Modified Capabilities + +（无现有 spec 级别的行为变更，仅实现层调整） + +## Impact + +**数据库** +- `tb_iot_card` 新增列 `device_virtual_no VARCHAR(100) NOT NULL DEFAULT ''` +- 迁移时回填现有绑定数据 + +**API** +- `GET /api/admin/iot-cards/standalone` + - 查询参数：移除 `virtual_no`，新增 `is_standalone`（可选布尔） + - 响应：新增 `device_virtual_no` 字段 +- `GET /api/admin/iot-cards/standalone/:iccid`（详情） + - 响应：新增 `device_virtual_no` 字段 + +**代码** +- `internal/model/iot_card.go`：新增字段 +- `internal/model/dto/iot_card_dto.go`：修改 Request / Response DTO +- `internal/store/postgres/iot_card_store.go`：移除硬编码过滤，支持可选 `is_standalone` 条件 +- `internal/service/iot_card/service.go`：传递新过滤参数，填充响应字段 +- `internal/service/device/binding.go`：BindCard / UnbindCard 时更新卡字段 +- `internal/task/device_import.go`：导入时批量写入 `device_virtual_no` diff --git a/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/specs/iot-card-device-snapshot/spec.md b/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/specs/iot-card-device-snapshot/spec.md new file mode 100644 index 0000000..efe85e8 --- /dev/null +++ b/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/specs/iot-card-device-snapshot/spec.md @@ -0,0 +1,59 @@ +## ADDED Requirements + +### Requirement: IoT 卡列表展示绑定设备的虚拟号 +`tb_iot_card` 表 SHALL 新增 `device_virtual_no VARCHAR(100) NOT NULL DEFAULT ''` 列，存储当前绑定设备的虚拟号快照。未绑定设备时该字段为空字符串。列表和详情接口 SHALL 在响应中返回 `device_virtual_no` 字段。 + +#### Scenario: 未绑定设备的卡响应 device_virtual_no 为空 +- **WHEN** 请求 `GET /api/admin/iot-cards/standalone` 列表 +- **THEN** `is_standalone = true` 的卡响应中 `device_virtual_no` 为空字符串 `""` + +#### Scenario: 已绑定设备的卡响应包含设备虚拟号 +- **WHEN** 请求 `GET /api/admin/iot-cards/standalone` 列表（不带 `is_standalone` 参数） +- **THEN** `is_standalone = false` 的卡也出现在结果中，且 `device_virtual_no` 等于绑定设备的 `virtual_no` + +#### Scenario: 详情接口包含设备虚拟号 +- **WHEN** 请求 `GET /api/admin/iot-cards/standalone/:iccid` 且该卡绑定了设备 +- **THEN** 响应中 `device_virtual_no` 等于绑定设备的 `virtual_no` + +### Requirement: `is_standalone` 作为可选查询参数 +列表接口 `GET /api/admin/iot-cards/standalone` SHALL 接受可选布尔参数 `is_standalone`。不传时 SHALL 返回全部卡（含绑定设备的卡）；传 `true` 时仅返回未绑定设备的卡；传 `false` 时仅返回已绑定设备的卡。 + +#### Scenario: 不传 is_standalone 返回全部卡 +- **WHEN** 请求列表且不携带 `is_standalone` 参数 +- **THEN** 返回结果包含独立卡和绑定设备的卡 + +#### Scenario: 传 is_standalone=true 仅返回独立卡 +- **WHEN** 请求列表携带 `is_standalone=true` +- **THEN** 返回结果只包含 `is_standalone = true` 的卡 + +#### Scenario: 传 is_standalone=false 仅返回绑定卡 +- **WHEN** 请求列表携带 `is_standalone=false` +- **THEN** 返回结果只包含 `is_standalone = false` 的卡 + +### Requirement: 移除列表接口的 virtual_no 查询参数 +`GET /api/admin/iot-cards/standalone` 请求 SHALL NOT 再接受 `virtual_no` 查询参数。 + +#### Scenario: 传入 virtual_no 参数不产生过滤效果 +- **WHEN** 请求列表携带 `virtual_no=xxx` +- **THEN** 参数被忽略，接口正常返回全部卡（不报错，不过滤） + +### Requirement: 绑定设备时快照写入 device_virtual_no +执行 `BindCard`（POST `/api/admin/devices/:virtual_no/cards`）成功后，系统 SHALL 将被绑定卡的 `device_virtual_no` 更新为设备的 `virtual_no`。 + +#### Scenario: 绑卡后卡的 device_virtual_no 被写入 +- **WHEN** 成功调用 BindCard 将 IoT 卡绑定到设备 +- **THEN** `tb_iot_card.device_virtual_no` = 对应设备的 `virtual_no` + +### Requirement: 解绑设备时清空 device_virtual_no +执行 `UnbindCard`（DELETE `/api/admin/devices/:virtual_no/cards/:iccid`）成功后，系统 SHALL 将被解绑卡的 `device_virtual_no` 清空为空字符串。 + +#### Scenario: 解绑后卡的 device_virtual_no 被清空 +- **WHEN** 成功调用 UnbindCard 将 IoT 卡从设备解绑 +- **THEN** `tb_iot_card.device_virtual_no` = `""` + +### Requirement: 设备导入时批量快照 device_virtual_no +设备导入任务处理成功绑定关系后，系统 SHALL 批量将被绑定卡的 `device_virtual_no` 更新为该设备的 `virtual_no`。 + +#### Scenario: 设备导入时绑定的卡 device_virtual_no 被写入 +- **WHEN** 设备导入 Excel 中某行包含设备虚拟号和一组 ICCID，导入任务处理成功 +- **THEN** 该组 ICCID 对应卡的 `device_virtual_no` = 设备的 `virtual_no` diff --git a/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/tasks.md b/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/tasks.md new file mode 100644 index 0000000..42da210 --- /dev/null +++ b/openspec/changes/archive/2026-04-09-feat-iot-card-device-virtual-no/tasks.md @@ -0,0 +1,39 @@ +## 1. 数据库迁移 + +- [x] 1.1 新建迁移文件 `migrations/000110_add_device_virtual_no_to_iot_card.up.sql`，添加 `device_virtual_no VARCHAR(100) NOT NULL DEFAULT ''` 列，并附回填 SQL（JOIN `tb_device_sim_binding` + `tb_device` 更新现有绑定数据） +- [x] 1.2 新建对应 down 文件 `migrations/000110_add_device_virtual_no_to_iot_card.down.sql`，执行 `DROP COLUMN device_virtual_no` +- [x] 1.3 执行迁移：`make migrate-up`，确认列存在且回填数据正确 + +## 2. Model 层 + +- [x] 2.1 在 `internal/model/iot_card.go` 的 `IotCard` 结构体新增字段 `DeviceVirtualNo string`，添加正确的 GORM tag 和中文注释 + +## 3. Store 层 + +- [x] 3.1 在 `internal/store/postgres/iot_card_store.go` 的 `ListStandalone` 方法中，将硬编码的 `WHERE is_standalone = true` 改为：仅当 filters["is_standalone"] 非 nil 时才拼接该条件 +- [x] 3.2 在 `IotCardStore` 新增方法 `UpdateDeviceVirtualNo(ctx, cardID uint, deviceVirtualNo string) error`，使用 GORM `Updates` 单卡更新 +- [x] 3.3 在 `IotCardStore` 新增方法 `BatchUpdateDeviceVirtualNo(ctx, cardIDs []uint, deviceVirtualNo string) error`，使用 GORM `WHERE id IN (?)` 批量更新 + +## 4. DTO 层 + +- [x] 4.1 在 `internal/model/dto/iot_card_dto.go` 的 `ListStandaloneIotCardRequest` 中：删除 `VirtualNo` 字段，新增 `IsStandalone *bool` 字段（含 query tag 和 description） +- [x] 4.2 在 `StandaloneIotCardResponse` 中新增 `DeviceVirtualNo string` 字段（含 json tag 和 description） + +## 5. Service 层 - IoT 卡列表 + +- [x] 5.1 在 `internal/service/iot_card/service.go` 的 `ListStandalone` 方法中：删除对 `req.VirtualNo` 的处理，改为读取 `req.IsStandalone` 并写入 `filters["is_standalone"]` +- [x] 5.2 在 `toStandaloneResponse` 方法中新增 `DeviceVirtualNo: card.DeviceVirtualNo` 字段赋值 + +## 6. Service 层 - 绑定/解绑快照 + +- [x] 6.1 在 `internal/service/device/binding.go` 的 `BindCard` 方法中，绑定记录创建成功后，调用 `s.iotCardStore.UpdateDeviceVirtualNo(ctx, card.ID, device.VirtualNo)`；失败仅记录 warn 日志，不阻断主流程 +- [x] 6.2 在 `internal/service/device/binding.go` 的 `UnbindCard` 方法中，解绑成功后，调用 `s.iotCardStore.UpdateDeviceVirtualNo(ctx, cardID, "")`；失败仅记录 warn 日志，不阻断主流程 + +## 7. Task 层 - 设备导入快照 + +- [x] 7.1 在 `internal/task/device_import.go` 的事务块内，创建绑定记录后，收集所有 `validCardIDs`，调用 `h.iotCardStore.BatchUpdateDeviceVirtualNo(ctx, validCardIDs, device.VirtualNo)`（在同一事务中执行） + +## 8. 构建验证 + +- [x] 8.1 运行 `go build ./...` 确认无编译错误 +- [x] 8.2 运行 `bash scripts/check-all.sh` 确认无规范违规（check 失败项为已有历史问题，本次变更未引入新违规） diff --git a/openspec/specs/iot-card-device-snapshot/spec.md b/openspec/specs/iot-card-device-snapshot/spec.md new file mode 100644 index 0000000..efe85e8 --- /dev/null +++ b/openspec/specs/iot-card-device-snapshot/spec.md @@ -0,0 +1,59 @@ +## ADDED Requirements + +### Requirement: IoT 卡列表展示绑定设备的虚拟号 +`tb_iot_card` 表 SHALL 新增 `device_virtual_no VARCHAR(100) NOT NULL DEFAULT ''` 列，存储当前绑定设备的虚拟号快照。未绑定设备时该字段为空字符串。列表和详情接口 SHALL 在响应中返回 `device_virtual_no` 字段。 + +#### Scenario: 未绑定设备的卡响应 device_virtual_no 为空 +- **WHEN** 请求 `GET /api/admin/iot-cards/standalone` 列表 +- **THEN** `is_standalone = true` 的卡响应中 `device_virtual_no` 为空字符串 `""` + +#### Scenario: 已绑定设备的卡响应包含设备虚拟号 +- **WHEN** 请求 `GET /api/admin/iot-cards/standalone` 列表（不带 `is_standalone` 参数） +- **THEN** `is_standalone = false` 的卡也出现在结果中，且 `device_virtual_no` 等于绑定设备的 `virtual_no` + +#### Scenario: 详情接口包含设备虚拟号 +- **WHEN** 请求 `GET /api/admin/iot-cards/standalone/:iccid` 且该卡绑定了设备 +- **THEN** 响应中 `device_virtual_no` 等于绑定设备的 `virtual_no` + +### Requirement: `is_standalone` 作为可选查询参数 +列表接口 `GET /api/admin/iot-cards/standalone` SHALL 接受可选布尔参数 `is_standalone`。不传时 SHALL 返回全部卡（含绑定设备的卡）；传 `true` 时仅返回未绑定设备的卡；传 `false` 时仅返回已绑定设备的卡。 + +#### Scenario: 不传 is_standalone 返回全部卡 +- **WHEN** 请求列表且不携带 `is_standalone` 参数 +- **THEN** 返回结果包含独立卡和绑定设备的卡 + +#### Scenario: 传 is_standalone=true 仅返回独立卡 +- **WHEN** 请求列表携带 `is_standalone=true` +- **THEN** 返回结果只包含 `is_standalone = true` 的卡 + +#### Scenario: 传 is_standalone=false 仅返回绑定卡 +- **WHEN** 请求列表携带 `is_standalone=false` +- **THEN** 返回结果只包含 `is_standalone = false` 的卡 + +### Requirement: 移除列表接口的 virtual_no 查询参数 +`GET /api/admin/iot-cards/standalone` 请求 SHALL NOT 再接受 `virtual_no` 查询参数。 + +#### Scenario: 传入 virtual_no 参数不产生过滤效果 +- **WHEN** 请求列表携带 `virtual_no=xxx` +- **THEN** 参数被忽略，接口正常返回全部卡（不报错，不过滤） + +### Requirement: 绑定设备时快照写入 device_virtual_no +执行 `BindCard`（POST `/api/admin/devices/:virtual_no/cards`）成功后，系统 SHALL 将被绑定卡的 `device_virtual_no` 更新为设备的 `virtual_no`。 + +#### Scenario: 绑卡后卡的 device_virtual_no 被写入 +- **WHEN** 成功调用 BindCard 将 IoT 卡绑定到设备 +- **THEN** `tb_iot_card.device_virtual_no` = 对应设备的 `virtual_no` + +### Requirement: 解绑设备时清空 device_virtual_no +执行 `UnbindCard`（DELETE `/api/admin/devices/:virtual_no/cards/:iccid`）成功后，系统 SHALL 将被解绑卡的 `device_virtual_no` 清空为空字符串。 + +#### Scenario: 解绑后卡的 device_virtual_no 被清空 +- **WHEN** 成功调用 UnbindCard 将 IoT 卡从设备解绑 +- **THEN** `tb_iot_card.device_virtual_no` = `""` + +### Requirement: 设备导入时批量快照 device_virtual_no +设备导入任务处理成功绑定关系后，系统 SHALL 批量将被绑定卡的 `device_virtual_no` 更新为该设备的 `virtual_no`。 + +#### Scenario: 设备导入时绑定的卡 device_virtual_no 被写入 +- **WHEN** 设备导入 Excel 中某行包含设备虚拟号和一组 ICCID，导入任务处理成功 +- **THEN** 该组 ICCID 对应卡的 `device_virtual_no` = 设备的 `virtual_no`