# 需求15/16/18/19/20/21 技术方案

---

## 需求15：套餐下架后允许续费

### 业务规则

- 下架套餐（`shelf_status=2`）不可被**新购**
- 下架套餐**可以续费**（已在使用该套餐的客户）
- 续费仅支持**客户自己购买**（不允许代理代购下架套餐给新客户）

### 后端

**当前逻辑**：下架套餐在购买时被拦截。

修改：在订单创建校验中，区分"新购"和"续费"场景：

```go
// internal/service/order/service.go 或 client_order/service.go
func (s *Service) validatePackageAvailability(
    ctx context.Context,
    pkg *model.Package,
    assetID uint,
    isRenewal bool,
) error {
    if pkg.Status == constants.StatusDisabled { // 0=禁用，定义在 pkg/constants/constants.go
        return errors.New(errors.CodeForbidden, "套餐已禁用")
    }
    if pkg.ShelfStatus == constants.ShelfStatusOff && !isRenewal { // 2=下架
        return errors.New(errors.CodeForbidden, "套餐已下架，不可新购")
    }
    return nil
}
```

**isRenewal 判断**：查当前资产是否有该套餐的历史生效记录：

```go
func (s *Service) isRenewal(ctx context.Context, assetType string, assetID uint, packageID uint) bool {
    count, _ := s.packageUsageStore.CountByAssetAndPackage(ctx, assetType, assetID, packageID)
    return count > 0
}
```

### 前端

C端续费页面：下架套餐不在"新购"列表中展示，但在"续费"入口中仍可展示。

后台代购时：下架套餐的"代购"按钮禁用，tooltip 提示"套餐已下架，不可代购"。

---

## 需求16：代理分销码与佣金提现

### 业务规则

**DST-001**：新建代理时自动建立分销归属关系（指定发展人）  
**DST-002**：员工可作为代理发展人进行标识  
**二维码**：代理或员工生成推广二维码 → 扫码进入H5填写信息 → 提交成为代理申请 → 平台审批

### 数据库变更

```sql
-- 1. Shop 表新增发展人字段
ALTER TABLE tb_shop
    ADD COLUMN referrer_type VARCHAR(20) DEFAULT NULL
        COMMENT '发展人类型 shop=代理介绍 admin=员工介绍',
    ADD COLUMN referrer_id BIGINT DEFAULT NULL
        COMMENT '发展人ID（shop_id 或 tb_account.id）',
    ADD COLUMN referrer_name VARCHAR(50) DEFAULT NULL
        COMMENT '发展人姓名快照';

-- 2. 分销码表
CREATE TABLE tb_distribution_code (
    id          BIGSERIAL PRIMARY KEY,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at  TIMESTAMPTZ,
    creator     BIGINT NOT NULL DEFAULT 0,
    updater     BIGINT NOT NULL DEFAULT 0,
    code        VARCHAR(32) NOT NULL,
    owner_type  VARCHAR(20) NOT NULL,  -- shop=代理 | admin=员工
    owner_id    BIGINT NOT NULL,
    owner_name  VARCHAR(50) NOT NULL DEFAULT '',
    qr_code_url TEXT,
    use_count   INT NOT NULL DEFAULT 0,
    status      INT NOT NULL DEFAULT 1, -- 1=有效 0=禁用
    expires_at  TIMESTAMPTZ
);
CREATE UNIQUE INDEX idx_distribution_code ON tb_distribution_code(code) WHERE deleted_at IS NULL;

-- 3. 代理申请表（H5扫码提交）
CREATE TABLE tb_agent_application (
    id                BIGSERIAL PRIMARY KEY,
    created_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at        TIMESTAMPTZ,
    creator           BIGINT NOT NULL DEFAULT 0,
    updater           BIGINT NOT NULL DEFAULT 0,
    apply_no          VARCHAR(30) NOT NULL,
    distribution_code VARCHAR(32) NOT NULL,
    referrer_type     VARCHAR(20) NOT NULL,
    referrer_id       BIGINT NOT NULL,
    applicant_name    VARCHAR(50) NOT NULL,
    applicant_phone   VARCHAR(20) NOT NULL,
    shop_name         VARCHAR(100) NOT NULL,
    province          VARCHAR(50),
    city              VARCHAR(50),
    district          VARCHAR(50),
    address           VARCHAR(255),
    status            INT NOT NULL DEFAULT 1, -- 1=待审批 2=已通过 3=已拒绝
    reject_reason     TEXT,
    reviewed_by       BIGINT,
    reviewed_at       TIMESTAMPTZ
);
CREATE UNIQUE INDEX idx_agent_application_no ON tb_agent_application(apply_no) WHERE deleted_at IS NULL;
```

### API 设计

**生成分销码**：
```
POST /admin/distribution-codes
body: { owner_type: "admin"|"shop", owner_id: 123 }
```

**H5 扫码获取分销码信息**：
```
GET /app/distribution-codes/{code}
```

**H5 提交代理申请**：
```
POST /app/agent-applications
body: { distribution_code, applicant_name, applicant_phone, shop_name, ... }
```

**后台代理申请列表/审批**：
```
GET  /admin/agent-applications?status=1
POST /admin/agent-applications/{id}/approve
POST /admin/agent-applications/{id}/reject
body: { reject_reason: "..." }
```

审批通过时：自动创建 `tb_shop` + `tb_account`，设置 `referrer_type` 和 `referrer_id`。

**佣金提现（DST-003~007）**：

现有 commission 框架基础上新增材料上传字段，提现申请时一次性上传所有材料（对象存储 Key 列表）。

---

## 需求18：多人审批（APR-001~009）

### 依赖

基于 [审批流基础设施](./基础设施/审批流.md) 和 [站内消息](./基础设施/站内消息.md)。

APR-009（企微审批对接）= Phase 2。

### 实现要点

| 编号 | 需求 | 实现 |
|------|------|------|
| APR-001~003 | 充值/退款多级审核 | 见需求20/21 |
| APR-004 | 审核环节：部门领导→财务 | 审批流固定两步：step=1 部门领导，step=2 财务 |
| APR-005 | 待审核有消息提示 | 站内消息 `NotifyTypeApprovalPending` |
| APR-006 | 上一级完成后才提示下一级 | `ApprovalFlowAggregate.Approve()` 触发 `ApprovalStepAdvancedEvent` |
| APR-007 | 通过后通知申请人 | `ApprovalCompletedEvent` handler |
| APR-008 | 驳回/退回后通知申请人含原因 | `ApprovalRejectedEvent` / `ApprovalReturnedEvent` handler |
| APR-009 | 对接企微 | **Phase 2** |

### 业务表与审批流的关联

充值单、退款单接入审批流，各自新增 `approval_flow_id` 字段：

```sql
ALTER TABLE tb_refund_request ADD COLUMN approval_flow_id BIGINT DEFAULT NULL
    COMMENT '当前审批流ID（已退回后重新提交会更新为新流程ID）';

ALTER TABLE tb_agent_recharge_record ADD COLUMN approval_flow_id BIGINT DEFAULT NULL
    COMMENT '当前审批流ID（已退回后重新提交会更新为新流程ID）';
```

接入协议详见 [审批流文档 - 接入协议](./基础设施/审批流.md#六接入协议业务层如何接入审批流)。

---

## 需求19：批量订购套餐（BPO-001~008）

### 业务流程

1. 员工进入批量订购页面
2. 选择代理 + 上传 Excel（字段：资产类型/资产标识/套餐编码/套餐名称/支付方式）
3. 系统解析并校验每一行
4. 支付方式：`offline=线下支付（默认成功）` / `agent_wallet=代理钱包支付`
5. 代理钱包支付时从代理余额扣款（含信用额度）
6. 线下支付时标记为已支付（不走钱包）
7. 校验失败的行展示在页面，带失败原因
8. **线下支付需上传整批次的支付凭证**

### 数据库变更

```sql
CREATE TABLE tb_bulk_purchase_task (
    id             BIGSERIAL PRIMARY KEY,
    created_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at     TIMESTAMPTZ,
    creator        BIGINT NOT NULL DEFAULT 0,
    updater        BIGINT NOT NULL DEFAULT 0,
    task_no        VARCHAR(30) NOT NULL,
    shop_id        BIGINT NOT NULL,
    operator_id    BIGINT NOT NULL,
    payment_method VARCHAR(20) NOT NULL,  -- offline | agent_wallet
    voucher_keys   JSONB,                 -- 线下支付凭证列表
    total_count    INT NOT NULL DEFAULT 0,
    success_count  INT NOT NULL DEFAULT 0,
    fail_count     INT NOT NULL DEFAULT 0,
    status         INT NOT NULL DEFAULT 1, -- 1=处理中 2=已完成
    failed_items   JSONB                   -- 失败明细
);
CREATE UNIQUE INDEX idx_bulk_purchase_task_no ON tb_bulk_purchase_task(task_no) WHERE deleted_at IS NULL;
```

> 失败明细存 JSONB（`failed_items`），与现有 DeviceImportTask 模式一致，无需单独明细表。

### API 设计

**下载 Excel 模板**：
```
GET /admin/bulk-purchases/template
```

**上传并提交**：
```
POST /admin/bulk-purchases
Content-Type: multipart/form-data

字段：
  shop_id: 123
  payment_method: offline | agent_wallet
  voucher_keys: ["key1","key2"]   (offline 时必填)
  file: <Excel文件>
```

**查询任务状态**：
```
GET /admin/bulk-purchases/{task_id}
```

---

## 需求20：退款审批

### 依赖

基于 [审批流基础设施](./基础设施/审批流.md)。

### 退款单现有状态（不变）

```
1=待审批  2=已通过  3=已拒绝  4=已退回
```

退款单本身的状态含义不变，审批进度由 `tb_approval_flow` 管理，两者通过 `approval_flow_id` 关联。

### 流程

```
提交退款申请（POST /admin/refund-requests）
  → 创建 RefundRequest（status=1 待审批）
  → 调 SubmitApprovalUseCase 创建 ApprovalFlow（biz_type=refund）
  → 把 approval_flow_id 写入 RefundRequest

审批人操作（POST /admin/approvals/{flow_id}/approve|reject|return）
  → ApprovalCompletedEvent → RefundRequest.status=2（已通过）→ 触发实际退款
  → ApprovalRejectedEvent  → RefundRequest.status=3（已拒绝）
  → ApprovalReturnedEvent  → RefundRequest.status=4（已退回）→ 通知提交人可修改
```

### 退回后重新提交

```
PUT /admin/refund-requests/{id}       仅 status=4 时可编辑退款单内容
POST /admin/refund-requests/{id}/resubmit
  → 校验 status=4
  → 新建 ApprovalFlow
  → 更新 approval_flow_id，status 回到 1（待审批）
```

---

## 需求21：充值审核流程

### 充值单现有状态

```
tb_agent_recharge_record：1=待支付 2=已支付 3=已完成 4=已关闭 5=已退款
```

员工线下充值走审批流，需在现有状态基础上**新增"已退回"状态**：

```sql
-- status 说明更新（不改原有值语义，追加新状态）
-- 6=已退回（审批人退回给提交人修改）
```

充值业务的状态语义：
- `1=待支付`：创建未支付（线下充值等待审批时也停在这里，由 approval_flow_id 判断是否在审批中）
- `2=已支付`：支付成功（线下充值审批通过后跳到已完成，不经过此状态）
- `3=已完成`：充值到账
- `4=已关闭`：取消/超时
- `5=已退款`：退款
- `6=已退回`：审批人退回给提交人修改

### 流程

**代理自行充值（不走审批）**：

```
代理提交充值申请 → 系统生成收款码 → 代理扫码支付 → 回调自动充值到钱包
```

**员工线下代充值（走审批）**：

```
POST /admin/agent-recharge-records（payment_method=offline）
  → 创建 AgentRechargeRecord（status=1）
  → 调 SubmitApprovalUseCase 创建 ApprovalFlow（biz_type=recharge）
  → 把 approval_flow_id 写入记录

审批通过 → AgentRechargeRecord.status=3（已完成）→ 实际充值到钱包
审批驳回 → AgentRechargeRecord.status=4（已关闭）
审批退回 → AgentRechargeRecord.status=6（已退回）→ 通知提交人可修改
```

### 退回后重新提交

```
PUT /admin/agent-recharge-records/{id}    仅 status=6 时可编辑
POST /admin/agent-recharge-records/{id}/resubmit
  → 校验 status=6
  → 新建 ApprovalFlow
  → 更新 approval_flow_id，status 回到 1（待支付/待审批）
```