This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-08-10
|
||||
@@ -0,0 +1,45 @@
|
||||
## Context
|
||||
|
||||
现有套餐管理列表服务于套餐管理页面，不能承载授权页面的店铺授权状态。现有低余额提醒在扣款 Outbox 消费者中派生；测试库证明一次有效跨阈值扣款已完成消费但未产生通知事件。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 以独立只读接口提供授权页面所需候选套餐和授权状态。
|
||||
- 将跨阈值通知事件与钱包扣款事实原子写入。
|
||||
|
||||
**Non-Goals:**
|
||||
- 不改套餐管理列表接口。
|
||||
- 不新增或替换首次创建、套餐管理的提交路由。
|
||||
- 不新增阈值配置或修改数据库 Schema。
|
||||
|
||||
## Decisions
|
||||
|
||||
### 独立授权候选列表
|
||||
|
||||
新增授权域路由，输入 `shop_id` 与 `series_id`。查询同时执行操作者可管理店铺、上级授权链和套餐系列校验，并按目标店铺现有授权填充状态。
|
||||
|
||||
候选项复用套餐列表的 `PackageResponse` 字段集，并追加 `authorized`；代理操作者的价格与上架状态沿用其上级授权记录。
|
||||
|
||||
复用 `GET /packages` 会将授权上下文混入套餐管理接口，影响其既有消费者；只返回未授权项则无法支持前端明确置灰，均不采用。
|
||||
|
||||
### 扣款事务内创建通知事件
|
||||
|
||||
由统一主钱包扣款事件 Writer 根据扣款前后余额判断跨阈值，并在相同事务写入低余额通知 Outbox。该 Writer已被直接扣款和预占完成扣款共同调用。
|
||||
|
||||
保留 Worker 对通知 Outbox 的投递；移除扣款消费者中低余额通知派生，只保留扣款事实校验。这样 API 与 Worker 重启之间不会遗失派生通知。
|
||||
|
||||
### 幂等与接收人
|
||||
|
||||
通知事件 ID 使用订单扣款引用构成稳定值，继续使用 Outbox 幂等写入。接收人于扣款事务中解析为当前有效平台业务员；无有效业务员时不创建通知事件。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [业务员在扣款后变更] → 通知接收人固定为扣款时有效的业务员，符合触发时的业务事实。
|
||||
- [候选查询与提交并发] → 现有部分唯一索引继续作为最终重复授权防线。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. 发布 API 与 Worker 代码。
|
||||
2. 使用 10000 分→9900 分、低余额连续扣款、回升后再次跌破三组数据验证事件与通知。
|
||||
3. 回滚时恢复前一版本；不涉及迁移或数据回滚。
|
||||
@@ -0,0 +1,26 @@
|
||||
## Why
|
||||
|
||||
代理系列授权页面无法获知套餐是否已授权，导致重复选择；主钱包低余额提醒依赖扣款事件的异步消费者再次判断，测试库已出现有效跌破阈值却没有生成通知事件的记录。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 为代理系列授权提供独立的套餐候选列表，返回指定店铺、系列下每个可授权套餐的已授权状态，供前端置灰已授权项。
|
||||
- 保持现有首次创建和授权套餐管理提交接口不变，并由现有唯一约束作为并发重复授权的最终防线。
|
||||
- 将主钱包首次跌破 100 元的通知事件与扣款事实写入同一事务；余额恢复至 100 元及以上后再次跌破时再次创建通知事件。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `agent-series-package-options`: 查询代理系列授权页面的套餐候选项及授权状态。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `package-lifecycle`: 代理系列授权页面可查询并区分已授权与未授权套餐。
|
||||
- `notification-delivery`: 主钱包余额跨过低余额阈值时可靠创建并投递业务员通知。
|
||||
|
||||
## Impact
|
||||
|
||||
- 涉及代理系列授权路由、Handler、DTO、查询服务和套餐分配查询。
|
||||
- 涉及主钱包扣款事件 Writer；低余额判断从其异步消费者迁入扣款事务。
|
||||
- 不增加依赖，不修改现有提交路由或数据库 Schema。
|
||||
@@ -0,0 +1,16 @@
|
||||
## Purpose
|
||||
|
||||
为代理系列授权页面提供与套餐管理列表隔离的候选套餐视图，使前端能够在首次授权和后续加套餐时识别不可重复授权的套餐。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 查询系列授权套餐候选项
|
||||
系统 SHALL 提供独立接口，按被授权店铺和套餐系列返回当前操作者可分配的非赠送套餐；每个候选项 MUST 包含与套餐列表一致的套餐字段，以及该店铺是否已授权该套餐的状态。
|
||||
|
||||
#### Scenario: 返回已授权与未授权候选项
|
||||
- **WHEN** 有权限的操作者查询指定店铺和套餐系列的候选套餐
|
||||
- **THEN** 系统返回该系列可分配套餐的完整套餐列表字段，且已存在有效授权记录的套餐标记为已授权
|
||||
|
||||
#### Scenario: 查询无权分配的套餐
|
||||
- **WHEN** 代理操作者查询其不具备上级授权的套餐系列
|
||||
- **THEN** 系统拒绝查询且不返回套餐候选项
|
||||
@@ -0,0 +1,16 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 主钱包低余额跨阈值提醒
|
||||
系统 SHALL 在店铺主钱包余额由不低于 100 元变为低于 100 元时，与扣款事实在同一事务创建面向当时有效业务员的低余额通知事件；余额持续低于 100 元时不得重复创建，余额恢复至不低于 100 元后再次跌破时 MUST 再次创建。
|
||||
|
||||
#### Scenario: 首次跌破阈值
|
||||
- **WHEN** 店铺主钱包扣款后余额从不低于 100 元变为低于 100 元，且存在有效业务员
|
||||
- **THEN** 系统在提交扣款事实时创建一条低余额通知事件，并由通知投递流程生成站内通知
|
||||
|
||||
#### Scenario: 持续低余额
|
||||
- **WHEN** 店铺主钱包余额已经低于 100 元且再次发生扣款
|
||||
- **THEN** 系统不创建新的低余额通知事件
|
||||
|
||||
#### Scenario: 回升后再次跌破
|
||||
- **WHEN** 店铺主钱包余额已恢复至不低于 100 元，随后扣款使其低于 100 元
|
||||
- **THEN** 系统创建新的低余额通知事件
|
||||
@@ -0,0 +1,12 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 授权页面禁止重复选择套餐
|
||||
系统 SHALL 使代理系列授权页面能够区分目标店铺已授权和未授权套餐；已授权套餐 MUST 以不可新增的状态返回，首次创建系列授权和既有系列新增套餐均适用。
|
||||
|
||||
#### Scenario: 首次创建前查询候选套餐
|
||||
- **WHEN** 操作者选择目标店铺和套餐系列以创建系列授权
|
||||
- **THEN** 系统返回可用于选择的候选套餐及其授权状态，前端可阻止选择已授权套餐
|
||||
|
||||
#### Scenario: 既有授权新增套餐前查询候选套餐
|
||||
- **WHEN** 操作者为已有系列授权添加套餐
|
||||
- **THEN** 系统返回同一店铺和系列的候选套餐及其授权状态，且不改变现有套餐管理提交接口的调价和删除语义
|
||||
@@ -0,0 +1,16 @@
|
||||
## 1. 授权套餐候选列表
|
||||
|
||||
- [x] 1.1 定义独立候选列表路由、请求与响应 DTO，并生成接口文档。
|
||||
- [x] 1.2 实现指定店铺和系列的可分配套餐查询及 `authorized` 状态，复用现有权限与上级授权链校验。
|
||||
- [x] 1.3 运行格式化、API/Worker 构建和文档生成，确认套餐管理列表接口未变。
|
||||
- [x] 1.4 候选套餐响应复用套餐列表字段集并追加 `authorized` 状态。
|
||||
|
||||
## 2. 主钱包低余额通知
|
||||
|
||||
- [x] 2.1 将跨 100 元阈值和有效业务员解析收口至主钱包扣款事件 Writer，并在扣款事务中幂等写入通知 Outbox。
|
||||
- [x] 2.2 删除扣款 Outbox 消费者中的低余额派生逻辑，保留扣款事实一致性校验。
|
||||
- [x] 2.3 以测试库的 10000→9900、持续低余额、回升后再次跌破数据验证通知事件行为。
|
||||
|
||||
## 3. 变更验证
|
||||
|
||||
- [x] 3.1 运行 `gofmt`、`go build ./cmd/api ./cmd/worker`、`go run cmd/gendocs/main.go`、`openspec validate --all` 和 `./scripts/context-health.sh`。
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-08-10
|
||||
@@ -0,0 +1,40 @@
|
||||
## Context
|
||||
|
||||
见 proposal.md。000178 在版本 140 之后尚未应用于生产库；其迁移前校验和唯一索引均把所有 `iccid_19` 纳入唯一范围，与双列模型中“20 位卡以完整 `iccid_20` 识别”的语义冲突。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- 在测试环境验证版本 140 生产库所需的 ICCID 索引语义。
|
||||
- 为两种 ICCID 长度分别建立正确的唯一性约束。
|
||||
- 保持查询索引名称与现有代码兼容。
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- 不清理、合并或修改现有卡数据。
|
||||
- 不改变 ICCID 查询接口或导入逻辑。
|
||||
|
||||
## Decisions
|
||||
|
||||
### 将 000178 的唯一范围限定为对应原始长度
|
||||
|
||||
`iccid_19` 冲突扫描和唯一索引增加 `length(iccid) = 19`；`iccid_20` 冲突扫描和唯一索引增加 `length(iccid) = 20`。
|
||||
|
||||
直接修正 000178，而不是新增后续迁移：生产库仍位于版本 140，必须能连续执行历史链路；新增迁移无法绕过 000178 的失败。该文件尚未在生产应用，变更需在上线前完成仓库内所有消费方同步。
|
||||
|
||||
### 保留双列格式校验
|
||||
|
||||
保留对 19/20 位原始值与派生列对应关系的校验，避免仅放宽唯一索引而掩盖错误回填。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [测试库已处于更高迁移版本] → 直接按修正后的 000178 谓词定向重建两个索引并核对结果。
|
||||
- [其他环境已经执行旧版 000178] → 迁移内容不会自动重放；上线前以索引定义核对并按同一谓词重建。
|
||||
- [错误编辑已发布迁移] → 仅限生产首次执行前的本次兼容修正，发布说明记录文件校验值。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. 在测试环境停止卡写入后，按修正后的 000178 谓词定向重建两个 ICCID 唯一索引。
|
||||
2. 验证两个索引均为唯一索引且谓词按原始 ICCID 长度限定，并执行 19/20 位重复组检查。
|
||||
3. 测试完成后保留修正后的索引；不对生产库执行迁移或验证操作。
|
||||
@@ -0,0 +1,24 @@
|
||||
## Why
|
||||
|
||||
线上活跃的 20 位 ICCID 可以共享前 19 位，现有 000178 迁移却将全部活跃卡的 `iccid_19` 设为唯一，导致从版本 140 升级时必然中止。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 修正 ICCID 唯一性迁移：仅对原始 ICCID 长度为 19 的活跃卡要求 `iccid_19` 唯一。
|
||||
- 保持原始 ICCID 长度为 20 的活跃卡以 `iccid_20` 为唯一标识，允许其共享 `iccid_19` 前缀。
|
||||
- 同步调整迁移前置校验、索引谓词与索引注释。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
无。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `asset-device`: 明确 19 位与 20 位 ICCID 的有效唯一性边界。
|
||||
|
||||
## Impact
|
||||
|
||||
- `migrations/000178_make_iot_card_iccid_exact_unique.up.sql`
|
||||
- 测试环境中的定向索引修复验证；不改变卡数据或 HTTP API，也不对生产库执行迁移。
|
||||
@@ -0,0 +1,15 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: ICCID 按原始长度精确唯一
|
||||
|
||||
系统 SHALL 将未删除卡的 ICCID 唯一性按原始 ICCID 长度分别约束：原始长度为 19 的卡以 `iccid_19` 唯一；原始长度为 20 的卡以 `iccid_20` 唯一。20 位 ICCID 卡共享相同的前 19 位 SHALL 被视为有效数据。
|
||||
|
||||
#### Scenario: 20 位 ICCID 共享前缀
|
||||
|
||||
- **WHEN** 两张未删除卡具有不同的 20 位完整 ICCID，但其前 19 位相同
|
||||
- **THEN** 数据库接受两张卡，并通过各自的 `iccid_20` 保证完整 ICCID 唯一
|
||||
|
||||
#### Scenario: 19 位 ICCID 重复
|
||||
|
||||
- **WHEN** 两张未删除卡具有相同的 19 位完整 ICCID
|
||||
- **THEN** 数据库拒绝第二张卡的重复值
|
||||
@@ -0,0 +1,10 @@
|
||||
## 1. 迁移修正
|
||||
|
||||
- [x] 1.1 修正 000178 的 19 位冲突扫描和唯一索引谓词，仅覆盖原始长度为 19 的活跃卡。
|
||||
- [x] 1.2 修正 000178 的 20 位冲突扫描、唯一索引谓词和迁移注释，使其仅覆盖原始长度为 20 的活跃卡。
|
||||
|
||||
## 2. 验证
|
||||
|
||||
- [x] 2.1 在测试环境按修正后的 000178 谓词定向重建两个 ICCID 唯一索引。
|
||||
- [x] 2.2 校验两个索引均为唯一索引、谓词按原始 ICCID 长度限定，并核对 19/20 位重复组。
|
||||
- [x] 2.3 运行 OpenSpec 校验并记录测试环境定向修复结果。
|
||||
26
openspec/specs/agent-series-package-options/spec.md
Normal file
26
openspec/specs/agent-series-package-options/spec.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# 代理系列授权套餐候选项当前行为
|
||||
|
||||
## Purpose
|
||||
|
||||
为代理系列授权页面提供与套餐管理列表隔离的候选套餐和授权状态，使前端能阻止重复授权。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 查询系列授权套餐候选项
|
||||
系统 SHALL 提供独立接口，按被授权店铺和套餐系列返回当前操作者可分配的非赠送套餐；每个候选项 MUST 包含与套餐列表一致的套餐字段，以及该店铺是否已授权该套餐的状态。
|
||||
|
||||
#### Scenario: 返回已授权与未授权候选项
|
||||
- **WHEN** 有权限的操作者查询指定店铺和套餐系列的候选套餐
|
||||
- **THEN** 系统返回该系列可分配套餐的完整套餐列表字段，且已存在有效授权记录的套餐标记为已授权
|
||||
|
||||
#### Scenario: 查询无权分配的套餐
|
||||
- **WHEN** 代理操作者查询其不具备上级授权的套餐系列
|
||||
- **THEN** 系统拒绝查询且不返回套餐候选项
|
||||
|
||||
## 可达操作索引
|
||||
|
||||
本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
|
||||
|
||||
### 代理系列授权套餐候选项
|
||||
|
||||
`GET /api/admin/shop-series-grants/package-options`（查询指定店铺和系列的候选套餐及授权状态）。
|
||||
@@ -26,6 +26,20 @@
|
||||
- **WHEN** 执行绑定或解绑
|
||||
- **THEN** 后续设备卡列表反映该关系变化
|
||||
|
||||
### Requirement: ICCID 按原始长度精确唯一
|
||||
|
||||
系统 SHALL 将未删除卡的 ICCID 唯一性按原始 ICCID 长度分别约束：原始长度为 19 的卡以 `iccid_19` 唯一；原始长度为 20 的卡以 `iccid_20` 唯一。20 位 ICCID 卡共享相同的前 19 位 SHALL 被视为有效数据。
|
||||
|
||||
#### Scenario: 20 位 ICCID 共享前缀
|
||||
|
||||
- **WHEN** 两张未删除卡具有不同的 20 位完整 ICCID，但其前 19 位相同
|
||||
- **THEN** 数据库接受两张卡，并通过各自的 `iccid_20` 保证完整 ICCID 唯一
|
||||
|
||||
#### Scenario: 19 位 ICCID 重复
|
||||
|
||||
- **WHEN** 两张未删除卡具有相同的 19 位完整 ICCID
|
||||
- **THEN** 数据库拒绝第二张卡的重复值
|
||||
|
||||
## 可达操作索引
|
||||
|
||||
本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
|
||||
|
||||
@@ -26,6 +26,22 @@
|
||||
- **WHEN** 再次执行单条或批量已读
|
||||
- **THEN** 通知保持原读取事实且不影响其他接收人的通知
|
||||
|
||||
### Requirement: 主钱包低余额跨阈值提醒
|
||||
|
||||
系统 SHALL 在店铺主钱包余额由不低于 100 元变为低于 100 元时，与扣款事实在同一事务创建面向当时有效业务员的低余额通知事件；余额持续低于 100 元时不得重复创建，余额恢复至不低于 100 元后再次跌破时 MUST 再次创建。
|
||||
|
||||
#### Scenario: 首次跌破阈值
|
||||
- **WHEN** 店铺主钱包扣款后余额从不低于 100 元变为低于 100 元，且存在有效业务员
|
||||
- **THEN** 系统在提交扣款事实时创建一条低余额通知事件，并由通知投递流程生成站内通知
|
||||
|
||||
#### Scenario: 持续低余额
|
||||
- **WHEN** 店铺主钱包余额已经低于 100 元且再次发生扣款
|
||||
- **THEN** 系统不创建新的低余额通知事件
|
||||
|
||||
#### Scenario: 回升后再次跌破
|
||||
- **WHEN** 店铺主钱包余额已恢复至不低于 100 元，随后扣款使其低于 100 元
|
||||
- **THEN** 系统创建新的低余额通知事件
|
||||
|
||||
## 可达操作索引
|
||||
|
||||
本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
|
||||
|
||||
@@ -26,6 +26,18 @@
|
||||
- **WHEN** 创建批量操作
|
||||
- **THEN** 同步操作直接返回结果；异步订购返回任务标识且可查询处理状态
|
||||
|
||||
### Requirement: 授权页面禁止重复选择套餐
|
||||
|
||||
系统 SHALL 使代理系列授权页面能够区分目标店铺已授权和未授权套餐；已授权套餐 MUST 以不可新增的状态返回，首次创建系列授权和既有系列新增套餐均适用。
|
||||
|
||||
#### Scenario: 首次创建前查询候选套餐
|
||||
- **WHEN** 操作者选择目标店铺和套餐系列以创建系列授权
|
||||
- **THEN** 系统返回可用于选择的候选套餐及其授权状态，前端可阻止选择已授权套餐
|
||||
|
||||
#### Scenario: 既有授权新增套餐前查询候选套餐
|
||||
- **WHEN** 操作者为已有系列授权添加套餐
|
||||
- **THEN** 系统返回同一店铺和系列的候选套餐及其授权状态，且不改变现有套餐管理提交接口的调价和删除语义
|
||||
|
||||
## 可达操作索引
|
||||
|
||||
本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
|
||||
@@ -44,7 +56,7 @@
|
||||
|
||||
### 代理系列授权
|
||||
|
||||
`GET /api/admin/shop-series-grants`（查询代理系列授权列表）；`POST /api/admin/shop-series-grants`（创建代理系列授权）；`DELETE /api/admin/shop-series-grants/{id}`（删除代理系列授权）；`GET /api/admin/shop-series-grants/{id}`（查询代理系列授权详情）；`PUT /api/admin/shop-series-grants/{id}`（更新代理系列授权）；`PUT /api/admin/shop-series-grants/{id}/packages`（管理授权套餐（新增/更新/删除））。
|
||||
`GET /api/admin/shop-series-grants`（查询代理系列授权列表）；`GET /api/admin/shop-series-grants/package-options`（查询代理系列授权套餐候选项）；`POST /api/admin/shop-series-grants`（创建代理系列授权）；`DELETE /api/admin/shop-series-grants/{id}`（删除代理系列授权）；`GET /api/admin/shop-series-grants/{id}`（查询代理系列授权详情）；`PUT /api/admin/shop-series-grants/{id}`（更新代理系列授权）；`PUT /api/admin/shop-series-grants/{id}/packages`（管理授权套餐，支持新增、更新和删除）。
|
||||
|
||||
### 批量套餐分配
|
||||
|
||||
|
||||
Reference in New Issue
Block a user