docs: 新增实名时间与历史、二次实名及按资产号批量延期提案

This commit is contained in:
邹进
2026-11-08 18:44:44 +09:00
parent 0138a3fb9c
commit 76d0f38b9e
12 changed files with 552 additions and 0 deletions

View File

@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-08

View File

@@ -0,0 +1,63 @@
## 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
- 批量是否需要按代理 / 店铺范围限制可延期资产(目前沿用延期权限的数据范围)。

View File

@@ -0,0 +1,32 @@
## Why
现有批量特殊延期藏在单个资产的延期弹窗里,导入 CSV 要填系统内部的 `package_usage_id` 且每行单独填天数,运营无法使用;名单有一条不合格就整批拒绝;企微审批单只显示首条资产和条数,审批人看不到 100 个资产的明细;管理端也没有批次查询页面。
## What Changes
- 管理端新增独立的「批量延期」弹窗:延期天数、延期类型、原因、依据、附件只填一次,所有资产统一天数。
- 导入文件只有一列:ICCID / 虚拟号 / IMEI;ICCID 对应卡绑定在设备上时按设备处理,同一资产重复只算一次。
- 资产名下所有处于沉默期的套餐(已过期、待实名)全部延期;**新增"过期前延期"**:待实名套餐也可通过特殊延期把截止日延后(原截止日 + 天数),状态保持待实名。
- 新增预检:逐资产逐套餐列出可延期 / 不可延期及原因、原截止日、新截止日;提交时只提交可延期的,不可延期的记入批次结果(不再整批拒绝)。
- 企微审批:资产数 ≤ 5 时审批单"资产"列出全部资产号;> 5 时系统生成 xlsx 明细作为附件上传到审批单(新增业务字段"延期明细",模板增加附件控件);明细文件同时可在管理端下载。
- 管理端新增延期批次列表与详情页:审批状态、成功 / 失败 / 跳过条数、逐条结果、下载明细。
- 原有按 `package_usage_id` 的单资产特殊延期保持不变。
## Capabilities
### New Capabilities
(无)
### Modified Capabilities
- `package-silence-extension`(本迭代 `add-package-silence-period` 引入,尚未归档):新增按资产号的批量特殊延期、预检、过期前延期、审批明细附件、批次查询。以 ADDED 需求补充,不修改未归档变更的原文。
## Impact
- 后端:`internal/application/packagesilence/`(新增批量资产解析、预检、过期前延期执行、明细 xlsx 生成)、审批字段常量与企微场景字段登记(`internal/application/wecom/scene.go`)、DTO 与路由。
- 依赖:复用已引入的 `github.com/xuri/excelize/v2` 与对象存储;企微附件复用现有审批附件上传。
- 数据库:延期批次增加明细文件 Key、跳过明细(jsonb)字段;延期明细允许来源状态为待实名。
- 企微:沉默期审批模板新增"延期明细"附件控件;场景配置新增映射。
- 管理端前端(`iteration/8-11`):批量延期弹窗、批次列表与详情页(另在前端仓库落地)。
- 只部署测试环境。

View File

@@ -0,0 +1,88 @@
## ADDED Requirements
### Requirement: 按资产号批量特殊延期
有 `package_silence:extend_batch` 权限的运营 SHALL 可按资产号提交批量特殊延期:一次填写延期类型(免费 / 优惠价 / 客诉补偿 / 系统异常补偿 / 特殊客户政策)、统一延期天数、原因、依据、申请附件(优惠价有收款时另填线下收款信息),资产名单为 ICCID / 虚拟号 / IMEI(单批最多 1000 个)。系统 MUST 按以下规则展开为套餐明细:
- ICCID 对应卡绑定在设备上时按设备处理;同一资产在名单中重复出现只算一次;
- 资产名下 `silence_status` 为 `expired` 或 `waiting` 的套餐全部纳入;
- 所有明细使用同一延期天数(按 30 天向上取整计费 / 延长)。
#### Scenario: ICCID 对应设备卡
- **WHEN** 名单中有设备 A 的一张绑定卡 ICCID,同时有设备 A 的 IMEI
- **THEN** 设备 A 只算一个资产,其名下沉默期套餐只延期一次
#### Scenario: 一个资产多笔套餐
- **WHEN** 设备 B 有 1 笔已过期、1 笔待实名、1 笔已结束沉默期的套餐
- **THEN** 已过期与待实名两笔纳入延期,已结束的不纳入
### Requirement: 批量延期预检
系统 SHALL 提供预检接口,输入与提交相同,返回逐资产、逐套餐结果:资产号、资产类型、套餐名称、沉默期状态、原截止日、新截止日、是否可延期及不可延期原因。不可延期原因包括:资产不存在或无权限、资产无沉默期套餐、套餐已有未结束的延期订单或申请、免费延期次数已用完、延期天数不足最小月数。预检 MUST NOT 产生任何数据变更。
#### Scenario: 名单含不存在资产
- **WHEN** 名单 100 个资产,其中 3 个不存在、2 个无沉默期套餐
- **THEN** 预检返回 95 个资产的可延期明细与 5 个不可延期资产及原因
### Requirement: 只提交可延期明细
提交时系统 SHALL 在服务端重新执行预检,只将可延期的套餐明细写入批次;不可延期的资产与套餐 MUST 记入批次的跳过明细(含原因),不得导致整批拒绝。可延期明细为 0 时 MUST 拒绝提交。审批、免审批与执行规则沿用现有特殊延期(政策 `batch` 免审批场景决定是否审批,审批通过后逐条执行,部分失败不影响其他行)。
#### Scenario: 部分不可延期
- **WHEN** 提交 100 个资产,预检 95 个可延期
- **THEN** 批次含 95 个资产的明细,5 个记为跳过及原因,审批与执行只针对 95 个
#### Scenario: 全部不可延期
- **WHEN** 名单中没有任何可延期套餐
- **THEN** 拒绝提交,提示没有可延期的套餐
### Requirement: 过期前延期
批量特殊延期中 `silence_status = waiting` 的套餐 SHALL 可执行延期:新截止日 = `SilenceDeadline(原截止日期, 延长天数)`,`silence_status` 保持 `waiting`,累计延期天数、延期次数、免费次数(免费延期)按现有规则累加,写明细、流水与审计。执行时 MUST 重读套餐:仍为 `waiting` 或已变为 `expired` 的照常延期;已变为 `ended`(期内已实名)或套餐已失效、退款的,该条记失败并注明原因,不影响其他行。
#### Scenario: 待实名套餐延期
- **WHEN** 待实名套餐截止日 11-20,批量延期 30 天
- **THEN** 截止日变为 12-20,状态仍为待实名
#### Scenario: 审批期间已实名
- **WHEN** 待实名套餐在审批期间完成实名、沉默期结束
- **THEN** 审批通过后该条记失败"沉默期已结束,无需延期",其他条照常执行
### Requirement: 审批单资产明细
批量特殊延期提交企微审批时,系统 SHALL 按资产数决定明细呈现:资产数 ≤ 5 时审批单"资产"字段列出全部资产号(顿号分隔);资产数 > 5 时"资产"字段为首个资产号并注明"等 N 个",同时系统 MUST 生成 xlsx 明细文件存入对象存储,作为新业务字段"延期明细"(附件)上传到审批单。明细列:序号、资产号、资产类型、套餐名称、沉默期状态、原截止日、延期天数、新截止日。明细文件 MUST 在审批创建前生成,生成失败则拒绝提交且不产生批次。
#### Scenario: 100 个资产的审批单
- **WHEN** 批量延期 100 个资产提交审批
- **THEN** 审批单"资产"显示"首个资产号 等 100 个",附件含 100 个资产全部套餐明细的 xlsx
#### Scenario: 3 个资产的审批单
- **WHEN** 批量延期 3 个资产
- **THEN** 审批单"资产"列出 3 个资产号,不生成附件
### Requirement: 沉默期审批场景新增延期明细字段
沉默期审批业务类型 SHALL 新增可映射业务字段"延期明细"(附件列表),企微场景配置可将其映射到模板附件控件;该字段非必须映射,未映射时 > 5 个资产的审批单只显示首个资产与条数并在"原因"后附注"明细见管理端批次 {批次号}"。
#### Scenario: 场景未映射延期明细
- **WHEN** 场景配置未映射"延期明细",提交 20 个资产的批量延期
- **THEN** 审批正常提交,原因字段附注批次号,管理端可下载明细
### Requirement: 延期批次查询
管理端 SHALL 提供延期批次列表(按批次号、路径、延期类型、审批状态、提交时间筛选,分页)与批次详情(基本信息、审批状态、成功 / 失败 / 跳过条数、逐条明细与失败原因、跳过资产及原因、下载明细 xlsx)。数据范围沿用现有延期权限。
#### Scenario: 查看批次结果
- **WHEN** 运营打开一个已执行的批量延期批次
- **THEN** 看到 95 条中成功 93、失败 2 及原因,以及跳过的 5 个资产及原因,可下载明细

View File

@@ -0,0 +1,37 @@
## 1. 数据模型
- [ ] 1.1 迁移:批次表加 `detail_file_key`、`skipped_items`(jsonb)、`skipped_count`;延期明细加 `source_silence_status`(默认 expired),含 down
- [ ] 1.2 model、常量:审批字段 `detail_file_keys`、明细上限、跳过原因编码
## 2. 资产展开与预检
- [ ] 2.1 资产号解析与去重:ICCID→卡(绑定设备则换设备)、虚拟号/IMEI→设备;查询 expired / waiting 套餐
- [ ] 2.2 抽取 `checkSpecialUsage`(支持 allowWaiting),旧 `validateSpecialItems` 改为调用它且行为不变
- [ ] 2.3 预检接口 DTO、handler、路由(`package_silence:extend_batch`),返回逐资产逐套餐结果
- [ ] 2.4 表驱动测试:设备去重、多套餐、无沉默期套餐、免费次数用完、已有进行中申请
## 3. 提交与执行
- [ ] 3.1 提交接口:服务端重跑预检,只写可延期明细,跳过明细入批次;0 条拒绝
- [ ] 3.2 复用批次创建、免审批判定与审批创建;审批字段 ≤5 列全部资产号、>5 写首个 + 条数并附注批次号
- [ ] 3.3 >5 时事务前生成 xlsx 明细并上传对象存储,记录 `detail_file_key`,作为 `detail_file_keys` 审批字段;失败拒绝提交
- [ ] 3.4 `executeExtensionInTx` 支持来源 waiting 的明细:仍 waiting 只延截止日,expired 走原流程,ended/失效/退款记失败
- [ ] 3.5 企微场景字段登记"延期明细"(FileList,非必须映射)
- [ ] 3.6 测试:部分跳过、全部跳过、waiting 延期、审批期间已实名失败、旧单资产特殊延期回归
## 4. 批次查询
- [ ] 4.1 批次列表筛选(批次号、路径、延期类型、审批状态、时间)与详情返回跳过明细、计数
- [ ] 4.2 明细下载接口:有 `detail_file_key` 签名下载,否则即时生成
## 5. 管理端前端(admin `iteration/8-11`)
- [ ] 5.1 批量延期弹窗:统一天数/类型/原因/依据/附件,导入一列资产号(xlsx/csv,≤1000),预检结果表,确认提交
- [ ] 5.2 延期批次列表与详情页,下载明细;菜单与权限
- [ ] 5.3 移除单资产弹窗中的旧 CSV 批量入口
## 6. 验证与部署
- [ ] 6.1 `go build ./...`、`go vet`、相关测试通过;前端构建与测试通过
- [ ] 6.2 部署测试环境,用 6 个以上过期 / 待实名设备验证预检、提交、xlsx 附件生成(企微场景配置后验证审批单附件)
- [ ] 6.3 更新 `docs/` 前端对接说明与企微模板配置说明