Files
junhong_cmp_fiber/openspec/changes/add-silence-batch-extension/design.md

64 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## Context
- 现有特殊延期 `SubmitSpecial`(`internal/application/packagesilence/extension_submit.go`)输入为 `items[{package_usage_id, days}]`,`validateSpecialItems` 只允许 `expired` 套餐,任一行不合格整批拒绝;审批字段只带首条资产与 `item_count`。
- 执行 `executeBatch` → `executeExtensionInTx` 逐条独立事务;校验套餐仍为 `expired`。
- 批次表已有 `import_file_key`、计数字段;审批附件由 `ApprovalAttachmentUploader` 从对象存储 Key 下载后上传企微。
- 已有 `excelize`(`pkg/utils/excel.go`)与对象存储服务。
- 管理端批量入口在 `SilenceExtendDialog.vue`(CSV 填 `package_usage_id,days`),无批次页面。
## Goals / Non-Goals
**Goals:** 按资产号、统一天数的批量特殊延期;预检与部分提交;待实名套餐过期前延期;> 5 个资产的审批 xlsx 附件;批次查询。
**Non-Goals:** 不改在线付费、线下付费延期;不改单资产特殊延期接口;不改审批回调分发;批量不支持线下付费延期。
## Decisions
### 1. 新接口而非改造旧接口
新增 `POST /api/admin/package-silence/batch-extensions/precheck` 与 `POST /api/admin/package-silence/batch-extensions`,入参 `{identifiers[], days, extension_type, reason, basis, evidence_refs, amount, 线下收款信息..., import_file_key}`。提交内部把可延期明细转换为现有 `specialRow` 后复用批次创建、审批创建、执行流程。旧 `SubmitSpecial` 保持兼容(单资产与旧前端)。理由:输入模型(资产号 + 统一天数)与旧接口(套餐 ID + 逐行天数)不同,改旧接口会破坏现有单资产弹窗。
### 2. 资产展开
复用资产标识解析(`asset_identifier_store` / `ResolveIdentifier`):ICCID → 卡,卡有有效设备绑定则换成设备;虚拟号 / IMEI → 设备。以 `(asset_type, asset_id)` 去重。再查询资产名下 `deleted_at IS NULL AND silence_status IN ('expired','waiting')` 的套餐。
### 3. 预检复用资格计算,放开 waiting
把 `validateSpecialItems` 的逐行判定抽成 `checkSpecialUsage(usage, days, free, allowWaiting)`,批量路径 `allowWaiting=true`;返回结构化原因而不是累积错误。预检与提交共用同一函数,提交时服务端重跑,保证与预检一致或更严格(期间状态变化以提交时为准)。
### 4. 过期前延期执行
明细增加来源沉默期状态快照 `source_silence_status`。`executeExtensionInTx` 的状态校验从"必须 expired"改为"必须 expired,或明细来源为 waiting 且当前仍为 waiting/expired";新截止日统一 `SilenceDeadline(当前截止日期, 延长天数)`;`waiting` 套餐延期后状态不变(不调用激活),`expired` 套餐沿用"改为 waiting 并重新判定"。`ended`、失效、退款 → 该条失败。
### 5. 明细 xlsx 生成时机与存储
资产数 > 5 时,在业务事务之前用 excelize 生成 xlsx,上传对象存储(Key 前缀 `silence/batch-detail/{batch_no}.xlsx`),批次新增 `detail_file_key` 记录。审批字段新增 `ApprovalFieldSilenceDetailKeys = "detail_file_keys"`(FileList),在 `scene.go` 沉默期业务字段中登记(非必须映射)。上传失败直接拒绝提交,不建批次。事务内不调用外部接口,符合现有约束。≤ 5 时 `asset_identifier` 字段写全部资产号(顿号分隔)。
未映射"延期明细"时附注批次号到原因:由表单构建阶段判断映射是否存在不便,改为提交时总是在原因后附注"(批次 {batch_no},共 N 个资产)"于 > 5 场景,规则简单且无副作用。
### 6. 跳过明细存储
批次新增 `skipped_items jsonb`(资产号、资产类型、套餐、原因)与 `skipped_count`;详情接口返回。
### 7. 管理端
新增「批量延期」弹窗(入口:沉默期管理 / 延期批次页):填写统一信息 → 选择 xlsx / csv(一列资产号,前端解析,≤1000)→ 调预检展示可 / 不可延期表 → 确认提交。新增「延期批次」列表与详情页,详情可下载明细 xlsx(`detail_file_key` 签名下载,≤ 5 个资产时由后端即时生成)。旧弹窗中的 CSV 批量入口移除。
## Risks / Trade-offs
- [过期前延期改变既有"只能延期已过期"规则] → 仅批量特殊延期路径放开,单资产与付费延期不变;明细记录来源状态便于审计。
- [预检与提交之间状态变化] → 提交时服务端重跑,以提交时结果为准,前端提示差异条数。
- [1000 个资产展开后套餐数更多] → 明细上限按套餐 3000 条控制,超出拒绝并提示拆分。
- [企微附件大小] → 1000 资产 xlsx 约数十 KB,远低于限制。
## Migration Plan
1. 迁移:批次表加 `detail_file_key`、`skipped_items`、`skipped_count`;明细表加 `source_silence_status`(默认 `expired`)。
2. 部署后端;企微模板加"延期明细"附件控件,管理端场景配置补映射(可后补)。
3. 部署管理端前端。
4. 回滚:回滚镜像;新增字段有默认值,不影响旧逻辑。
## Open Questions
- 批量是否需要按代理 / 店铺范围限制可延期资产(目前沿用延期权限的数据范围)。