csxj2026/junhong_cmp_fiber

Files

构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 4m35s

Details

新增功能：
- 店铺佣金查询：店铺佣金统计、店铺佣金记录列表、店铺提现记录
- 佣金提现审批：提现申请列表、审批通过、审批拒绝
- 提现配置管理：配置列表、新增配置、获取当前生效配置
- 企业管理：企业列表、创建、更新、删除、获取详情
- 企业卡授权：授权列表、批量授权、批量取消授权、统计
- 客户账号管理：账号列表、创建、更新状态、重置密码
- 我的佣金：佣金统计、佣金记录、提现申请、提现记录

数据库变更：
- 扩展 tb_commission_withdrawal_request 新增提现单号等字段
- 扩展 tb_account 新增 is_primary 字段
- 扩展 tb_commission_record 新增 shop_id、balance_after
- 扩展 tb_commission_withdrawal_setting 新增每日提现次数限制
- 扩展 tb_iot_card、tb_device 新增 shop_id 冗余字段
- 新建 tb_enterprise_card_authorization 企业卡授权表
- 新建 tb_asset_allocation_record 资产分配记录表
- 数据迁移：owner_type 枚举值 agent 统一为 shop

测试：
- 新增 7 个单元测试文件覆盖各服务
- 修复集成测试 Redis 依赖问题

2026-01-21 18:20:44 +08:00

54 KiB

Raw Blame History

账号与佣金管理模块需求规划

文档版本：v1.2 创建时间：2026-01-21 更新时间：2026-01-21 状态：✅ 已确认所有核心问题

一、总体概述

1.1 模块范围

本次需求涵盖以下功能模块：

模块	说明
账号管理-代理商(店铺)管理	查看代理商佣金信息、佣金提现记录、佣金明细
账号管理-佣金提现	佣金提现申请审批流程（放款/拒绝）
佣金提现设置	全局提现规则配置（次数、金额、手续费）
账号管理-企业客户管理	企业CRUD、卡分配/回收、启用禁用
账号管理-客户账号管理	代理商+企业客户的账号统一管理
财务-我的账号	当前登录账号的佣金数据查询

1.2 核心概念说明

概念	系统模型	说明
代理商/店铺	`Shop`	同一概念，代码中使用 Shop
代理账号	`Account` (UserType=3)	店铺下的员工账号
店铺主账号	`Account` (is_primary=true)	创建店铺时同步创建的账号，每个店铺有且仅有一个
企业客户	`Enterprise`	B端企业客户
企业账号	`Account` (UserType=4)	企业的登录账号
佣金钱包	`Wallet` (WalletType=commission)	店铺级别的佣金钱包

1.3 数据权限规则

角色	数据可见范围
平台用户	全部数据
代理商用户	自己店铺 + 下级店铺 + 归属的企业客户数据
企业用户	仅自己企业数据

二、数据模型变更

2.1 需要新增的字段

2.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	备注	否

2.1.2 `tb_account` 表新增字段

字段名	类型	说明	是否必填
`is_primary`	boolean	是否为店铺主账号（创建店铺时同步创建的账号）	否，默认false

说明：

每个店铺有且仅有一个主账号（is_primary=true）
创建店铺时自动创建的账号设置为主账号
主账号不可删除，只能禁用
未来销售系统会通过账号关联佣金归属

2.1.3 `tb_commission_record` 表新增字段

字段名	类型	说明	是否必填
`shop_id`	uint	店铺ID（冗余字段，佣金主要跟着店铺走）	是

说明：

佣金本质上跟着店铺走
同时保留 agent_id（账号ID），未来可支持查看某销售的佣金情况
佣金明细查询主要基于 shop_id

2.1.4 `tb_commission_withdrawal_setting` 表新增字段

字段名	类型	说明	是否必填
`daily_withdrawal_limit`	int	每日提现次数限制（每个代理商）	是

2.1.5 `tb_iot_card` 表新增字段

字段名	类型	说明	是否必填
`shop_id`	uint	店铺ID（冗余字段，owner_type=shop时等于owner_id）	否

2.1.6 `tb_device` 表新增字段

字段名	类型	说明	是否必填
`shop_id`	uint	店铺ID（冗余字段，owner_type=shop时等于owner_id）	否

2.1.7 `tb_commission_record` 表新增字段（补充）

字段名	类型	说明	是否必填
`balance_after`	int64	入账后佣金余额（分），创建时计算：本次佣金 + 历史累计佣金	是

2.1.8 `tb_iot_card` 和 `tb_device` 表 `owner_type` 统一

当前值：platform, agent, user, device

统一为：platform, shop

旧值	新值	说明
`platform`	`platform`	平台库存（不变）
`agent`	`shop`	代理商持有（统一命名）
`user`	废弃	不再使用
`device`	废弃	不再使用

核心设计：

卡/设备只在平台和代理商之间流转
owner_type=shop + owner_id=店铺ID 表示代理商持有
企业看到的卡是通过"授权"实现的，不改变归属

2.2 需要新增的表

2.2.1 `tb_enterprise_card_authorization` 企业-卡授权表（核心）

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

CREATE TABLE tb_enterprise_card_authorization (
    id BIGSERIAL PRIMARY KEY,
    enterprise_id BIGINT NOT NULL,                       -- 企业ID
    iot_card_id BIGINT NOT NULL,                         -- 卡ID
    shop_id BIGINT NOT NULL,                             -- 卡所属店铺ID（冗余，方便查询和权限校验）
    authorized_by BIGINT NOT NULL,                       -- 授权人账号ID
    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)
);

CREATE INDEX idx_eca_enterprise ON tb_enterprise_card_authorization(enterprise_id, status) WHERE deleted_at IS NULL;
CREATE INDEX idx_eca_card ON tb_enterprise_card_authorization(iot_card_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_eca_shop ON tb_enterprise_card_authorization(shop_id) WHERE deleted_at IS NULL;

核心设计说明：

卡的归属（owner）始终是代理商店铺，不会变成企业
企业通过授权表"看到"被授权的卡
授权是永久的，回收时更新 status=0
设备通过卡的授权间接可见（不需要单独的设备授权表）

2.2.2 `tb_asset_allocation_record` 资产分配记录表

用于记录卡/设备在平台和代理商之间流转的历史。

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,                            -- 资产ID
    asset_identifier VARCHAR(50) NOT NULL,               -- 资产标识（ICCID或设备号，方便查询）
    
    from_owner_type VARCHAR(20),                         -- 原归属类型
    from_owner_id BIGINT,                                -- 原归属ID
    to_owner_type VARCHAR(20) NOT NULL,                  -- 目标归属类型：platform/shop
    to_owner_id BIGINT NOT NULL,                         -- 目标归属ID
    
    related_device_id BIGINT,                            -- 关联设备ID（卡分配时如果绑定了设备）
    related_card_ids JSONB,                              -- 关联卡ID列表（设备分配时包含的卡）
    
    operator_id BIGINT NOT NULL,                         -- 操作人ID
    remark TEXT,                                         -- 备注
    
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    deleted_at TIMESTAMP WITH TIME ZONE
);

CREATE INDEX idx_asset_allocation_asset ON tb_asset_allocation_record(asset_type, asset_id);
CREATE INDEX idx_asset_allocation_to_owner ON tb_asset_allocation_record(to_owner_type, to_owner_id);
CREATE INDEX idx_asset_allocation_created ON tb_asset_allocation_record(created_at);

2.3 卡/设备归属与授权体系（已确认）

2.3.1 核心设计原则

┌─────────────────────────────────────────────────────────────────┐
│                    归属 vs 授权 - 核心区别                        │
└─────────────────────────────────────────────────────────────────┘

【归属流转】改变 owner_type/owner_id，涉及真实的资产转移：
    平台 (platform) ──分配──→ 代理商 (shop)

【授权可见】不改变归属，只是让企业"能看到"：
    代理商的卡 ──授权──→ 企业可见（通过授权表）

owner_type 只有两种值：

platform - 平台库存
shop - 代理商持有

企业不拥有卡：

企业看到的卡仍然属于代理商
企业通过 tb_enterprise_card_authorization 表获得可见性
授权是永久的，回收时更新状态

2.3.2 数据权限过滤修改

需要修改 pkg/gorm/callback.go，对 tb_iot_card 表做特殊处理：

// 企业用户查询 IotCard 时的特殊处理
if userType == constants.UserTypeEnterprise && tableName == "tb_iot_card" {
    enterpriseID := middleware.GetEnterpriseIDFromContext(ctx)
    if enterpriseID != 0 {
        // 企业用户只能看到被授权的卡
        tx.Where("id IN (SELECT iot_card_id FROM tb_enterprise_card_authorization WHERE enterprise_id = ? AND status = 1 AND deleted_at IS NULL)", enterpriseID)
    } else {
        tx.Where("1 = 0")
    }
    return
}

// 代理用户查询 IotCard 时，使用 shop_id 字段过滤
if userType == constants.UserTypeAgent && tableName == "tb_iot_card" {
    // 使用新增的 shop_id 冗余字段
    tx.Where("shop_id IN ?", subordinateShopIDs)
    return
}

2.3.3 分配/授权规则

场景	操作	说明
平台 → 代理商	修改 `owner_type=shop`, `owner_id=shop_id`, `shop_id=shop_id`	真实的归属转移
代理商 → 企业	创建 `tb_enterprise_card_authorization` 记录	只是授权可见，不改变归属
企业 → 代理商回收	更新授权表 `status=0`	取消授权
代理商 → 平台回收	修改 `owner_type=platform`, `shop_id=NULL`	同时清理相关授权记录

2.3.4 设备可见性（通过卡间接查询）

企业查询设备时，不直接查设备表，而是：

查询企业被授权的卡
通过 DeviceSimBinding 表关联到设备
返回设备信息

-- 企业可见的设备（通过卡间接查询）
SELECT DISTINCT d.*
FROM tb_device d
INNER JOIN tb_device_sim_binding dsb ON d.id = dsb.device_id AND dsb.bind_status = 1
INNER JOIN tb_enterprise_card_authorization eca ON dsb.iot_card_id = eca.iot_card_id
WHERE eca.enterprise_id = ? AND eca.status = 1 AND eca.deleted_at IS NULL;

2.4 卡/设备分配详细方案（已确认）

2.4.1 分配交互流程

┌─────────────────────────────────────────────────────────────────┐
│                    卡分配给企业流程                              │
└─────────────────────────────────────────────────────────────────┘

用户选择ICCID列表 → 调用预检接口 → 展示分配预览 → 用户确认 → 执行分配
                         │
                         ▼
              ┌─────────────────────┐
              │ 检查每张卡是否绑定设备 │
              └──────────┬──────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
    ┌────▼────┐    ┌─────▼─────┐   ┌─────▼─────┐
    │ 未绑定设备 │    │ 绑定了设备  │   │ 卡不存在   │
    │          │    │           │   │ /无权限    │
    └────┬────┘    └─────┬─────┘   └─────┬─────┘
         │               │               │
         │               ▼               │
         │    ┌─────────────────┐        │
         │    │ 查询设备绑定的   │        │
         │    │ 所有卡列表       │        │
         │    └────────┬────────┘        │
         │             │                 │
         ▼             ▼                 ▼
    ┌─────────────────────────────────────────┐
    │           返回分配预览结果               │
    │ - 可直接分配的卡                         │
    │ - 需要整体分配的设备（含所有卡）          │
    │ - 失败的卡（不存在/无权限）              │
    └─────────────────────────────────────────┘

2.4.2 新增接口：分配预检

接口路径：POST /api/admin/enterprises/:id/allocate-cards/preview

接口说明：预检要分配的卡，返回分配预览信息供用户确认

请求参数：

参数名	类型	必填	说明
id	uint	是	企业ID（路径参数）
iccids	[]string	是	需要分配的ICCID列表

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "standalone_cards": [                         // 可直接分配的卡（未绑定设备）
      {
        "iccid": "89860001234567890123",
        "msisdn": "1440012345678",
        "carrier_name": "中国移动"
      }
    ],
    "device_bundles": [                           // 需要整体分配的设备包
      {
        "device_no": "DEV001",
        "device_name": "测试设备1",
        "trigger_iccid": "89860001234567890124",  // 触发整体分配的卡
        "cards": [                                 // 设备下所有卡
          {
            "iccid": "89860001234567890124",
            "msisdn": "1440012345679",
            "is_trigger": true                    // 是用户选择的卡
          },
          {
            "iccid": "89860001234567890125",
            "msisdn": "1440012345680",
            "is_trigger": false                   // 连带分配的卡
          },
          {
            "iccid": "89860001234567890126",
            "msisdn": "1440012345681",
            "is_trigger": false
          }
        ]
      }
    ],
    "failed_items": [                             // 失败的卡
      {
        "iccid": "89860001234567890127",
        "reason": "卡不存在"
      },
      {
        "iccid": "89860001234567890128",
        "reason": "无权限操作该卡"
      }
    ],
    "summary": {
      "standalone_card_count": 1,
      "device_count": 1,
      "device_card_count": 3,
      "total_card_count": 4,                      // 将要分配的总卡数
      "failed_count": 2
    }
  }
}

前端交互建议：

用户选择ICCID后，先调用预检接口
展示分配预览：
- "将分配 1 张独立卡"
- "将分配 1 台设备（含 3 张卡），因为您选择的卡 xxx 绑定在该设备上"
- "2 张卡分配失败：xxx（卡不存在）、xxx（无权限）"
用户确认后，调用正式分配接口

2.4.3 授权确认接口调整

接口路径：POST /api/admin/enterprises/:id/allocate-cards

请求参数：

参数名	类型	必填	说明
id	uint	是	企业ID（路径参数）
iccids	[]string	是	需要授权的ICCID列表（与预检相同）
confirm_device_bundles	bool	是	确认整体授权设备下所有卡（必须为true才执行）

说明：

这是"授权"操作，不是"转移归属"
授权后卡仍然属于代理商，企业只是能看到和操作
confirm_device_bundles=true 表示用户已确认整体授权设备下所有卡

接口逻辑调整：

验证企业存在且归属于当前代理商（或其下级）
验证卡属于当前代理商（shop_id 在可见范围内）
如果卡绑定了设备，获取设备下所有卡一起授权
创建授权记录到 tb_enterprise_card_authorization 表（不修改卡的 owner）
返回授权结果

三、接口设计

3.1 账号管理-代理商(店铺)管理

3.1.1 代理商分页列表查询

接口路径：GET /api/admin/shops/commission-summary

接口说明：查询代理商列表及其佣金汇总信息

请求参数：

参数名	类型	必填	说明
page	int	否	页码，默认1
page_size	int	否	每页数量，默认20，最大100
shop_name	string	否	店铺名称（模糊查询）
username	string	否	代理商账号用户名（模糊查询）

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "shop_id": 1,
        "shop_name": "某某代理商",
        "shop_code": "SHOP001",
        "username": "agent001",                    // 店铺主账号用户名
        "phone": "13800138000",                    // 店铺主账号手机号
        "total_commission": 100000,                // 总佣金（分）
        "withdrawn_commission": 50000,             // 已提现佣金（分）
        "unwithdraw_commission": 50000,            // 未提现佣金（分）= 总佣金 - 已提现
        "frozen_commission": 10000,                // 冻结中佣金（分）
        "withdrawing_commission": 5000,            // 提现中佣金（分）= 待审批的提现申请金额
        "available_commission": 35000              // 可提现佣金（分）= 未提现 - 冻结 - 提现中
      }
    ],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

接口逻辑：

根据当前用户权限过滤店铺列表（平台看全部，代理看自己+下级）
查询店铺基本信息
关联查询店铺的主账号（is_primary=true 的账号）
计算佣金汇总：
- total_commission：从 Wallet (shop类型, commission钱包) 的 balance + frozen_balance + 已提现金额
- withdrawn_commission：从 CommissionWithdrawalRequest 统计 status=2(已通过) 的总金额
- frozen_commission：Wallet.frozen_balance
- withdrawing_commission：从 CommissionWithdrawalRequest 统计 status=1(待审批) 的总金额
- available_commission：Wallet.balance - withdrawing_commission

主账号说明：

每个店铺有且仅有一个主账号（is_primary=true）
创建店铺时自动创建的账号即为主账号
这里显示主账号的信息（username、phone）

3.1.2 佣金提现分页列表（代理商维度）

接口路径：GET /api/admin/shops/:shop_id/withdrawal-requests

接口说明：查询指定代理商的佣金提现记录

请求参数：

参数名	类型	必填	说明
shop_id	uint	是	店铺ID（路径参数）
page	int	否	页码，默认1
page_size	int	否	每页数量，默认20
withdrawal_no	string	否	提现单号（精确查询）
start_time	string	否	申请开始时间（ISO8601）
end_time	string	否	申请结束时间（ISO8601）

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "withdrawal_no": "W20260121143000001",     // 提现单号
        "shop_name": "某某代理商",
        "shop_hierarchy": "上上级代理_上级代理_某某代理商",  // 层级路径：本身往上最多两层（不含平台）
        "applicant_name": "张三",                   // 申请人姓名（账号username）
        "amount": 10000,                           // 提现金额（分）
        "fee_rate": 100,                           // 手续费比率（基点，100=1%）
        "fee": 100,                                // 手续费金额（分）
        "actual_amount": 9900,                     // 实际到账金额（分）
        "status": 1,                               // 状态：1=待审批,2=已通过,3=已拒绝,4=已放款
        "status_name": "待审批",
        "created_at": "2026-01-21T14:30:00+08:00", // 申请时间
        "withdrawal_method": "alipay",             // 收款类型
        "account_name": "张三",                    // 收款人姓名
        "account_number": "zhangsan@alipay.com",   // 支付宝账号
        "payment_type": "manual",                  // 放款类型
        "payment_type_name": "人工打款",
        "processor_name": "管理员",                 // 处理人姓名
        "processed_at": "2026-01-21T15:00:00+08:00", // 处理时间
        "remark": "备注信息"
      }
    ],
    "total": 50,
    "page": 1,
    "page_size": 20
  }
}

接口逻辑：

验证当前用户有权限查看该店铺
查询 CommissionWithdrawalRequest 表，过滤 shop_id
关联查询店铺信息、申请人信息、处理人信息
计算店铺层级路径：
- 从当前店铺往上最多查两层
- 格式：上上级_上级_本身（用下划线分隔）
- 如果只有一层上级：上级_本身
- 如果是一级代理（无上级）：本身
- 不包含平台

3.1.3 佣金明细分页查询（代理商维度）

接口路径：GET /api/admin/shops/:shop_id/commission-records

接口说明：查询指定代理商的佣金入账明细

请求参数：

参数名	类型	必填	说明
shop_id	uint	是	店铺ID（路径参数）
page	int	否	页码，默认1
page_size	int	否	每页数量，默认20
commission_type	string	否	佣金类型：one_time/long_term
iccid	string	否	ICCID（模糊查询）
device_no	string	否	设备号（模糊查询）
order_no	string	否	订单号（模糊查询）

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "shop_name": "某某代理商",
        "order_no": "ORD20260121001",              // 订单号
        "device_no": "DEV001",                     // 设备号（可能为空）
        "iccid": "89860001234567890123",           // ICCID（可能为空）
        "order_created_at": "2026-01-20T10:00:00+08:00", // 下单时间
        "commission_type": "one_time",             // 佣金类型
        "commission_type_name": "一次性佣金",
        "amount": 500,                             // 入账佣金（分）
        "balance_after": 10500,                    // 入账后佣金余额（分）
        "status": 3,                               // 状态：1=冻结,2=解冻中,3=已发放,4=已失效
        "status_name": "已发放",
        "created_at": "2026-01-21T10:00:00+08:00"  // 佣金记录创建时间
      }
    ],
    "total": 200,
    "page": 1,
    "page_size": 20
  }
}

接口逻辑：

验证当前用户有权限查看该店铺
查询 CommissionRecord 表，直接通过 shop_id 过滤（已确认新增该字段）
关联查询 Order 表获取订单号、下单时间
通过 Order.iot_card_id 关联 IotCard 获取 ICCID
通过 Order.device_id 关联 Device 获取设备号
balance_after 需要从 WalletTransaction 中获取

数据关联说明：

CommissionRecord 同时存储 agent_id（账号ID）和 shop_id（店铺ID）
佣金明细查询主要基于 shop_id
保留 agent_id 用于未来支持查看某销售的佣金情况

3.2 账号管理-佣金提现

3.2.1 佣金提现申请分页查询列表

接口路径：GET /api/admin/commission/withdrawal-requests

接口说明：查询所有待处理的佣金提现申请（审批列表）

请求参数：

参数名	类型	必填	说明
page	int	否	页码，默认1
page_size	int	否	每页数量，默认20
status	int	否	状态：1=待审批,2=已通过,3=已拒绝,4=已放款
withdrawal_no	string	否	提现单号（精确查询）
shop_name	string	否	店铺名称（模糊查询）
start_time	string	否	申请开始时间（ISO8601）
end_time	string	否	申请结束时间（ISO8601）

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "withdrawal_no": "W20260121143000001",
        "shop_id": 5,
        "shop_name": "某某代理商",
        "shop_hierarchy": "上上级代理_上级代理_某某代理商",  // 本身往上最多两层
        "applicant_id": 10,
        "applicant_name": "张三",
        "amount": 10000,
        "fee_rate": 100,
        "fee": 100,
        "actual_amount": 9900,
        "status": 1,
        "status_name": "待审批",
        "created_at": "2026-01-21T14:30:00+08:00",
        "withdrawal_method": "alipay",
        "withdrawal_method_name": "支付宝",
        "account_name": "张三",
        "account_number": "zhangsan@alipay.com",
        "payment_type": "manual",
        "payment_type_name": "人工打款",
        "processor_id": null,
        "processor_name": null,
        "processed_at": null,
        "remark": null
      }
    ],
    "total": 10,
    "page": 1,
    "page_size": 20
  }
}

接口逻辑：

根据当前用户权限过滤数据
支持多条件组合查询
按申请时间倒序排列

3.2.2 审批通过

接口路径：POST /api/admin/commission/withdrawal-requests/:id/approve

接口说明：审批通过提现申请（实际打款由人工线下完成）

请求参数：

参数名	类型	必填	说明
id	uint	是	提现申请ID（路径参数）
payment_type	string	是	放款类型：manual=人工打款
amount	int64	否	修正后的提现金额（分），不传则使用原金额
withdrawal_method	string	否	修正后的收款类型，不传则使用原值
account_name	string	否	修正后的收款人姓名，不传则使用原值
account_number	string	否	修正后的收款账号，不传则使用原值
remark	string	否	备注

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "withdrawal_no": "W20260121143000001",
    "status": 2,
    "status_name": "已通过",
    "processed_at": "2026-01-21T15:00:00+08:00"
  }
}

接口逻辑：

验证提现申请存在且状态为待审批
验证当前用户有审批权限
如果修正了金额，重新计算手续费和实际到账金额
更新提现申请状态为已通过（status=2）
从店铺佣金钱包扣除对应金额（解冻并扣除）
记录钱包交易流水
记录处理人和处理时间

审批流程说明：

审批只有一步：待审批(1) → 已通过(2) 或已拒绝(3)
审批通过后，系统自动扣除佣金
实际打款由人工在线下完成（目前只支持人工打款）
状态流转：1(待审批) → 2(已通过) → 人工线下打款

3.2.3 拒绝（审批拒绝）

接口路径：POST /api/admin/commission/withdrawal-requests/:id/reject

接口说明：拒绝提现申请

请求参数：

参数名	类型	必填	说明
id	uint	是	提现申请ID（路径参数）
remark	string	是	拒绝原因

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "withdrawal_no": "W20260121143000001",
    "status": 3,
    "status_name": "已拒绝",
    "processed_at": "2026-01-21T15:00:00+08:00"
  }
}

接口逻辑：

验证提现申请存在且状态为待审批
验证当前用户有审批权限
更新提现申请状态为已拒绝
解冻店铺佣金钱包中的冻结金额
记录钱包交易流水
记录处理人、处理时间和拒绝原因

3.3 佣金提现设置

3.3.1 新增佣金提现设置

接口路径：POST /api/admin/commission/withdrawal-settings

接口说明：新增全局佣金提现配置（新配置生效后旧配置自动失效）

请求参数：

参数名	类型	必填	说明
daily_withdrawal_limit	int	是	每日提现次数限制（每个代理商）
min_withdrawal_amount	int64	是	提现最低金额（分）
fee_rate	int64	是	提现手续费比率（基点，100=1%）

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "daily_withdrawal_limit": 3,
    "min_withdrawal_amount": 10000,
    "fee_rate": 100,
    "is_active": true,
    "creator_name": "管理员",
    "created_at": "2026-01-21T14:30:00+08:00"
  }
}

接口逻辑：

验证当前用户有配置权限（平台用户）
将当前生效配置的 is_active 设为 false
创建新配置，is_active 设为 true
记录创建人

3.3.2 分页查询设置记录

接口路径：GET /api/admin/commission/withdrawal-settings

接口说明：查询佣金提现配置历史记录

请求参数：

参数名	类型	必填	说明
page	int	否	页码，默认1
page_size	int	否	每页数量，默认20

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 2,
        "daily_withdrawal_limit": 3,
        "min_withdrawal_amount": 10000,
        "fee_rate": 100,
        "is_active": true,
        "creator_id": 1,
        "creator_name": "管理员",
        "created_at": "2026-01-21T14:30:00+08:00"
      },
      {
        "id": 1,
        "daily_withdrawal_limit": 5,
        "min_withdrawal_amount": 5000,
        "fee_rate": 50,
        "is_active": false,
        "creator_id": 1,
        "creator_name": "管理员",
        "created_at": "2026-01-01T10:00:00+08:00"
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20
  }
}

接口逻辑：

查询所有配置记录，按创建时间倒序
关联查询创建人姓名

3.3.3 获取当前生效配置

接口路径：GET /api/admin/commission/withdrawal-settings/current

接口说明：获取当前生效的提现配置

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 2,
    "daily_withdrawal_limit": 3,
    "min_withdrawal_amount": 10000,
    "fee_rate": 100,
    "is_active": true,
    "creator_name": "管理员",
    "created_at": "2026-01-21T14:30:00+08:00"
  }
}

3.4 账号管理-企业客户管理

3.4.1 新增企业

接口路径：POST /api/admin/enterprises

接口说明：创建企业客户，同时自动创建企业账号

请求参数：

参数名	类型	必填	说明
owner_shop_id	uint	否	归属代理商ID，不填则为平台自营
enterprise_name	string	是	企业名称
enterprise_code	string	是	企业编号（唯一）
legal_person	string	否	法人代表
contact_name	string	是	联系人姓名
contact_phone	string	是	联系人电话
login_phone	string	是	登录手机号（作为企业账号的登录账号）
password	string	是	登录密码
business_license	string	否	营业执照号
province	string	否	省份
city	string	否	城市
district	string	否	区县
address	string	否	详细地址

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "enterprise": {
      "id": 1,
      "enterprise_name": "某某企业",
      "enterprise_code": "ENT001",
      "owner_shop_id": 5,
      "owner_shop_name": "某某代理商",
      "legal_person": "李四",
      "contact_name": "王五",
      "contact_phone": "13900139000",
      "business_license": "91110000...",
      "province": "北京市",
      "city": "北京市",
      "district": "朝阳区",
      "address": "某某路123号",
      "status": 1,
      "created_at": "2026-01-21T14:30:00+08:00"
    },
    "account": {
      "id": 10,
      "username": "某某企业",
      "phone": "13800138000",
      "user_type": 4,
      "status": 1
    }
  }
}

接口逻辑：

验证企业编号唯一性
如果指定 owner_shop_id，验证店铺存在且当前用户有权限
验证 login_phone 在账号表中不存在
开启事务：
- 创建企业记录
- 创建企业账号（UserType=4, EnterpriseID=企业ID, Phone=login_phone, Username=企业名称）
提交事务

3.4.2 分页查询企业客户

接口路径：GET /api/admin/enterprises

接口说明：查询企业客户列表

请求参数：

参数名	类型	必填	说明
page	int	否	页码，默认1
page_size	int	否	每页数量，默认20
enterprise_name	string	否	企业名称（模糊查询）
login_phone	string	否	登录手机号（模糊查询）
contact_phone	string	否	联系人电话（模糊查询）
owner_shop_id	uint	否	归属代理商ID
status	int	否	状态：0=禁用,1=启用

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "enterprise_name": "某某企业",
        "enterprise_code": "ENT001",
        "owner_shop_id": 5,
        "owner_shop_name": "某某代理商",          // NULL时显示"平台自营"
        "contact_name": "王五",
        "contact_phone": "13900139000",
        "login_phone": "13800138000",             // 从关联的Account获取
        "province": "北京市",
        "city": "北京市",
        "district": "朝阳区",
        "address": "某某路123号",
        "status": 1,
        "status_name": "启用",
        "created_at": "2026-01-21T14:30:00+08:00"
      }
    ],
    "total": 50,
    "page": 1,
    "page_size": 20
  }
}

接口逻辑：

根据当前用户权限过滤：
- 平台用户：看全部
- 代理商用户：看 owner_shop_id 在自己+下级店铺范围内的企业
关联查询企业账号获取 login_phone
关联查询归属店铺名称

3.4.3 编辑企业

接口路径：PUT /api/admin/enterprises/:id

接口说明：编辑企业信息（不影响账号）

请求参数：

参数名	类型	必填	说明
id	uint	是	企业ID（路径参数）
owner_shop_id	uint	否	归属代理商ID
enterprise_name	string	否	企业名称
enterprise_code	string	否	企业编号
legal_person	string	否	法人代表
contact_name	string	否	联系人姓名
contact_phone	string	否	联系人电话
business_license	string	否	营业执照号
province	string	否	省份
city	string	否	城市
district	string	否	区县
address	string	否	详细地址

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "enterprise_name": "某某企业（新）",
    "enterprise_code": "ENT001",
    "updated_at": "2026-01-21T15:00:00+08:00"
  }
}

接口逻辑：

验证企业存在
验证当前用户有权限编辑该企业
如果修改了 enterprise_code，验证唯一性
如果修改了 owner_shop_id，验证店铺存在且当前用户有权限
更新企业信息
注意：修改联系人电话不影响账号的登录手机号

3.4.4 分配卡给企业客户

接口路径：POST /api/admin/enterprises/:id/allocate-cards

接口说明：将卡分配给企业客户

请求参数：

参数名	类型	必填	说明
id	uint	是	企业ID（路径参数）
iccids	[]string	是	需要分配的ICCID列表

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "success_count": 10,
    "fail_count": 2,
    "failed_items": [
      {
        "iccid": "89860001234567890123",
        "reason": "卡不存在"
      },
      {
        "iccid": "89860001234567890124",
        "reason": "无权限操作该卡"
      }
    ],
    "allocated_devices": [                        // 因卡分配而连带分配的设备
      {
        "device_no": "DEV001",
        "card_count": 4
      }
    ]
  }
}

接口逻辑：

验证企业存在且当前用户有权限
遍历ICCID列表：
- 验证卡存在
- 验证当前用户有权限操作该卡（卡的 owner 在用户可见范围内）
- 检查卡是否绑定了设备
如果卡绑定了设备：
- 将整个设备及其所有绑定的卡一起分配
- 记录到返回的 allocated_devices 中
更新卡/设备的 owner_type=enterprise, owner_id=enterprise_id
创建分配记录到 tb_asset_allocation_record

⚠️ 待确认：

如果卡A绑定在设备X上，设备X还绑定了卡B/C/D，分配卡A时是否要连带分配整个设备和所有卡？
我的理解是：是的，需要整体分配，否则会导致归属关系混乱

3.4.5 从企业客户回收卡授权

接口路径：POST /api/admin/enterprises/:id/recall-cards

接口说明：取消企业对卡的授权（卡仍属于代理商）

请求参数：

参数名	类型	必填	说明
id	uint	是	企业ID（路径参数）
iccids	[]string	是	需要回收授权的ICCID列表

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "success_count": 10,
    "fail_count": 1,
    "failed_items": [
      {
        "iccid": "89860001234567890123",
        "reason": "该卡未授权给此企业"
      }
    ],
    "recalled_devices": [
      {
        "device_no": "DEV001",
        "card_count": 4
      }
    ]
  }
}

接口逻辑：

验证企业存在且当前用户有权限
遍历ICCID列表：
- 验证卡存在
- 验证卡已授权给该企业（授权表中有记录且 status=1）
- 检查卡是否绑定了设备
如果卡绑定了设备，设备下所有卡的授权一起回收
更新授权记录 status=0（不是删除，不是修改卡的 owner）
卡仍然属于代理商，只是企业不再能看到

3.4.6 企业客户卡分页查询列表

接口路径：GET /api/admin/enterprises/:id/cards

接口说明：查询企业被授权可见的卡列表

请求参数：

参数名	类型	必填	说明
id	uint	是	企业ID（路径参数）
page	int	否	页码，默认1
page_size	int	否	每页数量，默认20
status	int	否	卡状态
carrier_id	uint	否	运营商ID
iccid	string	否	ICCID（模糊查询）
device_no	string	否	设备号（模糊查询）

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "iccid": "89860001234567890123",
        "msisdn": "1440012345678",                 // 接入号
        "device_id": 10,
        "device_no": "DEV001",                    // 设备号（可能为空）
        "carrier_id": 1,
        "carrier_name": "中国移动",
        "package_id": 5,
        "package_name": "月租套餐30G",             // 当前套餐名称
        "status": 3,
        "status_name": "已激活",
        "network_status": 1,                       // 网络状态：0=停机,1=开机
        "network_status_name": "开机"
      }
    ],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

接口逻辑：

验证企业存在且当前用户有权限

通过授权表查询企业被授权的卡：

SELECT c.* FROM tb_iot_card c
INNER JOIN tb_enterprise_card_authorization eca 
  ON c.id = eca.iot_card_id
WHERE eca.enterprise_id = ? AND eca.status = 1 AND eca.deleted_at IS NULL

关联查询设备信息、运营商信息、当前套餐信息

3.4.6.1 企业操作卡 - 停机

接口路径：POST /api/admin/enterprises/:id/cards/:card_id/suspend

接口说明：企业对授权卡执行停机操作

请求参数：

参数名	类型	必填	说明
id	uint	是	企业ID（路径参数）
card_id	uint	是	卡ID（路径参数）

接口逻辑：

验证企业存在
验证卡已授权给该企业（授权表中有有效记录）
调用运营商接口执行停机
更新卡的 network_status = 0

3.4.6.2 企业操作卡 - 复机

接口路径：POST /api/admin/enterprises/:id/cards/:card_id/resume

接口说明：企业对授权卡执行复机操作

请求参数：

参数名	类型	必填	说明
id	uint	是	企业ID（路径参数）
card_id	uint	是	卡ID（路径参数）

接口逻辑：

验证企业存在
验证卡已授权给该企业
调用运营商接口执行复机
更新卡的 network_status = 1

3.4.7 启用/禁用企业

接口路径：PUT /api/admin/enterprises/:id/status

接口说明：启用或禁用企业

请求参数：

参数名	类型	必填	说明
id	uint	是	企业ID（路径参数）
status	int	是	状态：0=禁用,1=启用

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "status": 0,
    "status_name": "禁用"
  }
}

接口逻辑：

验证企业存在且当前用户有权限
更新企业状态
同步禁用/启用企业关联的账号

3.4.8 修改企业账号密码

接口路径：PUT /api/admin/enterprises/:id/password

接口说明：重置企业账号的登录密码

请求参数：

参数名	类型	必填	说明
id	uint	是	企业ID（路径参数）
password	string	是	新密码

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "enterprise_name": "某某企业"
  }
}

接口逻辑：

验证企业存在且当前用户有权限
查找企业关联的账号
更新账号密码（bcrypt加密）

3.5 账号管理-客户账号管理

说明：统一管理代理商账号和企业账号（UserType=3或4）

3.5.1 分页查询客户账号

接口路径：GET /api/admin/customer-accounts

接口说明：查询代理商和企业的账号列表

请求参数：

参数名	类型	必填	说明
page	int	否	页码，默认1
page_size	int	否	每页数量，默认20
shop_id	uint	否	代理商ID（筛选该代理商及其下级的账号）
username	string	否	账号名称（模糊查询）
status	int	否	账号状态：0=禁用,1=启用
user_type	int	否	账号类型：3=代理,4=企业

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 10,
        "username": "张三",
        "phone": "13800138000",
        "user_type": 3,
        "user_type_name": "代理账号",
        "shop_id": 5,
        "shop_name": "某某代理商",
        "enterprise_id": null,
        "enterprise_name": null,
        "status": 1,
        "status_name": "启用",
        "created_at": "2026-01-21T14:30:00+08:00"
      },
      {
        "id": 11,
        "username": "某某企业",
        "phone": "13900139000",
        "user_type": 4,
        "user_type_name": "企业账号",
        "shop_id": null,
        "shop_name": null,
        "enterprise_id": 1,
        "enterprise_name": "某某企业",
        "status": 1,
        "status_name": "启用",
        "created_at": "2026-01-21T14:30:00+08:00"
      }
    ],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

接口逻辑：

过滤条件：user_type IN (3, 4)
根据当前用户权限过滤：
- 平台用户：看全部
- 代理商用户：看自己店铺+下级店铺的代理账号 + 归属企业的账号
关联查询店铺名称、企业名称

3.5.2 新增客户账号

接口路径：POST /api/admin/customer-accounts

接口说明：为代理商新增账号（企业账号通过新增企业时创建）

请求参数：

参数名	类型	必填	说明
shop_id	uint	是	代理商ID
username	string	是	账号名称
phone	string	是	登录手机号
password	string	是	登录密码
status	int	否	状态，默认1=启用

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 12,
    "username": "李四",
    "phone": "13700137000",
    "user_type": 3,
    "shop_id": 5,
    "shop_name": "某某代理商",
    "status": 1,
    "created_at": "2026-01-21T14:30:00+08:00"
  }
}

接口逻辑：

验证店铺存在且当前用户有权限
验证手机号在账号表中不存在
创建账号（UserType=3, ShopID=shop_id）

3.5.3 编辑客户账号

接口路径：PUT /api/admin/customer-accounts/:id

接口说明：编辑客户账号信息

请求参数：

参数名	类型	必填	说明
id	uint	是	账号ID（路径参数）
username	string	否	账号名称
phone	string	否	登录手机号

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 12,
    "username": "李四（新）",
    "phone": "13700137001",
    "updated_at": "2026-01-21T15:00:00+08:00"
  }
}

接口逻辑：

验证账号存在且类型为代理或企业（3或4）
验证当前用户有权限编辑该账号
如果修改了手机号，验证新手机号不存在
更新账号信息

3.5.4 修改客户账号密码

接口路径：PUT /api/admin/customer-accounts/:id/password

接口说明：重置客户账号密码

请求参数：

参数名	类型	必填	说明
id	uint	是	账号ID（路径参数）
password	string	是	新密码

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 12,
    "username": "李四"
  }
}

3.5.5 启用/禁用客户账号

接口路径：PUT /api/admin/customer-accounts/:id/status

接口说明：启用或禁用客户账号

请求参数：

参数名	类型	必填	说明
id	uint	是	账号ID（路径参数）
status	int	是	状态：0=禁用,1=启用

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 12,
    "status": 0,
    "status_name": "禁用"
  }
}

3.6 财务-我的账号（代理商端）

3.6.1 获取当前账号佣金概览

接口路径：GET /api/admin/my/commission-summary

接口说明：获取当前登录代理账号所属店铺的佣金汇总

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "shop_id": 5,
    "shop_name": "某某代理商",
    "total_commission": 100000,
    "withdrawn_commission": 50000,
    "unwithdraw_commission": 50000,
    "frozen_commission": 10000,
    "withdrawing_commission": 5000,
    "available_commission": 35000
  }
}

接口逻辑：

从当前用户上下文获取 shop_id
计算佣金汇总（逻辑同3.1.1）

3.6.2 佣金提现申请

接口路径：POST /api/admin/my/withdrawal-requests

接口说明：代理商发起佣金提现申请

请求参数：

参数名	类型	必填	说明
amount	int64	是	提现金额（分）
withdrawal_method	string	是	收款类型：alipay
account_name	string	是	收款人姓名
account_number	string	是	支付宝账号

返回参数：

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "withdrawal_no": "W20260121143000001",
    "amount": 10000,
    "fee_rate": 100,
    "fee": 100,
    "actual_amount": 9900,
    "status": 1,
    "status_name": "待审批",
    "created_at": "2026-01-21T14:30:00+08:00"
  }
}

接口逻辑：

从当前用户上下文获取 shop_id 和 account_id
获取当前生效的提现配置
验证：
- 提现金额 >= 最低提现金额
- 可提现余额 >= 提现金额
- 今日提现次数 < 每日提现次数限制
计算手续费和实际到账金额
创建提现申请记录
冻结店铺佣金钱包中对应金额
记录钱包交易流水

3.6.3 我的提现记录

接口路径：GET /api/admin/my/withdrawal-requests

接口说明：查询当前代理商的提现记录

请求参数：

参数名	类型	必填	说明
page	int	否	页码，默认1
page_size	int	否	每页数量，默认20
status	int	否	状态筛选
start_time	string	否	申请开始时间
end_time	string	否	申请结束时间

返回参数：

与 3.2.1 相同，但仅返回当前店铺的数据

3.6.4 我的佣金明细

接口路径：GET /api/admin/my/commission-records

接口说明：查询当前代理商的佣金入账明细

请求参数：

与 3.1.3 相同

返回参数：

与 3.1.3 相同，但仅返回当前店铺的数据

四、接口路径汇总

模块	方法	路径	说明
代理商管理	GET	/api/admin/shops/commission-summary	代理商佣金列表
	GET	/api/admin/shops/:shop_id/withdrawal-requests	代理商提现记录
	GET	/api/admin/shops/:shop_id/commission-records	代理商佣金明细
佣金提现审批	GET	/api/admin/commission/withdrawal-requests	提现申请列表
	POST	/api/admin/commission/withdrawal-requests/:id/approve	审批通过（人工线下打款）
	POST	/api/admin/commission/withdrawal-requests/:id/reject	审批拒绝
提现设置	POST	/api/admin/commission/withdrawal-settings	新增配置
	GET	/api/admin/commission/withdrawal-settings	配置列表
	GET	/api/admin/commission/withdrawal-settings/current	当前配置
企业客户管理	POST	/api/admin/enterprises	新增企业
	GET	/api/admin/enterprises	企业列表
	PUT	/api/admin/enterprises/:id	编辑企业
	PUT	/api/admin/enterprises/:id/status	启用禁用
	PUT	/api/admin/enterprises/:id/password	修改密码
	POST	/api/admin/enterprises/:id/allocate-cards/preview	授权预检
	POST	/api/admin/enterprises/:id/allocate-cards	授权卡（确认）
	POST	/api/admin/enterprises/:id/recall-cards	回收授权
	GET	/api/admin/enterprises/:id/cards	企业授权卡列表
	POST	/api/admin/enterprises/:id/cards/:card_id/suspend	企业操作-停机
	POST	/api/admin/enterprises/:id/cards/:card_id/resume	企业操作-复机
客户账号管理	GET	/api/admin/customer-accounts	账号列表
	POST	/api/admin/customer-accounts	新增账号
	PUT	/api/admin/customer-accounts/:id	编辑账号
	PUT	/api/admin/customer-accounts/:id/password	修改密码
	PUT	/api/admin/customer-accounts/:id/status	启用禁用
财务-我的账号	GET	/api/admin/my/commission-summary	我的佣金概览
	POST	/api/admin/my/withdrawal-requests	发起提现
	GET	/api/admin/my/withdrawal-requests	我的提现记录
	GET	/api/admin/my/commission-records	我的佣金明细

五、已确认事项

5.1 核心设计确认

#	问题	确认结果
1	CommissionRecord 存储什么ID？	同时存储账号ID和店铺ID。佣金主要跟着店铺走，但保留账号ID方便未来查看某销售的佣金。
2	店铺主账号如何定义？	新增 `is_primary` 字段标记。创建店铺时同步创建的账号就是主账号。
3	卡绑定设备后如何授权？	整个设备及所有卡一起授权。新增预检接口让用户确认。
4	审批流程几步？	只有一步。审批通过后状态变为"已通过"，实际打款由人工线下完成。
5	代理商层级路径格式？	本身往上最多两层：`上上级_上级_本身`

5.2 卡/设备归属与授权确认

#	问题	确认结果
6	卡的归属流转范围？	只在平台和代理商之间。企业不拥有卡，只是被授权可见。
7	owner_type 统一？	改为 `platform` / `shop`。去掉 `agent`、`user`、`device`。
8	企业看卡的机制？	通过授权表 `tb_enterprise_card_authorization`，不改变卡的 owner。
9	设备如何可见？	通过卡间接查询。不需要单独的设备授权表。
10	授权有效期？	永久授权。回收时更新 `status=0`。
11	企业能操作什么？	能看、可以停机/复机。

5.3 佣金明细确认

#	问题	确认结果
12	"入账后佣金"如何计算？	本次佣金 + 历史累计佣金。在 `CommissionRecord` 创建时计算并存储 `balance_after` 字段。

5.4 待确认事项

暂无待确认事项。如有遗漏请补充。

六、后续规划提示

本文档仅涵盖账号和佣金相关功能。以下功能待后续规划：

物联网卡管理（ICCID增删改查、状态管理、数据同步）
设备管理（设备增删改查、SIM绑定管理）
号卡管理（虚拟产品管理）
订单管理（套餐订购、支付流程）
数据统计（用量统计、业务报表）

文档结束

54 KiB Raw Blame History Unescape Escape

账号与佣金管理模块需求规划

一、总体概述

1.1 模块范围

1.2 核心概念说明

1.3 数据权限规则

二、数据模型变更

2.1 需要新增的字段

2.1.1 tb_commission_withdrawal_request 表新增字段

2.1.2 tb_account 表新增字段

2.1.3 tb_commission_record 表新增字段

2.1.4 tb_commission_withdrawal_setting 表新增字段

2.1.5 tb_iot_card 表新增字段

2.1.6 tb_device 表新增字段

2.1.7 tb_commission_record 表新增字段（补充）

2.1.8 tb_iot_card 和 tb_device 表 owner_type 统一

2.2 需要新增的表

2.2.1 tb_enterprise_card_authorization 企业-卡授权表（核心）

2.2.2 tb_asset_allocation_record 资产分配记录表

2.3 卡/设备归属与授权体系（已确认）

2.3.1 核心设计原则

2.3.2 数据权限过滤修改

2.3.3 分配/授权规则

2.3.4 设备可见性（通过卡间接查询）

2.4 卡/设备分配详细方案（已确认）

2.4.1 分配交互流程

2.4.2 新增接口：分配预检

2.4.3 授权确认接口调整

三、接口设计

3.1 账号管理-代理商(店铺)管理

3.1.1 代理商分页列表查询

3.1.2 佣金提现分页列表（代理商维度）

3.1.3 佣金明细分页查询（代理商维度）

3.2 账号管理-佣金提现

3.2.1 佣金提现申请分页查询列表

3.2.2 审批通过

3.2.3 拒绝（审批拒绝）

3.3 佣金提现设置

3.3.1 新增佣金提现设置

3.3.2 分页查询设置记录

3.3.3 获取当前生效配置

3.4 账号管理-企业客户管理

3.4.1 新增企业

3.4.2 分页查询企业客户

3.4.3 编辑企业

3.4.4 分配卡给企业客户

3.4.5 从企业客户回收卡授权

3.4.6 企业客户卡分页查询列表

3.4.6.1 企业操作卡 - 停机

3.4.6.2 企业操作卡 - 复机

3.4.7 启用/禁用企业

3.4.8 修改企业账号密码

3.5 账号管理-客户账号管理

3.5.1 分页查询客户账号

3.5.2 新增客户账号

3.5.3 编辑客户账号

3.5.4 修改客户账号密码

3.5.5 启用/禁用客户账号

3.6 财务-我的账号（代理商端）

3.6.1 获取当前账号佣金概览

3.6.2 佣金提现申请

3.6.3 我的提现记录

3.6.4 我的佣金明细

四、接口路径汇总

五、已确认事项

5.1 核心设计确认

5.2 卡/设备归属与授权确认

5.3 佣金明细确认

5.4 待确认事项

六、后续规划提示

54 KiB

Raw Blame History

2.1.1 `tb_commission_withdrawal_request` 表新增字段

2.1.2 `tb_account` 表新增字段

2.1.3 `tb_commission_record` 表新增字段

2.1.4 `tb_commission_withdrawal_setting` 表新增字段

2.1.5 `tb_iot_card` 表新增字段

2.1.6 `tb_device` 表新增字段

2.1.7 `tb_commission_record` 表新增字段（补充）

2.1.8 `tb_iot_card` 和 `tb_device` 表 `owner_type` 统一

2.2.1 `tb_enterprise_card_authorization` 企业-卡授权表（核心）

2.2.2 `tb_asset_allocation_record` 资产分配记录表