9.2 KiB
9.2 KiB
需求14：导出功能
复用现有 ExportTask 体系（
tb_export_task+ Asynq）
导出模块总览
| 编号 | 模块 | 新增/修改 |
|---|---|---|
| EXPD-001~003 | IoT卡导出 | 新增套餐名称、使用流量、剩余流量字段 |
| 6.8.2 | 代理资金概况-预充值钱包流水导出 | 全新 |
| 6.8.3 | 套餐列表导出 | 全新 |
| 6.8.4 | 退款管理退款列表导出 | 全新 |
| 6.8.5 | 换货管理导出 | 全新 |
| 6.8.6 | 代理充值导出 | 全新（去掉"支付通道"字段） |
现有导出体系说明
系统已有异步导出框架（internal/exporter/）：
tb_export_task表记录导出任务- 导出逻辑通过
DataSource接口实现，每个场景一个文件（如iot_card_scene.go） registry.go的NewDefaultRegistry()统一注册所有场景- Asynq Worker 根据任务里的
scene字段，从 Registry 取对应 DataSource 执行 - 前端轮询任务状态后下载
新增导出模块需要：
- 在
pkg/constants/constants.go新增ExportTaskSceneXxx场景常量 - 在
internal/exporter/新建xxx_scene.go，实现DataSource接口（Scene()/Count()/Headers()/Fetch()） - 在
registry.go的NewDefaultRegistry()中注册，并更新IsSupportedScene() - 新增对应的 Export API（创建导出任务，传入
scene字段）
EXPD-001~003：IoT卡导出字段新增
修改文件：internal/exporter/iot_card_scene.go
在 Headers() 末尾追加三列，Fetch() 的 Select 追加字段，iotCardExportRow 追加字段：
// Headers() 新增
"套餐名称", "使用流量(MB)", "剩余流量(MB)"
// baseQuery() 或 Fetch() 新增 JOIN
LEFT JOIN LATERAL (
SELECT pu.package_id, pu.data_usage_mb, pu.data_limit_mb, p.package_name
FROM tb_package_usage pu
JOIN tb_package p ON p.id = pu.package_id AND p.deleted_at IS NULL
WHERE pu.iot_card_id = c.id AND pu.status = 1
AND pu.master_usage_id IS NULL AND pu.deleted_at IS NULL
LIMIT 1
) AS pkg ON TRUE
// iotCardExportRow 新增
PackageName string `gorm:"column:package_name"`
DataUsageMB int64 `gorm:"column:data_usage_mb"`
DataLimitMB int64 `gorm:"column:data_limit_mb"`
剩余流量 = DataLimitMB - DataUsageMB（在行转换时计算）
6.8.2：代理资金概况-预充值钱包流水导出
新增接口：POST /admin/agent-wallet-transactions/export
支持与现有钱包流水列表相同的筛选条件，异步生成 Excel。
导出字段映射：
| 字段 | 数据来源 |
|---|---|
| 店铺名称 | JOIN tb_shop |
| 交易类型 | transaction_type（充值/扣款/退款等，中文化） |
| 交易金额 | amount / 100 转元 |
| 状态 | status 中文化 |
| 资产类型 | asset_type 中文化 |
| 资产标识 | asset_identifier |
| 交易时间 | created_at |
| 交易前金额 | balance_before / 100 |
| 交易后金额 | balance_after / 100 |
| 购买套餐名称 | metadata 中 JSON 字段 package_name，或 JOIN 订单 |
| 操作人 | JOIN tb_account（creator 字段关联 tb_account.id，取 username） |
| 交易 ID | id |
| 关联业务订单号 | reference_id 对应的单号（JOIN 对应表） |
| 交易渠道/支付方式 | metadata 中 payment_method 字段 |
6.8.3：套餐列表导出
新增接口：POST /admin/packages/export
支持现有套餐列表筛选条件。
导出字段（按需求文档 24 个字段）：
type PackageExportRow struct {
PackageCode string `xlsx:"套餐编码"`
PackageName string `xlsx:"套餐名称"`
SeriesName string `xlsx:"套餐系列名称"` // JOIN tb_package_series
PackageType string `xlsx:"套餐类型"` // formal/addon 中文化
DurationMonths int `xlsx:"套餐时长(月)"`
DurationDaysDesc string `xlsx:"套餐时长说明"` // 剩余天数说明
CalendarType string `xlsx:"套餐周期类型"`
DurationDays int `xlsx:"套餐天数"`
RealDataMB int64 `xlsx:"真流量额度(MB)"`
VirtualDataMB int64 `xlsx:"虚流量额度(MB)"`
EnableVirtualData string `xlsx:"是否启用虚流量"` // 是/否
VirtualRatio float64 `xlsx:"虚流量比例"`
DataResetCycle string `xlsx:"流量重置周期"`
ExpiryBase string `xlsx:"到期时间基准"`
CostPrice string `xlsx:"成本价(元)"` // 分→元
SuggestedRetailPrice string `xlsx:"建议售价(元)"`
PriceConfigStatus string `xlsx:"价格配置状态"`
Status string `xlsx:"状态"`
ShelfStatus string `xlsx:"上架状态"`
IsGift string `xlsx:"是否赠送套餐"`
CreatorID uint `xlsx:"创建人ID"`
UpdaterID uint `xlsx:"更新人ID"`
CreatedAt string `xlsx:"创建时间"`
UpdatedAt string `xlsx:"更新时间"`
DeletedAt string `xlsx:"删除时间"`
}
6.8.4：退款管理退款列表导出
新增接口：POST /admin/refund-orders/export
导出字段（去掉"退款到账方式"，保留其余字段，部门领导/财务审批人依赖审批流）：
type RefundExportRow struct {
RefundNo string `xlsx:"退款单号"`
ShopName string `xlsx:"代理店铺名称"`
PaymentOrderNo string `xlsx:"关联的支付订单号"`
AssetType string `xlsx:"资产类型"`
AssetIdentifier string `xlsx:"资产标识"`
PackageName string `xlsx:"套餐名称"`
OriginalAmount string `xlsx:"原订单金额"`
ActualAmount string `xlsx:"实收金额"`
RefundableAmount string `xlsx:"可退金额"`
AppliedAmount string `xlsx:"申请退款金额"`
ActualRefundAmount string `xlsx:"实际退款金额"`
Status string `xlsx:"状态"`
RefundReason string `xlsx:"退款原因"`
Remark string `xlsx:"备注"`
ApprovalRemark string `xlsx:"审批备注"`
AppliedAt string `xlsx:"退款申请时间"`
CompletedAt string `xlsx:"退款完成时间"`
SubmitterName string `xlsx:"提交人"`
DeptLeaderName string `xlsx:"部门领导审批人"`
FinanceName string `xlsx:"财务审批人"`
VoucherURLs string `xlsx:"退款凭证"`
}
6.8.5：换货管理导出
新增接口：POST /admin/exchange-orders/export
type ExchangeExportRow struct {
ExchangeNo string `xlsx:"换货单号"`
ExchangeType string `xlsx:"换货类型"`
ExchangeReason string `xlsx:"换货原因"`
ProblemDesc string `xlsx:"问题描述"`
OldAssetType string `xlsx:"旧资产类型"`
OldAssetIdentifier string `xlsx:"旧资产标识符"`
NewAssetIdentifier string `xlsx:"新资产标识符"`
ReceiverName string `xlsx:"收货人姓名"`
ReceiverPhone string `xlsx:"收货人电话"`
ReceiverAddress string `xlsx:"收货地址"`
ExpressCompany string `xlsx:"快递公司"`
TrackingNo string `xlsx:"快递单号"`
Status string `xlsx:"状态"`
CreatorName string `xlsx:"创建人"`
CreatedAt string `xlsx:"创建时间"`
}
6.8.6：代理充值导出
新增接口：POST /admin/agent-recharge-orders/export
去掉"支付通道"字段（需求文档中明确去掉），保留其他字段：
type AgentRechargeExportRow struct {
RechargeNo string `xlsx:"充值单号"`
ShopName string `xlsx:"店铺名称"`
RechargeType string `xlsx:"充值类型"`
RechargeAmount string `xlsx:"充值金额"`
ActualAmount string `xlsx:"实付金额"`
BalanceBefore string `xlsx:"充值前余额"`
BalanceAfter string `xlsx:"充值后余额"`
Status string `xlsx:"状态"`
PaymentMethod string `xlsx:"支付方式"`
// 去掉支付通道
OperationRemark string `xlsx:"运营备注"`
RejectReason string `xlsx:"驳回原因"`
CreatedAt string `xlsx:"创建时间"`
PaidAt string `xlsx:"支付时间"`
CompletedAt string `xlsx:"完成时间"`
SubmitterName string `xlsx:"提交人"`
DeptLeaderName string `xlsx:"部门领导审批人"`
FinanceName string `xlsx:"财务审批人"`
VoucherURLs string `xlsx:"支付凭证"`
Remark string `xlsx:"备注"`
}
前端对接（通用模式）
各导出入口：对应列表页右上角"导出"按钮（与现有导出按钮样式一致）。
调用流程：
- 点击"导出" → 携带当前筛选条件 →
POST /admin/{module}/export - 返回
export_task_id - 前端轮询
GET /admin/export-tasks/{id}直到status=completed - 下载
download_url
（与现有导出体系完全一致，复用现有前端导出 Hook）
权限导出配置（预留）
需求提到"不同权限显示的字段不同，角色管理中新增导出字段配置"。
本次迭代：统一导出全量字段，不做权限差异化（复杂度高，单独排期）。
预留方案：在导出 Handler 里预留 filterFieldsByRole(userRoles, rows) 的调用点，本次返回全量，后续加权限配置后在此处过滤。