# Change: 账号与佣金管理模块 - 数据模型变更

## Why

账号与佣金管理模块需要扩展现有数据模型以支持以下业务场景：
1. 佣金提现申请需要记录完整的审批流程信息（提现单号、申请人、处理人等）
2. 店铺主账号标识，用于在代理商列表中显示主账号信息
3. 企业客户卡授权机制，允许企业"看到"代理商的卡而不改变归属
4. 卡/设备归属体系统一，简化 `owner_type` 枚举值

这是账号与佣金管理模块的**基础依赖提案**，后续所有功能提案都依赖此数据模型变更。

## What Changes

### 1. 表字段新增

#### 1.1 `tb_commission_withdrawal_request` 佣金提现申请表
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `withdrawal_no` | varchar(50) | 提现单号（唯一，格式：W + 时间戳 + 随机数） |
| `applicant_id` | uint | 申请人账号ID |
| `shop_id` | uint | 店铺ID（冗余字段） |
| `fee_rate` | int64 | 手续费比率（基点，100=1%，快照） |
| `payment_type` | varchar(20) | 放款类型（manual=人工打款） |
| `processor_id` | uint | 处理人ID |
| `processed_at` | timestamp | 处理时间 |
| `remark` | text | 备注 |

#### 1.2 `tb_account` 账号表
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `is_primary` | boolean | 是否为店铺主账号（默认 false） |

#### 1.3 `tb_commission_record` 佣金记录表
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `shop_id` | uint | 店铺ID（佣金主要跟着店铺走） |
| `balance_after` | int64 | 入账后佣金余额（分） |

#### 1.4 `tb_commission_withdrawal_setting` 提现设置表
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `daily_withdrawal_limit` | int | 每日提现次数限制 |

#### 1.5 `tb_iot_card` 物联网卡表
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `shop_id` | uint | 店铺ID（冗余字段，方便查询） |

#### 1.6 `tb_device` 设备表
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `shop_id` | uint | 店铺ID（冗余字段，方便查询） |

### 2. 新增表

#### 2.1 `tb_enterprise_card_authorization` 企业卡授权表
用于记录企业被授权可见的卡。**这是企业查看卡的唯一途径，不改变卡的归属**。

```sql
CREATE TABLE tb_enterprise_card_authorization (
    id BIGSERIAL PRIMARY KEY,
    enterprise_id BIGINT NOT NULL,
    iot_card_id BIGINT NOT NULL,
    shop_id BIGINT NOT NULL,
    authorized_by BIGINT NOT NULL,
    authorized_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    status INT DEFAULT 1,  -- 1=有效, 0=已回收
    creator BIGINT,
    updater BIGINT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    deleted_at TIMESTAMP WITH TIME ZONE,
    CONSTRAINT uk_enterprise_card UNIQUE(enterprise_id, iot_card_id)
);
```

#### 2.2 `tb_asset_allocation_record` 资产分配记录表
用于记录卡/设备在平台和代理商之间流转的历史。

```sql
CREATE TABLE tb_asset_allocation_record (
    id BIGSERIAL PRIMARY KEY,
    allocation_no VARCHAR(50) NOT NULL UNIQUE,
    allocation_type VARCHAR(20) NOT NULL,  -- allocate/recall
    asset_type VARCHAR(20) NOT NULL,       -- iot_card/device
    asset_id BIGINT NOT NULL,
    asset_identifier VARCHAR(50) NOT NULL,
    from_owner_type VARCHAR(20),
    from_owner_id BIGINT,
    to_owner_type VARCHAR(20) NOT NULL,
    to_owner_id BIGINT NOT NULL,
    related_device_id BIGINT,
    related_card_ids JSONB,
    operator_id BIGINT NOT NULL,
    remark TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    deleted_at TIMESTAMP WITH TIME ZONE
);
```

### 3. 枚举值统一

**`owner_type` 字段值变更**（`tb_iot_card` 和 `tb_device` 表）：

| 旧值 | 新值 | 说明 |
|------|------|------|
| `platform` | `platform` | 不变 |
| `agent` | `shop` | 统一命名 |
| `user` | 废弃 | 不再使用 |
| `device` | 废弃 | 不再使用 |

## Impact

### 影响的规范
- **新增 Capability**：`commission-model`（佣金数据模型）
- **修改 Capability**：`iot-card`（新增 `shop_id` 字段）
- **修改 Capability**：`iot-device`（新增 `shop_id` 字段）

### 影响的代码

**迁移文件**（新增）：
- `migrations/XXXXXX_add_commission_model_changes.up.sql`
- `migrations/XXXXXX_add_commission_model_changes.down.sql`

**Model 文件**（修改）：
- `internal/model/commission.go`（新增字段）
- `internal/model/account.go`（新增 `is_primary` 字段）
- `internal/model/iot_card.go`（新增 `shop_id` 字段）
- `internal/model/device.go`（新增 `shop_id` 字段）

**Model 文件**（新增）：
- `internal/model/enterprise_card_authorization.go`
- `internal/model/asset_allocation_record.go`

**常量文件**（修改）：
- `pkg/constants/owner_type.go`（统一枚举值）

### 兼容性

- **BREAKING**：`owner_type` 枚举值变更（`agent` → `shop`），需要数据迁移
- 数据库迁移需要更新现有数据的 `owner_type` 值
- 现有代码中引用 `agent` 的地方需要改为 `shop`

### 风险评估

- **中等风险**：涉及数据迁移和枚举值变更
- **缓解措施**：
  1. 迁移脚本包含数据转换逻辑
  2. 提供回滚脚本
  3. 在测试环境充分验证

## Dependencies

- 无外部依赖
- 后续提案依赖此提案：
  - `add-shop-commission-query`
  - `add-commission-withdrawal-approval`
  - `add-commission-withdrawal-settings`
  - `add-enterprise-management`
  - `add-enterprise-card-authorization`
  - `add-customer-account-management`
  - `add-my-commission`

## Testing Strategy

1. **迁移测试**：
   - 验证 up 迁移成功执行
   - 验证 down 迁移可以回滚
   - 验证数据转换正确（`agent` → `shop`）

2. **Model 测试**：
   - 新增字段可正常读写
   - 新增表 CRUD 操作正常

## Documentation

- 更新 `README.md` 数据模型说明
- 在 `docs/` 目录创建数据模型变更说明