更新一下prd
This commit is contained in:
@@ -1345,21 +1345,23 @@
|
||||
|
||||
页面入口：批量订购套餐页或现有订单页批量入口。
|
||||
|
||||
权限：仅超级管理员或具备独立“批量订购套餐”权限的平台账号展示入口并调用创建、任务详情和明细接口；代理和企业账号不展示入口，后端仍必须独立拒绝。
|
||||
入口：页面是否展示沿用前端现有可见性规则；后端不新增批量订购权限码或账号类型拦截，调用复用现有后台认证。
|
||||
|
||||
页面结构：
|
||||
1. 选择整批支付方式（线下或代理钱包）并上传CSV；不选择代理，线下支付时上传整批凭证，不接受Excel。
|
||||
2. CSV模板下载使用前端静态文件，编码为UTF-8并允许BOM。
|
||||
1. 选择一个套餐和整批支付方式（线下或代理钱包）并上传CSV；不选择代理，线下支付时上传整批凭证，不接受Excel。
|
||||
2. CSV模板下载使用前端静态文件，编码为UTF-8并允许BOM，唯一表头为“资产标识”。
|
||||
3. 创建后展示任务号、状态、总数、成功数、失败数、金额汇总和失败明细表。
|
||||
4. 失败明细包含行号、资产、套餐编码、错误原因；支持按任务ID恢复页面。
|
||||
4. 失败明细包含行号、原始/规范资产标识和错误原因；支持按任务ID恢复页面。资产类型由统一资产解析能力识别，当前支持ICCID、卡virtual_no、MSISDN、设备virtual_no、IMEI和SN，前端不要求用户填写资产类型。
|
||||
|
||||
接口约定：
|
||||
- CSV先调用POST /api/admin/storage/upload-url，purpose=bulk_purchase，使用返回的upload_url直传后取得file_key；线下凭证按附件用途直传取得voucher_keys。
|
||||
- POST /api/admin/bulk-purchases只接收JSON：request_id、payment_method、file_key、voucher_keys；不接收shop_id、multipart或文件字节。
|
||||
- POST /api/admin/bulk-purchases只接收JSON：request_id、单个package_id、payment_method、file_key、voucher_keys；不接收shop_id、multipart或文件字节。
|
||||
- GET /api/admin/bulk-purchases/{task_id} 返回任务汇总。
|
||||
- GET /api/admin/bulk-purchases/{task_id}/items?page=&size=&status= 返回逐行结果。
|
||||
- GET /api/admin/bulk-purchases/{task_id}/items?page=&page_size=&status= 返回逐行结果。
|
||||
|
||||
交互规则：一个批次不能混合支付方式；同一CSV允许不同代理资产，代理归属由后端逐行解析，前端不提交或猜测；部分成功视为任务终态；某代理钱包余额不足只影响使用该钱包的相应行，不回滚已成功行。
|
||||
交互规则：一个批次固定一个套餐且不能混合支付方式；同一CSV允许不同代理资产，代理归属由后端逐行解析，前端不提交或猜测；任务状态统一为1待处理、2处理中、3已完成、4已失败、5已取消，部分成功只由成功数/失败数表达；wallet批次严格按CSV行号逐行结算，行序就是同一代理余额不足时的订购优先级，当前行余额不足只失败该行并继续尝试后续行，不预占或回滚该代理全部行。
|
||||
|
||||
文件级错误异步展示：创建接口通过后不代表CSV内容有效；Worker发现编码、表头、未知列、CSV语法、空文件或超过1000行时，任务整体失败且不会创建任何订单。资产、套餐、归属、钱包和重复行错误才展示为逐行失败。MSISDN未命中或命中多张卡时只失败该行，前端展示后端原因。
|
||||
|
||||
完成标准：上传、进度恢复、部分成功、失败筛选和凭证展示完整。
|
||||
```
|
||||
@@ -1381,11 +1383,13 @@
|
||||
|
||||
接口：POST /api/admin/bulk-purchases；GET /api/admin/bulk-purchases/{task_id}；GET /api/admin/bulk-purchases/{task_id}/items。
|
||||
|
||||
权限：仅超级管理员或具备独立“批量订购套餐”权限的平台账号可创建和读取任务；代理、企业账号一律拒绝。规则：整批选择offline或agent_wallet，不接收shop_id；同一CSV可以包含不同代理资产，逐行以资产当前归属解析结算代理；CSV和凭证先直传私有对象存储，业务接口只接收稳定file_key/voucher_keys；仅接受UTF-8 CSV（允许BOM），不接受Excel；模板按套餐编码匹配；文件最大10MB、最多1000行；同一文件按“资产类型+标准化资产标识+套餐编码”判重，首行正常处理、后续重复行失败并指出首行号，同一资产的不同套餐不算重复；request_id唯一返回原任务；行幂等键为bulk_purchase:{task_id}:{row_no}。
|
||||
入口与规则：后端不新增批量订购权限码、账号类型拦截或任务创建人隔离，复用现有后台认证；创建任务选择单个package_id和整批offline|wallet，wallet表示逐行扣结算代理主钱包，不新增agent_wallet；不接收shop_id；同一CSV可以包含不同代理资产，逐行以资产当前归属解析结算代理；CSV只有“资产标识”一列，资产类型和ID由系统统一资产解析能力识别，当前支持ICCID、卡virtual_no、MSISDN、设备virtual_no、IMEI和SN，批量模块不另写识别规则；CSV和凭证先直传私有对象存储，业务接口只接收稳定file_key/voucher_keys；创建接口校验套餐存在以及对象、上传归属、类型和10MB大小，Worker校验UTF-8（允许BOM）、单列表头、未知列、CSV语法、空文件和1000行上限，文件级错误使任务失败且不创建订单；不接受Excel；标识未命中或无法唯一解析只失败该行；同一文件按解析后的“资产类型+资产ID”判重，同一资产使用不同标识仍只处理首行，后续失败并指出首行号；request_id唯一返回原任务；行幂等键为bulk_purchase:{task_id}:{row_no}。任务统一状态为1待处理、2处理中、3已完成、4已失败、5已取消，部分成功只由success_count/fail_count表达；逐行明细状态为1待处理、2处理中、3成功、4失败。
|
||||
|
||||
钱包行事务：锁该行资产所属代理的主钱包，按信用不变量校验，订单、扣款、流水、结算代理快照和明细成功状态同事务；无代理归属、无有效主钱包或余额不足只失败对应行，单行失败不回滚其他行；任务统计从明细重新聚合。线下凭证只做本批资料，不校验跨批唯一。
|
||||
钱包行事务：严格按CSV行号逐行处理并锁该行资产所属代理的主钱包，按信用不变量校验，订单、扣款、流水、结算代理快照和明细成功状态同事务；不预占整批或某一代理全部行金额，无代理归属、无有效主钱包或余额不足只失败当前行并继续后续行，后续较小金额若余额足够仍可成功；任务统计从明细重新聚合。线下凭证只做本批资料，不校验跨批唯一。
|
||||
|
||||
完成标准：Worker处理租约、重复消费、进程中断恢复和部分成功均不产生重复订单或重复扣款。
|
||||
|
||||
测试环境约定：已部署测试环境使用Redis DB 6；本地开发和Agent自动化测试强制使用DB 7，测试启动时必须校验实际生效DB并在不是7时失败，禁止向DB 6投递任务，也禁止对DB 7执行FLUSHDB。自动化测试直连当前真实S3并按唯一Key精确清理，不做内存替身；PostgreSQL沿用现有测试库，夹具按唯一运行标识和实际记录ID精确清理，禁止TRUNCATE、清表、模糊删除或修改既有业务数据。Go HTTP集成测试使用Fiber app.Test穿过真实认证和业务链路，捕获任务后直接调用公开Worker Handler，不通过sleep等待后台Worker；实现时沉淀可复用的测试规范、环境守卫/清理Harness、CSV testdata和完整示例，并提供只用于部署冒烟的curl模板。
|
||||
```
|
||||
|
||||
## UR#35 退款审核
|
||||
@@ -1408,21 +1412,21 @@
|
||||
页面入口：退款创建、退款列表、退款详情。
|
||||
|
||||
页面结构：
|
||||
1. 创建表单包含退款金额、原因、备注和附件；金额提交后企微审批不可修改。
|
||||
1. 创建表单包含订单、退款金额、必填原因、可选备注和1～5个附件；附件提交file_key、file_name、file_size，金额提交后企微审批不可修改；前端不提交实收金额或套餐使用记录。
|
||||
2. 详情分为退款业务信息、企微审批信息、业务处理结果三个区域。
|
||||
3. 审批区展示sp_no、状态、申请人、审批人、意见、附件和时间线。
|
||||
3. 审批区按主体权限展示：代理只见真实申请人、审批状态和业务处理结果；平台/超级管理员具备退款查看权限时才展示sp_no、审批人、意见、审批附件和时间线。
|
||||
4. 处理区展示processing_status、失败摘要和“系统重试中/联系管理员”。
|
||||
5. 不显示本地通过、驳回、退回或人工退款确认按钮。
|
||||
|
||||
接口约定：
|
||||
- POST /api/admin/refunds 创建退款。
|
||||
- POST /api/admin/refunds 创建退款，请求只包含order_id、requested_refund_amount、refund_reason、remark和attachments。
|
||||
- GET /api/admin/refunds/{id} 返回退款数据、approval对象和processing_status。
|
||||
- attachments使用现有对象存储上传结果，提交结构为 {file_key,file_name,file_size}[]。
|
||||
- approval结构至少包含 source、sp_no、status、status_name、template_version、applicant、approvers、comments、attachments、timeline、business_process_result。
|
||||
|
||||
交互规则：非代理钱包由财务在系统外人工退款后再在企微通过。企微拒绝后当前退款单终结，详情只读且不提供编辑或重提；业务人员处理拒绝原因后仍需退款时，重新进入创建退款流程并填写金额、凭证和原因，成功后展示新的退款ID、退款单号和审批信息。
|
||||
|
||||
完成标准：审批中、通过处理中、处理成功、驳回、撤销和通过后撤销异常状态均展示明确。
|
||||
完成标准：审批中、通过处理中、处理成功、处理失败、驳回、撤销和通过后撤销异常状态均展示明确；申请金额小于实收金额时明确提示通过后仍按整单终结。
|
||||
```
|
||||
|
||||
### 后端研发需求
|
||||
@@ -1430,26 +1434,30 @@
|
||||
**标题**
|
||||
|
||||
```text
|
||||
[BE][UR#35] 退款企微终态与人工退款处理
|
||||
[BE][UR#35] 退款企微终态与整单退款终结
|
||||
```
|
||||
|
||||
**描述**
|
||||
|
||||
```markdown
|
||||
目标：退款通过企微审批驱动业务终态，系统只自动回溯代理主钱包支付。
|
||||
目标：退款通过企微审批驱动整单业务终态，系统只自动回溯代理主钱包支付。
|
||||
|
||||
预计工时：后端4～5小时。
|
||||
|
||||
接口：POST /api/admin/refunds；GET /api/admin/refunds/{id}；下线原approve/reject/return/resubmit路由。
|
||||
接口：POST /api/admin/refunds；GET /api/admin/refunds；GET /api/admin/refunds/{id}；下线原approve/reject/return/resubmit及任何manual-complete路由。
|
||||
|
||||
规则：
|
||||
1. 非代理钱包支付由财务人工退款，企微通过代表人工退款已确认，不调用渠道退款API。
|
||||
2. 代理钱包订单通过后按原扣款流水幂等回溯原代理主钱包并写退款流水。
|
||||
3. 个人客户或资产钱包不自动回款。
|
||||
4. 驳回更新为已拒绝；撤销/删除更新为已撤销；通过后撤销且资金已执行不自动冲正，记录critical审计。
|
||||
5. 一张退款单只创建一条企微审批申请，业务表保存唯一approval_instance_id并由(biz_type,biz_id)唯一约束防重。正常结果只有同意或拒绝，任一结果产生后审批与退款单同时完结；拒绝后原退款单不可修改、不可重提。若仍需退款，必须重新调用创建接口，生成新的退款ID、退款单号、业务快照、提交人快照和企微审批；旧单只保留为历史事实，已拒绝退款不阻止新建，但仍需阻止存在其他活跃退款时重复创建。撤销、删除或通过后撤销只作外部异常处置，不作为自动放行新退款的依据。
|
||||
1. 创建请求只接受order_id、requested_refund_amount、必填refund_reason、可选remark和1～5个结构化attachments；后端读取订单实收金额并校验0<申请金额<=实收金额，不接受actual_received_amount或package_usage_id。
|
||||
2. 申请金额在企微只读，审批人只能同意或拒绝。无论申请金额是否等于实收金额，通过后都把订单标记已退款、该订单全部有效套餐失效、全部佣金失效，并禁止再退剩余差额。
|
||||
3. 非代理主钱包支付由财务系统外退款，企微通过代表人工退款已确认，不调用渠道退款API、不回充个人资产钱包，也不再二次人工确认；actual_refund_amount在资金已完成时写申请金额。
|
||||
4. 代理钱包订单通过后只按原扣款流水幂等回溯原代理主钱包并写唯一退款流水；缺少原流水则失败，不按当前关系猜测钱包。
|
||||
5. 已发放佣金全额从佣金钱包扣回并允许负余额，其他未发放佣金直接失效；佣金记录保存结构化失效原因、退款引用和失效时间。订单套餐按整单失效，主套餐级联加油包并尝试下一排队主套餐。
|
||||
6. 驳回更新为已拒绝；撤销/删除更新为已撤销；通过后撤销且资金已执行不自动冲正，记录critical审计和站内告警。
|
||||
7. 一张退款单只创建一条企微审批申请，业务表保存唯一approval_instance_id并由(biz_type,biz_id)唯一约束防重。正常结果只有同意或拒绝，任一结果产生后审批与退款单同时完结；拒绝后原退款单不可修改、不可重提。若仍需退款，必须重新调用创建接口，生成新的退款ID、退款单号、业务快照、提交人快照和企微审批；旧单只保留为历史事实，已拒绝退款不阻止新建，但仍需阻止存在其他活跃退款时重复创建。撤销、删除或通过后撤销只作外部异常处置，不作为自动放行新退款的依据。
|
||||
8. 代理按既有店铺层级和退款业务权限查看本店及可管理下级退款，不再按creator隔离；代理不见审批人、内部意见或审批人附件，平台/超级管理员也须有退款业务查看权限。
|
||||
9. 企微终态通过Outbox和可靠Worker处理，processing_status固定0未触发、1处理中、2处理成功、3处理失败，局部失败可安全重试，不使用进程内Goroutine。
|
||||
|
||||
完成标准：审批状态与业务处理状态分离，重复终态不重复回款，失败任务可可靠重试。
|
||||
完成标准：审批状态与业务处理状态分离，重复终态不重复回款/扣佣/失效套餐，失败任务可可靠重试；实现期必须通过可编程Adapter自动化和真实企微两张独立退款验收（代理代提交同意、平台本人提交拒绝），INT-06不能替代。
|
||||
```
|
||||
|
||||
## UR#34 充值审核流程
|
||||
@@ -1596,7 +1604,7 @@
|
||||
|
||||
交付内容：
|
||||
1. 统一加载、空数据、权限不足、接口失败和重试状态。
|
||||
2. 统一异步任务进度结构：任务状态、总数、成功数、失败数、部分成功和失败明细。
|
||||
2. 统一异步任务进度结构：状态固定为1待处理、2处理中、3已完成、4已失败、5已取消；总数、成功数、失败数和失败明细独立返回，部分成功只由计数表达，不占状态码。
|
||||
3. 创建任务后按2秒、3秒、5秒递增轮询，最大间隔10秒；页面不可见暂停，恢复后立即刷新。
|
||||
4. 页面刷新后通过task_id恢复任务详情。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user