完成

docs/7月迭代/七月迭代实现与接口对接说明.md

@@ -94,11 +94,25 @@
 | #55 分配覆盖 | `POST /api/admin/shop-package-batch-allocations`；`PATCH /api/admin/shop-package-allocations/:id/expiry-base` | 分配时使用 `expiry_base_override`；`null` 表示跟随套餐默认值 |
 | #43 系列套餐多选 | `POST /api/admin/shop-series-grants`；`PUT /api/admin/shop-series-grants/:id/packages` | `packages` 是 1～100 项数组，每项包含 `package_id`、`cost_price`，删除时传 `remove=true` |
 
+#### 3.2.1 #43 套餐价格展示和已授权/未授权区分
+
+#43 不需要新增后端接口，前端按下面两个现有接口组合数据：
+
+1. 调用 `GET /api/admin/packages?series_id={series_id}&page=1&page_size=100` 分页取得该系列全部套餐。列表项直接使用：
+   - `suggested_retail_price`：建议售价，单位分；未配置时为空。
+   - `cost_price`：公司成本价，单位分。
+2. 编辑已有授权时，调用 `GET /api/admin/shop-series-grants/{grant_id}`，注意路径参数是授权记录 ID，不是系列 ID。
+3. 将授权详情的 `packages[].package_id` 组成已授权套餐 ID 集合。
+4. 套餐列表项的 `id` 在该集合中显示“已授权”，否则显示“未授权”。授权详情 `packages[].cost_price` 是该次店铺授权成本价，不要拿它替代套餐列表的公司成本价。
+5. 用户提交多选结果时，创建授权调用 `POST /api/admin/shop-series-grants`；编辑授权调用 `PUT /api/admin/shop-series-grants/{grant_id}/packages`。新增/调价项传 `package_id + cost_price`，删除项传 `package_id + remove=true`。
+
+套餐接口是分页接口；一个系列超过 100 个套餐时，前端必须继续请求后续页，再完成已授权集合标记。
+
 ### 3.3 审批、退款和员工线下代充值
 
 | 需求 | 接口 | 参数或返回变化 / 前端调用说明 |
 | --- | --- | --- |
-| #182/#44 退款 | `GET /api/admin/refunds`；`GET /api/admin/refunds/:id` | 新增/补齐 `submitter_id`、`submitter_name`、`approval_provider`、`approval_status`、`approval_status_name` |
+| #181/#182/#44 退款 | `GET /api/admin/refunds`；`GET /api/admin/refunds/:id` | 新增/补齐 `asset_identifier`、`submitter_id`、`submitter_name`、`approval_provider`、`approval_status`、`approval_status_name`；资产标识是退款创建时固化的快照，卡为 ICCID，设备按 VirtualNo 优先、IMEI 兜底；历史空快照不做兼容 |
 | #182/#44 充值 | `GET /api/admin/agent-recharges`；`GET /api/admin/agent-recharges/:id` | 同上；线下代充值的审批状态只读展示 |
 | #44 换货 | `GET /api/admin/exchanges`；`GET /api/admin/exchanges/:id` | 新增/补齐 `submitter_id`、`submitter_name` |
 | #34 员工线下代充 | `POST /api/admin/agent-recharges` | 仍用原入口；`payment_method=offline` 时传目标 `shop_id`、金额、1～5 个 `payment_voucher_key` 和备注，创建后等待企微审批 |
@@ -110,6 +124,83 @@
 | #37 场景模板 | `PUT /api/admin/wecom/scenes/:business_type`；`GET /api/admin/wecom/scenes` | `business_type` 为 `refund_approval` 或 `offline_recharge_approval`；传 `application_id`、`template_id`、`control_mapping[]` |
 | #37 回调 | `GET/POST /api/callback/wecom/approval/:application_id` | 由企微服务器调用，前端无需调用 |
 
+#### 3.3.1 企业微信审批 8 个接口的前端调用流程
+
+企业微信配置页使用 8 个 `/api/admin/wecom` 接口；账号绑定属于账号模块，因此完整闭环是“8 个企微配置接口 + 1 个账号绑定接口”。应用凭据和场景写操作应只向超级管理员开放；前端收到 403 时不要降级绕过。
+
+| 顺序 | 接口 | 页面动作与调用说明 |
+| --- | --- | --- |
+| 1 | `POST /api/admin/wecom/applications` | 保存应用。传 `corp_id`、`agent_id`、`name`、`secret`、`callback_token`、43 位 `encoding_aes_key`、`status=1`。相同 `corp_id + agent_id` 再次提交表示更新；保存响应中的 `id` 是后续 `application_id` |
+| 2 | `GET /api/admin/wecom/applications?page=1&page_size=20` | 进入配置页或保存后刷新应用列表，展示连接时间、启用状态、默认发起人和凭据是否完整 |
+| 3 | `POST /api/admin/wecom/applications/{id}/test` | 用户点击“测试连接”时调用；`data.success=true` 只表示成功取得 access_token，不表示通讯录、模板和回调均已配置完成 |
+| 4 | `POST /api/admin/wecom/applications/{id}/members/sync` | 连接成功后点击“同步成员”；后端拉取该自建应用可见范围，返回 `synced_count` 和 `synced_at` |
+| 5 | `GET /api/admin/wecom/applications/{id}/members?page=1&page_size=20&keyword=...` | 查询最近同步的本地成员快照，`keyword` 可按姓名或 userid 搜索；用于默认发起人和账号绑定的选择器，不要允许手输一个未同步 userid |
+| 6 | `PUT /api/admin/wecom/applications/{id}/default-creator` | 从成员选择器取 `userid`，请求体为 `{"userid":"zhangsan"}`。代理等非企微账号提交业务时，企微审批由该成员代为发起，但本地业务提交人仍保持真实账号 |
+| 7 | `PUT /api/admin/wecom/scenes/{business_type}` | 分别保存退款和线下代充值模板映射；后端会实时读取企微模板详情并校验控件 ID、类型、必填控件和选择项 key，校验失败时页面应保留用户输入并展示后端错误 |
+| 8 | `GET /api/admin/wecom/scenes?page=1&page_size=20` | 进入场景页或保存后刷新，展示 `business_type_name`、模板名称、状态、最近校验时间和控件映射 |
+
+应用保存请求示例：
+
+```json
+{
+  "corp_id": "wwxxxxxxxxxxxxxxxx",
+  "agent_id": 1000002,
+  "name": "测试环境审批应用",
+  "secret": "企微应用Secret",
+  "callback_token": "企微后台配置的回调Token",
+  "encoding_aes_key": "43位EncodingAESKey",
+  "status": 1
+}
+```
+
+场景路径只支持：
+
+- `refund_approval`：退款审批。
+- `offline_recharge_approval`：员工线下代充值审批。
+
+场景保存请求示例：
+
+```json
+{
+  "application_id": 1,
+  "template_id": "企微模板ID",
+  "control_mapping": [
+    {
+      "business_field": "refund_no",
+      "control_id": "Text-xxxxxxxx",
+      "control_type": "Text",
+      "option_mapping": {}
+    }
+  ],
+  "status": 1
+}
+```
+
+`control_mapping` 的 `control_id`、`control_type` 和选择项 key 必须来自企微后台已经创建的模板。退款可映射业务字段为 `refund_no`、`order_id`、`order_no`、`asset_identifier`、`asset_type`、`actual_received_amount`、`requested_refund_amount`、`refund_voucher_key`、`refund_reason`、`package_usage_id`、`submitter_id`、`submitter_name`；线下代充值可映射 `recharge_no`、`shop_id`、`shop_name`、`amount`、`amount_cent`、`payment_voucher_key`、`remark`、`submitter_id`、`submitter_name`。企微模板中的必填控件必须全部映射。
+
+完成成员同步后，账号管理页还要调用：
+
+```http
+PUT /api/admin/accounts/{account_id}/wecom-binding
+```
+
+```json
+{
+  "application_id": 1,
+  "userid": "zhangsan"
+}
+```
+
+前端完整配置顺序为：保存应用 → 测试连接 → 同步成员 → 查询成员 → 设置默认发起人 → 给需要本人发起审批的系统账号绑定成员 → 保存两个业务场景 → 查询场景确认均已启用。应用可见范围变化后，应重新同步成员并检查默认发起人和账号绑定。
+
+#### 3.3.2 配置完成后的业务审批流程
+
+1. 前端继续调用原业务接口创建退款或员工线下代充值，不直接调用企微发起审批接口。
+2. 后端保存业务单、通用审批实例和提交事件，并异步向企微发起审批；前端根据业务列表/详情的 `approval_provider`、`approval_status`、`approval_status_name` 只读展示进度。
+3. `approval_status` 可能为：`0` 提交中、`1` 审批中、`2` 已通过、`3` 已拒绝、`4` 已撤销、`5` 通过后撤销、`6` 已删除、`7` 提交失败、`8` 提交结果未知。页面名称优先直接使用 `approval_status_name`。
+4. 企微回调和 Worker 轮询共同同步最终状态；`GET/POST /api/callback/wecom/approval/{application_id}` 只由企微服务器调用，前端禁止调用。
+5. `approval_provider=wecom` 或存在 `approval_instance_id` 时，前端不得显示退款通过/驳回、线下充值确认等旧人工按钮。企微通过后，退款终结或钱包入账由后端自动幂等执行。
+
 ### 3.4 通知、批量任务、导出和 Gateway
 
 | 需求 | 接口 | 参数或返回变化 / 前端调用说明 |
@@ -127,6 +218,47 @@
 | #49 创建设备分配任务 | `POST /api/admin/devices/import/allocations` | 传 `file_key + operation_type + target_id`；`operation_type=assign_shop|assign_series` |
 | #49 查询任务 | `GET /api/admin/devices/import/tasks`；`GET /api/admin/devices/import/tasks/:id` | 复用原设备导入任务页面，新增展示 `operation_type`、`operation_name`、`target_id`、`status_name` |
 
+### 3.5 前端静态 CSV 模板
+
+本期需要前端提供两份静态文件模板，**都是 CSV，不接受 Excel（`.xls`/`.xlsx`）**。文件使用 UTF-8 编码，允许 UTF-8 BOM，最大 10MB，最多 1000 行数据（不含表头）。每个文件只允许一列，不要添加空行、说明行或示例外的其他列。
+
+#### 模板一：批量订购套餐
+
+- 建议文件名：`批量订购套餐模板.csv`
+- 上传用途：`purpose=batch_purchase`
+- 套餐、支付方式和线下凭证由页面另外选择，不放在 CSV 中。
+
+| 列序号 | 固定表头 | 必填 | 填写内容 |
+| --- | --- | --- | --- |
+| 1 | `资产标识` | 是 | 每行一个资产标识。卡支持 ICCID、VirtualNo 或 MSISDN；设备支持 VirtualNo、IMEI 或 SN |
+
+```csv
+资产标识
+89860012345678901234
+CARD-VIRTUAL-0001
+DEVICE-VIRTUAL-0001
+860123456789012
+```
+
+#### 模板二：设备批量分配
+
+- 建议文件名：`设备批量分配模板.csv`
+- 上传用途：`purpose=device_batch_allocation`
+- 目标代理或套餐系列由页面另外选择，不放在 CSV 中。“分配代理”和“设置套餐系列”可以共用这一份模板。
+
+| 列序号 | 固定表头 | 必填 | 填写内容 |
+| --- | --- | --- | --- |
+| 1 | `设备标识` | 是 | 每行一个设备标识，支持 VirtualNo、IMEI 或 SN |
+
+```csv
+设备标识
+DEVICE-VIRTUAL-0001
+860123456789012
+SN202607250001
+```
+
+> 前端下载的静态模板可以只保留表头，上述数据行仅用于说明格式。资产标识必须按文本原样保存，不得转换为科学计数法、浮点数或截断前导零。
+
 ## 四、前端本期最容易漏掉的工作
 
 - 换货列表拆成新、旧资产两个搜索参数。