1890 lines
68 KiB
Markdown
1890 lines
68 KiB
Markdown
# 7月迭代禅道研发需求逐条录入稿
|
||
|
||
> 用法：每条研发需求分别复制“标题”和“描述”到禅道。前端描述已包含页面结构、交互状态和接口契约，可先按 Mock 开发；后端描述包含业务规则和交付边界。
|
||
>
|
||
> 公共约定：接口统一返回 `{code,msg,data,timestamp}`，下文只写 `data`；金额单位为分；时间为 ISO 8601；分页结构为 `{items,total,page,size}`；状态判断使用 `status`，中文展示使用 `status_name`。返回字段除明确标注 `null` 或“特定状态返回”外均为必返字段，前端 Mock 不得自行改名或改变类型。
|
||
|
||
## 工时口径
|
||
|
||
- 单位为人时，1人日按8小时计算。
|
||
- FE/BE工时包含实现、自验、关联联调问题修复，不包含等待企微、支付、Gateway等外部配置的时间。
|
||
- INT-01～INT-07用于组织联调，不重复增加总工时；如禅道必须填写联调工时，应从关联FE/BE研发需求中拆出同等工时。
|
||
- INT-08为额外的全链路验收和停机发布准备，前端3～4小时、后端4～5小时。
|
||
- 按逐条工时汇总并去除联调重复计算后：前端58.5～89小时，后端92.5～127.5小时；对外取整仍为前端59～89小时、后端93～128小时。
|
||
- 总体仍按1前端+1后端并行12～15个工作日、风险上限16个工作日执行。
|
||
|
||
## UR#98 换货管理新资产归属
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#98] 换货新资产归属继承提示
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：换货操作时明确新资产最终归属，避免运营误认为可以手工选择目标店铺。
|
||
|
||
预计工时：前端0.5～1小时。
|
||
|
||
页面入口：现有换货创建页、发货确认页、换货详情页。
|
||
|
||
页面结构：
|
||
1. 选择旧资产后展示旧资产所属店铺。
|
||
2. 选择新资产后增加只读提示“换货完成后将归属：{店铺名称}”。
|
||
3. 不增加目标店铺选择控件。
|
||
4. 详情页展示继承后的店铺名称。
|
||
|
||
接口约定：
|
||
- 复用 POST /api/admin/exchanges、POST /api/admin/exchanges/{id}/ship、POST /api/admin/exchanges/{id}/complete。
|
||
- 创建入参沿用旧资产、新资产、换货类型和资料迁移字段。
|
||
- 返回 data 增加 inherited_shop_id:int64、inherited_shop_name:string。
|
||
|
||
交互规则：新资产属于其他店铺时展示后端错误；提交期间禁用按钮；成功后重新拉取详情。
|
||
|
||
完成标准：创建、发货、完成三个页面均能正确展示目标店铺，并覆盖加载中、失败和重复提交状态。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#98] 换货新资产继承旧资产店铺
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：换货完成时由系统自动维护新资产归属，不允许前端指定目标店铺。
|
||
|
||
预计工时：后端1～1.5小时。
|
||
|
||
接口：复用 POST /api/admin/exchanges、POST /api/admin/exchanges/{id}/ship、POST /api/admin/exchanges/{id}/complete。
|
||
|
||
规则：
|
||
1. 新资产允许处于平台库存，或已经属于旧资产店铺；属于其他店铺时拒绝。
|
||
2. 完成换货事务内迁移新资产 shop_id、租户标签和资产分配记录，再迁移客户、钱包、套餐和状态。
|
||
3. 旧资产保留原 shop_id，仅更新为已换货状态。
|
||
4. 返回 inherited_shop_id、inherited_shop_name，写入换货审计。
|
||
|
||
架构：换货完成逻辑迁入 exchange Domain，旧 Service 不保留第二套完成逻辑。
|
||
|
||
完成标准：跨资产数据在同一事务内一致，重复完成保持幂等，其他店铺资产不能被越权换入。
|
||
```
|
||
|
||
## UR#97 代理钱包阈值提醒
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#97] 代理现金余额不足100元展示
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：现金可用余额不足100元时给运营明确提示，不提供阈值配置。
|
||
|
||
预计工时：前端0.5～1小时，不含公共站内通知页面工时。
|
||
|
||
页面入口：代理资金概况、顶部通知抽屉、站内通知中心。
|
||
|
||
页面结构：
|
||
1. 资金概况显示现金余额、冻结金额和“现金余额不足100元”红色状态。
|
||
2. 不展示阈值输入框，不把信用额度计入预警文案。
|
||
3. 通知点击后跳转对应店铺资金页。
|
||
|
||
接口约定：
|
||
- GET /api/admin/shops/fund-summary 返回 balance:int64、frozen_balance:int64、cash_available:int64、low_balance_warning:bool。
|
||
- 通知复用 GET /api/admin/notifications，目标解析复用 GET /api/admin/notifications/{id}/target。
|
||
|
||
交互规则：只使用 low_balance_warning 控制提示，不由前端自行计算阈值；金额按分转元展示。
|
||
|
||
完成标准：余额高于、等于、低于100元三种状态展示正确，通知能跳转且无权限时按统一错误页处理。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#97] 代理主钱包固定100元余额预警
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：主钱包现金可用余额跨越固定阈值时可靠发送一次站内通知。
|
||
|
||
预计工时：后端1～1.5小时，不含公共站内通知基础设施工时。
|
||
|
||
规则：
|
||
1. cash_available=balance-frozen_balance，不包含信用额度。
|
||
2. 变动前>10000分且变动后<=10000分时发送通知。
|
||
3. 余额回升到10000分以上后重新布防；持续低余额不重复发送。
|
||
4. 接收人为店铺主账号和可用的店铺业务员。
|
||
|
||
接口：GET /api/admin/shops/fund-summary 增加 cash_available、low_balance_warning；通知复用现有通知接口。
|
||
|
||
实现：钱包聚合产生低余额领域事件，事务内写 Outbox，通知使用稳定业务键防重并记录审计。
|
||
|
||
完成标准：扣款、冻结、解冻、充值和退款回充都能正确触发或重新布防，通知失败不回滚资金事务。
|
||
```
|
||
|
||
## UR#96 员工作为发展人进行标识
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#96] 店铺业务员选择展示与筛选
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：为店铺绑定平台业务员，只表示业务归属和通知关系。
|
||
|
||
预计工时：前端0.5～1小时。
|
||
|
||
页面入口：店铺新建、店铺编辑、店铺列表、店铺详情。
|
||
|
||
页面结构：
|
||
1. 新建和编辑表单增加“平台业务员”可搜索下拉，可为空。
|
||
2. 候选项展示账号名和手机号摘要，只显示启用的平台账号。
|
||
3. 店铺列表增加业务员列和业务员筛选项。
|
||
4. 店铺详情展示业务员名称和手机号摘要。
|
||
|
||
接口约定：
|
||
- POST /api/admin/shops、PUT /api/admin/shops/{id} 增加 business_owner_account_id:int64|null。
|
||
- GET /api/admin/shops 增加 business_owner_account_id 查询参数。
|
||
- 业务员候选复用 GET /api/admin/accounts?account_type=platform&status=1，items至少返回 account_id、account_name、phone_masked。
|
||
- 列表和详情返回 business_owner_account_id:int64|null、business_owner_name:string、business_owner_phone_masked:string。
|
||
|
||
交互规则：不出现分销、佣金或发展层级文案；已停用业务员仍可在历史详情显示，但编辑候选中不可选。
|
||
|
||
完成标准：创建、编辑、筛选、详情展示一致，并覆盖清空业务员和无可选账号状态。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#96] 店铺业务员关联与查询
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：保存店铺的平台业务员归属，并用于查询和站内通知接收人计算。
|
||
|
||
预计工时：后端1～1.5小时。
|
||
|
||
数据：tb_shop 增加 business_owner_account_id，可空，不建立数据库外键。
|
||
|
||
接口：POST /api/admin/shops、PUT /api/admin/shops/{id} 支持 business_owner_account_id；GET /api/admin/shops 支持同名筛选；列表和详情返回账号名称及手机号摘要。
|
||
|
||
规则：
|
||
1. 只允许绑定启用的平台账号。
|
||
2. 字段不参与店铺层级、数据权限、佣金或分销关系计算。
|
||
3. 账号停用或删除后保留历史关联，通知时跳过不可用账号。
|
||
4. 变更前后值写入审计。
|
||
|
||
完成标准：创建、修改、清空和筛选均生效，不能绑定代理账号或停用平台账号。
|
||
```
|
||
|
||
## UR#94 系统状态同步优化以及回调处理
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#94] 资产同步状态与同步轨迹入口
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：让运营能看懂资产当前轮询策略和最近同步情况，不新增第二个同步按钮。
|
||
|
||
预计工时：前端2～3小时。
|
||
|
||
页面入口：卡详情、设备详情、全局审计外部集成页。
|
||
|
||
页面结构：
|
||
1. 详情页同步区域展示轮询是否启用、活跃级别、最后活跃时间、最后活跃场景和下次轮询时间。
|
||
2. 保留现有手动刷新按钮。
|
||
3. 增加“查看同步轨迹”，跳转全局审计并自动带入资产筛选。
|
||
4. 同步轨迹按立即、3分钟、5分钟连续展示结果。
|
||
|
||
接口约定：
|
||
- GET /api/admin/assets/resolve/{identifier} 返回 polling:{enabled:bool,activity_level:string,last_activity_at:string|null,last_activity_scene:string,next_poll_at:string|null}。
|
||
- 现有手动刷新接口保持原契约。
|
||
- GET /api/admin/audit/integrations 支持 resource_type、resource_key、correlation_id 查询。
|
||
|
||
交互规则：rate_limited 只展示本次失败，不显示自动退避倒计时；无下次轮询时显示“-”。
|
||
|
||
完成标准：卡和设备均能展示同步状态并跳转到过滤后的轨迹页，加载、空记录和失败状态完整。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#94] 资产状态同步DDD收口与轮询优化
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：将轮询、业务事件、手动刷新和运营商回调统一进入卡状态应用用例。
|
||
|
||
预计工时：后端7～9小时。
|
||
|
||
规则：
|
||
1. 只保留全局 enable_polling 开关，按活跃和不活跃卡使用不同轮询间隔。
|
||
2. 关键业务成功边界创建立即、3分钟、5分钟三个无自动重试任务；达到预期状态后后续任务提前完成。
|
||
3. Gateway 超频只记录 rate_limited，不做 blocked_until 或指数退避。
|
||
4. ApplyCardObservation 是实名、流量和网络状态的唯一写入口。
|
||
5. 行业卡是否实名由运营商 realname_link_type 决定。
|
||
|
||
接口：不新增显式同步接口；资产详情 Query 返回 polling；同步轨迹进入统一 Integration Log 和审计 Query。
|
||
|
||
架构：迁移到 card Domain、同步 Application、Gateway Adapter 和 Query，旧轮询及刷新逻辑改为调用统一用例。
|
||
|
||
完成标准：三条自动通道和手动刷新结果一致，事件序列可追踪，旧逻辑不再直接修改卡状态。
|
||
```
|
||
|
||
## UR#86 资产详情中换货标识
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#86] 资产详情前代后代换货标识
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：在资产详情中明确当前资产在换货链中的位置。
|
||
|
||
预计工时：前端0.5～1小时。
|
||
|
||
页面入口：卡详情、设备详情。
|
||
|
||
页面结构：
|
||
1. previous_asset 存在时显示“换货新资产”标签和前代资产信息。
|
||
2. next_asset 存在时显示“已换出旧资产”标签和后代资产信息。
|
||
3. 中间资产可同时显示前代和后代。
|
||
4. can_view=true 时支持点击跳转；false 时只显示标识文本。
|
||
|
||
接口约定：GET /api/admin/assets/resolve/{identifier} 返回 exchange_trace.previous_asset 和 exchange_trace.next_asset；单项结构为 asset_type:string、asset_id:int64|null、identifier:string、exchange_no:string、can_view:bool。
|
||
|
||
交互规则：不根据换货状态自行拼链路；关联资产为空时不展示对应区域。
|
||
|
||
完成标准：旧资产、新资产、链路中间资产和无权限四类状态均显示正确。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#86] 资产换货链Query
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：基于已完成换货单返回资产前代和后代关系。
|
||
|
||
预计工时：后端1～1.5小时。
|
||
|
||
接口：GET /api/admin/assets/resolve/{identifier} 增加 exchange_trace.previous_asset、exchange_trace.next_asset。
|
||
|
||
返回结构：asset_type、asset_id、identifier、exchange_no、can_view；无权限时 asset_id 返回 null，仍可返回脱敏后的标识和 can_view=false。
|
||
|
||
规则：复用 tb_exchange_order，不新建换货关系表；只使用已完成换货单；补充旧资产和新资产查询索引；查询遵守现有数据范围。
|
||
|
||
完成标准：卡和设备均可查询前后关系，无 N+1，越权用户不能获得可跳转资源 ID。
|
||
```
|
||
|
||
## UR#73 行业卡操作停复机
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#73] 复机实名校验提示适配
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：沿用现有复机入口，根据后端实名规则展示结果，不在前端按行业卡类型放行。
|
||
|
||
预计工时：前端0.5～1小时。
|
||
|
||
页面入口：卡详情、设备详情的复机操作。
|
||
|
||
页面结构：保持现有复机确认框；失败时原地展示后端中文业务原因。
|
||
|
||
接口约定：复用 POST /api/admin/assets/{identifier}/start；成功返回最新资产 status、status_name、real_name_status、real_name_status_name。
|
||
|
||
交互规则：前端不读取 card_category 判断实名要求；提交中禁用按钮；成功后重新拉取详情。
|
||
|
||
完成标准：同为行业卡但运营商实名能力不同的情况下，页面能正确展示放行或拦截结果。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#73] 按运营商实名能力控制复机
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：删除“行业卡统一无需实名”的错误规则。
|
||
|
||
预计工时：后端1小时。
|
||
|
||
接口：复用 POST /api/admin/assets/{identifier}/start。
|
||
|
||
规则：
|
||
1. realname_link_type=none 时允许未实名复机。
|
||
2. realname_link_type=template 或 gateway 时仍要求实名。
|
||
3. card_category 只用于分类展示，不参与复机判断。
|
||
4. 复机成功后触发实名、流量和网络状态的0/3/5同步序列。
|
||
|
||
架构：复机资格进入卡状态 Domain 规则，Handler/Service 不保留行业卡分支。
|
||
|
||
完成标准：不同运营商特性的行业卡行为正确，错误返回统一业务错误码并写审计。
|
||
```
|
||
|
||
## UR#62 H5设置先充值后实名
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#62] H5实名购买顺序与后台批量配置
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：支持无需实名、先实名后购买、先购买后实名三种流程，并提供后台批量配置。
|
||
|
||
预计工时：前端2～3小时。
|
||
|
||
页面入口：C端资产初始化流程；后台卡列表和设备列表。
|
||
|
||
页面结构：
|
||
1. C端按 effective_realname_policy 决定直接购买、先实名或购买后提示实名。
|
||
2. 后台卡和设备列表分别增加“批量修改实名顺序”入口。
|
||
3. 弹框提供无需实名、先实名后购买、先购买后实名三选一，并展示已选数量。
|
||
4. 修改设备下卡策略时提示“实际H5流程由设备策略决定”。
|
||
|
||
接口约定：
|
||
- PATCH /api/admin/assets/{identifier}/realname-mode，入参 realname_policy:none|before_order|after_order。
|
||
- POST /api/admin/iot-cards/batch-update-realname-policy、POST /api/admin/devices/batch-update-realname-policy，入参 asset_ids:int64[]、realname_policy:string。
|
||
- C端初始化返回 effective_realname_policy:string、realname_required:bool、realname_status:int。
|
||
|
||
交互规则：单次最多500条；批量接口全成全败；前端不根据资产类型自行覆盖策略。
|
||
|
||
完成标准：三种C端流程和卡/设备批量配置均可运行，冲突数据能展示明确错误。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#62] 资产实名顺序策略与批量配置
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：统一独立卡、设备和设备下卡的有效实名顺序计算。
|
||
|
||
预计工时：后端3～4小时。
|
||
|
||
接口：PATCH /api/admin/assets/{identifier}/realname-mode；POST /api/admin/iot-cards/batch-update-realname-policy；POST /api/admin/devices/batch-update-realname-policy。
|
||
|
||
规则：
|
||
1. 独立卡读取卡策略；设备及设备下卡读取设备策略。
|
||
2. realname_link_type=none 时有效策略固定为 none。
|
||
3. 需要实名的运营商配置为 none 属于冲突数据，运行时拒绝静默放行。
|
||
4. 批量最多500条，事务内全成全败。
|
||
5. 新资产默认 after_order。
|
||
|
||
完成标准：单条和批量配置使用同一校验规则，C端只需读取有效策略，配置变更写审计。
|
||
```
|
||
|
||
## UR#60 店铺联系电话检索
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#60] 店铺联系电话搜索控件
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：在店铺列表按11位联系电话精确检索。
|
||
|
||
预计工时：前端0.5～1小时。
|
||
|
||
页面入口：店铺列表筛选区。
|
||
|
||
页面结构：增加“联系电话”输入框、查询按钮和清空能力；输入框限制11位数字。
|
||
|
||
接口约定：GET /api/admin/shops?contact_phone=13800138000，返回原店铺分页结构。
|
||
|
||
交互规则：空值不传参数；非法号码不发请求并提示；清空后恢复原列表条件。
|
||
|
||
完成标准：有效号码精确命中，空结果、加载和参数错误状态完整。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#60] 店铺联系电话精确查询
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：扩展店铺列表Query，支持联系电话精确查询。
|
||
|
||
预计工时：后端0.5～1小时。
|
||
|
||
接口：GET /api/admin/shops 增加 contact_phone 查询参数。
|
||
|
||
规则：只接受合法11位手机号；空参数不影响原查询；查询继续应用现有数据权限和分页。
|
||
|
||
完成标准：命中、未命中、非法参数和越权数据范围均符合统一接口规范，查询可使用现有联系电话索引或补充必要索引。
|
||
```
|
||
|
||
## UR#57 退款中禁止换货
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#57] 换货退款拦截错误展示
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：创建换货时直接展示后端的退款拦截结果。
|
||
|
||
预计工时：前端0.5～1小时。
|
||
|
||
页面入口：换货创建页。
|
||
|
||
页面结构：不新增退款状态查询和预检查区域；提交失败时在表单顶部或资产行展示“该资产存在退款申请”。
|
||
|
||
接口约定：复用 POST /api/admin/exchanges；错误使用统一 code、msg，不改变成功返回结构。
|
||
|
||
交互规则：前端不自行判断审批或退款处理状态；失败后保留已填写表单，允许更换资产后重新提交。
|
||
|
||
完成标准：存在活跃退款时不进入下一步，已拒绝、撤销或处理完成的资产可正常换货。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#57] 换货前活跃退款校验
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：换货创建前统一拦截仍可能影响资产和资金状态的退款申请。
|
||
|
||
预计工时：后端1～1.5小时。
|
||
|
||
接口：复用 POST /api/admin/exchanges。
|
||
|
||
规则：企微审批中、历史已退回、企微已通过但退款业务处理未完成时禁止换货；已拒绝、已撤销、已删除或退款处理完成后放行。
|
||
|
||
实现：按提交资产批量查询活跃退款，禁止逐资产N+1；返回统一错误“该资产存在退款申请”；校验与换货创建保持一致性。
|
||
|
||
完成标准：所有退款状态边界明确，批量换货场景能指出失败资产且不产生半成品换货单。
|
||
```
|
||
|
||
## UR#55 套餐生效条件
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#55] 套餐分配生效条件选择
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：允许代理套餐分配覆盖套餐默认生效条件，并明确只影响未来购买。
|
||
|
||
预计工时：前端1.5～2.5小时。
|
||
|
||
页面入口：套餐授权/分配弹框、已分配套餐详情或编辑弹框。
|
||
|
||
页面结构：
|
||
1. 增加“生效条件”单选：跟随套餐默认、购买即生效、实名即生效。
|
||
2. 同时展示 default_expiry_base、override_expiry_base 和 effective_expiry_base 的中文名称。
|
||
3. 修改时提示“仅影响后续新订单，不影响已购买套餐”。
|
||
|
||
接口约定：
|
||
- POST /api/admin/shop-package-allocations，入参增加 expiry_base_override:string|null。
|
||
- PATCH /api/admin/shop-package-allocations/{id}/expiry-base，body 为 {expiry_base_override:null|"from_purchase"|"from_realname"}。
|
||
- 返回 default_expiry_base、expiry_base_override、effective_expiry_base 及对应 name 字段。
|
||
|
||
交互规则：选择“跟随默认”必须显式发送 null；不能省略字段代替恢复默认。
|
||
|
||
完成标准：新建、修改、恢复默认均可用，页面能区分默认值、覆盖值和最终值。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#55] 套餐分配生效条件覆盖与购买快照
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：建立“套餐默认→代理分配覆盖→购买使用记录快照”的完整规则。
|
||
|
||
预计工时：后端2.5～3.5小时。
|
||
|
||
接口：POST /api/admin/shop-package-allocations；PATCH /api/admin/shop-package-allocations/{id}/expiry-base。
|
||
|
||
数据：分配表增加 nullable expiry_base_override；PackageUsage 增加 expiry_base、周期类型和时长快照字段。
|
||
|
||
规则：null表示跟随默认；购买时计算有效值并写入快照；后续修改套餐或分配配置不影响已购买记录；旧数据仅做兼容回退。
|
||
|
||
架构：购买快照和激活规则进入套餐生命周期 Domain；查询侧返回默认、覆盖和最终值。
|
||
|
||
完成标准：新旧订单行为可区分，排队套餐激活和最终到期推算只读取购买快照。
|
||
```
|
||
|
||
## UR#53 资产实名状态筛选
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#53] 卡和设备实名状态筛选
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：在卡和设备列表按实名状态筛选并展示状态。
|
||
|
||
预计工时：前端1～2小时。
|
||
|
||
页面入口：卡列表、设备列表。
|
||
|
||
页面结构：筛选区增加全部、已实名、未实名；表格增加“实名状态”列，展示 real_name_status_name。
|
||
|
||
接口约定：
|
||
- GET /api/admin/iot-cards?real_name_status=0|1。
|
||
- GET /api/admin/devices?real_name_status=0|1。
|
||
- items 返回 real_name_status:int、real_name_status_name:string。
|
||
|
||
交互规则：设备状态直接使用接口结果，不在前端遍历绑定卡计算。
|
||
|
||
完成标准：卡和设备的全部、已实名、未实名筛选正确，分页切换保留筛选条件。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#53] 卡设备实名状态查询与设备快照
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：提供统一实名状态筛选，设备状态由有效绑定卡快照维护。
|
||
|
||
预计工时：后端2～3小时。
|
||
|
||
接口：GET /api/admin/iot-cards、GET /api/admin/devices 增加 real_name_status=0|1。
|
||
|
||
规则：卡读取自身实名状态；设备存在任一有效绑定实名卡即为已实名；实名变化、绑定、解绑和换卡时刷新旧设备及新设备快照。
|
||
|
||
返回：real_name_status、real_name_status_name；查询继续应用现有分页和数据权限。
|
||
|
||
完成标准：设备快照不因换卡残留，列表查询不做逐设备子查询，历史数据完成一次性初始化。
|
||
```
|
||
|
||
## UR#49 设备批量分配代理和套餐系列
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#49] 设备批量分配代理与套餐系列双入口
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：把“批量分配代理”和“批量分配套餐系列”作为两个独立功能，复用同一任务进度交互。
|
||
|
||
预计工时：前端2～3小时。
|
||
|
||
页面入口：设备列表工具栏。
|
||
|
||
页面结构：
|
||
1. 两个独立按钮：批量分配代理、批量分配套餐系列。
|
||
2. 两个弹框都包含前端静态模板下载、目标选择、Excel上传和提交按钮。
|
||
3. 创建成功后进入任务进度区，展示状态、总数、成功数、失败数和失败明细。
|
||
4. 页面刷新后根据 task_id 恢复进度。
|
||
|
||
接口约定：
|
||
- POST /api/admin/devices/batch-assign-shop，multipart包含 file、shop_id、request_id。
|
||
- POST /api/admin/devices/batch-assign-series，multipart包含 file、series_id、request_id。
|
||
- GET /api/admin/devices/batch-allocation/{task_id} 返回 task_id、operation_type、status、status_name、total_count、success_count、failed_count、failed_items。
|
||
|
||
交互规则：一个任务只能选择一种操作；任务处理中按2、3、5秒后最大10秒轮询；页面不可见时暂停。
|
||
|
||
完成标准：两个入口互不混淆，部分成功和失败原因可查看，模板由前端静态文件提供。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#49] 设备两类批量分配任务
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：使用统一批量基础设施分别执行设备代理分配和套餐系列分配。
|
||
|
||
预计工时：后端3～4小时。
|
||
|
||
接口：POST /api/admin/devices/batch-assign-shop；POST /api/admin/devices/batch-assign-series；GET /api/admin/devices/batch-allocation/{task_id}。
|
||
|
||
规则：
|
||
1. operation_type 只能是 assign_shop 或 assign_series，一个任务只修改一个目标字段。
|
||
2. 文件最大10MB、最多1000行、Worker每批200条。
|
||
3. 设备号去重后批量查询；失败明细最多保存1000条。
|
||
4. 已属于目标值按幂等成功；assign_shop 遇到其他代理资产失败；assign_series 不修改 shop_id。
|
||
5. Asynq载荷只传结构化ID和对象存储Key，不传本地路径或文件字节。
|
||
|
||
完成标准：任务支持部分成功、进度恢复和request_id防重，两种命令的数据边界清晰。
|
||
```
|
||
|
||
## UR#48 不同资产使用不同支付方式
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#48] C端按资产展示允许支付方式
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：C端支付页只展示当前资产允许使用的支付方式。
|
||
|
||
预计工时：前端1.5～2.5小时。
|
||
|
||
页面入口：卡和设备的套餐购买、充值支付页；后台系统配置页。
|
||
|
||
页面结构：
|
||
1. 支付方式使用单选列表，只渲染 allowed_payment_methods 中的选项。
|
||
2. 没有可用方式时展示原因并禁用提交。
|
||
3. 后台配置使用卡/设备两个分组的复选框，不允许直接编辑JSON。
|
||
|
||
接口约定：
|
||
- GET /api/c/v1/asset/info 返回 allowed_payment_methods:string[]，值为 alipay、wechat、wallet。
|
||
- POST /api/c/v1/orders/create 和 POST /api/c/v1/orders/{id}/pay 入参 payment_method:string。
|
||
- GET /api/admin/system/config?module=payment 查询配置；PUT /api/admin/system/config/{config_key} 保存卡和设备允许的支付方式。
|
||
|
||
交互规则：钱包是否可选完全使用后端返回；创建或支付时后端拒绝的方式直接展示错误，不由前端兜底放行。
|
||
|
||
完成标准：卡、设备、配置异常和无可用方式四类场景展示正确。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#48] 资产支付方式配置与订单校验
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：按资产类型返回允许支付方式，并在订单创建及支付阶段强校验。
|
||
|
||
预计工时：后端2～3小时。
|
||
|
||
接口：GET /api/c/v1/asset/info 增加 allowed_payment_methods；订单创建和支付接口校验 payment_method；后台复用系统配置接口。
|
||
|
||
规则：卡默认支付宝和钱包；设备默认微信和钱包；钱包始终允许；配置异常时使用安全默认值并记录错误，不能放开全部方式。
|
||
|
||
完成标准：前端隐藏不能绕过后端校验，订单创建和支付使用同一策略，配置变更写审计。
|
||
```
|
||
|
||
## UR#47 限速规则
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#47] 卡设备手动设置与取消限速
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：在卡和设备详情提供统一的手动限速入口，不展示自动限速规则。
|
||
|
||
预计工时：前端1～2小时。
|
||
|
||
页面入口：卡详情、设备详情。
|
||
|
||
页面结构：
|
||
1. “设置限速”弹框包含 speed_kbps 正整数输入框和确认按钮。
|
||
2. “取消限速”使用独立确认操作，提交 speed_kbps=0。
|
||
3. 设备详情必须显示本次实际作用的当前卡ICCID；无当前卡时禁用操作并展示原因。
|
||
4. 不展示“Gateway当前实际限速”，除非接口未来明确返回查询结果。
|
||
|
||
接口约定：POST /api/admin/assets/{identifier}/speed-limit，body={speed_kbps:int}；返回 asset_type、asset_identifier、card_no、speed_kbps、result、message。
|
||
|
||
交互规则：单位固定展示kbps；提交中禁用按钮；失败保留输入值；成功后展示后端结果。
|
||
|
||
完成标准：卡限速、设备解析当前卡、取消限速和无当前卡四类场景完整。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#47] Gateway按cardNo统一限速接口
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：只开放一个手动限速接口，最终始终按卡ICCID调用Gateway。
|
||
|
||
预计工时：后端2～3小时。
|
||
|
||
接口：POST /api/admin/assets/{identifier}/speed-limit，入参 speed_kbps；正数为设置，0为取消。
|
||
|
||
规则：资产为卡时读取ICCID；资产为设备时解析 is_current=true 的有效当前卡；不存在当前卡则拒绝；绝不把设备号传给Gateway。取消仍调用同一Gateway端口，由适配器转换上游取消参数。
|
||
|
||
非目标：不建立套餐固定限速，不因激活、到期、停机或切卡自动限速，不增加自动补偿Worker。
|
||
|
||
完成标准：返回最终card_no和调用结果，每次请求记录操作审计及Integration Log。
|
||
```
|
||
|
||
## UR#46 资产信息详情字段新增
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#46] 预计最终到期时间展示
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：资产层只展示当前及全部排队主套餐接续后的一个预计最终到期时间。
|
||
|
||
预计工时：前端1.5～2.5小时。
|
||
|
||
页面入口：卡详情、设备详情和相关资产列表。
|
||
|
||
页面结构：
|
||
1. 字段名称统一为“预计套餐到期时间”。
|
||
2. exact 时展示 estimated_final_expires_at。
|
||
3. waiting_activation 等不可预计状态展示“待激活后起算”，不伪造日期。
|
||
4. is_expiring=true 时按剩余天数使用临期颜色，普通资产列表不改变排序。
|
||
|
||
接口约定：GET /api/admin/assets/resolve/{identifier} 及资产列表返回 estimated_final_expires_at:string|null、days_until_final_expiry:int|null、expiry_estimate_status:string、is_expiring:bool。
|
||
|
||
交互规则：当前套餐自身到期时间仅保留在套餐明细；前端不叠加套餐时长自行计算。
|
||
|
||
完成标准：无套餐、仅当前套餐、存在多个排队套餐和等待未知激活时间四类状态正确。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#46] 当前及排队套餐最终到期Query
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：统一计算资产当前生效及全部排队主套餐连续接续后的预计最终到期时间。
|
||
|
||
预计工时：后端3～4小时。
|
||
|
||
接口：资产详情和列表Query返回 estimated_final_expires_at、days_until_final_expiry、expiry_estimate_status、is_expiring。
|
||
|
||
规则：按套餐队列顺序和购买时长快照推演；无套餐返回null；等待无法确定时间的实名激活时返回不可预计状态；临期、导出和C端复用同一Query。
|
||
|
||
完成标准：不维护第二套资产汇总到期字段，查询避免N+1，边界按Asia/Shanghai自然日计算。
|
||
```
|
||
|
||
## UR#45 换货管理
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#45] 换货新旧资产展示与独立搜索
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：换货列表能分别检索和识别旧资产、新资产。
|
||
|
||
预计工时：前端1～2小时。
|
||
|
||
页面入口：换货管理列表。
|
||
|
||
页面结构：
|
||
1. 筛选区拆为“旧资产”和“新资产”两个输入框。
|
||
2. 表格分别展示旧资产类型、旧资产标识、新资产类型、新资产标识。
|
||
3. 卡统一展示ICCID，设备展示设备号。
|
||
|
||
接口约定：GET /api/admin/exchanges?old_asset_keyword=&new_asset_keyword=；items返回 old_asset_type、old_asset_id、old_asset_identifier、new_asset_type、new_asset_id、new_asset_identifier、status、status_name。
|
||
|
||
交互规则：两个条件可单独或组合查询；空条件不传；不在前端转换接入号或虚拟号。
|
||
|
||
完成标准：旧资产和新资产不会混列，ICCID、接入号、虚拟号均可通过后端命中对应卡。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#45] 换货标识快照修正与新旧资产查询
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：规范换货单的新旧资产标识，并支持独立查询。
|
||
|
||
预计工时：后端1～2小时。
|
||
|
||
接口：GET /api/admin/exchanges 增加 old_asset_keyword、new_asset_keyword。
|
||
|
||
规则：卡的新旧资产快照统一保存ICCID，设备保存设备号；查询卡时支持ICCID、接入号和虚拟号映射；历史记录不强制回填；新建换货使用规范化标识。
|
||
|
||
完成标准：两个筛选条件可组合，查询遵守数据权限并具备必要索引，大结果集不出现逐行反查。
|
||
```
|
||
|
||
## UR#44 列表字段新增
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#44] 退款充值换货列表提交人与审批摘要
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：在业务列表直接看到谁提交、企微审批到哪一步、业务是否处理完成。
|
||
|
||
预计工时：前端1～2小时。
|
||
|
||
页面入口：退款列表、代理充值列表、换货列表。
|
||
|
||
页面结构：增加提交人、审批状态、当前审批人摘要、业务处理状态四列；历史本地审批显示“历史审批”，不提供操作按钮。
|
||
|
||
接口约定：GET /api/admin/refunds、GET /api/admin/agent-recharges、GET /api/admin/exchanges 的items增加 submitter_name、approval_source、approval_status、approval_status_name、current_approver_summary、processing_status、processing_status_name。
|
||
|
||
交互规则：approval_source=none时审批列显示“-”；legacy只读展示；wecom展示企微状态。长审批人摘要使用省略和悬浮完整文本。
|
||
|
||
完成标准：三类列表字段和空值规则一致，分页切换不会额外逐行请求审批详情。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#44] 提交人快照与企微审批摘要批量查询
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：为退款、充值和换货列表提供统一提交人及审批摘要。
|
||
|
||
预计工时：后端2～3小时。
|
||
|
||
接口：扩展现有三类列表返回 submitter_name、approval_source、approval_status_name、current_approver_summary、processing_status_name。
|
||
|
||
规则：提交人保存业务快照；企微摘要按当前页实例ID批量查询，禁止N+1；历史本地审批返回approval_source=legacy；无审批返回none。
|
||
|
||
完成标准：列表查询次数稳定，历史数据可读，审批摘要与详情状态一致。
|
||
```
|
||
|
||
## UR#43 代理系列授权
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#43] 系列套餐批量选择与已授权置灰
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：首次授权和后续追加套餐都支持批量选择，并明确哪些套餐已经授权。
|
||
|
||
预计工时：前端1～2小时。
|
||
|
||
页面入口：代理系列首次授权页、已授权系列的套餐管理页。
|
||
|
||
页面结构：
|
||
1. 两个入口复用同一套餐候选表格。
|
||
2. 列包含套餐名称、编码、公司成本价、当前授权成本价、建议售价、授权状态。
|
||
3. is_authorized=true 的行显示“已授权”、复选框置灰且不可全选。
|
||
4. 未授权套餐支持多选并一次提交。
|
||
|
||
接口约定：
|
||
- GET /api/admin/shop-series-grants/{id}/package-options 返回 items:{package_id,package_name,package_code,company_cost_price,authorized_cost_price,suggested_retail_price,is_authorized}。
|
||
- PUT /api/admin/shop-series-grants/{id}/packages，body={package_ids:int64[]}。
|
||
|
||
交互规则：三类价格按分转元；提交成功后重新加载候选列表；空候选和全部已授权状态有明确提示。
|
||
|
||
完成标准：首次和后续授权行为一致，已授权套餐不能被再次选择。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#43] 系列套餐候选Query与重复授权幂等
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：复用现有批量授权接口，新增可供前端一次选择的套餐候选Query。
|
||
|
||
预计工时：后端0.5～1小时。
|
||
|
||
接口：GET /api/admin/shop-series-grants/{id}/package-options；复用 PUT /api/admin/shop-series-grants/{id}/packages。
|
||
|
||
返回：package_id、名称、编码、company_cost_price、authorized_cost_price、suggested_retail_price、is_authorized。
|
||
|
||
规则：重复套餐按幂等处理；后端不依赖前端置灰；查询遵守代理、系列和套餐可见范围；三个价格字段语义分开。
|
||
|
||
架构：候选列表走Query，批量授权走轻量Application事务脚本。
|
||
|
||
完成标准：首次和后续授权共用契约，重复提交不生成重复关系。
|
||
```
|
||
|
||
## UR#42 导出功能
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#42] 导出字段选择权限配置与任务进度
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：用户按权限选择导出字段，管理员可给角色配置各场景可导出字段。
|
||
|
||
预计工时：前端3～4小时。
|
||
|
||
页面入口：卡、钱包流水、套餐、退款、换货、充值、临期列表的导出弹框；角色权限配置页。
|
||
|
||
页面结构：
|
||
1. 导出弹框先加载当前scene可选字段，使用复选框选择，未授权字段不展示。
|
||
2. 支持xlsx/csv格式及当前列表查询条件。
|
||
3. 创建后展示任务状态、进度、失败原因和下载按钮。
|
||
4. 角色配置按scene分组展示字段复选框并保存。
|
||
|
||
接口约定：
|
||
- GET /api/admin/export-fields?scene= 返回 fields:{field_key,label,selected_by_default}[]。
|
||
- POST /api/admin/export-tasks，body={scene,format,query,fields:string[]}，返回 task_id。
|
||
- GET /api/admin/export-tasks/{id} 返回 status、status_name、progress、download_url、error_message。
|
||
- GET/PUT /api/admin/roles/{role_id}/export-fields 查询和保存场景字段。
|
||
|
||
交互规则：下载地址为空时禁用下载；任务轮询复用统一异步任务规则；字段为空时禁止提交。
|
||
|
||
完成标准：字段权限、任务恢复、失败重试和文件下载流程完整。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#42] 统一导出场景与角色字段权限
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：复用现有导出任务体系，增加本期场景和角色字段级权限。
|
||
|
||
预计工时：后端4～6小时。
|
||
|
||
接口：GET /api/admin/export-fields；POST /api/admin/export-tasks；GET /api/admin/export-tasks/{id}；GET/PUT /api/admin/roles/{role_id}/export-fields。
|
||
|
||
规则：最终字段=用户申请字段∩角色授权字段并集∩场景支持字段；超级管理员拥有全部字段；字段授权不能扩大数据行范围；创建任务时快照字段和表头；权限解析失败直接拒绝。
|
||
|
||
场景：iot_card、agent_wallet_transaction、package、refund、exchange、agent_recharge、expiring_asset。审批附件只导出数量，不导出对象Key或永久URL。
|
||
|
||
完成标准：Count与Fetch条件一致，审批摘要批量查询，导出任务可恢复且无越权字段。
|
||
```
|
||
|
||
## UR#40 套餐设计
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#40] C端下架套餐续费入口
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：下架套餐不出现在新购列表，但历史使用资产可在当前套餐旁直接续费。
|
||
|
||
预计工时：前端1.5～2.5小时。
|
||
|
||
页面入口：C端资产当前套餐区域、套餐购买流程。
|
||
|
||
页面结构：
|
||
1. 当前套餐旁根据 can_purchase 显示“续费”按钮。
|
||
2. purchase_mode=renew_only 时只从当前套餐入口进入，不在套餐商城列表展示。
|
||
3. 不可续费时按钮禁用或隐藏，并可展示 disabled_reason。
|
||
4. 点击续费复用现有购买套餐流程，不拆出第二个套餐列表。
|
||
|
||
接口约定：GET /api/c/v1/asset/packages 返回 package_id、status、status_name、can_purchase、purchase_mode、disabled_reason；POST /api/c/v1/orders/create 沿用资产和套餐入参。
|
||
|
||
交互规则：前端不根据套餐上下架状态自行判断资格，以接口字段为准。
|
||
|
||
完成标准：正常在售购买、历史下架续费、禁用套餐和无历史资格四类场景正确。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#40] 下架套餐历史用户续费资格校验
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：统一套餐可售策略，支持资产所有人续费历史使用过的下架套餐。
|
||
|
||
预计工时：后端2～3小时。
|
||
|
||
接口：GET /api/c/v1/asset/packages 返回 can_purchase、purchase_mode、disabled_reason；POST /api/c/v1/orders/create 强校验。
|
||
|
||
规则：禁用套餐始终不可购买；下架套餐只允许当前资产所有人基于有效历史使用记录续费；禁止代理代购；新购列表不返回下架套餐。
|
||
|
||
完成标准：批量订购和普通下单复用同一可售策略，不能通过直接请求绕过资格校验。
|
||
```
|
||
|
||
## UR#38 不同渠道额度处理
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#38] 角色默认信用与店铺实际额度管理
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：角色只配置未来新建店铺的默认信用，已有店铺在资金页单独修改实际额度。
|
||
|
||
预计工时：前端2.5～3.5小时。
|
||
|
||
页面入口：客户角色配置页、店铺资金概况页、店铺创建页。
|
||
|
||
页面结构：
|
||
1. 客户角色增加“新建代理默认信用”开关和额度输入，并提示“修改后不会影响已有店铺”。
|
||
2. 店铺资金页展示现金余额、冻结金额、实际信用额度、可用金额、欠款金额和版本。
|
||
3. 店铺实际额度使用独立调整弹框，展示修改前后金额预览。
|
||
4. 平台员工角色不展示信用配置。
|
||
|
||
接口约定：
|
||
- PUT /api/admin/roles/{id}/default-credit，body={credit_enabled:bool,credit_limit:int64}。
|
||
- PUT /api/admin/shops/{id}/credit-limit，body={credit_enabled:bool,credit_limit:int64,version:int64}。
|
||
- GET /api/admin/shops/fund-summary 返回 balance、frozen_balance、credit_enabled、credit_limit、available_balance、is_in_debt、debt_amount、version。
|
||
|
||
交互规则：金额不在前端重新计算；并发冲突时刷新最新资金概况；关闭信用时额度输入归零。
|
||
|
||
完成标准：角色默认、创建店铺初始化、已有店铺调额和并发冲突提示完整。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#38] 代理主钱包信用额度与资金不变量
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：信用额度只属于代理主钱包，角色配置只作为新店铺初始化模板。
|
||
|
||
预计工时：后端4～5小时。
|
||
|
||
接口：PUT /api/admin/roles/{id}/default-credit；PUT /api/admin/shops/{id}/credit-limit；GET /api/admin/shops/fund-summary；创建店铺时读取默认角色模板。
|
||
|
||
不变量：available=balance-frozen_balance+effective_credit且必须>=0；关闭信用时额度为0；存在欠款或冻结导致新可用金额<0时禁止降额或关闭。
|
||
|
||
规则：修改角色不更新已有店铺；店铺后续角色变化不影响钱包；余额、冻结、信用、版本和资金流水在同一事务维护；调额按version乐观锁更新。
|
||
|
||
架构：钱包资金规则迁入Wallet Domain，查询走资金Query。
|
||
|
||
完成标准：扣款、冻结、解冻、充值、退款回充和调额都维护同一不变量并写资金审计。
|
||
```
|
||
|
||
## UR#37 审核流转
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#37] 企微配置账号绑定与审批只读详情
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：使用企业微信完成审批，本系统只负责配置、账号扫码绑定、状态查看和异常恢复。
|
||
|
||
预计工时：前端6～8.5小时，包含多人审批业务映射展示。
|
||
|
||
页面入口：/system/wecom、个人中心、/operations/wecom-approvals、退款和线下充值详情。
|
||
|
||
页面结构：
|
||
1. 企微配置页：连接状态、审批场景状态、模板版本列表、模板读取和业务字段到控件的可视化映射发布。
|
||
2. 个人中心：绑定状态、成员名称、扫码绑定、重新绑定、解绑；不提供userid输入框。
|
||
3. 审批运行页：业务类型、业务单号、sp_no、状态、模板版本、申请人、更新时间和异常标识；详情抽屉展示审批人、意见、附件、时间线和业务处理结果。
|
||
4. 业务详情复用统一approval区块，只读展示，不提供通过、驳回、退回按钮。
|
||
|
||
接口约定：
|
||
- GET /api/admin/wecom/status。
|
||
- PUT /api/admin/wecom/approval-scenes/{scene_code}/status。
|
||
- POST /api/admin/wecom/approval-templates/inspect、POST /api/admin/wecom/approval-templates/publish、GET /api/admin/wecom/approval-templates。
|
||
- POST /api/admin/wecom/account-binding/sessions，返回 session_id、login_url、expires_at；GET /api/admin/wecom/account-binding/sessions/{session_id} 查询结果；GET/DELETE /api/admin/wecom/account-binding/me。
|
||
- GET /api/admin/wecom/approvals、GET /api/admin/wecom/approvals/{id}、POST /api/admin/wecom/approvals/{id}/sync。
|
||
|
||
交互规则：扫码绑定页面轮询会话；未绑定创建审批时原地提供绑定入口；立即同步只拉取企微详情；通过后撤销且业务已执行时显示高风险提示。
|
||
|
||
完成标准：配置、绑定、列表、详情、同步和异常状态均有加载、空、失败及权限状态。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#37] 企业微信审批模板账号绑定回调与补偿
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：以稳定业务场景码接入企微审批，替代本地审批流。
|
||
|
||
预计工时：后端9～11.5小时，包含多人审批场景映射。
|
||
|
||
接口：实现企微状态、场景暂停恢复、模板读取发布、扫码绑定、绑定管理、审批列表详情、立即同步及企微回调接口。
|
||
|
||
规则：
|
||
1. 场景码固定为 refund_approval、offline_recharge_approval，模板ID和控件ID按不可变版本映射。
|
||
2. 模板编辑前暂停场景，发布新映射后恢复；历史实例保留模板和提交快照。
|
||
3. 系统账号通过5分钟一次性会话扫码绑定企微userid，account_id和userid均唯一。
|
||
4. 回调只验签解密并触发统一SyncApprovalStatus；getapprovaldetail为状态权威来源；审批中实例每2分钟兜底轮询。
|
||
5. 首次终态同事务写业务Outbox，business_processed_at保证只执行一次。
|
||
|
||
架构：使用wecomapproval、wecomidentity Domain/Application，外部API和加解密进入WeCom Adapter，列表详情走Query。
|
||
|
||
完成标准：不注册本地审批动作接口，提交未知、模板变更、回调重复和轮询重复均可恢复且可审计。
|
||
```
|
||
|
||
## UR#36 批量订购套餐
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#36] 批量订购上传支付进度与失败明细
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：运营按一个代理和一种支付方式批量导入套餐订单，并查看逐行结果。
|
||
|
||
预计工时：前端3～4小时。
|
||
|
||
页面入口：批量订购套餐页或现有订单页批量入口。
|
||
|
||
页面结构：
|
||
1. 选择代理、整批支付方式（线下或代理钱包）、上传Excel；线下支付时上传整批凭证。
|
||
2. 模板下载使用前端静态文件。
|
||
3. 创建后展示任务号、状态、总数、成功数、失败数、金额汇总和失败明细表。
|
||
4. 失败明细包含行号、资产、套餐编码、错误原因；支持按任务ID恢复页面。
|
||
|
||
接口约定：
|
||
- POST /api/admin/bulk-purchases，multipart包含 shop_id、payment_method、file、voucher_file、request_id。
|
||
- GET /api/admin/bulk-purchases/{task_id} 返回任务汇总。
|
||
- GET /api/admin/bulk-purchases/{task_id}/items?page=&size=&status= 返回逐行结果。
|
||
|
||
交互规则：一个批次不能混合支付方式；部分成功视为任务终态；钱包余额不足只影响对应行或后续行，不回滚已成功行。
|
||
|
||
完成标准：上传、进度恢复、部分成功、失败筛选和凭证展示完整。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#36] 批量订购任务与逐行幂等下单
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：以异步任务逐行创建订单，允许部分成功且每行可审计。
|
||
|
||
预计工时：后端4～6小时。
|
||
|
||
接口：POST /api/admin/bulk-purchases；GET /api/admin/bulk-purchases/{task_id}；GET /api/admin/bulk-purchases/{task_id}/items。
|
||
|
||
规则：整批选择offline或agent_wallet；模板按套餐编码匹配；文件最大10MB、最多1000行；request_id唯一返回原任务；行幂等键为bulk_purchase:{task_id}:{row_no}。
|
||
|
||
钱包行事务：锁主钱包，按信用不变量校验，订单、扣款、流水和明细成功状态同事务；单行失败不回滚其他行；任务统计从明细重新聚合。线下凭证只做本批资料，不校验跨批唯一。
|
||
|
||
完成标准：Worker处理租约、重复消费、进程中断恢复和部分成功均不产生重复订单或重复扣款。
|
||
```
|
||
|
||
## UR#35 退款审核
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#35] 退款企微审批详情与业务处理状态
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：退款创建时提交业务资料，审批在企微完成，本系统只读展示审批及退款处理结果。
|
||
|
||
预计工时：前端2.5～3.5小时。
|
||
|
||
页面入口：退款创建、退款列表、退款详情。
|
||
|
||
页面结构：
|
||
1. 创建表单包含退款金额、原因、备注和附件；金额提交后企微审批不可修改。
|
||
2. 详情分为退款业务信息、企微审批信息、业务处理结果三个区域。
|
||
3. 审批区展示sp_no、状态、申请人、审批人、意见、附件和时间线。
|
||
4. 处理区展示processing_status、失败摘要和“系统重试中/联系管理员”。
|
||
5. 不显示本地通过、驳回、退回或人工退款确认按钮。
|
||
|
||
接口约定：
|
||
- POST /api/admin/refunds 创建退款。
|
||
- GET /api/admin/refunds/{id} 返回退款数据、approval对象和processing_status。
|
||
- POST /api/admin/refunds/{id}/resubmit，仅已驳回、已撤销或已删除可重新申请。
|
||
- attachments使用现有对象存储上传结果，提交结构为 {file_key,file_name,file_size}[]。
|
||
- approval结构至少包含 source、sp_no、status、status_name、template_version、applicant、approvers、comments、attachments、timeline、business_process_result。
|
||
|
||
交互规则：非代理钱包由财务在系统外人工退款后再在企微通过；重新申请可改金额、凭证和原因，不可改订单、资产和提交人快照。
|
||
|
||
完成标准：审批中、通过处理中、处理成功、驳回、撤销和通过后撤销异常状态均展示明确。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#35] 退款企微终态与人工退款处理
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：退款通过企微审批驱动业务终态，系统只自动回溯代理主钱包支付。
|
||
|
||
预计工时：后端4～5小时。
|
||
|
||
接口：POST /api/admin/refunds；GET /api/admin/refunds/{id}；POST /api/admin/refunds/{id}/resubmit；下线原approve/reject/return路由。
|
||
|
||
规则：
|
||
1. 非代理钱包支付由财务人工退款，企微通过代表人工退款已确认，不调用渠道退款API。
|
||
2. 代理钱包订单通过后按原扣款流水幂等回溯原代理主钱包并写退款流水。
|
||
3. 个人客户或资产钱包不自动回款。
|
||
4. 驳回更新为已拒绝；撤销/删除更新为已撤销；通过后撤销且资金已执行不自动冲正，记录critical审计。
|
||
5. 重新申请创建round_no+1企微实例并保留历史。
|
||
|
||
完成标准：审批状态与业务处理状态分离，重复终态不重复回款，失败任务可可靠重试。
|
||
```
|
||
|
||
## UR#34 充值审核流程
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#34] 代理扫码充值与员工线下充值审批页面
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：区分代理在线扫码充值和平台员工线下代充值，两条路径不混用。
|
||
|
||
预计工时：前端5～7小时，包含在线扫码充值和线下审批两条页面链路。
|
||
|
||
页面入口：代理资金充值页、后台线下代充值创建页、充值列表和详情。
|
||
|
||
页面结构：
|
||
1. 在线充值：金额输入最低100元、支付方式选择、二维码、过期倒计时和支付状态；不显示审批区域。
|
||
2. 线下代充值：选择店铺、金额、备注、附件；提交后显示企微审批和入账处理状态。
|
||
3. 充值详情按approval_source显示：none隐藏审批区，wecom显示只读企微详情。
|
||
4. 不显示本地确认入账、驳回按钮和操作密码输入框。
|
||
|
||
接口约定：
|
||
- GET /api/admin/agent-recharges/payment-methods 返回 methods:string[]、min_amount:int64。
|
||
- POST /api/admin/agent-recharges，在线入参 amount、payment_method、request_id；线下入参 shop_id、amount、payment_method=offline、remark、attachments、request_id。
|
||
- 在线返回 recharge_id、recharge_no、qr_content、expires_at、payment_status、approval_source=none。
|
||
- GET /api/admin/agent-recharges/{id}/payment-status 返回 payment_status、payment_status_name、wallet_posting_status。
|
||
- GET /api/admin/agent-recharges/{id} 返回充值详情、approval和processing_status。
|
||
- 线下attachments使用现有对象存储上传结果，结构为 {file_key,file_name,file_size}[]。
|
||
|
||
交互规则：在线状态每3秒轮询，页面不可见暂停；二维码过期后重新创建新支付单；线下提交失败保留表单。
|
||
|
||
完成标准：微信、支付宝、二维码过期、重复回调后的最终状态、线下审批通过入账和驳回状态均可展示。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#34] 代理在线充值入账与线下充值企微终态
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：实现无需审批的代理在线充值，以及需要企微审批的平台员工线下代充值。
|
||
|
||
预计工时：后端8～11小时，包含支付渠道接入和线下审批入账。
|
||
|
||
接口：GET /api/admin/agent-recharges/payment-methods；POST /api/admin/agent-recharges；GET /api/admin/agent-recharges/{id}/payment-status；GET /api/admin/agent-recharges/{id}；下线offline-pay和reject旧接口。
|
||
|
||
在线规则：最低10000分；支持微信Native和支付宝预下单；统一返回qr_content；支付回调校验渠道、金额、配置、交易号和业务单；支付单、充值单、主钱包、版本、唯一流水和审计同事务推进；重复回调不重复入账。
|
||
|
||
线下规则：创建后提交企微；通过后自动增加代理主钱包并写流水，无操作密码；recharge:{recharge_no}防重；驳回为已驳回，撤销/删除为已关闭；通过后撤销且已入账不自动扣回。
|
||
|
||
完成标准：两条路径状态隔离，支付成功但入账失败可补偿，企微终态重复同步不重复加钱。
|
||
```
|
||
|
||
## UR#33 套餐临期提醒
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][UR#33] 临期列表高亮置顶通知与续费入口
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：统一展示资产预计最终到期的临期状态，并提供站内通知和续费入口。
|
||
|
||
预计工时：前端3～4.5小时，不含公共站内通知中心工时。
|
||
|
||
页面入口：/operations/expiring-assets或现有临期页、卡/设备列表和详情、代理首页、C端资产页、通知中心。
|
||
|
||
页面结构：
|
||
1. 临期独立列表展示资产、店铺、当前套餐、预计最终到期、剩余天数和颜色；0-3天固定置顶，再按到期时间升序。
|
||
2. 普通资产列表只按颜色高亮，不改变原排序。
|
||
3. 代理首页展示临期卡数量和设备数量。
|
||
4. C端资产页展示临期状态和续费按钮。
|
||
5. 通知中心展示15天、7天、3天站内提醒，不展示企微临期消息。
|
||
|
||
接口约定：
|
||
- GET /api/admin/expiring-assets 支持 asset_type、keyword、shop_id、package_id、days_min、days_max、expires_from、expires_to、page、size。
|
||
- items返回 asset_type、asset_id、identifier、shop_name、package_name、estimated_final_expires_at、days_until_final_expiry、expiry_level、expiry_level_name、can_renew。
|
||
- 资产列表/详情和GET /api/c/v1/asset/info返回同一临期字段。
|
||
- 通知复用通知接口。
|
||
|
||
交互规则：颜色为8-15天粉红、4-7天紫色、0-3天红色；已过期和不可预计资产不进入临期页。
|
||
|
||
完成标准：列表排序、普通列表高亮、首页计数、C端续费和通知跳转使用同一到期结果。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][UR#33] 最终到期临期Query与15/7/3站内通知
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：基于统一预计最终到期Query提供临期查询和站内通知。
|
||
|
||
预计工时：后端4～6小时，不含公共站内通知基础设施工时。
|
||
|
||
接口：GET /api/admin/expiring-assets；扩展卡/设备列表详情、代理首页和GET /api/c/v1/asset/info；复用通知接口和scene=expiring_asset导出。
|
||
|
||
规则：按Asia/Shanghai自然日计算0-15天；已过期和不可预计资产不计入；临期页0-3天优先，再按最终到期升序；普通列表不改排序。
|
||
|
||
通知：每日任务按package_usage_id+recipient+channel+node防重，节点为15/7/3天；漏跑只补当前最近未发送节点；接收店铺主账号和业务员；只发站内通知。
|
||
|
||
完成标准：查询、首页计数、C端和通知共用同一最终到期算法，重复任务不重复通知。
|
||
```
|
||
|
||
## 技术用户需求 七月迭代公共开发基础
|
||
|
||
> 建议与全局审计、站内通知一起挂到“七月迭代公共基础设施”技术用户需求下。
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][TECH] 七月迭代公共状态与异步任务交互
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：为批量分配、批量订购、导出等页面提供一致的加载、错误和异步任务交互。
|
||
|
||
预计工时：前端1～2小时。
|
||
|
||
交付内容：
|
||
1. 统一加载、空数据、权限不足、接口失败和重试状态。
|
||
2. 统一异步任务进度结构：任务状态、总数、成功数、失败数、部分成功和失败明细。
|
||
3. 创建任务后按2秒、3秒、5秒递增轮询，最大间隔10秒；页面不可见暂停，恢复后立即刷新。
|
||
4. 页面刷新后通过task_id恢复任务详情。
|
||
|
||
完成标准：设备批量分配、批量订购和导出页面复用同一交互规则，不各自实现不同状态语义。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][TECH] 七月迭代公共迁移幂等与异步任务基础
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：补齐本期跨需求共用的数据迁移、Outbox、幂等和异步任务能力。
|
||
|
||
预计工时：后端4～5小时。
|
||
|
||
交付内容：
|
||
1. 按标准稿准备增量迁移、索引、约束和停机迁移检查。
|
||
2. 统一Outbox写入和消费状态，供企微终态、钱包通知和状态同步使用。
|
||
3. 统一request_id防重、状态条件更新、乐观锁和Worker处理租约。
|
||
4. 统一异步任务状态及失败明细Query，Asynq载荷只传结构化数据。
|
||
5. 为渐进DDD新增的Domain、Application、Query和Adapter提供项目内一致目录及装配方式。
|
||
|
||
完成标准：业务研发需求复用公共能力，不分别创建不兼容的幂等、Outbox和任务状态实现。
|
||
```
|
||
|
||
## 技术用户需求 公共站内通知
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][TECH] 顶部通知铃铛与站内通知中心
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：提供本期余额预警、临期提醒、审批结果和系统告警共用的站内通知界面。
|
||
|
||
预计工时：前端3～4小时。
|
||
|
||
页面入口：顶部全局导航、/notifications。
|
||
|
||
页面结构：
|
||
1. 顶部铃铛固定宽度显示0、1～99或99+，点击展示最近10条通知抽屉。
|
||
2. 抽屉按全部、审批、临期、同步/系统分类，并提供进入通知中心入口。
|
||
3. 通知中心支持分类、类型、严重级别、已读状态筛选及全部已读。
|
||
4. 点击通知先标记已读，再根据ref_type受控跳转；未知目标只展示正文。
|
||
|
||
接口约定：GET /api/admin/notifications/unread-count、unread-summary、notifications；PUT /api/admin/notifications/{id}/read、read-all；GET /api/admin/notifications/{id}/target。C端使用对应/api/c/v1/notifications接口。
|
||
|
||
完成标准：余额、临期、审批和系统通知展示一致，未读数和列表状态同步，无任意URL跳转。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][TECH] 站内通知基础设施与受控跳转
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：为本期所有通知场景提供统一存储、模板、接收人、防重、未读和受控跳转能力。
|
||
|
||
预计工时：后端3～4小时。
|
||
|
||
接口：实现管理端和C端未读数、分类汇总、分页列表、单条已读、全部已读及受控目标解析接口。
|
||
|
||
规则：
|
||
1. 通知使用稳定业务键防重，按场景解析店铺主账号、业务员、申请人等接收人。
|
||
2. target只返回受控ref_type和ref_id，不保存或返回任意URL。
|
||
3. 通知失败不回滚资金、审批或套餐业务事务，由Outbox可靠重试。
|
||
4. 余额预警、15/7/3临期、审批结果和系统告警复用统一模板注册。
|
||
|
||
完成标准：重复事件不重复通知，接收人停用时跳过，管理端和C端数据范围正确。
|
||
```
|
||
|
||
## 技术用户需求 全局多视角审计与外部集成追踪
|
||
|
||
> 当前禅道CSV没有对应父用户需求。先创建该技术用户需求，再创建以下FE、BE研发需求。
|
||
|
||
### 前端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[FE][TECH] 全局多视角审计中心
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：提供一个工作台式审计中心，从全局、人员、资源、链路、资金、风险和外部集成多个视角追踪系统操作。
|
||
|
||
预计工时：前端6～8小时。
|
||
|
||
页面入口：/operations/audit。
|
||
|
||
页面结构：
|
||
1. Tab：全局事件、人员行为、资源轨迹、请求/业务链路、资金审计、风险事件、外部集成。
|
||
2. 公共筛选：时间、操作编码、结果、风险级别、操作者、资源、request_id、correlation_id。
|
||
3. 列表展示时间、操作者、操作、主要资源、结果、风险和链路编号；详情抽屉展示脱敏前后数据、关联资源和上下游事件。
|
||
4. 资源轨迹先搜索候选资源再打开时间线；外部集成按provider、operation、触发来源和序列展示立即/3分钟/5分钟结果。
|
||
5. 敏感字段默认脱敏；查看敏感值和导出使用独立权限。
|
||
|
||
接口约定：GET /api/admin/audit/events及详情、actors、resources/search及timeline、requests和correlations timeline、risks、integrations、finance/timeline；POST /api/admin/audit/exports。
|
||
|
||
完成标准：每个视角有独立筛选和空状态，可通过request_id/correlation_id在事件间跳转，旧历史日志可只读展示。
|
||
```
|
||
|
||
### 后端研发需求
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[BE][TECH] Audit Event与Integration Log统一审计
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
目标：一次停机发布切换全局审计写入，并提供多视角Query。
|
||
|
||
预计工时：后端8～11小时。
|
||
|
||
数据：tb_audit_event、tb_audit_event_resource、tb_integration_log；Audit Event不可变，支持主资源、影响资源和引用资源。
|
||
|
||
接口：实现事件、人员、资源、request、correlation、风险、外部集成、资金和导出Query。
|
||
|
||
规则：资金、权限、审批和关键配置变更与业务事务同事务写审计；失败和拒绝在回滚后短事务记录；外部交互写Integration Log；密码、Token、Secret、私钥、验证码、完整证件、签名URL和media_id禁止入库。
|
||
|
||
迁移：新旧敏感写操作统一接入Audit Writer，旧日志停止新写入；历史数据通过Query UNION ALL只读投影，不双写。
|
||
|
||
完成标准：多资源关联、链路追踪、脱敏、保留周期和审计自身权限完整，关键审计失败能阻止对应业务提交。
|
||
```
|
||
|
||
## 联调研发需求
|
||
|
||
> 建议先建立技术用户需求“7月迭代跨模块联调与发布验收”，以下每条作为可独立指派的联调研发需求。问题修复仍回到对应FE/BE研发需求。
|
||
|
||
### INT-01 资产实名、复机与状态同步联调
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[INT-01] 资产实名复机与状态同步联调
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
关联需求：UR#94、UR#73、UR#62、UR#53。
|
||
|
||
参与工时参考：前端1～1.5小时、后端1～1.5小时，从关联FE/BE研发需求工时中拆出，不新增总工时。
|
||
|
||
进入条件：H5流程、实名策略接口、卡状态统一应用用例、轮询和0/3/5任务已完成。
|
||
|
||
联调范围：
|
||
1. 不同realname_link_type下的实名要求和行业卡复机结果。
|
||
2. none、before_order、after_order三种H5流程。
|
||
3. 查询、获取实名链接、停复机、支付、套餐激活等埋点后的立即/3分钟/5分钟轨迹。
|
||
4. 19位和20位ICCID实名回调路由。
|
||
5. 卡和设备实名筛选及设备快照更新。
|
||
|
||
完成标准：前端状态、业务数据、审计轨迹和上游调用结果一致，无旧逻辑直接改卡状态。
|
||
```
|
||
|
||
### INT-02 换货完整链路联调
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[INT-02] 换货完整链路联调
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
关联需求：UR#98、UR#86、UR#57、UR#45。
|
||
|
||
参与工时参考：前端0.5～1小时、后端0.5～1小时，从关联FE/BE研发需求工时中拆出，不新增总工时。
|
||
|
||
进入条件：换货创建/完成接口、退款拦截、列表搜索和资产详情换货链已完成。
|
||
|
||
联调范围：退款中拦截、平台库存新资产继承旧店铺、其他店铺新资产拒绝、完成换货、旧店铺历史可见、新旧资产独立搜索、前代后代跳转和无权限显示。
|
||
|
||
完成标准：换货事务数据一致，列表、详情、资产归属和审计结果一致。
|
||
```
|
||
|
||
### INT-03 套餐生命周期联调
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[INT-03] 套餐授权购买续费到期与临期联调
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
关联需求：UR#55、UR#46、UR#43、UR#40、UR#33。
|
||
|
||
参与工时参考：前端1～1.5小时、后端1～1.5小时，从关联FE/BE研发需求工时中拆出，不新增总工时。
|
||
|
||
进入条件：套餐授权候选、生效条件快照、可售策略、最终到期Query和临期页面已完成。
|
||
|
||
联调范围：批量授权及已授权置灰、默认/覆盖生效条件、购买快照、下架套餐历史续费、多个排队套餐最终到期、临期高亮/置顶、15/7/3通知和C端续费。
|
||
|
||
完成标准：后台、C端、临期列表、通知和导出使用同一套餐生命周期结果。
|
||
```
|
||
|
||
### INT-04 Excel批量任务与导出联调
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[INT-04] Excel批量任务与导出联调
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
关联需求：UR#49、UR#36、UR#42。
|
||
|
||
参与工时参考：前端1～1.5小时、后端1～1.5小时，从关联FE/BE研发需求工时中拆出，不新增总工时。
|
||
|
||
进入条件：前端静态模板、上传页面、异步任务、Worker、失败明细和导出场景完成。
|
||
|
||
联调范围：表头校验、文件限制、重复request_id、部分成功、失败明细、任务刷新恢复、代理/系列双命令隔离、批量订购钱包扣款、导出字段权限和文件下载。
|
||
|
||
完成标准：任务中断可恢复，不重复分配、下单或扣款，前端进度与后端统计一致。
|
||
```
|
||
|
||
### INT-05 支付钱包信用与余额预警联调
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[INT-05] 支付钱包信用充值与余额预警联调
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
关联需求：UR#48、UR#38、UR#34、UR#36、UR#96、UR#97。
|
||
|
||
参与工时参考：前端1～1.5小时、后端1～1.5小时，从关联FE/BE研发需求工时中拆出，不新增总工时。
|
||
|
||
进入条件：支付配置、在线充值、钱包领域、信用调额、业务员关联和低余额通知完成。
|
||
|
||
联调范围：卡/设备支付方式、微信/支付宝扫码充值、支付回调幂等、角色默认信用、已有店铺调额、批量订购扣款、现金余额跨越100元阈值及店铺主账号/业务员通知。
|
||
|
||
完成标准：资金不变量成立，支付或审批重复回调不重复入账，信用额度不参与现金余额预警。
|
||
```
|
||
|
||
### INT-06 企业微信审批退款与线下充值联调
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[INT-06] 企业微信审批退款与线下充值联调
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
关联需求：UR#37、UR#35、UR#34、UR#44。
|
||
|
||
参与工时参考：前端1.5～2小时、后端1.5～2小时，从关联FE/BE研发需求工时中拆出，不新增总工时。
|
||
|
||
进入条件：模板映射、扫码绑定、审批提交、回调、2分钟轮询、退款和线下充值终态处理完成。
|
||
|
||
联调范围：账号扫码绑定、未绑定拦截、模板发布、发起审批、意见附件、通过/驳回/撤销/删除、回调重复、立即同步、退款人工处理、代理钱包回溯、线下充值入账和列表审批摘要。
|
||
|
||
完成标准：本系统无审批按钮，企微状态与业务处理状态分离，终态重复同步不重复执行资金动作。
|
||
```
|
||
|
||
### INT-07 Gateway卡限速联调
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[INT-07] Gateway卡限速联调
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
关联需求：UR#47。
|
||
|
||
参与工时参考：前端0.5～1小时、后端0.5～1小时，从关联FE/BE研发需求工时中拆出，不新增总工时。
|
||
|
||
进入条件：统一限速接口、卡和设备详情入口、Gateway联调配置完成。
|
||
|
||
联调范围：单卡设置、设备解析当前卡、speed_kbps单位、0取消限速、设备无当前卡、Gateway失败及审计记录。
|
||
|
||
完成标准：Gateway收到的cardNo始终为卡ICCID，设备号不会被发送，上游结果在页面和审计中可追踪。
|
||
```
|
||
|
||
### INT-08 全链路与停机发布验收
|
||
|
||
**标题**
|
||
|
||
```text
|
||
[INT-08] 7月迭代全链路与停机发布验收
|
||
```
|
||
|
||
**描述**
|
||
|
||
```markdown
|
||
关联需求：全部激活用户需求及全局审计技术需求。
|
||
|
||
预计工时：前端3～4小时、后端4～5小时，本项为额外发布工时并计入总工时。
|
||
|
||
进入条件：INT-01至INT-07完成，迁移脚本、配置、Worker和发布清单已准备。
|
||
|
||
验收范围：权限与越权、通知跳转、审计多视角、历史数据兼容、旧审批接口下线、旧审计停止写入、异步任务恢复、停机迁移、配置校验和回滚边界。
|
||
|
||
完成标准：前端和后端使用冻结接口契约，核心链路人工验收通过，发布检查项和已知风险已记录。
|
||
```
|