迭代方案确认
This commit is contained in:
@@ -74,7 +74,7 @@ handlers := &bootstrap.Handlers{
|
||||
|
||||
## 架构演进：MVC 与 DDD 共存
|
||||
|
||||
项目采用**触碰式渐进迁移**，不安排一次性全仓库重构。详细规则见 `docs/7月迭代/DDD规范.md`。
|
||||
项目采用**触碰式渐进迁移**，不安排一次性全仓库重构。详细规则见 `docs/7月迭代/独立方案/基础规范/DDD规范.md`。
|
||||
|
||||
### 三条执行通道
|
||||
|
||||
|
||||
@@ -1,254 +0,0 @@
|
||||
# 7月迭代技术方案总览
|
||||
|
||||
> 状态：待评审
|
||||
> 负责人：待指定
|
||||
> 评审人：后端、前端、产品、验收负责人、运维待指定
|
||||
> 讨论日期：2026-07-11
|
||||
> 最后更新：2026-07-14
|
||||
> 分支：Iteration/7-11
|
||||
> 系统：junhong_cmp_fiber（已上线，渐进迭代）
|
||||
|
||||
---
|
||||
|
||||
## 一、评审结论
|
||||
|
||||
当前方案的技术方向没有跑偏：渐进式 DDD、通用审批流、Outbox、异步任务复用和查询侧独立都符合当前系统约束。
|
||||
|
||||
此前版本缺少流程图、前端方案、发布方案和若干关键业务决策。本轮已经补齐这些评审材料，并确认以下口径：
|
||||
|
||||
- 平台员工不建立信用额度；信用额度只属于代理主钱包。
|
||||
- 批量订购的支付方式按整批统一，Excel 不携带支付方式。
|
||||
- 角色级导出字段配置属于本期必做能力。
|
||||
- Gateway 限速只面向卡号，设备场景先解析当前卡再调用 `cardNo`；本期仅人工设置/取消，不做套餐自动限速。
|
||||
- 需求 16“代理分销码与佣金提现”已移出 7 月迭代，后续独立立项。
|
||||
- 审批结论与退款、充值等业务处理结果分别建模和展示。
|
||||
- 审批详情必须展示业务快照、业务资料、历史意见和审批附件；业务资料与审批附件分开存储和展示。
|
||||
- 非代理钱包退款由财务人工处理；代理钱包退款仅回退原扣款代理主钱包。
|
||||
- 本次采用停机发布，不保留旧审批接口兼容窗口。
|
||||
|
||||
本目录按 [技术方案评审规范](../技术方案评审规范.md) 整理。当前范围为 21 项实施需求，需求 16 仅保留移出记录。评审建议按“基础设施 → 资金与审批 → 批量任务 → 展示类需求”分组。
|
||||
|
||||
---
|
||||
|
||||
## 二、评审材料导航
|
||||
|
||||
| 材料 | 作用 |
|
||||
|------|------|
|
||||
| [DDD 规范](./DDD规范.md) | 判断复杂写、简单写和 Query 通道，以及旧模块如何渐进迁移 |
|
||||
| [前端技术方案](./前端技术方案.md) | 跨需求的页面、状态、轮询、权限和停机发布约定 |
|
||||
| [审批流](./基础设施/审批流.md) | 流程定义、实例、任务、状态机、并发、事件和业务接入 |
|
||||
| [站内消息](./基础设施/站内消息.md) | 审批和临期提醒的站内通知基础设施 |
|
||||
| [系统配置](./基础设施/系统配置.md) | C 端支付方式的受控动态配置 |
|
||||
| 各需求专项文档 | 业务规则、接口、数据改动和专项前端差异 |
|
||||
|
||||
---
|
||||
|
||||
## 三、系统上下文
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Admin[后台管理端] --> API[Junhong API]
|
||||
Client[C端 H5/公众号] --> API
|
||||
API --> PG[(PostgreSQL)]
|
||||
API --> Redis[(Redis)]
|
||||
API --> Gateway[Gateway]
|
||||
API --> Outbox[(Outbox)]
|
||||
Relay[Outbox Relay] --> Outbox
|
||||
Relay --> Asynq[Asynq]
|
||||
Asynq --> Worker[Worker]
|
||||
Worker --> Notification[站内消息]
|
||||
Worker --> Business[退款/充值/临期等业务处理器]
|
||||
Worker -. Phase 2 .-> WeCom[企业微信]
|
||||
```
|
||||
|
||||
关键边界：
|
||||
|
||||
- API 负责同步校验、事务提交和返回可追踪的业务状态。
|
||||
- Worker 负责通知、导出、批量任务和审批后的业务处理。
|
||||
- Gateway 是本迭代唯一已确认可以直接接入的外部业务系统。
|
||||
- 企业微信相关能力属于 Phase 2，不得阻塞 Phase 1 的站内审批闭环。
|
||||
|
||||
---
|
||||
|
||||
## 四、依赖关系
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
DDD[渐进式 DDD 规范]
|
||||
Config[系统配置]
|
||||
Notice[站内消息]
|
||||
Approval[通用审批流]
|
||||
Export[统一导出任务]
|
||||
|
||||
DDD --> Approval
|
||||
Notice --> Approval
|
||||
Approval --> R18[需求18 多人审批]
|
||||
Approval --> R20[需求20 退款审批]
|
||||
Approval --> R21[需求21 充值审批]
|
||||
Config --> R09[需求09 支付限制]
|
||||
Notice --> R22[需求22 临期提醒]
|
||||
Export --> R14[需求14 导出]
|
||||
Approval --> R14
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、阶段划分
|
||||
|
||||
| 阶段 | 范围 | 说明 |
|
||||
|------|------|------|
|
||||
| Phase 1 | 需求 1-22 中除需求16外的本系统和 Gateway 能力 | 必须形成站内闭环、人工可追踪和可回滚的后台流程 |
|
||||
| Phase 2 | 需求 18 APR-009、需求 22 EXP-003 | 企业微信审批/推送与状态同步，单独评审外部 API、安全和补偿策略 |
|
||||
|
||||
Phase 1 不建设 BPMN 全规范、拖拽流程设计器、任意回退、子流程和复杂规则引擎。
|
||||
|
||||
---
|
||||
|
||||
## 六、需求总览
|
||||
|
||||
### 6.1 简单改动
|
||||
|
||||
| # | 需求 | 文档 | 实现要点 |
|
||||
|---|------|------|----------|
|
||||
| 1 | 行业卡复机允许未实名 | [需求01](./需求01-复机实名规则.md) | 复机规则修正，无新状态 |
|
||||
| 3 | 店铺列表加联系电话搜索 | [需求03](./需求03-07-11-12-13-简单改动.md#需求03店铺列表搜索新增联系电话) | Query 增加过滤条件 |
|
||||
| 4 | 退款中资产禁止换货 | [需求04](./需求04-06-退款拦截与最后到期时间.md#需求04退款中禁止换货) | 创建换货前校验活跃退款 |
|
||||
| 7 | IoT卡/设备加实名筛选 | [需求07](./需求03-07-11-12-13-简单改动.md#需求07iot卡设备管理新增已实名未实名筛选) | 列表筛选和索引评估 |
|
||||
| 11 | 当前套餐到期高亮 | [需求11](./需求03-07-11-12-13-简单改动.md#需求11资产详情-套餐到期时间字段--15天高亮) | 复用后端日期字段，前端统一颜色规则 |
|
||||
| 12 | 换货显示修复 | [需求12](./需求03-07-11-12-13-简单改动.md#需求12换货管理显示修复) | 字段和检索口径对齐 |
|
||||
| 13 | 列表字段新增 | [需求13](./需求03-07-11-12-13-简单改动.md#需求13列表字段新增) | 审批人改为动态摘要 |
|
||||
|
||||
简单改动不要求单独绘制系统图；涉及条件分支时用短流程图或规则表即可。
|
||||
|
||||
### 6.2 标准方案
|
||||
|
||||
| # | 需求 | 文档 | 关键评审点 |
|
||||
|---|------|------|------------|
|
||||
| 2 | H5流程顺序配置化 | [需求02](./需求02-H5流程配置.md) | 资产视角、配置优先级、C端跳转 |
|
||||
| 5 | 套餐分配生效条件 | [需求05](./需求05-套餐分配生效条件.md) | 覆盖值到使用记录的快照链 |
|
||||
| 6 | 资产最后到期时间 | [需求06](./需求04-06-退款拦截与最后到期时间.md#需求06资产详情-所有套餐的最后到期时间) | Query 聚合与排队套餐口径 |
|
||||
| 8 | 设备批量分配 Excel | [需求08](./需求08-设备批量分配Excel.md) | 异步任务、部分成功、失败明细 |
|
||||
| 9 | C端支付限制配置化 | [需求09](./需求09-C端支付限制配置化.md) | 前端隐藏与后端强校验一致 |
|
||||
| 10 | 限速规则 | [需求10](./需求10-限速规则.md) | 手动卡限速、`kbps` 单位和 Gateway 审计 |
|
||||
| 14 | 导出功能 | [需求14](./需求14-导出功能.md) | 复用 ExportTask、动态字段权限 |
|
||||
| 15 | 下架套餐允许续费 | [需求15](./需求15-16-18-19-20-21-复杂需求.md#需求15套餐下架后允许续费) | 续费身份和历史使用判断 |
|
||||
| 22 | 套餐临期提醒 | [需求22](./需求22-套餐临期提醒.md) | 15/7/3 天规则、去重、三端展示 |
|
||||
|
||||
### 6.3 完整方案
|
||||
|
||||
| # | 需求 | 文档 | 关键评审点 |
|
||||
|---|------|------|------------|
|
||||
| 17 | 信用额度 | [需求17](./需求17-信用额度.md) | 钱包不变量、主体模型、角色权限 |
|
||||
| 18 | 多人审批 | [需求18](./需求15-16-18-19-20-21-复杂需求.md#需求18多人审批apr-001009) | 动态审批人、串行节点、通知 |
|
||||
| 19 | 批量订购套餐 | [需求19](./需求15-16-18-19-20-21-复杂需求.md#需求19批量订购套餐bpo-001008) | 逐行审计、钱包幂等、部分成功 |
|
||||
| 20 | 退款审批 | [需求20](./需求15-16-18-19-20-21-复杂需求.md#需求20退款审批) | 审批与实际退款的最终一致性 |
|
||||
| 21 | 充值审批 | [需求21](./需求15-16-18-19-20-21-复杂需求.md#需求21充值审核流程) | 审批与钱包入账分离、停机切换旧接口 |
|
||||
|
||||
### 6.4 已移出本期
|
||||
|
||||
| # | 需求 | 状态 | 后续处理 |
|
||||
|---|------|------|----------|
|
||||
| 16 | 代理分销码与佣金提现 | 2026-07-14 移出 7 月迭代 | 独立立项，重新评审范围、技术方案和工时 |
|
||||
|
||||
---
|
||||
|
||||
## 七、跨需求技术决策
|
||||
|
||||
- 架构迁移按完整用例触碰式进行，禁止一次性重构旧模块。
|
||||
- 管理端 API 使用 `/api/admin/*`，C 端 API 使用 `/api/c/v1/*`。
|
||||
- 复杂查询进入 Query 模块，不通过聚合根拼装报表或导出。
|
||||
- 审批人只支持角色或指定账号，当前系统不引入部门模型。
|
||||
- 审批完成事件使用 Outbox + Asynq，通知和业务处理均按至少一次投递设计。
|
||||
- 导入、批量购买和导出必须有服务端任务状态，前端轮询只是展示手段。
|
||||
- 资金、审批、导出和敏感配置必须记录操作人和审计信息。
|
||||
- 信用额度只属于代理主钱包；平台员工是操作主体，不是结算和负债主体。
|
||||
- 批量订购支付方式整批统一；线下支付按整批上传凭证，代理钱包按整批选择代理钱包。
|
||||
- 角色管理必须提供导出字段配置，导出请求字段与角色授权字段取交集。
|
||||
- 限速最终目标始终是卡，Gateway 请求只传 `cardNo`；设备入口必须解析当前绑定卡，本期仅手动设置或取消。
|
||||
- 退款和员工线下充值统一通过任务级审批接口处理。
|
||||
- 审批状态与实际退款、钱包入账等处理状态分别返回；审批详情返回业务快照、业务资料和审批时间线。
|
||||
- 本次停机发布并同时切换 API、Worker 和前端，不建设旧审批接口兼容门面。
|
||||
|
||||
---
|
||||
|
||||
## 八、已确认技术决策
|
||||
|
||||
| 编号 | 已确认结论 | 影响需求 |
|
||||
|------|------------|----------|
|
||||
| D-01 | 不实现平台员工信用额度，只保留代理主钱包授信 | 17、19 |
|
||||
| D-02 | 角色级导出字段配置本期落地，服务端执行字段授权 | 14 |
|
||||
| D-03 | 批量订购支付方式整批统一，不允许 Excel 行级混合支付 | 19 |
|
||||
| D-04 | Gateway 限速统一按 `cardNo`；设备套餐取 `tb_device_sim_binding.is_current=true` 对应卡 | 10 |
|
||||
| D-05 | 审批结论和实际业务处理状态分离 | 20、21 |
|
||||
| D-06 | 采用停机发布，旧退款审批和线下充值直接入账/驳回接口同步下线 | 20、21 |
|
||||
| D-07 | 需求16移出本期，不创建相关表、接口、流程和前端页面 | 16 |
|
||||
| D-08 | 第三方退款本期由财务人工完成；代理钱包仅回退原扣款代理主钱包，客户资产钱包不走自动回退 | 20 |
|
||||
| D-09 | 设备批量分配代理与套餐系列拆为两个命令和两个前端入口 | 8 |
|
||||
| D-10 | 当前套餐与排队主套餐按购买时长快照推算预计最后到期时间；临期页面实时查询，定时任务只做通知 | 06、22 |
|
||||
|
||||
前端源码不在当前仓库。接口评审后仍需在前端仓库完成路由、权限指令、上传组件、任务轮询组件和动态表格能力的实现映射，但这不再是业务方案决策项。
|
||||
|
||||
---
|
||||
|
||||
## 九、发布与回滚总策略
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
S[进入维护模式并停止写入] --> M[执行数据库迁移]
|
||||
M --> D[同时发布 API、Worker 和前端]
|
||||
D --> C[初始化流程定义和业务绑定]
|
||||
C --> L[回填存量待审批单]
|
||||
L --> V[人工验证核心链路]
|
||||
V --> O[开放系统访问]
|
||||
```
|
||||
|
||||
发布原则：
|
||||
|
||||
1. 发布前进入维护模式，停止创建订单、退款、充值和审批操作。
|
||||
2. 维护窗口内执行数据库迁移，并同时发布 API、Worker/Relay 和前端静态资源。
|
||||
3. 初始化并发布 `refund_approval`、`recharge_approval`，完成业务绑定后再验证。
|
||||
4. 使用一次性 Application 命令为存量待审批退款和员工线下充值创建流程实例；历史终态记录保持只读，不伪造审批时间线。
|
||||
5. 旧退款业务单审批接口和线下充值 `offline-pay/reject` 在新版本中不再注册，不保留兼容门面。
|
||||
6. 人工验证发起审批、存量审批、任务处理、业务回调、通知和查询后再开放访问。
|
||||
7. 开放前验证失败可回滚应用版本和可逆迁移；已经形成的审批历史、资金流水、Outbox 和审计日志不得通过清表回滚。
|
||||
8. Worker 暂停时保留 Outbox 事件，恢复后继续消费。
|
||||
|
||||
---
|
||||
|
||||
## 十、可观测性与人工验收
|
||||
|
||||
关键日志和查询维度：
|
||||
|
||||
- `request_id`、`event_id`、`task_id`、`process_instance_id`、`biz_type`、`biz_id`。
|
||||
- Outbox 待投递数量、失败次数和最早积压时间。
|
||||
- 审批业务处理失败、批量任务失败和导出任务失败。
|
||||
- 钱包扣款前后余额、版本冲突和业务幂等键。
|
||||
|
||||
人工验收至少覆盖：
|
||||
|
||||
- 正常路径、无权限、重复点击、并发审批、退回重提。
|
||||
- Worker 暂停后恢复，事件和任务可继续处理。
|
||||
- 维护模式下不能产生新写入；开放前确认 API、Worker 和前端版本一致。
|
||||
- 所有仍需审批的存量退款和员工线下充值均已生成流程实例，历史终态记录只读可查。
|
||||
- 旧退款审批和线下充值 `offline-pay/reject` 路由不可访问。
|
||||
- PostgreSQL 中业务状态、审批状态、任务状态、操作日志和资金流水一致。
|
||||
|
||||
---
|
||||
|
||||
## 十一、执行顺序建议
|
||||
|
||||
```text
|
||||
评审批次 A：DDD 边界、系统配置、站内消息、审批流
|
||||
评审批次 B：退款、充值、信用额度、批量订购、导出权限
|
||||
评审批次 C：H5 流程、限速、临期提醒、批量分配
|
||||
评审批次 D：简单字段、筛选和显示修复
|
||||
|
||||
实施顺序：
|
||||
1. 增量迁移、TxManager/Outbox、系统配置和站内消息
|
||||
2. 审批定义、实例、任务和前端待办
|
||||
3. 退款和充值接入通用审批
|
||||
4. 批量任务、代理信用额度和导出权限
|
||||
5. 其他中小需求
|
||||
```
|
||||
|
||||
每个评审批次独立形成结论，未通过的复杂需求不阻塞已经闭环的简单需求实施。
|
||||
57
docs/7月迭代/7月迭代前后端任务工时表.md
Normal file
57
docs/7月迭代/7月迭代前后端任务工时表.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# 7月迭代前后端任务工时表
|
||||
|
||||
> 估算口径：实现工作全权交由 AI 编码代理执行，前后端可并行推进。
|
||||
> 工时单位：人时，1 人日按 8 小时计算。
|
||||
> 包含：代码实现、迁移、接口调整、页面交互、联调修复、手工接口验证和发布准备。
|
||||
> 不包含：等待企微/支付配置、产品临时改需求、外部接口申请审核和生产历史脏数据人工处理时间。
|
||||
> 前提：提供后端仓库、前端仓库、可用数据库、Gateway、企微和支付联调配置；需求范围以标准评审稿为准。
|
||||
>
|
||||
> 禅道逐条录入时，使用[7月迭代禅道研发需求逐条录入稿](./7月迭代禅道研发需求逐条录入稿.md)中的拆分工时；本表用于核对总量，逐条录入稿用于填写每条研发需求的预计工时。
|
||||
|
||||
|需求|前端任务|后端任务|前端任务工时|后端任务工时|相关风险可能导致的工时延长|
|
||||
|---|---|---|---:|---:|---|
|
||||
|公共基础|补齐公共状态、错误展示和异步任务交互组件|增量迁移、Outbox、DDD 目录和公共幂等能力|1～2小时|4～5小时|现有迁移冲突、Outbox 基础与文档不一致会增加 2～4 小时|
|
||||
|需求01：复机实名规则|调整复机失败提示，不再按行业卡写死文案|按 `realname_link_type` 判断实名要求，删除行业卡统一放行逻辑|0.5～1小时|1小时|运营商历史配置错误会增加数据修复时间|
|
||||
|需求02：H5 流程配置|按有效实名策略渲染先实名/先购买流程，补批量配置交互|统一运营商实名能力和资产顺序策略，补批量更新接口|2～3小时|3～4小时|前端现有 H5 状态机分散、冲突数据较多会增加 2～4 小时|
|
||||
|需求03：联系电话搜索|店铺列表增加联系电话搜索框|店铺 Query 增加 11 位联系电话精确过滤|0.5～1小时|0.5～1小时|现有列表参数命名不统一会增加约 1 小时|
|
||||
|需求04：退款中禁止换货|直接展示后端拦截原因|创建换货前批量校验活跃退款状态|0.5～1小时|1～1.5小时|历史退款状态语义不一致会增加 1～2 小时|
|
||||
|需求05：套餐分配生效条件|增加默认/购买生效/实名生效三选一及恢复默认|增加代理覆盖值和使用记录快照，统一生效条件计算|1.5～2.5小时|2.5～3.5小时|旧使用记录缺快照、套餐周期数据异常会增加 2～4 小时|
|
||||
|需求06/11：预计最终到期时间|资产层只展示预计最终到期时间、推算状态和统一高亮|Query 按当前及排队主套餐时长快照推算，供详情、临期和导出复用|1.5～2.5小时|3～4小时|旧套餐缺购买时长快照、等待实名激活无法确定起点会增加兼容处理时间|
|
||||
|需求07：实名筛选|卡和设备列表增加实名状态筛选|卡按自身状态，设备按有效绑定卡维护/查询实名状态|1～2小时|2～3小时|设备多当前卡、绑定历史异常会增加 2～3 小时|
|
||||
|需求08：设备批量分配|拆分“分配代理”和“分配套餐系列”两个入口，展示任务结果|复用 Excel/Asynq，新增两个独立批量命令和失败明细|2～3小时|3～4小时|前端无现成上传任务组件或生产文件格式不统一会增加 2～4 小时|
|
||||
|需求09：C 端支付限制|支付页按接口返回方式展示，后台增加配置控件|实现受控系统配置、缓存和订单支付二次校验|1.5～2.5小时|2～3小时|多端支付入口未复用同一接口会增加逐端排查时间|
|
||||
|需求10：Gateway 限速|卡/设备详情增加设置和取消入口|统一 `speed_kbps` 接口，设备解析当前卡后调用 Gateway|1～2小时|2～3小时|Gateway 取消参数不明确或联调不稳定会增加 2～4 小时|
|
||||
|需求11：当前套餐到期高亮|并入需求06/22，不单独建设第二个资产汇总字段|并入预计最终到期 Query|0小时|0小时|无独立工时|
|
||||
|需求12：换货显示与搜索|拆分新旧资产搜索并修正字段展示|修正新建换货快照，增加新旧资产关键词过滤|1～2小时|1～2小时|历史数据不回填导致验收口径混淆会增加沟通时间|
|
||||
|需求13：列表字段新增|退款、充值、换货列表增加提交人和企微审批摘要|补提交人快照，批量查询企微状态和审批人摘要|1～2小时|2～3小时|旧记录缺提交人或企微实例会增加兼容展示时间|
|
||||
|需求14：导出与字段权限|角色页配置导出字段，各列表接入统一导出入口|扩展 DataSource 场景、角色字段权限和字段快照|3～4小时|4～6小时|导出字段口径变更、现有数据源 N+1 会增加 3～5 小时|
|
||||
|需求15：下架套餐续费|当前套餐旁增加续费按钮，复用购买流程|统一可售策略，校验资产所有人及历史使用资格|1.5～2.5小时|2～3小时|C 端多个购买入口绕过统一策略会增加排查时间|
|
||||
|需求16：代理分销码与佣金提现|不实施|不实施|0小时|0小时|需求重新加入时必须单独评估，不计入本表|
|
||||
|需求17：代理主钱包信用额度|角色页配置新建店铺默认额度，店铺资金页单独调额并明确不追溯|增加角色默认模板、钱包实际额度、约束、扣款不变量和资金审计|2.5～3.5小时|4～5小时|现有负余额、CHECK 约束或创建店铺事务分散会增加 2～5 小时|
|
||||
|需求18：多人审批映射|不建设本地待办，只展示企微审批摘要|退款/充值场景映射到企微模板，复用企微状态同步|1～1.5小时|1～1.5小时|企微模板审批人配置不完整会阻塞联调|
|
||||
|需求19：批量订购套餐|批量上传、统一支付方式、任务进度和失败明细|任务/明细表、逐行幂等下单、钱包或线下支付处理|3～4小时|4～6小时|订单服务复用困难、钱包并发冲突会增加 3～6 小时|
|
||||
|需求20：退款审批|创建和详情展示企微状态、意见附件及处理结果|退款接入企微、代理钱包回溯、人工退款终态和撤销异常|2.5～3.5小时|4～5小时|存量退款买家类型混乱、通过后撤销场景会增加 3～5 小时|
|
||||
|需求21：平台员工线下充值|创建后展示企微审批状态，删除本地确认/驳回按钮|企微通过后幂等增加代理主钱包，旧接口下线|2～3小时|3～4小时|旧充值状态和钱包流水不一致会增加 2～4 小时|
|
||||
|需求22：套餐临期提醒|资产列表、详情、临期页、代理首页和 C 端展示；仅临期页将3天内置顶|复用预计最终到期 Query、15/7/3 天站内通知防重和导出接入|3～4.5小时|4～6小时|时区、排队套餐快照和多接收人数据异常会增加 2～4 小时|
|
||||
|禅道#98/#86：换货归属与资产标识|换货确认展示继承店铺，资产详情展示前代/后代标签和跳转|新资产继承旧资产店铺、保留旧资产归属、补换货链 Query 和索引|1～2小时|2～3小时|换货迁移涉及的租户标签或资产分配记录不完整会增加 2～4 小时|
|
||||
|禅道#96/#97：业务员与余额提醒|店铺业务员选择/筛选、资金不足100元状态和通知跳转|增加店铺业务员字段，钱包跨越固定100元阈值时向主账号和业务员发站内通知|1～2小时|2～3小时|店铺主账号异常、业务员停用或钱包写入口未统一会增加 2～4 小时|
|
||||
|禅道#43：系列套餐批量授权|套餐表格多选、已授权置灰、三类价格展示|复用现有批量写接口，新增套餐候选 Query 和重复授权幂等|1～2小时|0.5～1小时|前端旧页面结构不支持表格多选或成本价权限不完整会增加 1～3 小时|
|
||||
|新增01：数据同步触发与轮询优化|展示轮询活跃状态和审计跳转|卡状态领域收口、活跃调频、0/3/5 任务、回调防腐层|2～3小时|7～9小时|旧同步入口数量超出预期、Gateway 超频和 ICCID 重复会增加 4～8 小时|
|
||||
|新增02：企业微信审批接入|企微配置、模板映射、扫码绑定、审批运行和业务详情|Token、模板版本、上传提交、回调解密、轮询补偿和异常恢复|5～7小时|8～10小时|企微可信域名、模板 ID 变化、回调网络和真实账号权限会增加 4～8 小时|
|
||||
|新增03：站内通知|顶部铃铛、通知抽屉、通知中心和受控跳转|通知表、模板注册、接收人解析、未读/已读 API|3～4小时|3～4小时|前端多端布局差异、接收人关系不完整会增加 2～3 小时|
|
||||
|新增04：全局多视角审计|审计中心七个视角、详情抽屉和敏感字段展示|Audit Event、Integration Log、旧写入口切换、历史投影和脱敏|6～8小时|8～11小时|旧审计调用点遗漏、查询性能和历史字段差异会增加 5～10 小时|
|
||||
|新增05：代理钱包扫码充值|支付方式选择、二维码、倒计时和支付状态轮询|微信 Native、支付宝 PreCreate、支付单分发和钱包入账恢复|3～4小时|5～7小时|支付渠道配置、真实回调、微信 v2/富友差异会增加 3～6 小时|
|
||||
|全链路联调与发布|联调全部页面状态、修复交互、准备发布版本|数据核对、存量回填、旧入口清理、停机发布和恢复检查|3～4小时|4～5小时|生产数据与预期差异、外部回调不可达会增加 4～8 小时|
|
||||
|**合计**|**前端约 59～89 小时**|**后端约 93～128 小时**|**约 8～12 人日**|**约 12～16 人日**|**1 后端 + 1 前端并行时，正常目标 12～15 个工作日；历史数据或换货迁移超预期时可能到 16 个工作日**|
|
||||
|
||||
## 并行交付口径
|
||||
|
||||
| 项目 | 估算 |
|
||||
|------|------|
|
||||
| 前端投入 | 59～89 小时，约 8～12 人日 |
|
||||
| 后端投入 | 93～128 小时，约 12～16 人日 |
|
||||
| 合计投入 | 152～217 小时，约 19～28 人日 |
|
||||
| 1 后端 + 1 前端并行周期 | 正常 12～15 个工作日，风险上限 16 个工作日 |
|
||||
| 建议对外排期基线 | 14 个工作日 |
|
||||
|
||||
达到第 16 个工作日的主要条件：前端旧授权页面无法复用、换货归属需要补齐多张租户标签表、生产历史数据需要大规模人工修复、企微或支付联调配置不可用。
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,13 +1,13 @@
|
||||
# 7月迭代技术方案（标准评审稿）
|
||||
|
||||
> 状态：待评审
|
||||
> 最后更新：2026-07-15
|
||||
> 最后更新：2026-07-17
|
||||
> 分支：`Iteration/7-11`
|
||||
> 系统：`junhong_cmp_fiber` 及配套后台、代理端、C 端前端
|
||||
> 负责人：待指定
|
||||
> 评审人：后端、前端、产品、验收负责人、运维
|
||||
> 关联需求：7月迭代需求 01～22（需求16已移出）及新增的数据同步、企微审批、站内通知、全局审计、代理钱包扫码充值
|
||||
> 说明：本文是技术评审主文档；完整版和专项文档保留为设计素材，不作为会议逐页评审内容。
|
||||
> 关联需求：7月迭代需求 01～22（需求16已移出）、禅道补充需求 #43/#86/#96/#97/#98，以及新增的数据同步、企微审批、站内通知、全局审计、代理钱包扫码充值
|
||||
> 说明：本文是唯一技术评审主文档；`独立方案/` 和 `来源材料/` 仅用于实施细节与方案溯源。
|
||||
|
||||
---
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
|
||||
当前退款、线下充值审批各自维护，卡实名、流量和网络状态又被轮询、手动刷新及业务操作分别写入，容易出现同一业务动作只更新部分状态。现有账号和资产审计也没有统一模型，无法按人员、资源、请求、资金链路和外部交互追踪。复杂资金和状态业务仍集中在旧 Service 中，配置、批量任务、通知和导出权限缺少统一契约。
|
||||
|
||||
本次评审覆盖原需求 01～22（需求16移出）及五项新增技术需求，主要解决以下问题：
|
||||
本次评审覆盖原需求 01～22（需求16移出）、禅道补充需求 #43/#86/#96/#97/#98 及五项新增技术需求，主要解决以下问题：
|
||||
|
||||
- 退款和平台员工线下充值直接接入企业微信审批，本系统只维护业务快照、审批状态镜像和终态处理。
|
||||
- 将卡实名、流量和网络状态写入收口到统一 DDD 用例，以轮询兜底、业务事件阶梯触发和运营商回调提高同步及时性。
|
||||
@@ -25,6 +25,7 @@
|
||||
- 补齐代理后台微信/支付宝扫码充值，在线支付成功后直接幂等入代理主钱包，不进入审批。
|
||||
- 将信用额度、批量订购、退款和充值中的资金规则收敛为可并发校验的不变量。
|
||||
- 补齐异步任务、站内消息、动态配置、导出字段权限和 Gateway 限速等基础能力。
|
||||
- 补齐换货归属继承与资产换货链、店铺业务员、固定余额预警和代理系列套餐批量授权。
|
||||
- 统一后台、代理端和 C 端的页面状态、异步反馈和异常展示。
|
||||
- 在不一次性重构旧系统的前提下，按完整用例渐进迁移 DDD。
|
||||
|
||||
@@ -40,6 +41,7 @@
|
||||
- 后端提供 Excel 模板下载接口；模板由前端静态资源随版本发布。
|
||||
- 微信/支付宝自动退款，以及基于套餐规则的自动限速。
|
||||
- 运营商解除实名后自动回滚本地实名状态；第一版只保留防腐层入口和集成记录。
|
||||
- 禅道草稿 #41“代理查询限制”和 #51“不同品类资产换货”；草稿不进入本期开发、工时和验收。
|
||||
|
||||
### 1.3 已确认决策
|
||||
|
||||
@@ -58,12 +60,18 @@
|
||||
| D-11 | 采用停机发布，同时切换数据库、API、Worker 和前端，旧审批接口同步下线 | 20、21 |
|
||||
| D-12 | 企微模板 ID 和控件 ID 均按不可变版本映射；编辑模板前暂停场景，发布新映射后原子切换 | 企微审批 |
|
||||
| D-13 | 设备批量分配代理与套餐系列拆为两个独立命令 | 08 |
|
||||
| D-14 | 排队套餐使用购买时长快照推算预计最后到期时间；临期页面实时查询，定时任务仅发送通知 | 06、22 |
|
||||
| D-14 | 排队套餐使用购买时长快照推算预计最终到期时间；资产详情、临期和导出共用实时 Query，定时任务仅发送通知 | 06、11、22 |
|
||||
| D-15 | 行业卡是否需要实名由运营商 `realname_link_type` 决定，`card_category` 不参与实名、复机和轮询判断 | 01、02、数据同步 |
|
||||
| D-16 | 数据同步保留轮询兜底，关键业务事件按立即、3 分钟、5 分钟触发；超频不建立退避状态 | 数据同步 |
|
||||
| D-17 | 企微账号由已登录平台员工扫码自助绑定，普通运营不录入 `userid` | 企微审批 |
|
||||
| D-18 | 全系统审计本次一次性切换到 Audit Event + Integration Log，多视角 API 和前端同时发布 | 全局 |
|
||||
| D-19 | 代理在线充值最低 100 元，支持微信 Native 和支付宝 PreCreate，支付成功直接入主钱包且不审批 | 21、新增充值 |
|
||||
| D-20 | 资产层只展示一个预计最终到期时间；当前套餐和全部排队主套餐共同参与推算，临期也使用同一结果 | 06、11、22 |
|
||||
| D-21 | 换货完成时新资产自动继承旧资产店铺；旧资产保留原店铺用于历史查询和权限追踪 | 禅道 #98 |
|
||||
| D-22 | 店铺可选绑定一个平台业务员；该字段只表达业务归属，不恢复需求16的分销和佣金关系 | 禅道 #96 |
|
||||
| D-23 | 代理主钱包现金可用余额降至 100 元及以下时，向代理主账号和店铺业务员发送一次站内通知；信用额度不参与预警计算 | 禅道 #97 |
|
||||
| D-24 | 客户角色只提供新建店铺的默认信用配置；修改角色配置不更新任何已有店铺，已有店铺额度只能单独调整 | 17 |
|
||||
| D-25 | 代理系列套餐授权复用现有批量接口；前端批量选择，已授权套餐明确标记并置灰 | 禅道 #43 |
|
||||
|
||||
### 1.4 本期边界
|
||||
|
||||
@@ -115,9 +123,9 @@ flowchart LR
|
||||
|
||||
| 场景 | 选择 | 判断依据 |
|
||||
|------|------|----------|
|
||||
| 钱包扣款、授信、卡状态应用、退款状态转换 | Domain | 有不变量、状态机、并发或跨表一致性 |
|
||||
| 单字段修改、简单开关、局部 CRUD | Application 事务脚本 | 规则少且不会形成复杂状态 |
|
||||
| 列表、报表、导出、跨聚合详情 | Query | 只读、字段多、需要 JOIN/聚合/分页 |
|
||||
| 钱包扣款、授信、换货完成、卡状态应用、退款状态转换 | Domain | 有不变量、状态机、并发或跨表一致性 |
|
||||
| 店铺业务员、角色默认额度、简单开关、局部 CRUD | Application 事务脚本 | 规则少且不会形成复杂状态 |
|
||||
| 系列套餐候选、换货链、列表、报表、导出、跨聚合详情 | Query | 只读、字段多、需要 JOIN/聚合/分页 |
|
||||
| 未被本次用例触碰的旧逻辑 | 保持旧架构 | 避免扩大认知和回归范围 |
|
||||
|
||||
站内消息只是幂等写入和已读状态管理，采用轻量 Application/Infrastructure 即可，不为满足目录形式强行创建空洞聚合。
|
||||
@@ -529,6 +537,10 @@ POST /api/admin/audit/exports
|
||||
| 站内消息 | `/notifications` | 未读数、列表、已读和受控业务跳转 |
|
||||
| 全局审计 | `/operations/audit` | 全局、人员、资源、链路、资金、风险和外部集成多视角 |
|
||||
| 系统配置 | `/settings/system-config` | 受控单选、复选和开关 |
|
||||
| 店铺管理 | 现有店铺创建、编辑、列表和详情 | 平台业务员绑定、业务员筛选和信用额度来源展示 |
|
||||
| 代理资金概况 | 现有资金页面 | 固定 100 元余额预警、角色默认额度和店铺单独调额 |
|
||||
| 代理系列授权 | 现有系列授权创建和详情页 | 套餐候选批量选择、已授权标记和不可重复选择 |
|
||||
| 资产详情 | 现有卡/设备详情页 | 预计最终到期时间、换货前代/后代标识和受控跳转 |
|
||||
| 异步任务 | 复用各业务页面 | 导入、批量订购、导出进度和失败明细 |
|
||||
|
||||
全局状态只保存登录用户、权限和通知未读数。列表、详情和表单草稿保留在页面或模块级状态，避免复制服务端状态后长期失真。
|
||||
@@ -606,9 +618,8 @@ stateDiagram-v2
|
||||
| 需求 01 行业卡复机 | 是否要求实名只看运营商 `realname_link_type`；`none` 可未实名复机，`template/gateway` 仍需实名 | 删除按 `card_category=industry` 放行或跳过实名的逻辑，复用卡状态领域规则 | 验证同为行业卡但不同运营商实名能力时行为不同，卡类别不再影响结果 |
|
||||
| 需求 03 联系电话搜索 | 店铺联系电话 11 位精确查询 | 店铺列表 Query 增加 `contact_phone` | 增加搜索框；空参数不影响原查询，非法号码返回参数错误 |
|
||||
| 需求 04 退款中禁止换货 | 企微审批中、历史已退回、企微已通过但退款终态未完成的资产禁止换货；已拒绝、已撤销或退款完成后放行 | 创建换货前批量校验活跃退款，返回“该资产存在退款申请” | 前端直接展示后端错误，不自行判断退款状态 |
|
||||
| 需求 06 最后到期时间 | 返回当前生效及排队主套餐全部接续后的预计最终到期时间 | 资产详情 Query 按队列顺序使用购买时长快照推演；无套餐返回 `null` | 文案使用“预计最后到期时间”，实时查询，不保存冗余结果 |
|
||||
| 需求 06/11 套餐到期时间 | 资产层只展示当前生效及排队主套餐全部接续后的预计最终到期时间；当前套餐自身到期时间只保留在套餐明细 | 资产详情 Query 按队列顺序使用购买时长快照推演；无套餐返回 `null`，等待未知实名激活时返回不可预计状态 | 文案使用“预计套餐到期时间”；高亮和临期统一使用最终剩余天数，不维护第二套资产汇总字段 |
|
||||
| 需求 07 实名筛选 | 卡按自身实名状态；设备任一有效绑定卡实名即视为设备实名 | 设备增加 `real_name_status` 快照；实名变化、绑定、解绑、换卡均刷新旧/新设备 | 卡和设备列表增加全部/已实名/未实名筛选 |
|
||||
| 需求 11 当前套餐到期 | 统一并入需求 22 的剩余天数和颜色规则 | 不再单独维护第二套计算 | 资产详情直接使用需求 22 字段 |
|
||||
| 需求 12 换货显示与搜索 | 卡的新旧资产标识统一快照 ICCID；设备维持设备号；历史数据不回填 | 创建快照逻辑修正；列表增加 `old_asset_keyword/new_asset_keyword`，支持 ICCID、接入号、虚拟号 | 搜索框拆为旧资产和新资产；验收大结果集查询性能 |
|
||||
| 需求 13 列表字段 | 提交人写业务快照；企微审批摘要动态读取 | 换货、退款、充值增加 `submitter_name`；按本页企微实例批量查询状态和审批人摘要，禁止 N+1 | 展示企微状态、当前审批人摘要、处理状态和历史审批标识 |
|
||||
| 需求 15 下架套餐续费 | 禁用套餐始终不可购买；下架套餐只允许资产所有人基于有效历史使用记录续费，禁止代理代购 | 复用统一套餐可售策略；后端根据资产和登录主体判定续费资格 | C 端当前套餐旁展示“续费”，复用购买流程；新购入口隐藏，后台代购禁用 |
|
||||
@@ -802,23 +813,24 @@ PUT /api/admin/roles/{role_id}/export-fields
|
||||
- Count 和 Fetch 必须使用相同权限及查询条件。
|
||||
- 退款和充值审批摘要按本批实例批量查询，禁止 N+1。
|
||||
- 导出审批附件只输出数量，不输出对象 Key 或永久 URL。
|
||||
- `scene=iot_card` 支持按预计最终到期时间筛选 30 天内资产；该导出条件独立于页面 15 天临期定义，复用需求 06/11/22 的最终到期 Query。
|
||||
|
||||
### 5.8 需求 22：套餐临期提醒
|
||||
|
||||
临期定义：按 `Asia/Shanghai` 自然日计算，当前生效套餐剩余 `0～15` 天，且资产没有可接续排队套餐。已过期资产不按 0 天计入临期。需求 06、11、22 共用查询侧日期计算，但需求06另行推算排队套餐接续后的预计最后到期时间。
|
||||
临期定义：按 `Asia/Shanghai` 自然日计算，资产当前生效主套餐与全部排队主套餐连续接续后的**预计最终剩余天数**为 `0～15` 天。已过期资产不按 0 天计入临期；没有生效套餐且队首仍等待无法确定时间的实名激活时，不伪造到期日期，也不进入临期。需求 06、11、22 共用同一个最终到期 Query。
|
||||
|
||||
| 剩余天数 | 展示颜色 | 通知节点 |
|
||||
|----------|----------|----------|
|
||||
| 8～15 天 | 粉红色 | 15 天 |
|
||||
| 4～7 天 | 紫色 | 7 天 |
|
||||
| 0～3 天 | 黄色 | 3 天 |
|
||||
| 0～3 天 | 红色 | 3 天 |
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Schedule[每日定时任务] --> Query[批量查询实时临期候选]
|
||||
Query --> Queue{存在排队套餐?}
|
||||
Queue -->|是| Skip[不临期、不通知]
|
||||
Queue -->|否| Days[计算剩余自然日]
|
||||
Schedule[每日定时任务] --> Query[计算预计最终到期时间]
|
||||
Query --> Predictable{可以推算?}
|
||||
Predictable -->|否| Skip[不临期、不通知]
|
||||
Predictable -->|是| Days[计算最终剩余自然日]
|
||||
Days --> Node{存在最近未发送阈值?}
|
||||
Node -->|是| Notify[按使用记录+节点+接收人幂等通知]
|
||||
Node -->|否| End[结束]
|
||||
@@ -826,13 +838,87 @@ flowchart TD
|
||||
|
||||
后端：
|
||||
|
||||
- 卡/设备列表和详情增加 `days_until_expiry`、`is_expiring`。
|
||||
- 卡/设备列表和详情增加 `estimated_final_expires_at`、`days_until_final_expiry`、`expiry_estimate_status`、`is_expiring`。
|
||||
- 列表、详情、临期页、代理首页和 C 端均实时 SQL 计算，不读取每日任务快照，也不需要前端轮询临期状态。
|
||||
- 新增 `GET /api/admin/expiring-assets`，支持资产、套餐、店铺、到期范围和剩余天数筛选。
|
||||
- 临期独立列表固定将 `0～3` 天资产置顶，再按预计最终到期时间升序；普通卡/设备列表只高亮，不改变原排序。
|
||||
- 代理首页增加临期卡/设备数量。
|
||||
- C 端 `GET /api/c/v1/asset/info` 增加临期字段并提供续费入口。
|
||||
- 临期导出复用 `scene=expiring_asset`。
|
||||
- `tb_expiry_push_record` 从本期起按 `package_usage_id + recipient + channel + node` 防重；漏跑后只补发当前最近且尚未发送的阈值，避免一次补发多条旧通知。
|
||||
- 本期只发送站内通知，不发送企业微信临期消息；店铺业务员通过系统账号接收站内通知。
|
||||
|
||||
### 5.9 禅道补充需求：换货、业务员、余额预警和系列授权
|
||||
|
||||
#### 5.9.1 #98 换货新资产归属
|
||||
|
||||
- 新资产允许处于平台库存或已经属于旧资产店铺；如果已经属于其他店铺则拒绝换货。
|
||||
- 换货完成事务内先将新资产 `shop_id`、租户标签和资产分配记录切换为旧资产店铺，再迁移客户绑定、钱包/套餐资料并更新新旧资产状态。
|
||||
- 旧资产保留原 `shop_id`，状态改为已换货，确保原店铺仍可查看历史订单、退款和换货链。
|
||||
- 前端选择新资产后展示“完成后将归属：{旧资产店铺}”，不增加人工选择目标店铺的控件。
|
||||
- 换货完成是跨资产、客户绑定、钱包、套餐和状态的一致性用例，迁移到 `exchange` Domain；旧 Service 不再保留第二套完成逻辑。
|
||||
|
||||
#### 5.9.2 #86 资产详情换货标识
|
||||
|
||||
资产详情 Query 基于已完成换货单返回：
|
||||
|
||||
```json
|
||||
{
|
||||
"exchange_trace": {
|
||||
"previous_asset": null,
|
||||
"next_asset": {
|
||||
"asset_type": "iot_card",
|
||||
"asset_id": 2002,
|
||||
"identifier": "89860...",
|
||||
"exchange_no": "EXC202607170001"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 存在 `previous_asset` 时显示“换货新资产”；存在 `next_asset` 时显示“已换出旧资产”。链路中间资产可以同时存在前代和后代。
|
||||
- 关联资产仍需通过后端数据权限校验；无权限时只显示标识，不返回可跳转的资产 ID。
|
||||
- 复用 `tb_exchange_order`，不新建换货关系表；补充旧资产查询已完成换货和新资产查询索引。
|
||||
|
||||
#### 5.9.3 #96 店铺业务员
|
||||
|
||||
- `tb_shop` 增加可空 `business_owner_account_id`，只允许绑定启用的平台账号。
|
||||
- 创建、编辑、列表、详情和筛选接口返回业务员 ID、账号名和手机号摘要。
|
||||
- 业务员仅表示店铺业务归属和通知接收关系，不参与店铺层级、数据权限、佣金或分销关系计算。
|
||||
- 业务员停用或删除后保留店铺字段和历史审计，通知时跳过不可用账号；运营可重新绑定。
|
||||
|
||||
#### 5.9.4 #97 固定 100 元钱包余额预警
|
||||
|
||||
预警阈值固定为 `10000` 分，不提供系统配置、角色配置或店铺配置：
|
||||
|
||||
```text
|
||||
cash_available = balance - frozen_balance
|
||||
变动前 cash_available > 10000
|
||||
变动后 cash_available <= 10000
|
||||
=> 发送一次低余额站内通知
|
||||
```
|
||||
|
||||
- 信用额度不参与余额预警，避免授信掩盖代理现金不足。
|
||||
- 接收人是店铺主账号和可用的店铺业务员；站内通知使用稳定业务键防重。
|
||||
- 余额回升到 100 元以上后重新布防，再次跌破时可重新通知；持续低于阈值的连续扣款不重复提醒。
|
||||
- 资金概况只展示“现金余额不足 100 元”状态，不提供阈值编辑控件。
|
||||
- 钱包聚合在余额变更后产生低余额领域事件，事务内写 Outbox；通知失败不能回滚资金事务。
|
||||
|
||||
#### 5.9.5 #43 代理系列套餐批量授权
|
||||
|
||||
现有 `PUT /api/admin/shop-series-grants/{id}/packages` 已接受套餐数组，继续作为批量写接口。新增套餐候选 Query：
|
||||
|
||||
```text
|
||||
GET /api/admin/shop-series-grants/{id}/package-options
|
||||
```
|
||||
|
||||
返回 `package_id`、名称、编码、公司成本价、当前代理授权成本价、建议售价和 `is_authorized`。首次授权系列和后续管理套餐都使用同一候选列表：
|
||||
|
||||
- 已授权套餐显示“已授权”并置灰，不可重复选择。
|
||||
- 未授权套餐支持复选框多选并一次提交。
|
||||
- 后端对重复套餐按幂等处理，不能依赖前端置灰保证一致性。
|
||||
- `company_cost_price`、`authorized_cost_price` 和 `suggested_retail_price` 分字段返回，禁止继续使用含义不明确的单一 `cost_price` 展示。
|
||||
- 套餐候选属于 Query，批量授权属于轻量 Application 事务脚本，不为此创建空洞聚合。
|
||||
|
||||
---
|
||||
|
||||
@@ -842,13 +928,20 @@ flowchart TD
|
||||
|
||||
> 状态：2026-07-14 移出 7 月迭代
|
||||
|
||||
本期不建设分销码、H5 代理申请、代理申请审批、自动开店、发展人关系和佣金提现材料。本需求后续独立立项时重新评审数据模型、H5 安全、审批接入、开店幂等、提现材料和工时。
|
||||
本期不建设分销码、H5 代理申请、代理申请审批、自动开店、分销发展关系和佣金提现材料。禅道 #96 新增的店铺业务员字段只用于业务归属、筛选和通知，不产生分销层级或佣金关系。本需求后续独立立项时重新评审数据模型、H5 安全、审批接入、开店幂等、提现材料和工时。
|
||||
|
||||
本期审批流仅接入退款和平台员工线下充值；迁移、API、前端、发布及工时均不包含需求 16。
|
||||
|
||||
### 6.2 需求 17：代理主钱包信用额度
|
||||
|
||||
平台员工不是结算和负债主体，不建立员工钱包或信用额度。角色只表达权限，不能承载财务余额和债务。
|
||||
平台员工不是结算和负债主体，不建立员工钱包或信用额度。客户角色可以保存新建店铺的默认信用模板，但不能成为债务主体；真正参与资金计算的信用额度始终写入代理主钱包。
|
||||
|
||||
角色默认规则：
|
||||
|
||||
- 新建店铺时读取 `default_role_id` 的默认信用配置并初始化主钱包。
|
||||
- 修改角色默认信用配置只影响以后新建的店铺，不更新任何已有店铺。
|
||||
- 已有店铺通过独立资金接口直接修改实际额度，之后也不跟随角色变化。
|
||||
- 店铺后续增加其他角色不改变钱包信用额度，避免多角色组合影响资金事实。
|
||||
|
||||
#### 不变量
|
||||
|
||||
@@ -873,6 +966,15 @@ credit_enabled BOOLEAN NOT NULL DEFAULT FALSE
|
||||
credit_limit BIGINT NOT NULL DEFAULT 0
|
||||
```
|
||||
|
||||
`tb_role` 增加：
|
||||
|
||||
```text
|
||||
default_credit_enabled BOOLEAN NOT NULL DEFAULT FALSE
|
||||
default_credit_limit BIGINT NOT NULL DEFAULT 0
|
||||
```
|
||||
|
||||
角色字段仅允许客户角色使用。平台角色固定关闭；运行时扣款不 JOIN 角色表。
|
||||
|
||||
数据库 CHECK 至少保证：
|
||||
|
||||
```sql
|
||||
@@ -894,17 +996,20 @@ CHECK (
|
||||
|
||||
| 用例 | 规则 |
|
||||
|------|------|
|
||||
| 修改角色默认额度 | 只更新角色模板和审计，不扫描、不修改任何已有店铺钱包 |
|
||||
| 创建店铺 | 在创建事务中读取默认角色模板并初始化代理主钱包实际额度 |
|
||||
| 修改额度 | 校验权限、加载主钱包、校验新可用金额、按 `version` 条件更新、写信用变更审计 |
|
||||
| 钱包扣款 | 使用有效额度计算可用金额，同事务更新余额、版本和资金流水 |
|
||||
| 查询/导出 | Query 返回 `credit_enabled`、`credit_limit`、`available_balance`、`is_in_debt`、`debt_amount` |
|
||||
|
||||
```text
|
||||
POST /api/admin/shops 创建代理时可初始化信用配置
|
||||
PUT /api/admin/roles/{id}/default-credit 修改新建店铺默认信用模板
|
||||
PUT /api/admin/shops/{id}/credit-limit 独立调整信用额度
|
||||
GET /api/admin/shops/fund-summary 返回信用和可用金额
|
||||
```
|
||||
|
||||
前端只展示接口返回的可用金额，不自行重新计算。额度调整弹框显示修改前后金额预览；并发冲突时刷新最新钱包版本。
|
||||
角色页面显示“新建代理默认信用额度”，并明确提示“修改后不会影响已有店铺”。店铺资金页面独立显示和修改实际信用额度。前端只展示接口返回的可用金额，不自行重新计算；额度调整弹框显示修改前后金额预览，并发冲突时刷新最新钱包版本。
|
||||
|
||||
### 6.3 需求 18：多人审批业务映射
|
||||
|
||||
@@ -1129,8 +1234,11 @@ POST /api/admin/agent-recharges/{id}/reject
|
||||
| 修改 | `tb_polling_config` | 收口为全局活跃/不活跃间隔，不再按卡类别形成轮询资格 |
|
||||
| 修改 | `tb_iot_card.iccid_19` | 未删除数据范围 Partial Unique Index |
|
||||
| 修改 | `tb_shop_package_allocation`、`tb_package_usage` | 生效条件、周期和时长快照 |
|
||||
| 修改 | `tb_exchange_order` | 提交人快照；新建记录修正资产标识快照 |
|
||||
| 修改 | `tb_agent_wallet` | 信用开关、额度和 CHECK 约束 |
|
||||
| 修改 | `tb_exchange_order` | 提交人快照、资产标识快照和新旧资产查询索引 |
|
||||
| 修改 | `tb_iot_card`、`tb_device` | 换货完成时新资产继承旧资产店铺和租户标签 |
|
||||
| 修改 | `tb_shop` | 可空平台业务员字段 `business_owner_account_id` |
|
||||
| 修改 | `tb_role` | 新建店铺默认信用开关和额度模板 |
|
||||
| 修改 | `tb_agent_wallet` | 实际信用开关、额度和 CHECK 约束 |
|
||||
| 修改 | `tb_refund_request` | 提交人、企微实例轮次、撤销状态和终态处理结果 |
|
||||
| 修改 | `tb_agent_recharge_record` | 提交人、企微实例、支付状态和入账处理结果 |
|
||||
| 修改 | `tb_payment` | 支持 `order_type=agent_recharge` 和创建时支付配置快照 |
|
||||
@@ -1196,6 +1304,10 @@ flowchart LR
|
||||
| C-15 | 企微账号只允许扫码绑定；一个 `userid` 不能覆盖绑定到第二个系统账号。 |
|
||||
| C-16 | 代理在线充值最低 100 元，支付成功直接入主钱包，不因金额大进入审批。 |
|
||||
| C-17 | 全局审计本次停止旧表新写入；历史只读投影，不双写、不在线回填。 |
|
||||
| C-18 | 角色默认信用配置只作用于以后新建的店铺；修改角色不更新已有店铺。 |
|
||||
| C-19 | 钱包预警阈值固定 100 元，按 `balance - frozen_balance` 判断，不包含信用额度。 |
|
||||
| C-20 | 临期只发站内通知；3 天内使用红色，且只在临期独立列表置顶。 |
|
||||
| C-21 | 换货新资产继承旧资产店铺；旧资产保留原归属，已属于其他店铺的新资产不得换入。 |
|
||||
|
||||
Gateway 的取消限速具体报文不是产品决策：上线前由上游接口契约确定，业务层始终只传 `speed_kbps=0`。
|
||||
|
||||
@@ -1217,6 +1329,9 @@ Gateway 的取消限速具体报文不是产品决策：上线前由上游接口
|
||||
| 限速对象错误 | 设备无当前卡或错误把 IMEI 当卡号 | 统一解析当前卡 ICCID；无卡拒绝调用并记录审计 |
|
||||
| 导出敏感字段泄露 | 权限缺失或 Worker 回退全字段 | 服务端字段交集、任务快照、失败关闭 |
|
||||
| 临期重复通知 | 定时任务重试 | 稳定事件 ID 和接收人维度唯一约束 |
|
||||
| 余额预警刷屏 | 钱包持续低于 100 元并发生多次扣款 | 仅跨越阈值时发送，回升后才重新布防 |
|
||||
| 换货归属越权 | 新资产已属于其他店铺或关联资产无查看权限 | 事务内归属校验；关联跳转继续执行后端数据权限 |
|
||||
| 角色额度误改存量 | 管理员修改角色默认额度 | API 只更新角色模板，不批量更新钱包；页面明确影响范围 |
|
||||
|
||||
---
|
||||
|
||||
@@ -1247,12 +1362,16 @@ Gateway 的取消限速具体报文不是产品决策：上线前由上游接口
|
||||
| 数据同步 | 活跃调频、0/3/5 阶梯、同场景合并、单卡互斥、超频不退避、19/20位回调、解除实名忽略、旧入口收口 |
|
||||
| 全局审计 | 关键事务失败回滚、人员/资源/请求/资金/风险/集成视角、历史投影、脱敏、旧表停止新写入 |
|
||||
| 钱包 | 普通余额扣款、信用扣款、额度降低失败、并发版本冲突、负余额回充 |
|
||||
| 角色默认额度 | 新建店铺继承默认值、修改角色不影响已有店铺、店铺独立调额 |
|
||||
| 余额预警 | 现金余额跨越 100 元阈值、持续低余额不重复、回升后再次跌破、代理和业务员接收通知 |
|
||||
| 批量订购 | 钱包/线下两种支付、部分成功、重复提交、Worker 重试、失败明细、模板错误 |
|
||||
| 退款 | 金额发起时固定、财务人工退款企微确认、代理钱包回退原主钱包、个人资产钱包不误入、通过后撤销不冲正 |
|
||||
| 充值 | 微信/支付宝最低100元扫码、重复回调不重复入账、已支付恢复、在线不审批、线下企微通过自动入账且无操作密码 |
|
||||
| 导出 | 普通角色、敏感字段角色、超级管理员、权限为空、审批摘要批量查询 |
|
||||
| 限速 | 单卡、设备当前卡、无当前卡、设置、取消、Gateway 失败和审计记录 |
|
||||
| 临期 | 有/无排队套餐、15/7/3 天、漏跑补发、重复定时任务、不同接收人、列表/详情/C端一致 |
|
||||
| 临期 | 当前与排队套餐最终到期推算、等待实名不可预计、15/7/3 天、3天红色和临期页置顶、漏跑补发、列表/详情/C端一致 |
|
||||
| 换货补充 | 新资产继承店铺、其他店铺资产拒绝、旧资产保留归属、前代/后代标识和受控跳转 |
|
||||
| 系列授权 | 首次和后续批量选择、已授权置灰、重复提交幂等、三类价格含义正确 |
|
||||
| 发布 | 存量退款和充值回填、历史 `legacy`、旧路由不可访问、Worker 暂停后恢复 |
|
||||
|
||||
验收使用接口调用、PostgreSQL 数据核对、日志检查和页面操作，不以自动化测试作为本项目交付前提。
|
||||
@@ -1267,8 +1386,8 @@ Gateway 的取消限速具体报文不是产品决策：上线前由上游接口
|
||||
3. 卡状态领域、轮询活跃调频、事件阶梯和运营商回调防腐层
|
||||
4. 企微连接、模板版本、账号扫码绑定、提交/回调/轮询
|
||||
5. 退款和平台员工线下充值接入企微，代理微信/支付宝扫码充值
|
||||
6. 钱包信用额度、批量订购、导出权限、设备批量分配、限速和临期提醒
|
||||
7. 其他查询、字段和显示修复、存量回填和停机发布演练
|
||||
6. 钱包信用额度、业务员和余额预警、批量订购、导出权限、设备批量分配、系列套餐批量授权、限速和临期提醒
|
||||
7. 换货归属与换货链、其他查询和显示修复、存量回填及停机发布演练
|
||||
```
|
||||
|
||||
每个复杂用例按“迁移 → Application/Domain → Infrastructure → Handler → 前端 → 人工验收”形成完整闭环，不在同一任务中顺带重构未触碰模块。
|
||||
@@ -1280,7 +1399,7 @@ Gateway 的取消限速具体报文不是产品决策：上线前由上游接口
|
||||
### 11.1 估算口径
|
||||
|
||||
- 1 人日按 8 小时计算。
|
||||
- 当前固定投入为 1 名后端和 1 名前端，两人并行开发，目标自然周期为 11～15 个工作日。
|
||||
- 当前固定投入为 1 名后端和 1 名前端，两人并行开发，正常目标为 12～15 个工作日，风险上限为 16 个工作日。
|
||||
- 包含本期企业微信审批、数据同步重构、全局审计一次性切换、代理微信/支付宝扫码充值及原 7 月迭代范围。
|
||||
- 不包含套餐临期企业微信消息推送、自动第三方退款、运营商解除实名回滚和需求16。
|
||||
- 包含后端、前端、第三方联调、人工接口验证、PostgreSQL 数据核对、存量回填和停机发布；不单独预留长期缓冲。
|
||||
@@ -1293,28 +1412,28 @@ Gateway 的取消限速具体报文不是产品决策：上线前由上游接口
|
||||
|
||||
| 工作包 | 后端人日 | 前端人日 | 快速交付说明 |
|
||||
|--------|----------|----------|--------------|
|
||||
| 迁移、Outbox、全局审计和站内通知 | 2 | 2 | 复用现有日志、列表和抽屉组件，先完成核心多视角 |
|
||||
| 数据同步领域收口、活跃轮询和运营商回调 | 2～3 | 1 | 后端为主，前端只补状态和审计跳转 |
|
||||
| 企微模板、扫码绑定、提交/回调/轮询 | 2～3 | 2～3 | 复用企微官方页面和现有业务详情布局 |
|
||||
| 退款、线下充值终态和代理扫码充值 | 2～3 | 2～3 | 复用现有钱包、支付回调和充值页面 |
|
||||
| 信用、批量、导出、限速、临期及其他需求 | 2～2.5 | 2～3 | 多个小需求并行处理，避免额外抽象 |
|
||||
| 联调、数据核对、回填和停机发布 | 1～1.5 | 1～2 | 随开发持续联调，最后集中验证核心链路 |
|
||||
| **合计投入** | **11～15** | **10～14** | **总投入约 21～29 人日，两人并行 11～15 个工作日** |
|
||||
| 迁移、Outbox、全局审计和站内通知 | 2 | 1.5～2 | 复用现有日志、列表和抽屉组件，先完成核心多视角 |
|
||||
| 数据同步领域收口、活跃轮询和运营商回调 | 2～3 | 0.5～1 | 后端为主，前端只补状态和审计跳转 |
|
||||
| 企微模板、扫码绑定、提交/回调/轮询 | 2～3 | 1.5～2 | 复用企微官方页面和现有业务详情布局 |
|
||||
| 退款、线下充值终态和代理扫码充值 | 2～3 | 1.5～2 | 复用现有钱包、支付回调和充值页面 |
|
||||
| 信用、业务员预警、换货、系列授权、批量、导出、限速和临期 | 2.5～3.5 | 2.5～3 | 系列授权和换货链已有后端基础，只补增量能力 |
|
||||
| 联调、数据核对、回填和停机发布 | 1～1.5 | 0.5～1 | 随开发持续联调，最后集中验证核心链路 |
|
||||
| **合计投入** | **约 12～16** | **约 8～12** | **总投入约 19～28 人日，两人并行正常 12～15 个工作日，风险上限 16 天** |
|
||||
|
||||
排期基线按 **13 个工作日**，对外承诺范围为 **11～15 个工作日**。如真实企微/支付配置无法按时提供、生产 ICCID 或审计旧入口存在大量异常，问题记录为外部阻塞，不在开发阶段扩展额外重构范围。
|
||||
排期基线按 **14 个工作日**，正常范围为 **12～15 个工作日**。如换货归属需要补齐超出预期的租户标签表、真实企微/支付配置无法按时提供、生产 ICCID 或审计旧入口存在大量异常，风险上限为第 16 个工作日，不在开发阶段扩展额外重构范围。
|
||||
|
||||
### 11.3 当前团队排期
|
||||
|
||||
当前团队固定为 **1 后端 + 1 前端**，两人从第一天开始并行，预计 **11～15 个工作日**。推荐节奏：
|
||||
当前团队固定为 **1 后端 + 1 前端**，两人从第一天开始并行，正常预计 **12～15 个工作日**，风险上限 **16 个工作日**。推荐节奏：
|
||||
|
||||
```text
|
||||
第 1～2 天：迁移、Outbox、审计/通知骨架，前端同步搭建页面框架
|
||||
第 3～5 天：数据同步收口、活跃轮询、回调防腐层和审计外部集成视角
|
||||
第 4～7 天：企微模板、扫码绑定、审批提交/回调/轮询及前端配置页面
|
||||
第 6～9 天：退款、线下充值终态、代理微信/支付宝扫码充值
|
||||
第 8～11 天：信用、批量、导出、限速、临期和其他小需求
|
||||
第 11～13 天：全链路联调、数据核对、旧入口清理和存量回填演练
|
||||
第 14～15 天：问题修复和停机发布缓冲；进度稳定时可提前
|
||||
第 8～12 天：信用、业务员预警、换货归属与标识、系列批量授权、批量、导出、限速和临期
|
||||
第 12～14 天：全链路联调、数据核对、旧入口清理和存量回填演练
|
||||
第 15 天：问题修复和停机发布；换货租户标签或历史数据超预期时使用第 16 天风险缓冲
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
242
docs/7月迭代/7月迭代禅道研发需求拆分表.md
Normal file
242
docs/7月迭代/7月迭代禅道研发需求拆分表.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# 7月迭代禅道研发需求拆分表
|
||||
|
||||
> 来源：禅道用户需求导出与7月迭代标准评审稿。
|
||||
> 范围：只包含激活需求；草稿 #41/#51 和已关闭重复需求 #54 不创建研发需求。
|
||||
>
|
||||
> 本文件用于总览、排期和关联关系，不用于逐条复制。实际录入禅道请使用：[7月迭代禅道研发需求逐条录入稿](./7月迭代禅道研发需求逐条录入稿.md)。录入稿中每条 FE/BE/INT 都有可独立复制的标题和完整描述。
|
||||
|
||||
## 一、拆分规则
|
||||
|
||||
每条用户需求下创建两条研发需求：
|
||||
|
||||
```text
|
||||
[FE][UR#编号] 前端交付名称
|
||||
[BE][UR#编号] 后端交付名称
|
||||
```
|
||||
|
||||
- FE、BE 研发需求分别指派给前端和后端，可并行进入开发。
|
||||
- 研发需求必须描述可独立交付的页面或接口能力，不能只写“配合前端”“配合后端”。
|
||||
- 联调属于研发需求完成后的交付活动，不为每条用户需求机械创建第三条研发需求。
|
||||
- 跨页面、跨模块、异步任务或第三方系统场景，统一创建链路级联调任务。
|
||||
- 简单搜索、字段展示等需求在 FE/BE 研发需求中完成自验，不单独创建联调任务。
|
||||
|
||||
推荐状态依赖：
|
||||
|
||||
```text
|
||||
FE/BE 研发需求开发完成
|
||||
-> 接口契约冻结
|
||||
-> 进入对应联调任务
|
||||
-> 问题回到原 FE/BE 研发需求修复
|
||||
-> 联调任务验收通过
|
||||
```
|
||||
|
||||
## 二、用户需求到研发需求映射
|
||||
|
||||
| 用户需求 | 前端研发需求 | 后端研发需求 | 联调归属 |
|
||||
|---|---|---|---|
|
||||
| #98 换货管理新资产归属 | `[FE][UR#98] 换货新资产归属继承提示`：选择新资产后展示将继承的店铺 | `[BE][UR#98] 换货新资产继承旧资产店铺`：事务内迁移归属、租户标签和分配记录 | INT-02 换货链路 |
|
||||
| #97 代理钱包阈值提醒 | `[FE][UR#97] 代理现金余额不足100元展示与通知跳转` | `[BE][UR#97] 主钱包固定100元余额预警`：跨越阈值、重新布防、站内通知 | INT-05 钱包支付 |
|
||||
| #96 员工作为发展人进行标识 | `[FE][UR#96] 店铺业务员选择、展示和筛选` | `[BE][UR#96] 店铺业务员关联与查询`：只绑定启用平台账号 | INT-05 钱包支付 |
|
||||
| #94 系统状态同步优化以及回调处理 | `[FE][UR#94] 资产同步状态与审计入口展示` | `[BE][UR#94] 资产状态同步DDD收口`：轮询、0/3/5事件、回调防腐层 | INT-01 实名与同步 |
|
||||
| #86 资产详情中换货标识 | `[FE][UR#86] 资产详情前代/后代换货标识与跳转` | `[BE][UR#86] 资产换货链Query`：返回 previous/next asset并校验权限 | INT-02 换货链路 |
|
||||
| #73 行业卡操作停复机 | `[FE][UR#73] 复机实名校验结果与错误提示适配` | `[BE][UR#73] 按运营商实名能力控制复机` | INT-01 实名与同步 |
|
||||
| #62 H5设置先充值后实名 | `[FE][UR#62] H5实名与购买顺序流程`：先实名/先购买/无需实名 | `[BE][UR#62] 资产实名顺序策略与批量配置接口` | INT-01 实名与同步 |
|
||||
| #60 店铺联系电话检索 | `[FE][UR#60] 店铺联系电话搜索控件` | `[BE][UR#60] 店铺联系电话精确查询` | 不单建，FE/BE自验 |
|
||||
| #57 退款中禁止换货 | `[FE][UR#57] 换货退款拦截错误展示` | `[BE][UR#57] 换货前活跃退款校验` | INT-02 换货链路 |
|
||||
| #55 套餐生效条件 | `[FE][UR#55] 套餐分配生效条件选择与恢复默认` | `[BE][UR#55] 套餐分配生效条件覆盖与购买快照` | INT-03 套餐生命周期 |
|
||||
| #53 资产实名状态筛选 | `[FE][UR#53] 卡和设备实名状态筛选` | `[BE][UR#53] 卡/设备实名状态查询与设备快照维护` | INT-01 实名与同步 |
|
||||
| #49 设备批量分配代理和套餐系列 | `[FE][UR#49] 设备批量分配代理/套餐系列双入口` | `[BE][UR#49] 两类设备批量分配任务与失败明细` | INT-04 批量与导出 |
|
||||
| #48 不同资产使用不同支付方式 | `[FE][UR#48] C端按资产展示允许支付方式` | `[BE][UR#48] 支付方式配置与订单二次校验` | INT-05 钱包支付 |
|
||||
| #47 限速规则 | `[FE][UR#47] 卡/设备手动设置与取消限速` | `[BE][UR#47] Gateway按cardNo限速统一接口` | INT-07 Gateway限速 |
|
||||
| #46 资产信息详情字段新增 | `[FE][UR#46] 预计最终到期时间与临期高亮` | `[BE][UR#46] 当前及排队套餐最终到期Query` | INT-03 套餐生命周期 |
|
||||
| #45 换货管理 | `[FE][UR#45] 换货新旧资产展示与独立搜索` | `[BE][UR#45] 换货标识快照修正与新旧资产查询` | INT-02 换货链路 |
|
||||
| #44 列表字段新增 | `[FE][UR#44] 退款/充值/换货提交人与审批摘要展示` | `[BE][UR#44] 提交人快照与企微审批摘要批量查询` | INT-06 企微审批 |
|
||||
| #43 代理系列授权 | `[FE][UR#43] 系列套餐批量选择与已授权置灰` | `[BE][UR#43] 系列套餐候选Query与重复授权幂等` | INT-03 套餐生命周期 |
|
||||
| #42 导出功能 | `[FE][UR#42] 导出字段选择、权限展示和任务进度` | `[BE][UR#42] 导出场景、角色字段权限与30天到期筛选` | INT-04 批量与导出 |
|
||||
| #40 套餐设计 | `[FE][UR#40] C端下架套餐续费入口` | `[BE][UR#40] 下架套餐历史用户续费资格校验` | INT-03 套餐生命周期 |
|
||||
| #38 不同渠道额度处理 | `[FE][UR#38] 角色默认信用和店铺实际额度管理` | `[BE][UR#38] 代理主钱包信用额度与并发资金不变量` | INT-05 钱包支付 |
|
||||
| #37 审核流转 | `[FE][UR#37] 企微审批状态、意见附件和结果通知展示` | `[BE][UR#37] 企微审批模板、账号绑定、回调和轮询补偿` | INT-06 企微审批 |
|
||||
| #36 批量订购套餐 | `[FE][UR#36] 批量订购上传、支付方式、进度和失败明细` | `[BE][UR#36] 批量订购任务、逐行幂等下单和钱包扣款` | INT-04 批量与导出、INT-05 钱包支付 |
|
||||
| #35 退款审核 | `[FE][UR#35] 退款企微审批详情与业务处理状态` | `[BE][UR#35] 退款企微终态、人工退款和代理钱包回溯` | INT-06 企微审批 |
|
||||
| #34 充值审核流程 | `[FE][UR#34] 代理扫码充值与员工线下审批状态页面` | `[BE][UR#34] 微信/支付宝充值入账和线下充值企微终态` | INT-05 钱包支付、INT-06 企微审批 |
|
||||
| #33 套餐临期提醒 | `[FE][UR#33] 临期列表、各端高亮、3天置顶和续费入口` | `[BE][UR#33] 最终到期临期Query与15/7/3站内通知` | INT-03 套餐生命周期 |
|
||||
|
||||
## 三、前后端并行约定
|
||||
|
||||
研发需求创建前先冻结本表中的接口契约。前端按 Mock 数据开发页面，后端按同一契约实现接口。
|
||||
|
||||
- 响应统一为 `{code,msg,data,timestamp}`，下表只描述 `data`。
|
||||
- 分页统一返回 `{items,total,page,size}`。
|
||||
- 金额入参和返回均使用分；前端显示元。
|
||||
- 生命周期判断使用 `status`，展示使用 `status_name`。
|
||||
- 字段允许增加但不能改名或改变类型；确需调整时，必须同步修改 FE、BE 两条研发需求。
|
||||
- 前端先完成页面、交互、Mock、加载/空/错误状态；后端完成后只替换数据源并进入联调。
|
||||
|
||||
每组需求按以下顺序启动：
|
||||
|
||||
```text
|
||||
1. FE/BE共同确认路径、方法、入参、返回和枚举
|
||||
2. 后端先补DTO/OpenAPI契约或提供固定JSON示例
|
||||
3. 前端按JSON示例完成页面和Mock请求
|
||||
4. 后端实现真实查询、写入、权限、幂等和审计
|
||||
5. 前端切换真实接口，进入对应INT联调任务
|
||||
```
|
||||
|
||||
契约确认时必须标记字段是必返、可空还是仅特定状态返回，避免前端通过猜测补默认值。
|
||||
|
||||
## 四、研发需求压缩总览
|
||||
|
||||
> 下表仅用于快速核对，不建议复制到禅道。前端页面结构、交互状态、接口入参和返回字段以[逐条录入稿](./7月迭代禅道研发需求逐条录入稿.md)为准。
|
||||
|
||||
| 用户需求 | 前端研发需求说明 | 后端研发需求与接口契约 |
|
||||
|---|---|---|
|
||||
| #98 换货新资产归属 | **标题：**换货新资产归属继承提示。<br>**页面：**换货创建、发货确认。选择新资产后展示“完成后归属到某店铺”，提交中禁止重复操作，失败展示后端原因。 | **标题：**换货新资产继承旧资产店铺。<br>**接口：**复用 `POST /api/admin/exchanges`、`POST /api/admin/exchanges/{id}/ship`、`POST /api/admin/exchanges/{id}/complete`。<br>**入参：**旧/新资产标识、换货类型、是否迁移资料。<br>**返回：**换货单及 `inherited_shop_id/inherited_shop_name`。<br>**规则：**平台库存新资产继承旧店铺；其他店铺资产拒绝。 |
|
||||
| #97 钱包100元预警 | **标题：**代理现金余额不足100元展示。<br>**页面：**资金概况显示红色预警；顶部通知和通知中心支持跳转店铺资金页，不提供阈值配置。 | **标题：**代理主钱包固定100元余额预警。<br>**接口：**`GET /api/admin/shops/fund-summary` 增加 `cash_available/low_balance_warning`；通知复用 `/api/admin/notifications`。<br>**规则：**`balance-frozen_balance<=10000`，不含信用额度；只在跨越阈值时通知，回升后重新布防。 |
|
||||
| #96 店铺业务员 | **标题：**店铺业务员选择、展示与筛选。<br>**页面：**店铺新建/编辑增加平台业务员下拉，列表和详情展示业务员，筛选栏支持按业务员查询。 | **标题：**店铺业务员关联与查询。<br>**接口：**`POST /api/admin/shops`、`PUT /api/admin/shops/{id}` 入参增加 `business_owner_account_id`；`GET /api/admin/shops` 增加同名筛选。<br>**返回：**`business_owner_account_id/business_owner_name`。只允许启用的平台账号。 |
|
||||
| #94 状态同步优化 | **标题：**资产同步状态与审计入口。<br>**页面：**资产详情展示活跃级别、最后活跃、下次轮询；保留原刷新按钮，增加“查看同步轨迹”跳转。 | **标题：**资产状态同步DDD收口。<br>**接口：**不新增刷新入口，复用 `POST /api/admin/assets/{identifier}/refresh`；`GET /api/admin/assets/resolve/{identifier}` 返回 `polling`；轨迹使用 `GET /api/admin/audit/integrations`。<br>**规则：**轮询、0/3/5事件和回调统一应用状态。 |
|
||||
| #86 资产换货标识 | **标题：**资产详情换货前代/后代展示。<br>**页面：**显示“换货新资产”“已换出旧资产”标签，可查看前代和后代；无权限时不可点击。 | **标题：**资产换货链Query。<br>**接口：**`GET /api/admin/assets/resolve/{identifier}` 增加 `exchange_trace.previous_asset/next_asset`。<br>**返回：**资产类型、ID、标识、换货单号和 `can_view`。 |
|
||||
| #73 行业卡复机 | **标题：**复机实名结果和错误提示。<br>**页面：**沿用资产详情复机按钮；未满足实名条件时展示后端中文原因。 | **标题：**按运营商实名能力控制复机。<br>**接口：**复用 `POST /api/admin/assets/{identifier}/start`。<br>**返回：**最新资产状态。<br>**规则：**只看运营商 `realname_link_type`，不按行业卡类型统一放行。 |
|
||||
| #62 H5实名顺序 | **标题：**H5先实名/先购买流程及后台批量配置。<br>**页面：**C端按接口策略跳转；后台卡和设备列表提供批量修改入口。 | **标题：**资产实名顺序策略。<br>**接口：**`PATCH /api/admin/assets/{identifier}/realname-mode`；`POST /api/admin/iot-cards/batch-update-realname-policy`；`POST /api/admin/devices/batch-update-realname-policy`。<br>**入参：**资产标识列表、`policy=none/before_order/after_order`。<br>**返回：**生效策略及成功数量。 |
|
||||
| #60 联系电话搜索 | **标题：**店铺联系电话搜索。<br>**页面：**店铺列表新增11位联系电话输入框，支持清空和重新查询。 | **标题：**店铺联系电话精确查询。<br>**接口：**`GET /api/admin/shops?contact_phone=`。<br>**入参：**11位手机号。<br>**返回：**原店铺分页结构。 |
|
||||
| #57 退款中禁止换货 | **标题：**换货退款拦截提示。<br>**页面：**创建换货失败时原地展示“该资产存在退款申请”，不自行判断退款状态。 | **标题：**换货前活跃退款校验。<br>**接口：**复用 `POST /api/admin/exchanges`。<br>**规则：**审批中、已退回或退款处理未完成时返回业务错误；已拒绝、撤销或处理完成后放行。 |
|
||||
| #55 套餐生效条件 | **标题：**套餐分配生效条件选择。<br>**页面：**授权/分配弹框提供跟随默认、购买生效、实名生效三选一；已分配记录支持修改和恢复默认。 | **标题：**套餐分配生效条件覆盖与快照。<br>**接口：**`POST /api/admin/shop-package-allocations`；`PATCH /api/admin/shop-package-allocations/{id}/expiry-base`。<br>**入参：**`expiry_base_override`，`null` 表示恢复默认。<br>**返回：**默认值、覆盖值和最终生效值。 |
|
||||
| #53 实名状态筛选 | **标题：**卡和设备实名状态筛选。<br>**页面：**两个资产列表增加全部/已实名/未实名筛选和状态列。 | **标题：**卡和设备实名状态查询。<br>**接口：**`GET /api/admin/iot-cards?real_name_status=0\|1`；`GET /api/admin/devices?real_name_status=0\|1`。<br>**返回：**`real_name_status/real_name_status_name`。 |
|
||||
| #49 设备批量分配 | **标题：**设备批量分配代理和套餐系列双入口。<br>**页面：**两个独立上传弹框，展示总数、成功数、失败数和失败原因。 | **标题：**设备两类批量分配任务。<br>**接口：**`POST /api/admin/devices/batch-assign-shop`、`POST /api/admin/devices/batch-assign-series`、`GET /api/admin/devices/batch-allocation/{task_id}`。<br>**入参：**文件和目标ID。<br>**返回：**任务状态及失败明细。 |
|
||||
| #48 支付方式限制 | **标题：**C端按资产展示支付方式。<br>**页面：**支付页只展示接口返回的支付方式；无可用方式时禁止提交。 | **标题：**资产支付方式配置与订单校验。<br>**接口：**`GET /api/c/v1/asset/info` 返回 `allowed_payment_methods`；`POST /api/c/v1/orders/create`、`POST /api/c/v1/orders/{id}/pay` 再次校验。<br>**后台：**`PUT /api/admin/system/config/{config_key}`。 |
|
||||
| #47 Gateway限速 | **标题：**卡和设备手动限速。<br>**页面：**详情页提供设置、取消入口；设备显示最终使用的当前卡ICCID。 | **标题：**Gateway按cardNo统一限速。<br>**接口：**`POST /api/admin/assets/{identifier}/speed-limit`。<br>**入参：**`speed_kbps`，0表示取消。<br>**返回：**资产标识、最终 `card_no`、目标值和执行结果。 |
|
||||
| #46 预计最终到期 | **标题：**预计套餐到期时间和临期高亮。<br>**页面：**资产详情只显示一个最终到期字段；不可预计时显示“待激活后起算”。 | **标题：**当前及排队套餐最终到期Query。<br>**接口：**`GET /api/admin/assets/resolve/{identifier}`。<br>**返回：**`estimated_final_expires_at/days_until_final_expiry/expiry_estimate_status/is_expiring`。 |
|
||||
| #45 换货管理 | **标题：**换货新旧资产展示和独立搜索。<br>**页面：**列表分别搜索旧资产、新资产，展示统一卡ICCID或设备号。 | **标题：**换货标识快照和查询。<br>**接口：**`GET /api/admin/exchanges?old_asset_keyword=&new_asset_keyword=`。<br>**返回：**新旧资产类型、ID、标识及换货状态。新建换货统一保存规范化标识。 |
|
||||
| #44 列表字段新增 | **标题：**退款、充值、换货列表提交人与审批摘要。<br>**页面：**增加提交人、企微状态、当前审批人摘要和业务处理状态。 | **标题：**提交人快照与企微摘要查询。<br>**接口：**复用 `GET /api/admin/refunds`、`GET /api/admin/agent-recharges`、`GET /api/admin/exchanges`。<br>**返回：**`submitter_name/approval_status_name/current_approver_summary/processing_status_name`。 |
|
||||
| #43 系列批量授权 | **标题：**系列套餐批量选择与已授权置灰。<br>**页面：**首次和后续授权共用多选表格；已授权套餐置灰，展示公司成本、授权成本和建议售价。 | **标题：**系列套餐候选和批量授权。<br>**接口：**`GET /api/admin/shop-series-grants/{id}/package-options`；`PUT /api/admin/shop-series-grants/{id}/packages`。<br>**返回：**三类价格、`is_authorized`；重复授权幂等。 |
|
||||
| #42 导出功能 | **标题：**导出字段选择、权限和任务进度。<br>**页面：**导出弹框加载可选字段，提交后展示进度、失败和下载。 | **标题：**统一导出场景和字段权限。<br>**接口：**`GET /api/admin/export-fields?scene=`、`POST /api/admin/export-tasks`、`GET /api/admin/export-tasks/{id}`。<br>**入参：**`scene/format/query/fields`。<br>**返回：**任务进度和下载地址。 |
|
||||
| #40 下架套餐续费 | **标题：**C端当前套餐续费入口。<br>**页面：**当前套餐旁显示续费；下架套餐不出现在新购列表。 | **标题：**下架套餐续费资格。<br>**接口：**`GET /api/c/v1/asset/packages` 返回 `can_purchase/purchase_mode/disabled_reason`；`POST /api/c/v1/orders/create` 强校验资产所有人和历史使用记录。 |
|
||||
| #38 代理信用额度 | **标题：**角色默认信用和店铺实际额度管理。<br>**页面：**客户角色配置新建默认额度并提示不影响存量；店铺资金页单独调整实际额度。 | **标题：**代理主钱包信用额度。<br>**接口：**`PUT /api/admin/roles/{id}/default-credit`、`PUT /api/admin/shops/{id}/credit-limit`、`GET /api/admin/shops/fund-summary`。<br>**入参：**开关、额度、钱包版本。<br>**返回：**额度、可用金额、欠款和版本。 |
|
||||
| #37 企微审核流转 | **标题：**企微配置、账号绑定和审批详情。<br>**页面：**企微配置页、个人扫码绑定、审批运行列表；业务详情只读展示意见和附件。 | **标题：**企业微信审批接入。<br>**接口：**`GET /api/admin/wecom/status`、`POST /api/admin/wecom/account-binding/sessions`、`GET /api/admin/wecom/approvals`、`POST /api/admin/wecom/approvals/{id}/sync`。<br>**业务详情：**统一返回 `approval` 对象。 |
|
||||
| #36 批量订购套餐 | **标题：**批量订购上传、支付、进度和失败明细。<br>**页面：**选择代理和整批支付方式，上传Excel及线下凭证，展示部分成功。 | **标题：**批量订购任务。<br>**接口：**`POST /api/admin/bulk-purchases`、`GET /api/admin/bulk-purchases/{task_id}`、`GET /api/admin/bulk-purchases/{task_id}/items`。<br>**入参：**代理、支付方式、文件、凭证。<br>**返回：**任务和逐行结果。 |
|
||||
| #35 退款审核 | **标题：**退款企微审批和退款处理状态。<br>**页面：**创建时上传备注附件；详情展示审批、人工退款说明和业务处理结果。 | **标题：**退款企微终态处理。<br>**接口：**`POST /api/admin/refunds`、`GET /api/admin/refunds/{id}`、`POST /api/admin/refunds/{id}/resubmit`。<br>**返回：**退款数据、`approval` 和 `processing_status`。代理钱包通过后幂等回溯。 |
|
||||
| #34 充值审核流程 | **标题：**代理扫码充值与员工线下充值审批。<br>**页面：**在线充值展示支付方式、二维码和支付状态；线下充值展示只读企微审批状态。 | **标题：**代理在线充值和员工线下审批。<br>**接口：**`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}`。<br>**返回：**二维码、过期时间、支付/审批/入账状态。 |
|
||||
| #33 套餐临期提醒 | **标题：**临期列表、各端高亮和续费入口。<br>**页面：**临期页3天内置顶；普通资产列表只高亮；代理首页显示数量；C端显示续费按钮。 | **标题：**预计最终到期临期Query和站内通知。<br>**接口：**`GET /api/admin/expiring-assets`、资产列表/详情增加临期字段、`GET /api/c/v1/asset/info`、通知接口。<br>**返回：**最终到期、剩余天数、颜色节点；15/7/3天通知防重。 |
|
||||
|
||||
## 五、前端Mock公共样例
|
||||
|
||||
资产详情扩展字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"estimated_final_expires_at": "2026-08-01T23:59:59+08:00",
|
||||
"days_until_final_expiry": 15,
|
||||
"expiry_estimate_status": "exact",
|
||||
"is_expiring": true,
|
||||
"allowed_payment_methods": ["alipay", "wallet"],
|
||||
"polling": {
|
||||
"enabled": true,
|
||||
"activity_level": "active",
|
||||
"last_activity_at": "2026-07-17T10:00:00+08:00",
|
||||
"next_poll_at": "2026-07-17T10:03:00+08:00"
|
||||
},
|
||||
"exchange_trace": {
|
||||
"previous_asset": null,
|
||||
"next_asset": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
统一异步任务：
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": 1001,
|
||||
"status": 2,
|
||||
"status_name": "处理中",
|
||||
"total_count": 100,
|
||||
"success_count": 60,
|
||||
"failed_count": 3,
|
||||
"failed_items": []
|
||||
}
|
||||
```
|
||||
|
||||
代理资金概况：
|
||||
|
||||
```json
|
||||
{
|
||||
"balance": 8000,
|
||||
"frozen_balance": 0,
|
||||
"cash_available": 8000,
|
||||
"credit_enabled": true,
|
||||
"credit_limit": 100000,
|
||||
"available_balance": 108000,
|
||||
"low_balance_warning": true,
|
||||
"version": 3
|
||||
}
|
||||
```
|
||||
|
||||
企微审批摘要：
|
||||
|
||||
```json
|
||||
{
|
||||
"source": "wecom",
|
||||
"instance_id": 123,
|
||||
"sp_no": "202607170001",
|
||||
"status": 1,
|
||||
"status_name": "审批中",
|
||||
"current_approver_summary": "财务审批",
|
||||
"approvers": [],
|
||||
"attachments": [],
|
||||
"business_process_result": "pending"
|
||||
}
|
||||
```
|
||||
|
||||
## 六、联调任务拆分
|
||||
|
||||
联调项建议创建为项目执行任务，而不是研发需求。每个任务可关联多条 FE/BE 研发需求和用户需求。
|
||||
|
||||
如果团队流程强制要求联调也必须使用“研发需求”类型，则先新增一条技术用户需求“7月迭代跨模块联调与发布验收”，再将下列 INT-01～08 建成它的子研发需求。不要把同一条联调需求重复挂到每个业务用户需求下。
|
||||
|
||||
| 编号 | 联调任务名称 | 关联用户需求 | 参与工时 | 进入条件 | 主要验收链路 |
|
||||
|---|---|---|---|---|---|
|
||||
| INT-01 | 资产实名、复机与状态同步联调 | #94、#73、#62、#53 | FE 1～1.5h / BE 1～1.5h，已含 | 实名策略接口、同步任务和H5页面完成 | 不同运营商实名能力、先实名/先购买、0/3/5同步、回调后状态和筛选一致 |
|
||||
| INT-02 | 换货完整链路联调 | #98、#86、#57、#45 | FE 0.5～1h / BE 0.5～1h，已含 | 换货接口、详情和列表页面完成 | 退款拦截、新资产继承店铺、完成换货、列表搜索、前代/后代跳转 |
|
||||
| INT-03 | 套餐授权、购买、续费、到期与临期联调 | #55、#46、#43、#40、#33 | FE 1～1.5h / BE 1～1.5h，已含 | 套餐快照、授权候选和各端到期字段完成 | 批量授权、购买生效条件、下架续费、排队套餐最终到期、临期高亮和通知 |
|
||||
| INT-04 | Excel批量任务与导出联调 | #49、#36、#42 | FE 1～1.5h / BE 1～1.5h，已含 | 上传、任务详情、Worker和导出场景完成 | 模板校验、部分成功、失败明细、任务恢复、字段权限和文件下载 |
|
||||
| INT-05 | 支付、代理钱包、信用和余额预警联调 | #48、#38、#34、#36、#96、#97 | FE 1～1.5h / BE 1～1.5h，已含 | 支付配置、钱包领域和业务员接口完成 | 支付方式限制、扫码充值、信用扣款、角色默认额度、店铺调额、100元预警 |
|
||||
| INT-06 | 企业微信审批、退款和线下充值联调 | #37、#35、#34、#44 | FE 1.5～2h / BE 1.5～2h，已含 | 企微模板、绑定、回调、轮询和业务详情完成 | 扫码绑定、发起审批、意见附件、通过/驳回/撤销、退款/充值终态和列表摘要 |
|
||||
| INT-07 | Gateway卡限速联调 | #47 | FE 0.5～1h / BE 0.5～1h，已含 | Gateway联调配置和卡/设备入口完成 | 单卡限速、设备解析当前卡、取消限速、无当前卡、失败审计 |
|
||||
| INT-08 | 七月迭代全链路与停机发布验收 | 全部激活需求 | FE 3～4h / BE 4～5h，额外 | INT-01～07完成 | 权限、通知、审计、历史数据、旧入口关闭、Worker恢复和发布检查 |
|
||||
|
||||
## 七、联调任务责任方式
|
||||
|
||||
- 涉及企微、支付、Gateway、运营商回调和异步 Worker 的联调任务由后端主责，前端参与。
|
||||
- 主要是页面与接口契约的批量、导出、套餐和换货联调可由前端主责，后端参与。
|
||||
- 禅道只有一个指派人时，指派给主责人；另一人写入抄送和参与人，不拆成两条重复联调任务。
|
||||
- 联调发现的代码问题回到对应 FE/BE 研发需求处理；联调任务只记录场景、阻塞和最终结论。
|
||||
|
||||
## 八、研发需求描述模板
|
||||
|
||||
前端研发需求至少填写：页面入口、交互状态、调用接口、权限、异常状态、完成标准。
|
||||
|
||||
后端研发需求至少填写：业务规则、数据变更、API、权限、幂等/并发、事件与审计、完成标准。
|
||||
|
||||
联调任务至少填写：关联研发需求、环境和账号、测试数据、完整操作步骤、预期结果、阻塞项和最终结论。
|
||||
|
||||
## 九、额外禅道项
|
||||
|
||||
当前用户需求 CSV 没有覆盖公共开发基础、公共站内通知和全局审计。建议补建三条技术用户需求：
|
||||
|
||||
```text
|
||||
用户需求：七月迭代公共开发基础
|
||||
用户需求：公共站内通知
|
||||
用户需求：全局多视角审计与外部集成追踪
|
||||
```
|
||||
|
||||
再分别拆分：
|
||||
|
||||
```text
|
||||
[FE] 七月迭代公共状态与异步任务交互
|
||||
[BE] 七月迭代公共迁移幂等与异步任务基础
|
||||
[FE] 顶部通知铃铛与站内通知中心
|
||||
[BE] 站内通知基础设施与受控跳转
|
||||
[FE] 全局多视角审计中心
|
||||
[BE] Audit Event与Integration Log统一审计
|
||||
```
|
||||
|
||||
具体描述和工时直接使用[逐条录入稿](./7月迭代禅道研发需求逐条录入稿.md)。
|
||||
1889
docs/7月迭代/7月迭代禅道研发需求逐条录入稿.md
Normal file
1889
docs/7月迭代/7月迭代禅道研发需求逐条录入稿.md
Normal file
File diff suppressed because it is too large
Load Diff
62
docs/7月迭代/README.md
Normal file
62
docs/7月迭代/README.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# 7月迭代文档索引
|
||||
|
||||
本目录只保留一份当前有效的评审结论和可追溯的独立来源稿。
|
||||
|
||||
## 当前有效方案
|
||||
|
||||
- [7月迭代技术方案（标准评审稿）](./7月迭代技术方案-标准评审稿.md)
|
||||
- [7月迭代前后端任务工时表](./7月迭代前后端任务工时表.md)
|
||||
- [7月迭代禅道研发需求拆分表](./7月迭代禅道研发需求拆分表.md)
|
||||
- [7月迭代禅道研发需求逐条录入稿](./7月迭代禅道研发需求逐条录入稿.md)
|
||||
|
||||
评审、开发和验收均以标准评审稿为准。独立稿用于解释方案来源；与标准稿冲突时，标准稿优先。
|
||||
|
||||
## 原需求独立稿
|
||||
|
||||
| 需求 | 来源文件 |
|
||||
|------|----------|
|
||||
| 01 | [复机实名规则](./独立方案/原需求/需求01-复机实名规则.md) |
|
||||
| 02 | [H5 流程配置](./独立方案/原需求/需求02-H5流程配置.md) |
|
||||
| 03、07、11、12、13 | [简单改动合集](./独立方案/原需求/需求03-07-11-12-13-简单改动.md) |
|
||||
| 04、06 | [退款拦截与最后到期时间](./独立方案/原需求/需求04-06-退款拦截与最后到期时间.md) |
|
||||
| 05 | [套餐分配生效条件](./独立方案/原需求/需求05-套餐分配生效条件.md) |
|
||||
| 08 | [设备批量分配 Excel](./独立方案/原需求/需求08-设备批量分配Excel.md) |
|
||||
| 09 | [C 端支付限制配置化](./独立方案/原需求/需求09-C端支付限制配置化.md) |
|
||||
| 10 | [Gateway 限速规则](./独立方案/原需求/需求10-限速规则.md) |
|
||||
| 14 | [导出功能](./独立方案/原需求/需求14-导出功能.md) |
|
||||
| 15、16、18、19、20、21 | [复杂需求来源稿](./独立方案/原需求/需求15-16-18-19-20-21-复杂需求.md) |
|
||||
| 17 | [信用额度](./独立方案/原需求/需求17-信用额度.md) |
|
||||
| 22 | [套餐临期提醒](./独立方案/原需求/需求22-套餐临期提醒.md) |
|
||||
|
||||
需求16已经移出本期，仅在来源稿中保留讨论记录。
|
||||
|
||||
## 新增需求独立稿
|
||||
|
||||
| 编号 | 来源文件 |
|
||||
|------|----------|
|
||||
| 新增01 | [数据同步触发与轮询优化](./独立方案/新增需求/01-数据同步触发与轮询优化.md) |
|
||||
| 新增02 | [企业微信审批接入](./独立方案/新增需求/02-企业微信审批接入.md) |
|
||||
| 新增03 | [站内通知详细方案](./独立方案/新增需求/03-站内通知详细方案.md) |
|
||||
| 新增04 | [全局多视角审计方案](./独立方案/新增需求/04-全局多视角审计方案.md) |
|
||||
| 新增05 | [代理钱包扫码充值](./独立方案/新增需求/05-代理钱包扫码充值.md) |
|
||||
| 禅道 #98/#86 | [换货归属与资产换货标识](./独立方案/新增需求/06-换货归属与资产换货标识.md) |
|
||||
| 禅道 #96/#97 | [店铺业务员与钱包余额预警](./独立方案/新增需求/07-店铺业务员与钱包余额预警.md) |
|
||||
| 禅道 #43 | [代理系列套餐批量授权](./独立方案/新增需求/08-代理系列套餐批量授权.md) |
|
||||
|
||||
## 基础规范与历史方案
|
||||
|
||||
- [DDD 规范](./独立方案/基础规范/DDD规范.md)
|
||||
- [系统配置独立方案](./独立方案/基础规范/系统配置.md)
|
||||
- [本地通用审批流（已废弃）](./独立方案/历史方案/本地通用审批流-已废弃方案.md)
|
||||
- [站内消息初版（已被详细方案替代）](./独立方案/历史方案/站内消息-初版.md)
|
||||
- [前端共性方案历史稿](./独立方案/历史方案/前端共性方案-历史稿.md)
|
||||
|
||||
原始讨论材料：
|
||||
|
||||
- [原始业务需求](./来源材料/业务需求.md)
|
||||
- [新增需求讨论与示例代码](./来源材料/新需求.md)
|
||||
- [禅道用户需求导出](./物联网卡管系统-需求.csv)
|
||||
|
||||
这些文件只用于追溯，不是技术实施结论。
|
||||
|
||||
已删除的 `00-总览.md` 和 `7月迭代完整技术方案-评审稿.md` 都是重复汇编，不包含独立来源信息。
|
||||
@@ -1,4 +1,4 @@
|
||||
> 本文保留原始业务需求措辞。涉及架构、字段和接口的最终技术口径，以同目录的专项技术方案和 `基础设施/` 文档为准。
|
||||
> 本文只保留原始业务需求措辞，不作为技术实施结论。最终口径以 [标准评审稿](../7月迭代技术方案-标准评审稿.md) 为准。
|
||||
|
||||
其中有一些需要对接第三方系统的,除了gateway,都可以划分阶段
|
||||
|
||||
@@ -233,7 +233,7 @@
|
||||
| BPO-011 | 授权额度用于订购套餐、代理余额充值等需要涉及金额的所有模块。 |
|
||||
| BPO-012 | 授权额度代理可显示负数余额。平台用户也可显示负数余额。 |
|
||||
|
||||
> 评审结论：信用额度只属于代理主钱包。平台员工是操作主体而不是结算主体，不建立员工钱包、不配置员工信用额度，也不展示员工负余额；角色仅控制谁可以查看或调整代理额度。
|
||||
> 评审结论：信用额度只属于代理主钱包。平台员工是操作主体而不是结算主体，不建立员工钱包、不配置员工信用额度，也不展示员工负余额。客户角色可以配置以后新建店铺的默认额度；修改角色不更新已有店铺，已有店铺只能在店铺资金页面直接调整实际额度。
|
||||
|
||||
18. 系统原先对于审核都是单人审核,现在希望增加多人审批以及相关设置
|
||||
| 编号 | 需求 |
|
||||
@@ -392,3 +392,5 @@ C端公众号 小于等于15天
|
||||
临期天数小于等于15天时，显示粉红色；
|
||||
临期天数小于等于7天时，显示紫色；
|
||||
临期天数小于等于3天时，显示黄色；
|
||||
|
||||
> 最终评审口径：资产临期按当前及排队主套餐的预计最终到期时间计算；3天内改为红色，只在临期独立列表置顶。七月迭代不发送企业微信临期消息，只发送站内通知。
|
||||
@@ -1,3 +1,5 @@
|
||||
> 本文保留新增需求讨论和示例代码，不作为技术实施结论。最终口径以 [标准评审稿](../7月迭代技术方案-标准评审稿.md) 及对应新增需求独立稿为准。
|
||||
|
||||
处理回调的代码
|
||||
```golang
|
||||
package main
|
||||
329
docs/7月迭代/物联网卡管系统-需求.csv
Normal file
329
docs/7月迭代/物联网卡管系统-需求.csv
Normal file
@@ -0,0 +1,329 @@
|
||||
"编号","所属产品","所属模块","所属计划","来源","来源备注","用户需求名称","描述","验收标准","需求层级","父需求","关键词","优先级","预计工时","当前状态","所处阶段","类别","T","B","C","由谁创建","创建日期","指派给","指派日期","抄送给","已评审人","评审时间","由谁关闭","关闭日期","关闭原因","最后修改","最后修改日期","反馈者","重复需求","附件"
|
||||
"98 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","换过管理新资产归属","默认换货把旧资产的所属权一起划过去
|
||||
","","1 ","0 ","","3(#3)","0.50 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-15 14:08:57","黄燚麒","2026-07-16 11:51:00","","
|
||||
黄燚麒(#huang)","2026-07-16 11:50:00","","","","黄燚麒","2026-07-16 11:51:00","","","",""
|
||||
"97 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","代理钱包阈值提醒","代理资金概况板块新增余额预警。不同代理可设置不同的预警额度。达到阈值时可提醒代理和其发展人。
|
||||
","","1 ","0 ","","3(#3)","0.50 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-15 11:23:35","黄燚麒","2026-07-16 15:40:38","","
|
||||
黄燚麒(#huang)","2026-07-16 15:40:00","","","","黄燚麒","2026-07-16 15:40:38","","","",""
|
||||
"96 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","员工作为发展人进行标识","新建店铺添加业务员字段，可以进行指定相应业务员。非必填。同时店铺列表以及详情中新增发展人字段。发展人也可作为检索条件，检索发展人名下的相关店铺。
|
||||
","","1 ","0 ","","2(#2)","1.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-15 11:22:00","黄燚麒","2026-07-15 11:23:15","","
|
||||
黄燚麒(#huang)","2026-07-15 11:23:00","","","","李昕娉","2026-07-15 11:23:42","","","",""
|
||||
"94 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","系统状态同步优化以及回调处理","因资产迁移需要涉及回调和状态同步，故进行相关优化
|
||||
","","1 ","0 ","","1(#1)","40.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-14 10:53:29","黄燚麒","2026-07-14 11:00:14","","
|
||||
黄燚麒(#huang)","2026-07-14 10:59:00","","","","李昕娉","2026-07-14 11:01:12","","","",""
|
||||
"86 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","资产详情中换货标识","在资产详情页卡信息或设备信息列表中需要显示是否发生过换货或是换货标识，标注新资产或旧资产。旧资产需要可以链接至新资产。<img src="{128.png}" alt="index.php?m=file&f=read&t=png&fileID=128" /><img src="{129.png}" alt="index.php?m=file&f=read&t=png&fileID=129" />
|
||||
","","1 ","0 ","","1(#1)","2.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-13 11:50:17","黄燚麒","2026-07-13 11:54:36","","
|
||||
黄燚麒(#huang)","2026-07-13 11:54:00","","","","黄燚麒","2026-07-13 11:54:36","","","",""
|
||||
"73 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","行业卡操作停复机","行业卡允许未实名复机
|
||||
","","1 ","0 ","","3(#3)","1.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-11 10:02:33","黄燚麒","2026-07-11 14:22:26","","
|
||||
黄燚麒(#huang)","2026-07-11 14:22:00","","","","黄燚麒","2026-07-11 14:22:26","","","",""
|
||||
"62 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","新卡管H5需要设置先充值后实名","用户进入H5后需要先绑定手机号后强制先充值后强制实名。这个功能能否进行后台设置，例如这一批设备需要强制先充值后实名，这一批资产可以先实名后充值？
|
||||
","","1 ","0 ","","3(#3)","2.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-09 17:04:27","李昕娉","2026-07-09 18:13:07","","
|
||||
黄燚麒(#huang)","2026-07-11 14:23:00","","","","黄燚麒","2026-07-11 14:23:36","","","",""
|
||||
"60 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","店铺管理新增检索条件","店铺列表搜索栏新增一项：联系电话，便于搜索
|
||||
","","1 ","0 ","","3(#3)","0.10 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-09 16:00:56","黄燚麒","2026-07-09 17:37:57","","
|
||||
黄燚麒(#huang)","2026-07-09 17:37:00","","","","黄燚麒","2026-07-09 17:37:57","","","",""
|
||||
"57 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","操作拦截","若当前资产存在退款申请时（但为通过审批时），该资产不允许操作换货。且出现提示：该资产存在退款申请
|
||||
","","1 ","0 ","","3(#3)","1.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-09 15:07:17","黄燚麒","2026-07-09 17:32:56","","
|
||||
黄燚麒(#huang)","2026-07-09 17:32:00","","","","李昕娉","2026-07-09 17:33:21","","","",""
|
||||
"55 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","套餐生效条件","套餐延续创建时选择购买即生效或实名即生效的条件，同时在套餐分配时提供修改条件的功能，并以变更后的条件为最终版本
|
||||
","","1 ","0 ","","1(#1)","4.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-09 11:57:51","黄燚麒","2026-07-09 16:54:53","","
|
||||
黄燚麒(#huang)","2026-07-09 16:54:00","","","","黄燚麒","2026-07-09 16:54:53","","","",""
|
||||
"54 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","资产详情页面新增套餐到期时间显示","增加所有待生效套餐加上生效套餐加起来的最后到期时间
|
||||
","","1 ","0 ","","2(#2)","","已关闭(#closed)","已关闭(#closed)","功能(#feature)","","","","李昕娉","2026-07-09 11:56:50","closed","2026-07-09 17:26:38","","
|
||||
黄燚麒(#huang)","2026-07-09 17:26:00","黄燚麒","2026-07-09 17:26:38","重复(#duplicate)","黄燚麒","2026-07-09 17:26:38","","#46 资产信息详情字段新增","",""
|
||||
"53 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","资产管理查询字段新增","lot卡管理和设备管理新增已实名/未实名的筛选查询条件
|
||||
","","1 ","0 ","","1(#1)","1.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-09 09:39:53","黄燚麒","2026-07-09 16:53:29","","
|
||||
黄燚麒(#huang)","2026-07-09 16:53:00","","","","黄燚麒","2026-07-09 16:53:29","","","",""
|
||||
"51 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","不同品类资产的换货","因换货存在不同资产间的换货，且存在补差价进行卡换设备的操作。但卡的套餐和设备套餐不同会存在补差价等操作。且原卡套餐需失效，新资产设备需要使用设备套餐。直接操作换货，套餐会同步卡套餐，对公司来说成本增加。
|
||||
","","1 ","0 ","","1(#1)","","草稿(#draft)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 17:54:32","李昕娉","2026-07-09 16:53:05","","","2026-07-09 16:52:00","","","","黄燚麒","2026-07-09 16:53:05","","","",""
|
||||
"49 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","设备批量分配代理和套餐系列","因设备号不是连号，故需要提供导入excel表的方式进行批量分配代理和套餐系列。excle表头为：设备号
|
||||
","","1 ","0 ","","1(#1)","2.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 17:43:58","黄燚麒","2026-07-08 17:43:58","","
|
||||
黄燚麒(#huang)","2026-07-09 16:45:00","","","","黄燚麒","2026-07-09 16:46:08","","","",""
|
||||
"48 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","根据不同的资产使用不同的支付方式","C端支付时,卡资产只允许支付宝支付以及钱包支付,如果用微信支付就拒绝,设备只允许微信支付以及钱包支付,如果用支付宝支付就拒绝","","1 ","0 ","","1(#1)","1.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:56:52","黄燚麒","2026-07-09 16:45:21","","
|
||||
黄燚麒(#huang)","2026-07-09 16:45:00","","","","黄燚麒","2026-07-09 16:45:21","","","",""
|
||||
"47 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","限速规则","根据不同运营商限速规则，基于套餐流量设置不同的卡/设备的限速规则","","1 ","0 ","","3(#3)","4.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:54:39","黄燚麒","2026-07-09 17:30:42","","
|
||||
黄燚麒(#huang)","2026-07-09 17:27:00","","","","黄燚麒","2026-07-09 17:30:42","","","",""
|
||||
"46 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","资产信息详情字段新增","资产信息页面卡信息/设备信息板块，将当前生效套餐的过期时间作为一个字段显示且套餐还剩15天到期时该字段高亮显示。","","1 ","0 ","","2(#2)","1.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:52:36","黄燚麒","2026-07-09 17:25:53","","
|
||||
黄燚麒(#huang)","2026-07-09 17:25:00","","","","黄燚麒","2026-07-09 17:25:53","","","",""
|
||||
"45 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","换货管理","| 编号 | 需求 |
|
||||
| ------- | ---------------------------------------------------- |
|
||||
| EXC-001 | 修正换货列表旧资产标识和新资产标识显示混乱问题。 |
|
||||
| EXC-002 | 换货列表中旧资产标识符和新资产标识符均显示为 ICCID。 |
|
||||
| EXC-003 | 旧资产查询支持 ICCID、接入号、虚拟号。 |
|
||||
| EXC-004 | 新资产查询支持 ICCID、接入号、虚拟号。 |","","1 ","0 ","","1(#1)","3.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:51:13","黄燚麒","2026-07-09 16:44:46","","
|
||||
黄燚麒(#huang)","2026-07-09 16:44:00","","","","黄燚麒","2026-07-09 16:44:46","","","",""
|
||||
"44 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","列表字段新增","| 编号 | 模块 | 新增字段 |
|
||||
| ------- | ------------ | -------------- |
|
||||
| COL-001 | 退款管理列表 | 提交人、审批人 |
|
||||
| COL-002 | 代理充值列表 | 提交人、审批人 |
|
||||
| COL-003 | 换号管理列表 | 提交人 |","","1 ","0 ","","1(#1)","1.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:51:13","黄燚麒","2026-07-09 16:44:20","","
|
||||
黄燚麒(#huang)","2026-07-09 16:44:00","","","","黄燚麒","2026-07-09 16:44:20","","","",""
|
||||
"43 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","代理系列授权","| 编号 | 需求 |
|
||||
| ------- | ------------------------------------------------------------ |
|
||||
| AUT-001 | 代理系列授权-套餐列表中，添加授权套餐支持一次性多选分套餐。 |
|
||||
| AUT-002 | 授权套餐时展示建议售价。 |
|
||||
| AUT-003 | 授权套餐时展示公司成本价。 |
|
||||
| AUT-004 | 已分配套餐和未分配套餐需要明显区分。 |
|
||||
| AUT-005 | 新增代理系列授权时，选择套餐需明确显示当前代理已经被分配过的套餐。 |","","1 ","0 ","","2(#2)","5.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:51:13","黄燚麒","2026-07-09 17:25:42","","
|
||||
黄燚麒(#huang)","2026-07-09 17:12:00","","","","黄燚麒","2026-07-09 17:25:42","","","",""
|
||||
"42 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","导出功能","#### 6.8.1 lot 卡导出
|
||||
|
||||
##### 支持套餐临期30天内所有资产的导出。字段按照卡/设备的导出表进行导出。
|
||||
|
||||
| 编号 | 需求 |
|
||||
| -------- | ---------------------------- |
|
||||
| EXPD-001 | lot 卡导出字段新增套餐名称。 |
|
||||
| EXPD-002 | lot 卡导出字段新增使用流量。 |
|
||||
| EXPD-003 | lot 卡导出字段新增剩余流量。 |
|
||||
|
||||
#### 6.8.2 代理资金概况-预充值钱包流水导出
|
||||
|
||||
导出字段：
|
||||
|
||||
| 字段 | 说明 |
|
||||
| ------------------- | ------------------------------------------------------------ |
|
||||
| 店铺名称 | 代理店铺名称 |
|
||||
| 交易类型 | 充值、扣款、退款等 |
|
||||
| 交易金额 | 以元为单位 |
|
||||
| 状态 | 交易状态 |
|
||||
| 资产类型 | 卡/设备等 |
|
||||
| 资产标识 | ICCID/设备号等 |
|
||||
| 交易时间 | 流水生成时间 |
|
||||
| 交易前金额 | 交易前余额 |
|
||||
| 交易后金额 | 交易后余额 |
|
||||
| 购买套餐名称 | 资产此条扣款记录对应的套餐名称 |
|
||||
| 操作人 | 明确交易执行主体：代理账号 / 平台账号（明确账号名称） |
|
||||
| 交易 ID | 每一笔流水的全局唯一主键，彻底避免重复流水、对账串号、精准定位单条交易 |
|
||||
| 关联业务订单号 | 充值、扣款、退款等交易对应的原始业务订单编号 |
|
||||
| 交易渠道 / 支付方式 | 明确交易来源：余额支付等 |
|
||||
|
||||
#### 6.8.3 套餐列表导出
|
||||
|
||||
导出字段：
|
||||
|
||||
| 字段 |
|
||||
| -------------- |
|
||||
| 套餐编码 |
|
||||
| 套餐名称 |
|
||||
| 套餐系列名称 |
|
||||
| 套餐类型 |
|
||||
| 套餐时长(月) |
|
||||
| 套餐时长说明 |
|
||||
| 套餐周期类型 |
|
||||
| 套餐天数 |
|
||||
| 真流量额度(MB) |
|
||||
| 虚流量额度(MB) |
|
||||
| 是否启用虚流量 |
|
||||
| 虚流量比例 |
|
||||
| 流量重置周期 |
|
||||
| 到期时间基准 |
|
||||
| 成本价(元) |
|
||||
| 建议售价(元) |
|
||||
| 价格配置状态 |
|
||||
| 状态 |
|
||||
| 上架状态 |
|
||||
| 是否赠送套餐 |
|
||||
| 创建人ID |
|
||||
| 更新人ID |
|
||||
| 创建时间 |
|
||||
| 更新时间 |
|
||||
| 删除时间 |
|
||||
|
||||
#### 6.8.4 退款管理退款列表导出
|
||||
|
||||
导出字段：
|
||||
|
||||
| 字段 |
|
||||
| ---------------- |
|
||||
| 退款单号 |
|
||||
| 代理店铺名称 |
|
||||
| 关联的支付订单号 |
|
||||
| 资产类型 |
|
||||
| 资产标识 |
|
||||
| 套餐名称 |
|
||||
| 原订单金额 |
|
||||
| 实收金额 |
|
||||
| 可退金额 |
|
||||
| 申请退款金额 |
|
||||
| 实际退款金额 |
|
||||
| 退款到账方式 |
|
||||
| 状态 |
|
||||
| 退款原因 |
|
||||
| 备注 |
|
||||
| 审批备注 |
|
||||
| 退款申请时间 |
|
||||
| 退款完成时间 |
|
||||
| 提交人 |
|
||||
| 部门领导审批人 |
|
||||
| 财务审批人 |
|
||||
| 退款凭证 |
|
||||
|
||||
#### 6.8.5 换货管理导出
|
||||
|
||||
##### C端客户有自己的唯一标识码。换货管理可以针对该C端客户记录该客户换过几次设备或卡。同时资产本身也做换货标识。
|
||||
|
||||
导出字段：
|
||||
|
||||
| 字段 |
|
||||
| ------------ |
|
||||
| 换货单号 |
|
||||
| 换货类型 |
|
||||
| 换货原因 |
|
||||
| 问题描述 |
|
||||
| 旧资产类型 |
|
||||
| 旧资产标识符 |
|
||||
| 新资产标识符 |
|
||||
| 收货人姓名 |
|
||||
| 收货人电话 |
|
||||
| 收货地址 |
|
||||
| 快递公司 |
|
||||
| 快递单号 |
|
||||
| 状态 |
|
||||
| 创建人 |
|
||||
| 创建时间 |
|
||||
|
||||
#### 6.8.6 代理充值导出
|
||||
|
||||
导出字段：
|
||||
|
||||
| 字段 |
|
||||
| -------------- |
|
||||
| 充值单号 |
|
||||
| 店铺名称 |
|
||||
| 充值类型 |
|
||||
| 充值金额 |
|
||||
| 实付金额 |
|
||||
| 充值前余额 |
|
||||
| 充值后余额 |
|
||||
| 状态 |
|
||||
| 支付方式 |
|
||||
| 支付通道 |
|
||||
| 运营备注 |
|
||||
| 驳回原因 |
|
||||
| 创建时间 |
|
||||
| 支付时间 |
|
||||
| 完成时间 |
|
||||
| 提交人 |
|
||||
| 部门领导审批人 |
|
||||
| 财务审批人 |
|
||||
| 支付凭证 |
|
||||
| 备注 |","","1 ","0 ","","1(#1)","16.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:49:25","黄燚麒","2026-07-09 16:42:07","","
|
||||
黄燚麒(#huang)","2026-07-09 16:40:00","","","","黄燚麒","2026-07-09 16:42:07","","","",""
|
||||
"41 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","代理查询限制（类似酷蛙这种客户）","下级只能看到上级给的信息。api对接客户无法通过他的上级代理查到我们公司的信息。
|
||||
| 编号 | 需求 | | ------- | -------------------------------------------------------- | | API-001 | 支持配置代理 API 对接查询限制。下级客户/代理无法跨级查询 |
|
||||
","","1 ","0 ","","1(#1)","","草稿(#draft)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:49:25","李昕娉","2026-07-09 16:42:55","","","2026-07-11 14:24:00","","","","黄燚麒","2026-07-11 14:25:30","","","",""
|
||||
"40 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","套餐设计","| 编号 | 需求 |
|
||||
| ------- | ------------------------------------------ |
|
||||
| PKG-001 | 套餐需标准化管理。 |
|
||||
| PKG-002 | 套餐下架后，正在使用该套餐的客户仍可续费。 |
|
||||
| PKG-003 | 下架套餐续费仅支持客户自己购买。 |
|
||||
| PKG-004 | 下架套餐不可被新购买。 |","","1 ","0 ","","2(#2)","3.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:49:25","黄燚麒","2026-07-09 17:11:34","","
|
||||
黄燚麒(#huang)","2026-07-09 17:10:00","","","","黄燚麒","2026-07-09 17:11:34","","","",""
|
||||
"38 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","不同渠道额度处理","| 编号 | 需求 |
|
||||
| ------- | ------------------------------------------------------------ |
|
||||
| BPO-009 | 新建代理时新增“是否可授权额度”开关。平台用户账号默认拥有授权额度。 |
|
||||
| BPO-010 | 不同代理可设置不同额度下限。平台用户可根据不同的角色设置不同的额度下限。 |
|
||||
| BPO-011 | 授权额度用于订购套餐、代理余额充值等需要涉及金额的所有模块。 |
|
||||
| BPO-012 | 授权额度代理可显示负数余额。平台用户也可显示负数余额。 |","","1 ","0 ","","2(#2)","16.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:49:25","黄燚麒","2026-07-09 16:58:16","","
|
||||
黄燚麒(#huang)","2026-07-09 16:57:00","","","","黄燚麒","2026-07-09 16:58:16","","","",""
|
||||
"37 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","审核流转","| 编号 | 需求 |
|
||||
| ------- | ------------------------------------------------------------ |
|
||||
| APR-001 | 代理可在系统提交充值申请。 |
|
||||
| APR-002 | 提交充值申请后系统展示收款二维码，代理扫码支付。 |
|
||||
| APR-003 | 充值和退款均支持多级审核。 |
|
||||
| APR-004 | 审核环节包括提交人部门领导审核和财务审核。 |
|
||||
| APR-005 | 待审核订单需有消息提示。 |
|
||||
| APR-006 | 审核提醒按流程环节触发，上一审批人完成审批后才提示下一审批人。 |
|
||||
| APR-007 | 审核通过后通知申请人。 |
|
||||
| APR-008 | 审核驳回后通知申请人，并附带驳回原因。 |
|
||||
| APR-009 | 审核流程需对接企业微信审批流程。 |","","1 ","0 ","","2(#2)","24.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:49:25","黄燚麒","2026-07-09 16:57:35","","
|
||||
黄燚麒(#huang)","2026-07-09 16:57:00","","","","黄燚麒","2026-07-09 16:57:35","","","",""
|
||||
"36 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","批量订购套餐","1. 内部员工进入批量订购页面。
|
||||
2. 选择代理、ICCID号段/设备号、订购套餐。或上传 Excel 文件，资产标识支持 ICCID/设备号
|
||||
3. Excel表头：跳转至6.3会显示。
|
||||
4. 系统校验导入文件和资产状态。
|
||||
5. 校验通过的资产从代理余额扣款并完成订购。
|
||||
6. 校验失败的明细在页面展示失败原因。
|
||||
7. 系统记录操作员、导入明细、导入数量和导入时间。
|
||||
|
||||
| 编号 | 需求 |
|
||||
| ------- | ---------------------------------------------------- |
|
||||
| BPO-001 | 批量订购由内部员工操作。 |
|
||||
| BPO-002 | 支持代理自行充值钱包后，由员工批量订购并从余额扣款。 |
|
||||
| BPO-003 | 支持员工代充值至代理余额后，再批量订购并从余额扣款。 |
|
||||
| BPO-004 | 批量订购无需审核。 |
|
||||
| BPO-005 | 资产标识支持 ICCID/设备号。 |
|
||||
| BPO-006 | 支持 Excel 模板导入。 |
|
||||
| BPO-007 | 需记录操作员、导入明细、导入数量和导入时间。 |
|
||||
| BPO-008 | 导入失败明细需展示在页面，并显示失败原因。 |
|
||||
|
||||
excel表导入字段：
|
||||
| 字段 |
|
||||
| ----------------------------- |
|
||||
| 资产类型 |
|
||||
| 资产标识 |
|
||||
| 套餐系列名称 |
|
||||
| 套餐名称 |
|
||||
| 代理名称 |
|
||||
| 支付方式：代理商账户/员工账户 |","","1 ","0 ","","1(#1)","4.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:49:25","黄燚麒","2026-07-09 16:31:53","","
|
||||
黄燚麒(#huang)","2026-07-09 16:31:00","","","","黄燚麒","2026-07-09 16:31:53","","","",""
|
||||
"35 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","退款审核","（审批均可通过企微进行提醒和显示并将最新状态同步至卡管）
|
||||
1. 员工提交退款申请。
|
||||
2. 退款单进入多级审核流程。
|
||||
3. 按部门领导、财务顺序审批。
|
||||
4. 当前环节审批完成后，下一环节审批人收到消息提示。
|
||||
5. 审批通过或驳回后通知申请人。","","1 ","0 ","","2(#2)","24.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:49:25","黄燚麒","2026-07-09 16:56:31","","
|
||||
黄燚麒(#huang)","2026-07-09 16:55:00","","","","黄燚麒","2026-07-09 16:56:31","","","",""
|
||||
"34 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","充值审核流程","代理自己充值：
|
||||
1. 代理在系统提交充值申请。
|
||||
2. 系统展示收款二维码。
|
||||
3. 代理扫码支付。
|
||||
|
||||
员工代充值：（审批均可通过企微进行提醒和显示并将最新状态同步至卡管）
|
||||
1. 充值单进入多级审核流程。
|
||||
2. 提交人部门领导先审批。
|
||||
3. 财务在上一审批人通过后收到待办提醒并审批。
|
||||
4. 审批通过后通知申请人。
|
||||
5. 审批驳回后通知申请人，并展示驳回原因。","","1 ","0 ","","2(#2)","32.00 ","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:49:25","黄燚麒","2026-07-09 16:55:42","","
|
||||
黄燚麒(#huang)","2026-07-09 16:55:00","","","","黄燚麒","2026-07-09 16:55:42","","","",""
|
||||
"33 ","物联网卡管系统(#2)","/(#0)","7月份迭代计划 [2026-07-10 ~ 2026-07-31](#1)","","","套餐临期提醒","1. 系统每日计算卡/设备套餐剩余有效期。
|
||||
2. 命中临期规则后生成临期数据。临期提醒规则：按 15 天、7 天、3 天节点分别进行不同方式的提醒。
|
||||
3. 企业客户场景：按 15 天、7 天、3 天节点生成临期列表，并通过企业微信推送给对应业务员。
|
||||
4. 代理端场景（展示）：首页展示卡、设备临期数量；资产列表按临期天数高亮。
|
||||
5. C 端场景（展示）：公众号首页在套餐剩余有效期小于或等于 15天时展示续费提醒，并显示立即续费按钮。
|
||||
6. 当资产续费成功或不再满足临期条件时，临期提醒自动取消。
|
||||
#### 6.1.1 企业客户临期提醒
|
||||
| 编号 | 需求 |
|
||||
| ------- | ------------------------------------------------------------ |
|
||||
| EXP-001 | 后台每日生成企业客户临期列表。 |
|
||||
| EXP-002 | 临期节点包括 15 天、7 天、3 天。 |
|
||||
| EXP-003 | 系统需对接企业微信，将临期列表推送给对应业务员。 |
|
||||
| EXP-004 | 同一资产在不同临期节点可重复触发对应节点提醒，但同一节点每日不可重复推送给同一业务员。 |
|
||||
|
||||
#### 6.1.2 代理端临期提醒
|
||||
|
||||
| 编号 | 需求 |
|
||||
| ------- | ------------------------------------------------------------ |
|
||||
| EXP-005 | 代理端首页分别展示临期卡数量和临期设备数量。 |
|
||||
| EXP-006 | 代理端资产列表对临期资产进行颜色标记。 |
|
||||
| EXP-007 | 剩余 15 天标记为粉色，剩余 7 天标记为紫色，剩余 3 天标记为红色。 |
|
||||
| EXP-008 | 剩余 3 天资产在列表中置顶优先展示。 |
|
||||
|
||||
#### 6.1.3 C 端公众号首页提醒
|
||||
|
||||
| 编号 | 需求 |
|
||||
| ------- | ------------------------------------------------------------ |
|
||||
| EXP-009 | 当客户套餐剩余有效期小于或等于 15 天时，公众号首页展示套餐到期提醒。 |
|
||||
| EXP-010 | 提醒展示卡号/设备号、剩余有效期和续费引导文案。 |
|
||||
| EXP-011 | 按钮文案为“立即续费”。 |
|
||||
| EXP-012 | 剩余天数需要按日期每天自动更新。 |
|
||||
| EXP-013 | 当套餐已续费或不再满足临期条件时，提醒不再展示。 |
|
||||
推荐展示文案：
|
||||
您的套餐即将到期
|
||||
|
||||
卡号/设备号：xxx
|
||||
剩余有效期：xx 天
|
||||
|
||||
为避免到期后影响正常使用，请您提前完成续费。","","1 ","0 ","","1(#1)","","激活(#active)","已计划(#planned)","功能(#feature)","","","","李昕娉","2026-07-08 15:49:25","黄燚麒","2026-07-09 16:30:06","","
|
||||
黄燚麒(#huang)","2026-07-09 16:29:00","","","","黄燚麒","2026-07-09 16:30:06","","","",""
|
||||
|
@@ -1,6 +1,7 @@
|
||||
# 7月迭代前端技术方案
|
||||
|
||||
> 状态：待评审
|
||||
> 历史状态：共性前端来源稿；本地审批交互已废弃，最终以前端标准章节和各独立方案为准。
|
||||
> 当前方案：[标准评审稿](../../7月迭代技术方案-标准评审稿.md)。
|
||||
> 适用端：后台管理端、代理端、C 端 H5/公众号
|
||||
> 最后更新：2026-07-14
|
||||
> 说明：当前仓库不包含前端源码，本文定义页面、交互和接口契约；实际目录、状态库和组件名称由前端仓库现状映射，禁止据此凭空更换前端技术栈。
|
||||
@@ -1,6 +1,7 @@
|
||||
# 基础设施：通用审批流领域
|
||||
|
||||
> 状态：待评审
|
||||
> 历史状态：已废弃，仅保留用于追溯本地审批引擎方案；当前采用企业微信审批。
|
||||
> 替代方案：[企业微信审批独立稿](../新增需求/02-企业微信审批接入.md) 和 [标准评审稿](../../7月迭代技术方案-标准评审稿.md)。
|
||||
> 被依赖：需求 18（多人审批）、需求 20（退款审批）、需求 21（充值审核）
|
||||
> 范围变更：需求16已于2026-07-14移出本期，代理申请不在第一版接入范围
|
||||
> 架构：DDD，`internal/domain/approval/` + `internal/application/approval/`
|
||||
@@ -1068,7 +1069,7 @@ ALTER TABLE tb_xxx ADD COLUMN approval_instance_id BIGINT;
|
||||
|
||||
## 十二、前端技术方案
|
||||
|
||||
跨需求共性规则见 [7月迭代前端技术方案](../前端技术方案.md)，本节只描述审批流专项。
|
||||
历史跨需求规则见 [前端共性方案历史稿](./前端共性方案-历史稿.md)，本节只保留旧审批流设计。
|
||||
|
||||
### 12.1 页面与路由
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# 基础设施：站内消息（Notification）
|
||||
|
||||
> 状态：待评审
|
||||
> 历史状态：初版方案，已被站内通知详细方案替代。
|
||||
> 替代方案：[站内通知详细方案](../新增需求/03-站内通知详细方案.md) 和 [标准评审稿](../../7月迭代技术方案-标准评审稿.md)。
|
||||
> 被依赖：需求 18/20/21（审批流通知）、需求 22（临期提醒）
|
||||
> Phase 2 扩展：企业微信推送、短信通知（预留插拔接口）
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 需求01：行业卡后台手动复机允许未实名
|
||||
|
||||
> 状态：待评审
|
||||
> 状态：原需求来源稿；实名最终规则已由数据同步方案和标准评审稿修正。
|
||||
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 需求02：H5 流程顺序配置化
|
||||
|
||||
> 状态：待评审
|
||||
> 状态：原需求独立稿；最终口径以标准评审稿为准。
|
||||
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 需求03/07/11/12/13：简单改动合集
|
||||
|
||||
> 状态：待评审
|
||||
> 状态：原需求独立稿；最终口径以标准评审稿为准。
|
||||
|
||||
---
|
||||
|
||||
@@ -145,36 +145,21 @@ IoT卡管理筛选栏新增"实名状态"下拉（全部/已实名/未实名）
|
||||
|
||||
---
|
||||
|
||||
## 需求11：资产详情-套餐到期时间字段 + 15天高亮
|
||||
## 需求11：资产详情套餐到期时间（与需求06合并）
|
||||
|
||||
### 后端
|
||||
需求11和需求06属于同一业务需求：资产层只展示当前及排队主套餐连续使用后的预计最终到期时间。详细计算、DTO 和前端规则统一见[需求04/06独立稿](./需求04-06-退款拦截与最后到期时间.md)。
|
||||
|
||||
**无需改动。**
|
||||
现有 `current_package_expires_at` 只表示当前套餐结束时间，不能代表资产服务最终结束时间，因此不得继续作为资产详情汇总到期时间或临期判断依据。
|
||||
|
||||
后台资产详情页实际调用的是：
|
||||
统一使用：
|
||||
|
||||
```
|
||||
GET /api/admin/assets/resolve/:identifier
|
||||
```text
|
||||
estimated_final_expires_at
|
||||
days_until_final_expiry
|
||||
expiry_estimate_status
|
||||
```
|
||||
|
||||
该接口的 `AssetResolveResponse`（`internal/model/dto/asset_dto.go`）已包含：
|
||||
|
||||
```go
|
||||
CurrentPackage string `json:"current_package"` // 当前套餐名称
|
||||
CurrentPackageActivatedAt *time.Time `json:"current_package_activated_at"` // 开始时间
|
||||
CurrentPackageExpiresAt *time.Time `json:"current_package_expires_at"` // 到期时间（无套餐为 null）
|
||||
```
|
||||
|
||||
到期时间字段已有，前端直接读 `current_package_expires_at` 即可，不需要新增后端字段。
|
||||
|
||||
### 前端
|
||||
|
||||
资产详情页"套餐信息"板块展示到期时间，并在剩余 ≤15 天时高亮：
|
||||
|
||||
- 读取 `resolve` 接口返回的 `current_package_expires_at`
|
||||
- 若为 `null`：展示"暂无套餐"
|
||||
- 剩余天数由前端计算：`Math.ceil((expiresAt - now) / 86400000)`
|
||||
- 剩余 ≤15 天：**红色/高亮**展示（建议红色文字 + 标签）
|
||||
前端不自行计算天数；高亮颜色和临期状态直接使用需求22统一返回字段。
|
||||
|
||||
---
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 需求04：退款中资产禁止换货
|
||||
# 需求06：资产最后到期时间
|
||||
# 需求06/11：资产预计最终到期时间
|
||||
|
||||
> 状态：待评审
|
||||
> 状态：原需求独立稿；最终口径以标准评审稿为准。
|
||||
|
||||
---
|
||||
|
||||
@@ -111,11 +111,11 @@ func (s *ExchangeService) validateNoActiveRefund(ctx context.Context, asset *res
|
||||
|
||||
---
|
||||
|
||||
## 需求06：资产详情-所有套餐的最后到期时间
|
||||
## 需求06/11：资产详情-预计最终到期时间
|
||||
|
||||
### 业务规则
|
||||
|
||||
资产详情页展示：**当前生效主套餐 + 所有待生效主套餐按队列接续后的预计最后到期时间**。
|
||||
需求06与需求11是同一个业务需求的两种描述，不再拆成“当前套餐到期”和“所有套餐最后到期”两个资产汇总字段。资产详情页只展示：**当前生效主套餐 + 所有待生效主套餐按队列接续后的预计最终到期时间**。
|
||||
|
||||
不能只取已经写入 `expires_at` 的最大值。排队套餐通常尚未激活，`expires_at` 为空，但其购买时的周期和时长已经确定，正常情况下仍可推算最终到期时间。
|
||||
|
||||
@@ -131,15 +131,16 @@ GET /api/admin/assets/resolve/:identifier
|
||||
|
||||
响应 DTO：`AssetResolveResponse`（`internal/model/dto/asset_dto.go`）
|
||||
|
||||
该 DTO 目前**不含** `last_package_expires_at` 字段，需新增。
|
||||
该 DTO 目前只有当前套餐到期时间，需新增统一的最终到期响应，并由前端替代原资产汇总展示。
|
||||
|
||||
### 后端
|
||||
|
||||
**DTO 新增字段**（`internal/model/dto/asset_dto.go` → `AssetResolveResponse`）：
|
||||
|
||||
```go
|
||||
// 当前主套餐及排队主套餐接续后的预计最后到期时间，无可推算套餐时为 null
|
||||
LastPackageExpiresAt *time.Time `json:"last_package_expires_at" description:"当前主套餐及排队主套餐接续后的预计最后到期时间，无可推算套餐时为null"`
|
||||
EstimatedFinalExpiresAt *time.Time `json:"estimated_final_expires_at" description:"当前及排队主套餐接续后的预计最终到期时间"`
|
||||
DaysUntilFinalExpiry *int `json:"days_until_final_expiry" description:"预计最终剩余自然日"`
|
||||
ExpiryEstimateStatus string `json:"expiry_estimate_status" description:"推算状态 (exact:可推算, waiting_activation:等待未知激活时间, none:无套餐)"`
|
||||
```
|
||||
|
||||
**Store 新增方法**（`internal/store/postgres/package_usage_store.go`）：
|
||||
@@ -187,17 +188,19 @@ lastExpiry, err := s.packageUsageStore.ProjectLastMainPackageExpiry(ctx, assetTy
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
resp.LastPackageExpiresAt = lastExpiry
|
||||
resp.EstimatedFinalExpiresAt = lastExpiry
|
||||
```
|
||||
|
||||
`ProjectLastMainPackageExpiry` 是 Query 计算，不写快照表：当前主套餐到期时间变化、排队套餐新增/退款失效后，下一次详情查询立即反映。若资产没有当前套餐且队首套餐仍等待无法预测的外部前置条件（例如尚未实名），返回 `null`，前端显示“—”，不伪造日期。
|
||||
|
||||
### 前端
|
||||
|
||||
资产详情"套餐信息"板块新增展示：
|
||||
资产详情“套餐信息”板块只保留一个资产汇总展示：
|
||||
|
||||
```
|
||||
预计最后到期时间：2027-01-01
|
||||
预计套餐到期时间：2027-01-01
|
||||
```
|
||||
|
||||
读取 `resolve` 接口返回的 `last_package_expires_at`，有值则展示，无值（无套餐）展示"—"。
|
||||
读取 `estimated_final_expires_at`。`exact` 时展示日期；`waiting_activation` 时展示“待激活后起算”；`none` 时展示“—”。当前套餐自身的 `expires_at` 仅在套餐明细列表展示，不再作为第二个资产汇总字段。
|
||||
|
||||
高亮和临期提醒统一使用 `days_until_final_expiry`，前端不得再根据 `current_package_expires_at` 自行计算另一套剩余天数。
|
||||
@@ -1,6 +1,6 @@
|
||||
# 需求05：套餐分配生效条件（ExpiryBase 覆盖）
|
||||
|
||||
> 状态：待评审
|
||||
> 状态：原需求独立稿；最终口径以标准评审稿为准。
|
||||
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 需求08：设备批量分配代理或套餐系列（Excel导入）
|
||||
|
||||
> 状态：待评审
|
||||
> 状态：原需求独立稿；最终口径以标准评审稿为准。
|
||||
> 模板：前端静态资源，后端仅负责上传校验和异步处理。
|
||||
|
||||
---
|
||||
@@ -1,7 +1,7 @@
|
||||
# 需求09：C端支付方式限制配置化
|
||||
|
||||
> 状态：待评审
|
||||
> 依赖：[系统配置](./基础设施/系统配置.md)
|
||||
> 状态：原需求独立稿；最终口径以标准评审稿为准。
|
||||
> 依赖：[系统配置](../基础规范/系统配置.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 需求10：Gateway 手动卡限速
|
||||
|
||||
> 状态：待评审
|
||||
> 状态：原需求独立稿；最终口径以标准评审稿为准。
|
||||
> 已确认边界：本期只提供手动设置/取消限速；Gateway 最终对象始终是卡，统一使用 `cardNo`。
|
||||
|
||||
---
|
||||
@@ -1,6 +1,6 @@
|
||||
# 需求14：导出功能
|
||||
|
||||
> 状态：待评审
|
||||
> 状态：原需求独立稿；最终口径以标准评审稿为准。
|
||||
> 复用现有 ExportTask 体系（`tb_export_task` + Asynq），不为每个业务模块新增一套导出路由。
|
||||
|
||||
---
|
||||
@@ -1,6 +1,6 @@
|
||||
# 需求15/16/18/19/20/21 技术方案
|
||||
|
||||
> 状态：待评审
|
||||
> 状态：原需求来源稿；其中本地审批流、审批页面和操作密码方案已废弃，最终以企微审批方案和标准评审稿为准。
|
||||
> 评审建议：需求 15/16、需求 18/20/21、需求 19 分三组评审，不在一次会议中混合确认。
|
||||
|
||||
---
|
||||
@@ -95,7 +95,7 @@ C端资产详情/当前套餐卡片：在当前套餐旁提供“续费”按钮
|
||||
|
||||
### 依赖
|
||||
|
||||
基于 [审批流基础设施](./基础设施/审批流.md) 和 [站内消息](./基础设施/站内消息.md)。
|
||||
历史设计基于 [已废弃的本地审批流](../历史方案/本地通用审批流-已废弃方案.md) 和 [站内消息初版](../历史方案/站内消息-初版.md)。
|
||||
|
||||
APR-009（企微审批对接）= Phase 2。
|
||||
|
||||
@@ -145,13 +145,13 @@ sequenceDiagram
|
||||
|
||||
充值单和退款单接入审批流，各自新增 `approval_instance_id` 字段。具体增量 DDL 与业务处理状态字段分别在需求 20、需求 21 中定义，迁移文件只能创建一次。
|
||||
|
||||
业务表只保存当前审批实例 ID，历史实例通过 `biz_type + biz_id` 查询。接入协议详见 [审批流文档 - 业务接入协议](./基础设施/审批流.md#十一业务接入协议)。
|
||||
本段是历史设计。旧接入协议见 [本地通用审批流 - 业务接入协议](../历史方案/本地通用审批流-已废弃方案.md#十一业务接入协议)。
|
||||
|
||||
退款和充值详情统一返回 `approval_source=none|workflow|legacy`。代理在线充值等无需审批的记录返回 `none`；发布前已经结束且没有流程实例的历史审批记录返回 `legacy` 并只读展示；发布时仍待审批的退款和员工线下充值必须在维护窗口回填流程实例。
|
||||
|
||||
### 前端技术方案
|
||||
|
||||
- 新增“待我审批”和动态审批详情，具体页面、状态和请求幂等规则见 [前端技术方案](./前端技术方案.md#六统一审批交互)。
|
||||
- 历史前端交互见 [前端共性方案历史稿](../历史方案/前端共性方案-历史稿.md#六统一审批交互)；当前已改为企微审批只读页面。
|
||||
- 退款、充值列表只展示审批摘要；审批详情首屏展示发起时固化的业务关键字段和业务资料，随后展示完整审批人、意见和历史实例。
|
||||
- 每次通过、驳回、退回分别保存审批意见和可选附件；驳回、退回意见必填，附件不与退款/充值业务凭证混用。
|
||||
- 时间线必须能查看此前审批人的动作、时间、意见和审批附件；业务资料与审批附件分区展示。
|
||||
@@ -325,7 +325,7 @@ GET /api/admin/bulk-purchases/{task_id}/items?status=4&page=1&page_size=50
|
||||
|
||||
### 依赖
|
||||
|
||||
基于 [审批流基础设施](./基础设施/审批流.md)。
|
||||
本段历史设计基于 [已废弃的本地审批流](../历史方案/本地通用审批流-已废弃方案.md)。
|
||||
|
||||
### 退款单现有状态（不变）
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 需求17：信用额度
|
||||
|
||||
> 状态：待评审
|
||||
> 状态：原需求独立稿；最终口径以标准评审稿为准。
|
||||
> DDD 范围：仅迁移代理主钱包的复杂写用例，资金列表和统计继续走 Query
|
||||
> 关联需求：BPO-009~012、需求19批量订购
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
平台员工信用额度不实施，原因如下：
|
||||
|
||||
- 平台员工是操作主体，不是订单结算主体；实际付款方只能是代理钱包或线下支付主体。
|
||||
- 角色表达权限范围，不表达资产、余额和债务，给角色配置资金会混淆 RBAC 与财务账本。
|
||||
- 客户角色可以保存“新建店铺默认额度”模板，但角色本身不持有余额和债务；实际额度仍写入代理主钱包。
|
||||
- 系统不存在员工钱包、员工充值、员工还款和离职债务交接链路，负余额无法对账和追责。
|
||||
- 批量订购已经明确由代理钱包扣款或使用线下支付，不存在必须从员工个人额度扣款的业务场景。
|
||||
- 引入员工信用会与代理钱包形成两套资金来源，增加订单归属、退款去向和审计解释成本，但不产生实际业务价值。
|
||||
@@ -45,9 +45,12 @@ flowchart TD
|
||||
Tx --> Success[返回扣款后余额]
|
||||
```
|
||||
|
||||
### 2.2 信用开关
|
||||
### 2.2 角色默认与店铺实际额度
|
||||
|
||||
- 创建代理时可以提交 `enable_credit` 和 `credit_limit`。
|
||||
- 客户角色可以配置 `default_credit_enabled` 和 `default_credit_limit`，作为以后新建店铺的默认值。
|
||||
- 新建店铺时读取请求中的 `default_role_id`，将该角色当时的默认配置复制到新建主钱包。
|
||||
- 修改角色默认值不更新任何已有店铺，也不批量扫描钱包。
|
||||
- 已有店铺通过独立资金接口直接修改实际额度；店铺后续角色变化不影响钱包。
|
||||
- 关闭开关时额度必须为 0。
|
||||
- 打开开关时额度必须大于 0。
|
||||
- 修改额度前必须校验修改后的可用金额不为负，而不是只判断 `balance >= 0`。
|
||||
@@ -56,15 +59,21 @@ flowchart TD
|
||||
|
||||
## 三、数据库变更
|
||||
|
||||
信用额度属于钱包，不在 `tb_shop` 和 `tb_agent_wallet` 各保存一份，避免双写失真。创建/编辑代理接口可以接收信用参数，但最终权威数据写入代理主钱包。
|
||||
角色字段只是新建店铺模板，不参与运行时扣款。创建店铺后，最终权威数据只读取代理主钱包；修改角色默认值不会产生角色与钱包双写同步。
|
||||
|
||||
```sql
|
||||
ALTER TABLE tb_agent_wallet
|
||||
ADD COLUMN credit_enabled BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
ADD COLUMN credit_limit BIGINT NOT NULL DEFAULT 0;
|
||||
|
||||
ALTER TABLE tb_role
|
||||
ADD COLUMN default_credit_enabled BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
ADD COLUMN default_credit_limit BIGINT NOT NULL DEFAULT 0;
|
||||
|
||||
COMMENT ON COLUMN tb_agent_wallet.credit_enabled IS '是否启用信用额度，仅主钱包有效';
|
||||
COMMENT ON COLUMN tb_agent_wallet.credit_limit IS '信用额度上限（分），仅主钱包有效';
|
||||
COMMENT ON COLUMN tb_role.default_credit_enabled IS '新建代理店铺是否默认启用信用额度，仅客户角色有效';
|
||||
COMMENT ON COLUMN tb_role.default_credit_limit IS '新建代理店铺默认信用额度（分），仅客户角色有效';
|
||||
|
||||
ALTER TABLE tb_agent_wallet
|
||||
DROP CONSTRAINT IF EXISTS chk_agent_wallet_frozen_balance;
|
||||
@@ -173,7 +182,19 @@ WHERE id = ?
|
||||
|
||||
受影响行数为 0 时，重新读取钱包以区分并发冲突和额度低于当前欠款。
|
||||
|
||||
### 5.2 钱包扣款
|
||||
### 5.2 修改角色默认信用额度
|
||||
|
||||
```text
|
||||
Handler
|
||||
→ UpdateRoleDefaultCreditUseCase
|
||||
→ 校验角色为客户角色
|
||||
→ 校验开关和额度组合
|
||||
→ 只更新 tb_role 默认模板
|
||||
→ 写角色配置审计
|
||||
→ 不查询、不更新已有店铺钱包
|
||||
```
|
||||
|
||||
### 5.3 钱包扣款
|
||||
|
||||
所有现有主钱包扣款语句必须从：
|
||||
|
||||
@@ -190,7 +211,7 @@ CASE WHEN credit_enabled THEN credit_limit ELSE 0 END >= amount
|
||||
|
||||
扣款、版本递增和钱包流水必须在同一事务。禁止只修改 `GetAvailableBalance()` 而遗漏 Store 中的 SQL 条件，否则页面显示可用但实际仍无法扣款。
|
||||
|
||||
### 5.3 受影响用例
|
||||
### 5.4 受影响用例
|
||||
|
||||
- 后台订单和批量订购的代理钱包支付。
|
||||
- C端/代理端使用代理主钱包的订单支付。
|
||||
@@ -227,22 +248,20 @@ DebtAmount int64 `json:"debt_amount" description:"欠款金额（分）"`
|
||||
|
||||
## 七、API 设计
|
||||
|
||||
### 7.1 创建代理
|
||||
|
||||
现有：
|
||||
### 7.1 角色默认额度
|
||||
|
||||
```text
|
||||
POST /api/admin/shops
|
||||
PUT /api/admin/roles/{id}/default-credit
|
||||
```
|
||||
|
||||
新增参数：
|
||||
|
||||
```go
|
||||
EnableCredit bool `json:"enable_credit" description:"是否开启信用额度"`
|
||||
CreditLimit int64 `json:"credit_limit" validate:"min=0" description:"信用额度（分）"`
|
||||
type UpdateRoleDefaultCreditRequest struct {
|
||||
EnableCredit bool `json:"enable_credit" description:"新建店铺是否默认开启信用额度"`
|
||||
CreditLimit int64 `json:"credit_limit" validate:"min=0" description:"新建店铺默认信用额度（分）"`
|
||||
}
|
||||
```
|
||||
|
||||
Application 创建店铺和主钱包时，将信用配置写入钱包；任何一步失败整笔事务回滚。
|
||||
现有 `POST /api/admin/shops` 继续使用 `default_role_id`。Application 在创建店铺和主钱包的同一事务中读取角色默认值并复制到钱包；角色模板之后变化不影响该钱包。
|
||||
|
||||
### 7.2 修改信用额度
|
||||
|
||||
@@ -266,19 +285,20 @@ type UpdateCreditLimitRequest struct {
|
||||
|
||||
## 八、前端技术方案
|
||||
|
||||
### 8.1 创建/编辑代理
|
||||
### 8.1 角色管理
|
||||
|
||||
```text
|
||||
信用额度
|
||||
[开关] 允许使用信用额度
|
||||
授信上限 [金额输入，单位元]
|
||||
新建代理默认信用额度
|
||||
[开关] 默认允许使用信用额度
|
||||
默认授信上限 [金额输入，单位元]
|
||||
提示：修改后只影响以后新建的代理，不影响已有店铺
|
||||
```
|
||||
|
||||
- 开关关闭时清空输入并提交 `credit_limit=0`。
|
||||
- 金额输入使用分/元安全转换，不允许负数和小数精度超过两位。
|
||||
- 编辑代理基础资料不自动覆盖信用额度；信用调整使用独立权限和独立接口。
|
||||
- 仅客户角色展示该配置；平台角色不展示。
|
||||
|
||||
### 8.2 资金概况和详情
|
||||
### 8.2 店铺资金概况和详情
|
||||
|
||||
```text
|
||||
账面余额：-¥200.00
|
||||
@@ -291,6 +311,8 @@ type UpdateCreditLimitRequest struct {
|
||||
- 可用金额以接口值为准，不在前端自行重复计算。
|
||||
- 修改额度弹框展示当前余额、冻结金额、额度和修改后可用金额预览；提交后仍以后端校验为准。
|
||||
- 后端返回并发冲突时刷新钱包版本和最新金额，不保留旧计算结果。
|
||||
- 修改店铺角色、账号角色或角色默认额度都不能覆盖已有钱包额度。
|
||||
- 编辑代理基础资料不自动修改信用额度；信用调整使用独立权限和独立接口。
|
||||
|
||||
平台员工端不展示个人余额或个人信用额度。拥有信用额度管理权限的员工，只能在代理资金页面查看和调整代理主钱包额度。
|
||||
|
||||
@@ -319,9 +341,9 @@ type UpdateCreditLimitRequest struct {
|
||||
|
||||
本需求随七月迭代停机发布：
|
||||
|
||||
1. 维护窗口内先核对并调整钱包现有 CHECK 约束，再增加信用字段，历史数据默认关闭。
|
||||
1. 维护窗口内先核对并调整钱包现有 CHECK 约束，再增加钱包信用字段和角色默认模板字段，历史钱包默认关闭。
|
||||
2. 同时发布钱包聚合、全部主钱包扣款条件、查询字段和管理端信用配置页面，禁止只改余额展示而遗漏真实扣款 SQL。
|
||||
3. 开放访问前保持所有代理信用开关关闭，人工验证普通余额、信用扣款、并发冲突和额度调整。
|
||||
4. 系统开放后再由有权限的管理员对指定代理逐个开启额度。
|
||||
4. 系统开放后配置客户角色的新建默认额度；已有店铺需要授信时仍由管理员在店铺资金页面逐个设置。
|
||||
|
||||
尚未开启任何信用额度时可以回滚应用版本和可逆迁移。额度启用并产生负余额后，不能直接关闭信用或删除字段；必须先完成还款或保留当前资金逻辑，数据库字段和资金流水不做破坏性回滚。
|
||||
@@ -1,6 +1,6 @@
|
||||
# 需求22：套餐临期提醒
|
||||
|
||||
> 状态：待评审
|
||||
> 状态：原需求独立稿；最终口径以标准评审稿为准。
|
||||
|
||||
---
|
||||
|
||||
@@ -8,9 +8,9 @@
|
||||
|
||||
### 临期定义
|
||||
|
||||
当资产的**当前生效主套餐**（`PackageUsage.status=1`）按 `Asia/Shanghai` 自然日计算的剩余天数在 `0～15` 天时，该资产进入临期状态。
|
||||
当资产的当前生效主套餐与全部排队主套餐连续接续后的**预计最终剩余天数**按 `Asia/Shanghai` 自然日计算处于 `0～15` 天时，该资产进入临期状态。预计最终到期时间与需求06/11共用同一个 Query，不再维护“当前套餐临期”和“最终到期”两套口径。
|
||||
|
||||
资产有可接续的排队主套餐时不进入临期提醒，因为服务不会在当前套餐到期后中断；需求06仍会单独展示排队套餐接续后的“预计最后到期时间”。已过期资产不属于临期。
|
||||
没有生效套餐且队首套餐仍等待无法确定时间的实名激活时，返回不可预计状态，不进入临期。已过期资产不属于临期。
|
||||
|
||||
### 查询与通知职责
|
||||
|
||||
@@ -24,28 +24,27 @@
|
||||
|---------|------|
|
||||
| ≤ 15天 | 粉红色 |
|
||||
| ≤ 7天 | 紫色 |
|
||||
| ≤ 3天 | 黄色 |
|
||||
| ≤ 3天 | 红色 |
|
||||
|
||||
### 各端提醒规则
|
||||
|
||||
| 场景 | 提醒方式 | 触发节点 |
|
||||
|------|---------|---------|
|
||||
| **后台管理** | 列表加临期天数列 + 高亮；详情加临期字段（≤15天高亮） | 实时计算 |
|
||||
| **企业客户** | 企微推送（Phase 2）；后台每日生成临期列表 | 15天/7天/3天节点 |
|
||||
| **企业客户** | 对应店铺业务员接收站内通知；后台每日生成临期列表 | 15天/7天/3天节点 |
|
||||
| **代理端** | 首页展示临期卡/设备数量；列表高亮 | 实时计算 |
|
||||
| **C端公众号** | 套餐到期提醒模块（≤15天展示） | 实时展示 |
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Schedule[每日定时任务] --> Query[批量查询实时临期候选]
|
||||
Query --> QueueCheck{存在排队套餐?}
|
||||
QueueCheck -->|是| Skip[不进入临期提醒]
|
||||
QueueCheck -->|否| Days[计算剩余自然日]
|
||||
Schedule[每日定时任务] --> Query[计算预计最终到期时间]
|
||||
Query --> Predictable{可以推算?}
|
||||
Predictable -->|否| Skip[不进入临期提醒]
|
||||
Predictable -->|是| Days[计算最终剩余自然日]
|
||||
Days --> Node{命中 15/7/3 天节点?}
|
||||
Node -->|否| End[本次不发送]
|
||||
Node -->|是| Upsert[按资产+节点+接收人幂等写通知记录]
|
||||
Upsert --> Notification[站内消息]
|
||||
Upsert -. Phase 2 .-> WeCom[企业微信推送]
|
||||
```
|
||||
|
||||
---
|
||||
@@ -64,7 +63,7 @@ CREATE TABLE tb_expiry_push_record (
|
||||
asset_type VARCHAR(20) NOT NULL, -- iot_card | device
|
||||
asset_id BIGINT NOT NULL,
|
||||
recipient_id BIGINT NOT NULL,
|
||||
channel VARCHAR(20) NOT NULL, -- notification | wecom
|
||||
channel VARCHAR(20) NOT NULL, -- notification
|
||||
push_node INT NOT NULL, -- 推送节点（3/7/15天）
|
||||
event_id VARCHAR(64) NOT NULL,
|
||||
pushed_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
@@ -79,7 +78,7 @@ CREATE UNIQUE INDEX idx_expiry_push_event
|
||||
ON tb_expiry_push_record(event_id);
|
||||
```
|
||||
|
||||
同一资产可能对应多个业务员，唯一约束必须包含接收人和渠道；否则第一位业务员写入记录后会错误拦截其他接收人。`package_usage_id` 让同一资产续费生成新使用记录后可以再次触发 15/7/3 天提醒。站内消息和 Phase 2 企业微信都使用该表防重。
|
||||
同一资产可能同时通知代理主账号和店铺业务员，唯一约束必须包含接收人和渠道；否则第一位接收人写入记录后会错误拦截其他接收人。`package_usage_id` 让同一资产续费生成新使用记录后可以再次触发 15/7/3 天提醒。本期只使用站内通知渠道。
|
||||
|
||||
---
|
||||
|
||||
@@ -93,34 +92,14 @@ CREATE UNIQUE INDEX idx_expiry_push_event
|
||||
```go
|
||||
type IotCardListItem struct {
|
||||
// ...原有字段...
|
||||
DaysUntilExpiry *int `json:"days_until_expiry" description:"当前套餐剩余天数（无生效套餐为null）"`
|
||||
IsExpiring bool `json:"is_expiring" description:"是否临期（≤15天且无排队套餐）"`
|
||||
EstimatedFinalExpiresAt *time.Time `json:"estimated_final_expires_at,omitempty" description:"预计最终到期时间"`
|
||||
DaysUntilFinalExpiry *int `json:"days_until_final_expiry" description:"预计最终剩余天数"`
|
||||
ExpiryEstimateStatus string `json:"expiry_estimate_status" description:"推算状态"`
|
||||
IsExpiring bool `json:"is_expiring" description:"是否临期"`
|
||||
}
|
||||
```
|
||||
|
||||
**计算方式**（在 SQL 层计算，避免 N+1）：
|
||||
|
||||
```sql
|
||||
-- 列表查询时 JOIN PackageUsage 获取剩余天数
|
||||
SELECT
|
||||
ic.*,
|
||||
CASE
|
||||
WHEN pu.expires_at IS NULL THEN NULL
|
||||
WHEN (pu.expires_at AT TIME ZONE 'Asia/Shanghai')::date
|
||||
< (NOW() AT TIME ZONE 'Asia/Shanghai')::date THEN NULL
|
||||
WHEN EXISTS (
|
||||
SELECT 1 FROM tb_package_usage q
|
||||
WHERE q.iot_card_id = ic.id AND q.status = 0 AND q.deleted_at IS NULL
|
||||
) THEN NULL -- 有排队套餐，不临期
|
||||
ELSE (pu.expires_at AT TIME ZONE 'Asia/Shanghai')::date
|
||||
- (NOW() AT TIME ZONE 'Asia/Shanghai')::date
|
||||
END AS days_until_expiry
|
||||
FROM tb_iot_card ic
|
||||
LEFT JOIN tb_package_usage pu
|
||||
ON pu.iot_card_id = ic.id AND pu.status = 1 AND pu.deleted_at IS NULL
|
||||
```
|
||||
|
||||
`is_expiring` 由同一 SQL 表达式派生：`days_until_expiry IS NOT NULL AND days_until_expiry BETWEEN 0 AND 15`。设备查询复用同一规则，不能另写一套日期计算。
|
||||
列表 Query 批量加载当前和排队主套餐，复用需求06/11的周期、时长快照推算逻辑，禁止逐资产查询。`is_expiring` 由 `days_until_final_expiry BETWEEN 0 AND 15` 派生；设备和卡不得各写一套日期规则。
|
||||
|
||||
#### 资产列表筛选条件新增
|
||||
|
||||
@@ -138,8 +117,10 @@ type IotCardListRequest struct {
|
||||
新增字段：
|
||||
```go
|
||||
// AssetResolveResponse 追加
|
||||
DaysUntilExpiry *int `json:"days_until_expiry" description:"当前套餐剩余天数（无生效套餐或有排队套餐时为null）"`
|
||||
IsExpiring bool `json:"is_expiring" description:"是否临期（≤15天且无排队套餐）"`
|
||||
EstimatedFinalExpiresAt *time.Time `json:"estimated_final_expires_at,omitempty" description:"预计最终到期时间"`
|
||||
DaysUntilFinalExpiry *int `json:"days_until_final_expiry" description:"预计最终剩余天数"`
|
||||
ExpiryEstimateStatus string `json:"expiry_estimate_status" description:"推算状态"`
|
||||
IsExpiring bool `json:"is_expiring" description:"是否临期"`
|
||||
```
|
||||
|
||||
### 2. 新增临期列表接口（独立页面）
|
||||
@@ -157,7 +138,7 @@ type ExpiringAssetsRequest struct {
|
||||
ShopID *uint `query:"shop_id" description:"店铺ID"`
|
||||
ExpiresAtStart string `query:"expires_at_start" description:"到期时间起"`
|
||||
ExpiresAtEnd string `query:"expires_at_end" description:"到期时间止"`
|
||||
MaxDaysUntilExpiry *int `query:"max_days_until_expiry" description:"最大剩余天数（如15）"`
|
||||
MaxDaysUntilFinalExpiry *int `query:"max_days_until_final_expiry" description:"最大预计最终剩余天数（如15）"`
|
||||
Page int `query:"page" default:"1"`
|
||||
PageSize int `query:"page_size" default:"20"`
|
||||
}
|
||||
@@ -171,7 +152,7 @@ type ExpiringAssetItem struct {
|
||||
AssetStatus int `json:"asset_status"`
|
||||
ShopName string `json:"shop_name"`
|
||||
PackageName string `json:"package_name"`
|
||||
DaysUntilExpiry int `json:"days_until_expiry"`
|
||||
DaysUntilFinalExpiry int `json:"days_until_final_expiry"`
|
||||
ExpiresAt time.Time `json:"expires_at"`
|
||||
DataUsageMB int64 `json:"data_usage_mb"`
|
||||
RemainingDataMB int64 `json:"remaining_data_mb"`
|
||||
@@ -194,7 +175,7 @@ func (h *ExpiryReminderHandler) HandleExpiryReminder(ctx context.Context, t *asy
|
||||
continue
|
||||
}
|
||||
today := time.Now().In(shanghaiLocation).Format("2006-01-02") // shanghaiLocation 由 time.LoadLocation("Asia/Shanghai") 初始化
|
||||
for _, recipientID := range asset.SalesmanIDs {
|
||||
for _, recipientID := range asset.RecipientAccountIDs {
|
||||
eventID := fmt.Sprintf(
|
||||
"expiry:%d:%d:%d:%d:%s",
|
||||
asset.PackageUsageID, node, recipientID, asset.AssetID, today,
|
||||
@@ -255,8 +236,9 @@ scene=expiring_asset
|
||||
现有接口（`GET /api/c/v1/asset/info`，通过 query param 传资产标识）的响应 DTO `AssetInfoResponse`（`internal/model/dto/client_asset_dto.go`）新增字段：
|
||||
|
||||
```go
|
||||
DaysUntilExpiry *int `json:"days_until_expiry" description:"当前套餐剩余天数（≤15天时有值，有排队套餐时为null）"`
|
||||
IsExpiring bool `json:"is_expiring" description:"是否临期"`
|
||||
EstimatedFinalExpiresAt *time.Time `json:"estimated_final_expires_at,omitempty" description:"预计最终到期时间"`
|
||||
DaysUntilFinalExpiry *int `json:"days_until_final_expiry" description:"预计最终剩余天数"`
|
||||
IsExpiring bool `json:"is_expiring" description:"是否临期"`
|
||||
```
|
||||
|
||||
前端逻辑：`is_expiring=true` 时展示续费提醒模块：
|
||||
@@ -279,10 +261,10 @@ IsExpiring bool `json:"is_expiring" description:"是否临期"`
|
||||
### 资产列表（IoT卡管理 / 设备管理）
|
||||
|
||||
1. 列表新增"剩余天数"列
|
||||
2. 根据 `days_until_expiry` 高亮行：
|
||||
2. 根据 `days_until_final_expiry` 高亮行：
|
||||
- ≤ 15天：行背景粉红色
|
||||
- ≤ 7天：行背景紫色
|
||||
- ≤ 3天：行背景黄色
|
||||
- ≤ 3天：行背景红色
|
||||
3. 筛选条件新增"临期天数"（下拉：≤15天/≤7天/≤3天）
|
||||
- 选中后传 `expiring_within_days=15`
|
||||
|
||||
@@ -298,6 +280,8 @@ IsExpiring bool `json:"is_expiring" description:"是否临期"`
|
||||
操作：导出按钮 → `POST /api/admin/export-tasks`，`scene=expiring_asset`
|
||||
```
|
||||
|
||||
临期独立列表将 `days_until_final_expiry <= 3` 的资产置顶，再按预计最终到期时间升序。普通卡列表和设备列表只按颜色高亮，不改变原有排序。
|
||||
|
||||
### 代理端首页
|
||||
|
||||
在首页数据接口新增字段（需要确认代理端首页接口）：
|
||||
@@ -1,6 +1,6 @@
|
||||
# 项目 DDD 设计规范
|
||||
|
||||
> 状态：待评审
|
||||
> 状态：项目渐进迁移规范；7月迭代标准稿已采用。
|
||||
> 务实型 DDD——不是学院派，不强制 Event Sourcing，不追求完美，追求可维护、可扩展、AI 辅助友好。
|
||||
> 基准文档：`docs/改造方向.md`（绞杀者模式）
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 基础设施：系统配置（tb_system_config）
|
||||
|
||||
> 状态：待评审
|
||||
> 状态：独立方案来源稿；最终口径以7月迭代标准评审稿为准。
|
||||
> 被依赖：需求 09（C端支付限制）
|
||||
|
||||
---
|
||||
@@ -1,7 +1,7 @@
|
||||
# 新增需求 01：数据同步触发与轮询优化
|
||||
|
||||
> 状态：已合并至标准评审稿，本文保留为实施明细。
|
||||
> 评审主文档：`../7月迭代技术方案-标准评审稿.md`
|
||||
> 评审主文档：`../../7月迭代技术方案-标准评审稿.md`
|
||||
> 范围：IoT 卡实名、流量、网络状态和设备实时数据同步。
|
||||
|
||||
## 一、已确认决策
|
||||
@@ -1,7 +1,7 @@
|
||||
# 新增需求 02：企业微信审批接入
|
||||
|
||||
> 状态：已合并至标准评审稿，本文保留为实施明细。
|
||||
> 评审主文档：`../7月迭代技术方案-标准评审稿.md`
|
||||
> 评审主文档：`../../7月迭代技术方案-标准评审稿.md`
|
||||
> 范围：退款审批、平台员工线下充值审批，以及企业微信模板配置、回调和轮询补偿。
|
||||
|
||||
## 一、已确认决策
|
||||
@@ -1,7 +1,7 @@
|
||||
# 新增需求 03：站内通知详细方案
|
||||
|
||||
> 状态：已合并至标准评审稿，本文保留为实施明细。
|
||||
> 评审主文档：`../7月迭代技术方案-标准评审稿.md`
|
||||
> 评审主文档：`../../7月迭代技术方案-标准评审稿.md`
|
||||
> 范围：后台账号、代理账号、企业账号和个人客户的站内通知。
|
||||
|
||||
## 一、定位
|
||||
@@ -1,7 +1,7 @@
|
||||
# 新增需求 04：全局多视角审计方案
|
||||
|
||||
> 状态：已合并至标准评审稿，本文保留为实施明细。
|
||||
> 评审主文档：`../7月迭代技术方案-标准评审稿.md`
|
||||
> 评审主文档：`../../7月迭代技术方案-标准评审稿.md`
|
||||
> 范围：全系统业务写操作、安全操作、外部集成和审计查询前端。
|
||||
|
||||
## 一、目标
|
||||
@@ -1,7 +1,7 @@
|
||||
# 新增需求 05：代理钱包扫码充值
|
||||
|
||||
> 状态：已合并至标准评审稿，本文保留为实施明细。
|
||||
> 评审主文档：`../7月迭代技术方案-标准评审稿.md`
|
||||
> 评审主文档：`../../7月迭代技术方案-标准评审稿.md`
|
||||
> 范围：代理在后台使用微信或支付宝扫码充值代理主钱包。
|
||||
|
||||
## 一、已确认决策
|
||||
72
docs/7月迭代/独立方案/新增需求/06-换货归属与资产换货标识.md
Normal file
72
docs/7月迭代/独立方案/新增需求/06-换货归属与资产换货标识.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# 禅道补充需求：换货归属与资产换货标识
|
||||
|
||||
> 来源：禅道 #98、#86。最终口径以标准评审稿为准。
|
||||
|
||||
## 一、现状
|
||||
|
||||
当前换货要求新旧资产已经属于同一店铺；归属不一致时直接拒绝。换货完成只更新资产状态，没有把旧资产店铺归属赋给平台库存中的新资产。
|
||||
|
||||
资产已有 `asset_status`、`generation`，换货单也保存新旧资产 ID，但资产详情没有统一返回前代和后代资产关系。
|
||||
|
||||
## 二、换货归属规则
|
||||
|
||||
- 新资产处于平台库存或已经属于旧资产店铺时可以换入。
|
||||
- 新资产已经属于其他店铺时拒绝换货，不能覆盖其他代理资产。
|
||||
- 换货完成事务内，新资产继承旧资产 `shop_id` 和租户标签，并写资产分配记录。
|
||||
- 旧资产保留原 `shop_id`，状态改为已换货，继续用于历史订单、退款和换货查询。
|
||||
- 前端不提供目标店铺选择；选择新资产后展示将继承的店铺名称。
|
||||
|
||||
处理顺序：
|
||||
|
||||
```text
|
||||
锁定换货单和新旧资产
|
||||
-> 校验新资产库存及归属
|
||||
-> 新资产继承旧资产店铺
|
||||
-> 迁移客户绑定、钱包和套餐资料
|
||||
-> 更新新旧资产状态
|
||||
-> 完成换货单
|
||||
-> 写资产分配记录和审计事件
|
||||
```
|
||||
|
||||
任一步失败整笔事务回滚。
|
||||
|
||||
## 三、资产详情换货链
|
||||
|
||||
卡和设备详情统一返回：
|
||||
|
||||
```json
|
||||
{
|
||||
"exchange_trace": {
|
||||
"previous_asset": {
|
||||
"asset_type": "iot_card",
|
||||
"asset_id": 1001,
|
||||
"identifier": "89860...001",
|
||||
"exchange_no": "EXC202607170001"
|
||||
},
|
||||
"next_asset": {
|
||||
"asset_type": "iot_card",
|
||||
"asset_id": 1003,
|
||||
"identifier": "89860...003",
|
||||
"exchange_no": "EXC202607180001"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 有前代时显示“换货新资产”。
|
||||
- 有后代时显示“已换出旧资产”。
|
||||
- A→B→C 场景中，B 可以同时展示前代 A 和后代 C。
|
||||
- 关联资产必须再次经过后端数据权限校验；无权限时只返回标识，不返回可跳转 ID。
|
||||
|
||||
复用 `tb_exchange_order`，补充按旧资产查询已完成换货的方法，以及 `new_asset_type + new_asset_id + status` 查询索引，不新增关系表。
|
||||
|
||||
## 四、接口与前端
|
||||
|
||||
现有卡、设备详情接口增加 `exchange_trace`，不新增独立换货链接口。
|
||||
|
||||
前端在资产基础信息附近展示状态标签和关联资产链接。链接进入对应卡或设备详情，不直接跳换货单；换货单号作为辅助信息展示。
|
||||
|
||||
## 五、审计
|
||||
|
||||
记录旧资产、新资产、换货单、原店铺、新店铺、状态变更和操作人。新资产归属继承属于关键资产变更，必须与换货事务同时写 Audit Event。
|
||||
|
||||
81
docs/7月迭代/独立方案/新增需求/07-店铺业务员与钱包余额预警.md
Normal file
81
docs/7月迭代/独立方案/新增需求/07-店铺业务员与钱包余额预警.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# 禅道补充需求：店铺业务员与钱包余额预警
|
||||
|
||||
> 来源：禅道 #96、#97。最终口径以标准评审稿为准。
|
||||
|
||||
## 一、边界
|
||||
|
||||
店铺业务员只表示平台内部的业务归属，用于列表筛选和通知接收。它不建立代理分销关系，不参与店铺上下级、佣金、提现或数据权限计算。
|
||||
|
||||
钱包预警阈值固定为 100 元，不做系统配置、角色配置或店铺配置。
|
||||
|
||||
## 二、店铺业务员
|
||||
|
||||
`tb_shop` 增加：
|
||||
|
||||
```text
|
||||
business_owner_account_id BIGINT NULL
|
||||
```
|
||||
|
||||
- 只允许绑定启用的平台账号。
|
||||
- 创建、编辑店铺时可不选择。
|
||||
- 店铺列表支持按业务员筛选，列表和详情返回账号名称。
|
||||
- 业务员停用或删除后保留关联和历史审计，但不再作为通知接收人；运营可以重新绑定。
|
||||
- 不建立数据库外键，Application 显式校验账号类型和状态。
|
||||
|
||||
API 调整：
|
||||
|
||||
```text
|
||||
POST /api/admin/shops
|
||||
PUT /api/admin/shops/{id}
|
||||
GET /api/admin/shops?business_owner_account_id={id}
|
||||
```
|
||||
|
||||
## 三、固定 100 元余额预警
|
||||
|
||||
固定常量：
|
||||
|
||||
```go
|
||||
const AgentWalletLowBalanceThreshold int64 = 10000 // 代理主钱包现金余额预警阈值：100元
|
||||
```
|
||||
|
||||
只计算代理主钱包现金可用余额：
|
||||
|
||||
```text
|
||||
cash_available = balance - frozen_balance
|
||||
```
|
||||
|
||||
信用额度不参与预警。触发条件：
|
||||
|
||||
```text
|
||||
before_cash_available > 10000
|
||||
after_cash_available <= 10000
|
||||
```
|
||||
|
||||
接收人：
|
||||
|
||||
- 店铺启用的主账号。
|
||||
- 店铺绑定且仍启用的平台业务员。
|
||||
|
||||
本期只发送站内通知，不发送企业微信消息。
|
||||
|
||||
## 四、防重复
|
||||
|
||||
- 首次跌至 100 元及以下时发送一次。
|
||||
- 持续低于阈值时，后续扣款不重复通知。
|
||||
- 余额充值到 100 元以上后重新布防，再次跌破可以重新发送。
|
||||
- 通知使用钱包 ID、预警轮次和接收人组成稳定业务键。
|
||||
|
||||
可以在主钱包保存 `low_balance_alert_active`，或者使用通知状态投影记录当前预警轮次；无论实现方式如何，资金事务不能因为通知失败而回滚，事件先写 Outbox。
|
||||
|
||||
## 五、前端
|
||||
|
||||
- 店铺创建、编辑增加可搜索的平台业务员下拉框。
|
||||
- 店铺列表和详情展示业务员，并支持筛选。
|
||||
- 资金概况在现金可用余额小于等于 100 元时显示红色“现金余额不足 100 元”。
|
||||
- 不展示阈值编辑入口。
|
||||
- 通知点击后受控跳转到对应店铺资金概况。
|
||||
|
||||
## 六、审计
|
||||
|
||||
记录业务员绑定变更、预警触发时的余额/冻结金额、接收人、通知事件 ID 和失败原因。信用额度不得写入余额预警判断结果。
|
||||
|
||||
81
docs/7月迭代/独立方案/新增需求/08-代理系列套餐批量授权.md
Normal file
81
docs/7月迭代/独立方案/新增需求/08-代理系列套餐批量授权.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# 禅道补充需求：代理系列套餐批量授权
|
||||
|
||||
> 来源：禅道 #43。最终口径以标准评审稿为准。
|
||||
|
||||
## 一、现状与范围
|
||||
|
||||
系统已经存在代理系列授权和套餐授权数据，后端 `PUT /api/admin/shop-series-grants/{id}/packages` 也已经接受套餐数组。本需求不是重建授权模型，而是补齐套餐候选 Query 和前端批量交互。
|
||||
|
||||
当前主要问题：
|
||||
|
||||
- 前端只能逐个授权套餐。
|
||||
- 首次授权系列和后续管理套餐时，看不出哪些套餐已经授权给当前代理。
|
||||
- 公司成本价、代理授权成本价和建议售价缺少明确区分。
|
||||
|
||||
## 二、套餐候选 Query
|
||||
|
||||
新增：
|
||||
|
||||
```text
|
||||
GET /api/admin/shop-series-grants/{id}/package-options
|
||||
```
|
||||
|
||||
查询参数支持套餐名称、编码和授权状态。响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"package_id": 1001,
|
||||
"package_name": "移动月包",
|
||||
"package_code": "CMCC-M01",
|
||||
"company_cost_price": 5000,
|
||||
"authorized_cost_price": 6500,
|
||||
"suggested_retail_price": 8800,
|
||||
"is_authorized": true,
|
||||
"shelf_status": 1,
|
||||
"status": 1
|
||||
}
|
||||
```
|
||||
|
||||
金额单位统一为分。`authorized_cost_price` 在未授权时返回 `null`。
|
||||
|
||||
## 三、批量授权
|
||||
|
||||
继续使用现有批量写接口：
|
||||
|
||||
```text
|
||||
PUT /api/admin/shop-series-grants/{id}/packages
|
||||
```
|
||||
|
||||
请求一次提交多个套餐：
|
||||
|
||||
```json
|
||||
{
|
||||
"packages": [
|
||||
{"package_id": 1001, "cost_price": 6500},
|
||||
{"package_id": 1002, "cost_price": 7000}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- 同一请求内套餐 ID 必须去重。
|
||||
- 已经授权且价格相同的套餐按幂等成功处理。
|
||||
- 已经授权但价格不同的套餐不能被“新增授权”静默改价，应走明确的价格更新操作。
|
||||
- 套餐必须属于当前授权系列，后端不能只相信前端候选列表。
|
||||
- 批量写入在同一事务完成，任一套餐不合法则整批失败。
|
||||
|
||||
## 四、前端
|
||||
|
||||
首次创建系列授权和后续“管理套餐”共用同一个套餐选择组件：
|
||||
|
||||
- 表格使用复选框多选。
|
||||
- 展示套餐名称、编码、公司成本价、当前授权成本价和建议售价。
|
||||
- 已授权套餐显示“已授权”标签并置灰，不可选择。
|
||||
- 支持只看未授权套餐和关键词搜索。
|
||||
- 提交前显示本次新增套餐数量和价格摘要。
|
||||
|
||||
已授权置灰只是交互反馈，后端仍负责幂等和归属校验。
|
||||
|
||||
## 五、权限与审计
|
||||
|
||||
公司成本价属于敏感字段，只有具备系列授权和成本价查看权限的角色可以读取。审计记录代理、系列、套餐列表、授权价格、操作人和变更前后数据。
|
||||
|
||||
Reference in New Issue
Block a user