junhong_cmp_fiber/openspec/changes/fix-device-sim-binding-issues/design.md

# 设计文档：修复设备-SIM卡绑定隐患

## Context

### 当前状态

设备-SIM卡绑定功能在 `iot-device` 能力中实现，涉及以下核心组件：

| 组件 | 文件 | 职责 |
|------|------|------|
| 绑定模型 | `internal/model/package.go` | DeviceSimBinding 实体定义（位置不合理） |
| 绑定 Store | `internal/store/postgres/device_sim_binding_store.go` | 数据访问层 |
| 绑定 Service | `internal/service/device/binding.go` | BindCard/UnbindCard 业务逻辑 |
| 设备导入 | `internal/task/device_import.go` | 异步批量导入设备并绑定卡 |

### 现有数据库约束

```sql
-- 已存在：防止同一张卡同时绑定到多个设备
CREATE UNIQUE INDEX idx_device_sim_bindings_active_card 
ON tb_device_sim_binding(iot_card_id) WHERE bind_status = 1;

-- 缺失：防止同一设备插槽绑定多张卡
-- 无 (device_id, slot_position) 的唯一约束
```

### 约束条件

1. 必须向后兼容，不影响现有数据
2. 不能长时间锁表影响生产环境
3. 错误信息必须对用户友好（中文）
4. 遵循项目的分层架构规范

## Goals / Non-Goals

**Goals:**
- 防止并发场景下的数据完整性问题（竞态条件）
- 导入时确保卡与设备归属权一致
- 提供清晰的部分成功反馈机制
- 优化代码组织结构

**Non-Goals:**
- 不改变现有的绑定/解绑 API 接口定义
- 不实现乐观锁或分布式锁（数据库约束已足够）
- 不修改设备分销（AllocateDevices）的逻辑（它已正确同步卡归属）

## Decisions

### Decision 1: 数据库层面防止插槽竞态条件

**方案**: 新增部分唯一索引 `idx_active_device_slot`

```sql
CREATE UNIQUE INDEX idx_active_device_slot 
ON tb_device_sim_binding (device_id, slot_position) 
WHERE bind_status = 1 AND deleted_at IS NULL;
```

**理由**:
- 数据库级约束是最可靠的并发保护
- 部分索引只针对活动绑定，不影响历史数据
- PostgreSQL 原生支持部分唯一索引，性能优秀
- 无需修改应用层事务逻辑

**备选方案**:
1. ~~应用层分布式锁~~ - 引入额外复杂性，Redis 故障会影响可用性
2. ~~SELECT FOR UPDATE~~ - 需要事务包装，增加代码复杂度

### Decision 2: 应用层正确处理唯一约束错误

**方案**: 在 Store 层检测 PostgreSQL 唯一约束冲突错误码，返回业务错误

```go
// device_sim_binding_store.go
func (s *DeviceSimBindingStore) Create(ctx context.Context, binding *model.DeviceSimBinding) error {
    err := s.db.WithContext(ctx).Create(binding).Error
    if err != nil {
        if isUniqueViolation(err) {
            // 根据违反的约束名判断是哪种冲突
            if strings.Contains(err.Error(), "idx_active_device_slot") {
                return errors.New(errors.CodeConflict, "该插槽已有绑定的卡")
            }
            if strings.Contains(err.Error(), "idx_device_sim_bindings_active_card") {
                return errors.New(errors.CodeIotCardBoundToDevice, "该卡已绑定到其他设备")
            }
        }
        return err
    }
    return nil
}

func isUniqueViolation(err error) bool {
    var pgErr *pgconn.PgError
    if stderrors.As(err, &pgErr) {
        return pgErr.Code == "23505" // unique_violation
    }
    return false
}
```

**理由**:
- PostgreSQL 错误码 `23505` 是唯一约束冲突的标准码
- 在 Store 层处理保持分层架构清晰
- 返回业务错误码，对用户友好

### Decision 3: 导入时的归属权校验策略

**方案**: 导入时只允许绑定"平台库存"的卡（shop_id = NULL）

**规则**:
1. 设备导入默认为平台库存（shop_id = NULL）
2. 只能绑定 shop_id = NULL 的卡
3. 如果卡已分配给店铺（shop_id != NULL），拒绝绑定并记录原因

```go
// 归属权校验逻辑
for _, iccid := range row.ICCIDs {
    card, exists := existingCards[iccid]
    if !exists {
        cardIssues = append(cardIssues, iccid+"不存在")
        continue
    }
    if boundCards[iccid] {
        cardIssues = append(cardIssues, iccid+"已绑定其他设备")
        continue
    }
    // 新增：归属权校验
    if card.ShopID != nil {
        cardIssues = append(cardIssues, iccid+"已分配给店铺,不能绑定到平台库存设备")
        continue
    }
    validCardIDs = append(validCardIDs, card.ID)
}
```

**理由**:
- 保持数据一致性：平台库存设备只能绑定平台库存卡
- 避免后续分销时出现归属权混乱
- 明确拒绝而非静默忽略，便于用户排查问题

**备选方案**:
1. ~~自动将卡的 shop_id 更新为 NULL~~ - 改变卡的归属权会影响代理商数据
2. ~~允许绑定任意卡，分销时修复~~ - 在分销前系统状态不一致

### Decision 4: 部分成功的反馈机制

**方案**: 新增 `warning_count` 和 `warning_items` 字段

**模型变更**:
```go
type DeviceImportTask struct {
    // ... 现有字段
    WarningCount int                `gorm:"column:warning_count;comment:警告数量" json:"warning_count"`
    WarningItems ImportResultItems  `gorm:"column:warning_items;type:jsonb;comment:警告记录详情" json:"warning_items"`
}
```

**结果分类**:
| 类型 | 条件 | 字段 |
|------|------|------|
| 完全成功 | 设备创建且所有指定的卡都绑定成功 | success_count++ |
| 部分成功 | 设备创建但部分卡绑定失败 | success_count++, warning_count++, warning_items 记录失败的卡 |
| 跳过 | 设备已存在 | skip_count++, skipped_items |
| 失败 | 设备创建失败或所有卡都不可用 | fail_count++, failed_items |

**反馈示例**:
```json
{
  "total_count": 100,
  "success_count": 95,
  "warning_count": 3,
  "skip_count": 1,
  "fail_count": 1,
  "warning_items": [
    {"line": 5, "device_no": "DEV-005", "reason": "部分卡绑定失败: ICCID-002已分配给店铺,不能绑定到平台库存设备"},
    {"line": 12, "device_no": "DEV-012", "reason": "部分卡绑定失败: ICCID-008不存在, ICCID-009已绑定其他设备"}
  ]
}
```

### Decision 5: 模型文件组织

**方案**: 将 `DeviceSimBinding` 移动到独立文件

- 从: `internal/model/package.go`
- 到: `internal/model/device_sim_binding.go`

**理由**:
- `package.go` 应只包含与套餐相关的模型
- 每个模型独立文件便于维护和查找
- 与项目中其他模型的组织方式一致

## Risks / Trade-offs

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 索引创建锁表 | 生产环境短暂阻塞写入 | 使用 `CREATE INDEX CONCURRENTLY` 避免锁表 |
| 现有数据违反新约束 | 索引创建失败 | 迁移前检查并清理重复数据（预计不存在） |
| 导入归属权校验过严 | 用户需要先确保卡在平台库存 | 在错误信息中明确说明原因和解决方法 |
| API 响应结构变更 | 老版本客户端可能不识别新字段 | 新字段为可选，不影响现有解析逻辑 |

## Migration Plan

### 数据库迁移

**迁移文件**: `migrations/000XXX_fix_device_sim_binding_constraints.up.sql`

```sql
-- 使用 CONCURRENTLY 避免锁表
CREATE UNIQUE INDEX CONCURRENTLY idx_active_device_slot 
ON tb_device_sim_binding (device_id, slot_position) 
WHERE bind_status = 1 AND deleted_at IS NULL;

-- 为导入任务表添加警告字段
ALTER TABLE tb_device_import_task 
ADD COLUMN warning_count INT NOT NULL DEFAULT 0,
ADD COLUMN warning_items JSONB;

COMMENT ON COLUMN tb_device_import_task.warning_count IS '警告数量（部分成功的设备）';
COMMENT ON COLUMN tb_device_import_task.warning_items IS '警告记录详情';
```

### 回滚策略

```sql
-- down.sql
DROP INDEX IF EXISTS idx_active_device_slot;

ALTER TABLE tb_device_import_task 
DROP COLUMN IF EXISTS warning_count,
DROP COLUMN IF EXISTS warning_items;
```

### 部署步骤

1. **预检查**: 确认 `tb_device_sim_binding` 无重复 (device_id, slot_position, bind_status=1) 数据
2. **执行迁移**: 在低峰期执行数据库迁移
3. **部署代码**: 更新应用代码
4. **验证**: 测试绑定 API 和导入功能

## Open Questions

1. **是否需要清理现有的重复绑定数据?**
   - 需要在迁移前检查是否存在违反新约束的数据
   - 如果存在，需要决定如何处理（保留最新的？手动确认？）

2. **警告信息是否需要国际化?**
   - 当前设计使用中文错误信息
   - 如果需要多语言支持，需要调整错误码机制