七月迭代短暂完结,还有很多后端的关键东西没有弄,这是一版赶时间做的东西

docs/business-data-export/功能总结.md

@@ -0,0 +1,59 @@
+# 业务数据导出功能总结
+
+## 公共交付方式
+
+业务导出复用现有 `POST /api/admin/export-tasks` 异步任务入口、DataSource 注册、Asynq 分片、对象存储和 CSV/XLSX 汇总流程。前端只提交 `scene`、`format` 和当前列表的 `query.filters`，不另外选择导出列。
+
+Worker 使用任务创建时固化的用户类型、店铺和下级店铺范围，不从运行时上下文猜测权限。`Count` 与 `Fetch` 使用同一套筛选和权限条件，分片按稳定 ID 顺序读取。
+
+## IoT 卡导出
+
+- 场景编码：`iot_card`。
+- 继续沿用现有卡列表筛选和店铺层级权限。
+- 在原有 ICCID、MSISDN、设备、运营商、店铺、实名和网络状态列后，追加“套餐名称”、“使用流量(MB)”和“剩余流量(MB)”。
+- 套餐字段取当前生效主套餐，名称优先使用购买时快照；剩余流量由套餐真流量总量减已用量得出，超额使用时收敛为 `0`。
+
+## 套餐列表导出
+
+- 场景编码：`package`。
+- 支持现有套餐列表的 `package_name`、`series_id`、`status`、`shelf_status`、`package_type` 筛选。
+- 平台和超级管理员导出套餐本体数据；代理只导出已分配给自己店铺且分配状态启用的非赠送套餐，成本价和上下架状态取自当前店铺分配记录。
+- 固定输出已确认的 25 列：编码、名称、系列、类型、时长、周期、真/虚流量、虚流量配置、重置周期、到期基准、价格、状态、赠送标识、创建/更新人及时间。当前列表不返回软删除套餐，因此“删除时间”按契约保留为空列。
+- 金额从数据库的“分”转为两位小数的“元”；未配置建议售价时输出空值，不用 `0.00` 冒充已配置价格。
+
+## 代理主钱包流水导出
+
+- 场景编码：`agent_wallet_transaction`。
+- 仅导出主钱包流水，代理按任务创建时固化的自己及下级店铺范围读取；平台和超级管理员可读取全部有权数据。
+- 支持现有流水列表的 `shop_id`、`transaction_type`、`start_date`、`end_date`、`asset_identifier` 筛选，纯日期截止时间包含当天。
+- 固定输出 14 列：店铺、交易类型、交易金额、状态、资产类型与标识、交易时间、交易前后金额、购买套餐名称、操作人、交易 ID、关联业务订单号、支付方式。
+- 金额沿用钱包流水中的分值事实并格式化为两位小数的元；套餐名称优先读取订单项快照，历史缺失时回退流水元数据。历史操作账号即使已软删除仍保留名称展示，但不参与权限判断。
+
+## 代理充值导出
+
+- 场景编码：`agent_recharge`。
+- 支持现有充值列表的 `shop_id`、`status`、`start_date`、`end_date` 筛选，代理权限使用任务创建时固化的店铺范围。
+- 固定输出 18 列：充值单号、店铺、充值类型、充值/实付金额、充值前后余额、状态、支付方式、运营备注、驳回原因、三个业务时间、提交人、审批来源、审批状态和支付凭证。
+- 充值金额取充值单事实；成功入账后的实付金额和余额前后值取首条匹配的成功主钱包充值流水，缺失时留空，不用零值冒充。
+- 审批字段只读取本地通用审批实例，不逐行实时调用企业微信。支付凭证按业务需要输出明文对象存储 Key，并按原顺序以逗号连接；Integration Log 仍不得记录 Secret、access_token、media_id 或附件正文。
+
+## 退款导出
+
+- 场景编码：`refund`。
+- 支持退款列表的 `status`、`order_id`、`shop_id`、`asset_identifier` 筛选，代理按任务创建时固化的自己及下级店铺范围导出。
+- 固定输出 21 列：退款单号、店铺、支付订单号、资产、套餐、五项金额、退款状态与原因、审批备注、审批来源与状态、退款处理状态、申请/审批时间、提交人和退款凭证。
+- 订单号和资产标识使用退款申请快照；套餐名称优先使用指定套餐使用记录快照，否则聚合同一订单的订单项快照。原订单金额、可退金额、申请金额和实际退款金额均读取既有订单或退款事实，来源缺失时留空，不用零值冒充。
+- 退款处理状态仅从退款状态、佣金回扣和资产处理完成标记稳定推导。当前模型没有可靠的当前审批节点和逐节点审批记录结构，因此不输出无意义空列；审批来源与状态只读取本地通用审批实例，不实时调用企业微信。
+- 退款凭证按业务需要输出明文对象存储 Key。历史软删除账号仍可用于提交人名称展示，但不参与权限判断。
+
+## 换货导出
+
+- 场景编码：`exchange`。
+- 支持换货列表的 `status`、`flow_type`、`old_asset_keyword`、`new_asset_keyword`、`created_at_start`、`created_at_end` 筛选；新旧资产关键词继续按 AND 组合，并按卡/设备当前权威标识命中资产 ID。
+- 固定输出 15 列：换货单号、流程类型、原因、问题描述/备注、新旧资产标识、收货信息、物流信息、状态、创建人和创建时间。
+- 新旧资产列直接使用换货单已固化的权威快照，卡为完整 ICCID，设备按虚拟号、IMEI、SN 的既定优先级保存；不会在导出时重新拼接或覆盖历史快照。
+- 收货人电话、地址等业务字段按用户确认保持明文输出。代理权限使用任务创建时固化的店铺层级范围，历史软删除创建人只用于名称展示。
+
+## 当前验证边界
+
+本次不运行测试、完整构建、LSP 或迁移；按用户后续明确要求已运行 OpenAPI 生成器。静态收口使用 `gofmt`、只读一致性检查和 `git diff --check`；真实数据行数、筛选、分片、CSV/XLSX 文件和下载链接由后续联调验证。