触发通知轮询

2026-07-28 14:25:18 +08:00
parent 4aff9937e5
commit 9303af3d46
9 changed files with 228 additions and 1 deletions
--- a/docs/7月迭代/README.md
+++ b/docs/7月迭代/README.md
@@ -9,6 +9,7 @@
 - [7月迭代禅道研发需求拆分表](./7月迭代禅道研发需求拆分表.md)
 - [7月迭代禅道研发需求逐条录入稿](./7月迭代禅道研发需求逐条录入稿.md)
 - [七月迭代 AI 实施与验收操作手册](./七月迭代-AI实施与验收操作手册.md)
+- [七月迭代人工验收清单](./七月迭代人工验收清单.md)

 评审、开发和验收均以标准评审稿为准。独立稿用于解释方案来源；与标准稿冲突时，标准稿优先。

--- a/docs/7月迭代/七月迭代人工验收清单.md
+++ b/docs/7月迭代/七月迭代人工验收清单.md
@@ -0,0 +1,101 @@
+# 七月迭代人工验收清单
+
+> 用途：前后端联调完成后的逐项人工核对。页面可访问不等于验收通过；每项至少检查权限、正常路径、失败路径、重复操作和最终数据。
+
+## 一、业务需求
+
+- [ ] **UR#33 套餐临期提醒**：核对 0～15 天临期列表、0～3 天置顶、Dashboard 数量、C 端续费入口，以及 15/7/3 天站内通知和防重。
+- [ ] **UR#34 充值审核流程**：核对代理在线扫码充值与平台线下代充值隔离；支付、企微审批、重复回调、入账补偿和到账通知正确。
+- [ ] **UR#35 退款审核**：核对企微审批、整单终结、钱包回充、套餐失效和佣金处理；审批状态与业务处理状态分开，重复终态不重复退款。
+- [ ] **UR#36 批量订购套餐**：核对 CSV 上传、跨代理资产、统一支付方式、逐行结果、部分成功、失败原因、任务恢复及重复执行不重复扣款。
+- [ ] **UR#37 企业微信审核流转**：核对企微应用、模板、成员绑定、代理固定代提交人、回调、主动同步和异常恢复；系统内不得提供本地同意或拒绝入口。
+- [ ] **UR#38 不同渠道额度处理**：核对角色默认信用只影响新店铺；已有店铺单独调额；扣款、冻结、退款、充值及并发修改遵守代理主钱包信用边界。
+- [ ] **UR#40 下架套餐历史续费**：核对下架套餐不能新购，但历史使用资产可以续费；直接请求不能绕过资格校验。
+- [ ] **UR#42 统一导出与字段权限**：核对角色字段配置、不同角色最终列、数据行范围、CSV/XLSX、任务恢复及受保护附件。当前仓库已知角色级导出字段权限尚未实现。
+- [ ] **UR#43 代理系列套餐批量授权**：核对首次授权必须包含套餐；后续支持批量新增、改价和移除；已授权项不可重复选择，并兼容 `packages[].remove`。
+- [ ] **UR#44 列表提交人与审批摘要**：核对退款、充值、换货列表的提交人、审批来源、审批状态、当前审批人和处理状态；分页不得逐行请求审批详情。
+- [ ] **UR#45 换货新旧资产独立搜索**：核对旧资产和新资产筛选互不混淆，支持 ICCID、接入号和虚拟号，组合筛选及数据权限正确。
+- [ ] **UR#46 预计最终到期时间**：核对无套餐、单套餐、多个排队套餐和未知激活时间；后台详情、卡/设备列表与 C 端结果一致。
+- [ ] **UR#47 卡片手动限速**：核对仅 IoT 卡详情提供固定档位和恢复不限速；设备无入口；明确失败与结果未知提示正确。
+- [ ] **UR#48 不同资产使用不同支付方式**：核对卡、设备允许方式不同；订单创建固化方式，支付再次校验；配置变化后旧单取消重建。
+- [ ] **UR#49 设备批量分配代理和套餐系列**：核对两个独立入口、CSV 文本格式、任务进度、部分成功、失败明细、重试幂等及平台代理权限。
+- [ ] **UR#53 卡和设备实名状态筛选**：核对全部、已实名、未实名筛选；设备状态随绑定、解绑、换卡正确变化，翻页保留筛选条件。
+- [ ] **UR#55 套餐生效条件**：核对套餐默认值、代理覆盖值和最终值；只影响未来购买；订单和使用记录保存并使用购买快照。
+- [ ] **UR#57 退款中禁止换货**：核对活跃退款资产创建换货直接失败且不产生半成品；退款拒绝、撤销或处理完成后允许换货。
+- [ ] **UR#60 店铺联系电话检索**：核对 11 位联系电话精确查询、非法号码、空结果及代理数据范围。
+- [ ] **UR#62 H5 购买与实名顺序**：核对无需实名、先实名后购买、先购买后实名三种流程；卡/设备批量配置和冲突提示正确。
+- [ ] **UR#73 按运营商实名能力控制复机**：核对不能只按行业卡放行；不同运营商的无需实名、模板实名、Gateway 实名规则分别生效。
+- [ ] **UR#86 资产换货链**：核对资产详情前代、后代和链路跳转；旧资产、新资产、中间资产及无权限场景正确。
+- [ ] **UR#94 卡状态同步与运营商回调**：核对轮询、手动刷新、业务操作和移动/联通/电信回调统一更新；设备号不得传给要求 ICCID 的 Gateway。
+- [ ] **UR#96 店铺业务员归属**：核对店铺创建、编辑、清空、筛选和详情；只能绑定启用的平台账号，代理不能指定其他业务员。
+- [ ] **UR#97 代理钱包低余额提醒**：核对现金可用余额首次降至 100 元以下时通知一次；持续低位不重复，回升后可再次触发。
+- [ ] **UR#98 换货新资产继承店铺**：核对换货完成后新资产自动继承旧资产店铺；前端不能选择目标店铺；重复完成幂等且不能越权换入其他店铺资产。
+
+需求16明确排除，不应出现对应入口、迁移或业务逻辑。
+
+## 二、公共技术能力
+
+- [ ] **七月公共开发基础**：Outbox、幂等、异步任务五态、配置、迁移和任务中断恢复。
+- [ ] **公共站内通知**：未读数、列表、已读、防重、接收人和受控跳转。
+- [ ] **全局审计与外部集成追踪**：人员、资源、资金、风险、请求链路和外部调用。该部分曾移出当前交付范围，应单独确认最终约定。
+
+## 三、临期功能专项验证
+
+### 3.1 实时列表
+
+```http
+GET /api/admin/expiring-assets
+```
+
+该接口每次请求都根据当前套餐、排队套餐和购买快照实时计算，不依赖定时任务。建议准备预计最终到期分别为 15、8、7、4、3、0、已过期和无法预计的资产，核对：
+
+- [ ] 只有剩余 0～15 个上海自然日且可精确推算的资产进入列表。
+- [ ] 0～3 天为红色并优先，4～7 天为紫色，8～15 天为粉色。
+- [ ] 已过期、无套餐和等待未知实名激活的资产不进入临期列表。
+- [ ] 卡、设备数量汇总和分页列表使用相同筛选及权限口径。
+
+### 3.2 手动触发通知扫描
+
+```http
+POST /api/admin/expiring-assets/reminder-scan
+Authorization: Bearer <超级管理员Token>
+```
+
+成功响应示例：
+
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "task_type": "package:expiry:reminder",
+    "message": "套餐临期提醒扫描任务已提交"
+  }
+}
+```
+
+接口只允许超级管理员调用，并立即提交与每日 03:00 相同的异步任务。Worker 只处理当天恰好剩余 15、7、3 天的资产，随后通过 Outbox 生成个人客户站内通知。
+
+- [ ] API 返回成功后 Worker 日志出现“开始执行套餐临期节点提醒”。
+- [ ] 15、7、3 天资产产生通知；其他剩余天数不产生节点通知。
+- [ ] 同一资产、到期日、节点和接收人重复触发不重复通知。
+- [ ] 未绑定启用个人客户的资产不产生错误通知。
+- [ ] Worker 或 Outbox 暂时失败后可重试，且最终仍只有一条通知。
+
+## 四、全链路检查
+
+- [ ] **INT-01**：实名、复机、卡状态同步和运营商回调。
+- [ ] **INT-02**：换货创建、退款拦截、完成、资产归属和换货链。
+- [ ] **INT-03**：套餐授权、购买、生效条件、续费、预计到期和临期提醒。
+- [ ] **INT-04**：CSV 批量任务、进度恢复、导出和字段权限。
+- [ ] **INT-05**：支付方式、扫码充值、钱包信用、退款回充和余额预警。
+- [ ] **INT-06**：企微审批、退款、线下充值和重复回调。
+- [ ] **INT-07**：IoT 卡限速和 Gateway 调用。
+- [ ] **INT-08**：权限收回、重复提交、Worker 重启、外部超时和发布回滚。
+
+## 五、依据
+
+- [七月迭代技术方案（标准评审稿）](./7月迭代技术方案-标准评审稿.md)
+- [七月迭代禅道研发需求逐条录入稿](./7月迭代禅道研发需求逐条录入稿.md)
+- [七月迭代 AI 实施与验收操作手册](./七月迭代-AI实施与验收操作手册.md)
+
--- a/docs/admin-openapi.yaml
+++ b/docs/admin-openapi.yaml
@@ -9889,6 +9889,15 @@ components:
                    description: 表名，为空则清理所有
                    type: string
            type: object
+        DtoTriggerPackageExpiryReminderResponse:
+            properties:
+                message:
+                    description: 任务提交结果说明
+                    type: string
+                task_type:
+                    description: 已提交的异步任务类型
+                    type: string
+            type: object
        DtoTriggerSingleReq:
            properties:
                card_id:
@@ -18959,6 +18968,65 @@ paths:
            summary: 查询临期资产列表
            tags:
                - 资产管理
+    /api/admin/expiring-assets/reminder-scan:
+        post:
+            description: 仅超级管理员可调用。立即提交与每日 03:00 相同的 15、7、3 天节点扫描任务；任务异步执行并沿用通知防重，不生成临期列表快照。
+            responses:
+                "200":
+                    content:
+                        application/json:
+                            schema:
+                                properties:
+                                    code:
+                                        description: 响应码
+                                        example: 0
+                                        type: integer
+                                    data:
+                                        $ref: '#/components/schemas/DtoTriggerPackageExpiryReminderResponse'
+                                    msg:
+                                        description: 响应消息
+                                        example: success
+                                        type: string
+                                    timestamp:
+                                        description: 时间戳
+                                        format: date-time
+                                        type: string
+                                required:
+                                    - code
+                                    - msg
+                                    - data
+                                    - timestamp
+                                type: object
+                    description: 成功
+                "400":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                    description: 请求参数错误
+                "401":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                    description: 未认证或认证已过期
+                "403":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                    description: 无权访问
+                "500":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                    description: 服务器内部错误
+            security:
+                - BearerAuth: []
+            summary: 手动触发套餐临期提醒扫描
+            tags:
+                - 资产管理
    /api/admin/export-tasks:
        get:
            description: 支持按 scene/status/time 过滤，分页默认 20，最大 100。