This commit is contained in:
64
openspec/specs/client-realname-auto-trigger/spec.md
Normal file
64
openspec/specs/client-realname-auto-trigger/spec.md
Normal file
@@ -0,0 +1,64 @@
|
||||
# Capability: 客户端实名跳转自动触发实名检查优先级提升功能
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 客户端实名跳转自动触发实名检查
|
||||
|
||||
系统 SHALL 在用户成功获取实名跳转链接时，自动触发该ICCID的实名状态检查，提高检测优先级。
|
||||
|
||||
#### Scenario: 用户主动获取实名链接时自动触发优先级检查
|
||||
|
||||
- **WHEN** 个人客户调用 `GET /api/c/v1/realname/link` 接口成功获取实名链接
|
||||
- **THEN** 系统自动将该ICCID加入实名检查的高优先级队列，无需等待定时轮询
|
||||
|
||||
#### Scenario: 自动触发失败不影响主流程
|
||||
|
||||
- **WHEN** 个人客户调用实名链接接口，但自动触发实名检查失败
|
||||
- **THEN** 系统仍正常返回实名链接，不因触发失败而阻断用户操作
|
||||
|
||||
#### Scenario: 异步处理不影响响应时间
|
||||
|
||||
- **WHEN** 个人客户调用实名链接接口
|
||||
- **THEN** 系统异步执行实名检查触发，主接口响应时间增加不超过5ms
|
||||
|
||||
### Requirement: 自动触发的权限适配
|
||||
|
||||
系统 SHALL 使用系统用户身份执行自动触发操作，绕过个人客户的权限限制。
|
||||
|
||||
#### Scenario: 个人客户无权限但能触发检查
|
||||
|
||||
- **WHEN** 个人客户获取实名链接（个人客户本身无手动触发权限）
|
||||
- **THEN** 系统使用配置的系统用户身份自动触发，成功将ICCID加入优先级队列
|
||||
|
||||
#### Scenario: 系统用户身份操作记录
|
||||
|
||||
- **WHEN** 系统使用系统用户身份执行自动触发
|
||||
- **THEN** 系统在 `tb_polling_manual_trigger_log` 表中记录操作，`triggered_by` 字段记录系统用户ID
|
||||
|
||||
### Requirement: 自动触发的错误处理和日志
|
||||
|
||||
系统 SHALL 提供完善的错误处理和日志记录机制，确保可观测性。
|
||||
|
||||
#### Scenario: 触发失败时记录详细日志
|
||||
|
||||
- **WHEN** 自动触发实名检查失败（如Redis连接失败、权限错误等）
|
||||
- **THEN** 系统记录包含客户ID、ICCID、错误原因的详细日志，级别为WARN
|
||||
|
||||
#### Scenario: 触发成功时记录操作日志
|
||||
|
||||
- **WHEN** 自动触发实名检查成功
|
||||
- **THEN** 系统记录包含客户ID、ICCID的INFO级别日志，便于运维追踪
|
||||
|
||||
### Requirement: 配置管理和灵活性
|
||||
|
||||
系统 SHALL 支持通过配置管理自动触发功能的关键参数。
|
||||
|
||||
#### Scenario: 系统用户ID配置
|
||||
|
||||
- **WHEN** 系统初始化或配置更新时
|
||||
- **THEN** 系统从环境变量 `JUNHONG_AUTO_TRIGGER_SYSTEM_USER_ID` 读取系统用户ID
|
||||
|
||||
#### Scenario: 自动触发功能开关
|
||||
|
||||
- **WHEN** 需要临时关闭自动触发功能时
|
||||
- **THEN** 系统支持通过环境变量 `JUNHONG_ENABLE_AUTO_TRIGGER` 控制功能开关（默认开启）
|
||||
147
openspec/specs/polling-manual-trigger/spec.md
Normal file
147
openspec/specs/polling-manual-trigger/spec.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# Capability: 手动触发功能
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 手动触发去重
|
||||
|
||||
系统 SHALL 对手动触发进行去重，避免重复执行，确保去重机制的时间一致性。
|
||||
|
||||
#### Scenario: 同卡重复触发
|
||||
|
||||
- **WHEN** 管理员对同一张卡连续触发两次实名检查
|
||||
- **THEN** 系统检查手动队列，如果卡ID已存在则不重复加入
|
||||
|
||||
#### Scenario: 使用 Redis Set 去重
|
||||
|
||||
- **WHEN** 批量触发 100 张卡，其中有 10 张重复
|
||||
- **THEN** 系统使用 Redis Set 临时存储卡ID，去重后再加入队列
|
||||
|
||||
#### Scenario: 手动触发与定时任务去重
|
||||
|
||||
- **WHEN** 卡A在手动队列中，同时定时队列也到期
|
||||
- **THEN** 系统优先执行手动触发，定时队列检测到卡已在执行则跳过
|
||||
|
||||
#### Scenario: 去重key TTL与日限制时间对齐
|
||||
|
||||
- **WHEN** 管理员在当天第一次触发某张卡的实名检查
|
||||
- **THEN** 系统设置去重key的TTL为24小时，与日限制周期保持一致，避免同一天内重复触发
|
||||
|
||||
#### Scenario: 去重key跨天自动清理
|
||||
|
||||
- **WHEN** 午夜12点过后，新一天开始
|
||||
- **THEN** 系统允许重新触发前一天已触发过的卡，去重key自动过期清理
|
||||
|
||||
### Requirement: 手动触发限流
|
||||
|
||||
系统 SHALL 对手动触发进行合理限流，既防止滥用又保证正常使用。
|
||||
|
||||
#### Scenario: 单次批量限制
|
||||
|
||||
- **WHEN** 管理员单次批量触发超过 1000 张卡
|
||||
- **THEN** 系统拒绝请求，提示超过单次限制
|
||||
|
||||
#### Scenario: 频率限制
|
||||
|
||||
- **WHEN** 管理员在 1 分钟内触发超过 10 次
|
||||
- **THEN** 系统拒绝请求，提示操作过于频繁，建议稍后再试
|
||||
|
||||
#### Scenario: 每日限制
|
||||
|
||||
- **WHEN** 管理员当日累计触发超过 500 次
|
||||
- **THEN** 系统拒绝请求，提示已达每日限制，支持正常运维需求和客户端自动触发
|
||||
|
||||
#### Scenario: 超级管理员无限制
|
||||
|
||||
- **WHEN** 超级管理员手动触发
|
||||
- **THEN** 系统不应用限流规则
|
||||
|
||||
#### Scenario: 客户端自动触发不受个人频次限制影响
|
||||
|
||||
- **WHEN** 客户端实名跳转自动触发功能调用手动触发服务
|
||||
- **THEN** 系统使用系统用户身份，不受个人用户的频次限制影响
|
||||
|
||||
### Requirement: 手动触发权限控制
|
||||
|
||||
系统 SHALL 控制手动触发的权限，支持系统用户身份的特殊权限适配。
|
||||
|
||||
#### Scenario: 普通管理员触发自己管理的卡
|
||||
|
||||
- **WHEN** 代理账号请求手动触发卡ID为 12345，该卡属于代理管理的店铺
|
||||
- **THEN** 系统验证权限通过，允许触发
|
||||
|
||||
#### Scenario: 代理账号无权触发其他店铺的卡
|
||||
|
||||
- **WHEN** 代理账号请求手动触发卡ID为 99999，该卡不属于代理管理的店铺
|
||||
- **THEN** 系统拒绝请求，返回权限不足错误
|
||||
|
||||
#### Scenario: 超级管理员可触发任意卡
|
||||
|
||||
- **WHEN** 超级管理员请求手动触发任意卡
|
||||
- **THEN** 系统跳过权限验证，允许触发
|
||||
|
||||
#### Scenario: 系统用户身份自动触发
|
||||
|
||||
- **WHEN** 客户端实名跳转功能使用系统用户身份调用手动触发
|
||||
- **THEN** 系统验证系统用户身份有效，允许触发任意ICCID的实名检查
|
||||
|
||||
#### Scenario: 企业账号禁止手动触发
|
||||
|
||||
- **WHEN** 企业账号请求手动触发卡ID为 12345，该卡属于企业
|
||||
- **THEN** 系统拒绝请求，返回无权限错误
|
||||
|
||||
### Requirement: 优化权限检查逻辑
|
||||
|
||||
系统 SHALL 简化和优化权限检查逻辑，减少代码重复，提高可维护性。
|
||||
|
||||
#### Scenario: 统一权限检查函数
|
||||
|
||||
- **WHEN** 系统需要验证用户对卡的管理权限
|
||||
- **THEN** 系统使用统一的权限检查函数，避免在多个地方重复实现相同逻辑
|
||||
|
||||
#### Scenario: 权限检查缓存优化
|
||||
|
||||
- **WHEN** 批量操作需要检查大量卡的权限
|
||||
- **THEN** 系统使用批量权限检查，减少数据库查询次数，提高性能
|
||||
|
||||
#### Scenario: 权限检查错误信息优化
|
||||
|
||||
- **WHEN** 权限检查失败时
|
||||
- **THEN** 系统返回明确的错误信息，帮助用户了解权限不足的具体原因
|
||||
|
||||
### Requirement: 增强错误处理和日志
|
||||
|
||||
系统 SHALL 提供更完善的错误处理和日志记录，提高系统可观测性。
|
||||
|
||||
#### Scenario: 详细错误日志记录
|
||||
|
||||
- **WHEN** 手动触发过程中发生错误（Redis连接失败、权限错误等）
|
||||
- **THEN** 系统记录包含错误原因、用户ID、卡ID、上下文信息的详细日志
|
||||
|
||||
#### Scenario: 性能关键路径日志
|
||||
|
||||
- **WHEN** 手动触发操作执行时间超过预期
|
||||
- **THEN** 系统记录性能日志，包含各阶段耗时，便于性能优化
|
||||
|
||||
#### Scenario: 异常情况恢复机制
|
||||
|
||||
- **WHEN** Redis临时不可用导致手动触发失败
|
||||
- **THEN** 系统记录错误并提供恢复建议，不影响其他正常功能
|
||||
|
||||
### Requirement: 配置管理和灵活性
|
||||
|
||||
系统 SHALL 支持通过配置管理手动触发功能的关键参数，提高系统灵活性。
|
||||
|
||||
#### Scenario: 频次限制可配置
|
||||
|
||||
- **WHEN** 需要调整手动触发的频次限制时
|
||||
- **THEN** 系统支持通过配置文件或环境变量调整每日限制、单次限制等参数
|
||||
|
||||
#### Scenario: 去重TTL可配置
|
||||
|
||||
- **WHEN** 需要调整去重机制的时间窗口时
|
||||
- **THEN** 系统支持配置去重key的TTL时长，默认24小时
|
||||
|
||||
#### Scenario: 系统用户ID配置
|
||||
|
||||
- **WHEN** 系统启动或配置更新时
|
||||
- **THEN** 系统从环境变量 `JUNHONG_MANUAL_TRIGGER_SYSTEM_USER_ID` 读取系统用户ID用于客户端自动触发
|
||||
Reference in New Issue
Block a user