This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-08-31
|
||||
@@ -0,0 +1,32 @@
|
||||
## Context
|
||||
|
||||
现有佣金提现有申请和钱包事实；本 Change 以资格及审批实例补齐其前置条件，不以外部线下打款作为完成条件。
|
||||
|
||||
## Decisions
|
||||
|
||||
- 分销码由店铺唯一约束保护；扫码注册与审批结果使用稳定审批实例幂等消费。
|
||||
- 资格申请与附件版本分表/快照，替换、作废和代理停用以状态失效，不覆盖历史审批。
|
||||
- 提现创建在事务内锁定佣金钱包并写冻结和审批提交；通过仅一次扣减/确认，驳回仅一次释放。
|
||||
|
||||
## 业务动作契约
|
||||
|
||||
### 分销码与扫码注册
|
||||
|
||||
- 代理店铺创建事务生成全局唯一、不可修改的随机 `distribution_code`；二维码只包含 H5 注册入口及该码。唯一冲突重试生成，不允许人工指定或编辑。
|
||||
- `POST /api/c/v1/agent-distribution-registrations`：提交 `distribution_code`、短信已验证手机号、密码及既有注册必填资料。服务锁定上级店铺，校验其代理启用；失效码/停用代理统一返回“分销码不可用”。成功仅创建待审批代理/店铺和企业微信审批实例，不建立下级归属。
|
||||
- 企业微信通过消费者幂等启用新代理/店铺，并在同一事务写直接上级店铺和上级当前业务员快照；驳回不启用。重复回调不重复创建层级或账号。
|
||||
|
||||
### 提现资格资料
|
||||
|
||||
- `POST /shops/:shop_id/withdrawal-qualifications`：仅本人代理店铺。请求合同、法人身份证正反面附件；企业必须提供统一社会信用代码，个人必须提供法人身份证号；可选营业执照、门头照；企业可选发票，发票抬头和统一社会信用代码必须与合同主体一致。创建新资料版本并提交企业微信，替换合同或身份证立即使旧有效资格失效。
|
||||
- 超级管理员作废资格必须填写原因；代理停用自动失效全部有效资格。合同与身份证审批通过后长期有效，直至替换、作废或停用；历史版本、附件、审批实例永不覆盖。
|
||||
|
||||
### 提现申请与审批
|
||||
|
||||
- 既有 `POST /shops/:shop_id/withdrawal-requests` 增加资格有效校验。锁定该店铺佣金钱包后冻结可提现余额、申请金额、手续费/实际到账金额、收款信息和可选发票快照；余额不足、资格无效或非本人代理均不创建申请或冻结。
|
||||
- 企业微信通过时以申请/审批实例条件更新一次确认到账；驳回时仅一次释放冻结。代理可在资格仍有效时修改被驳回申请的金额、收款信息和申请级发票并创建新审批实例；资料资格不因提现驳回失效。
|
||||
- 新业务禁用本地 `approve/reject` 终审；提交/回调未知复用既有审批恢复，不允许通过重提制造第二笔冻结。每次资格、冻结、审批终态和重提均记录审计。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
新增成对迁移及唯一/状态索引；隔离库验证码唯一和停用、资格失效、提现冻结/重提、重复审批回调及 up/down/up。
|
||||
@@ -0,0 +1,25 @@
|
||||
## Scope
|
||||
|
||||
- 迭代编号：`AUG26-008`。
|
||||
|
||||
## Why
|
||||
|
||||
代理下级归属和提现资料/资金缺少企业微信终审及失效边界，无法可靠追溯。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 代理店铺唯一分销码和审批后下级注册。
|
||||
- 合同、法人身份证为核心的提现资格审批与失效。
|
||||
- 提现余额/资料快照、企微终审和驳回释放。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `agent-distribution-withdrawal`: 分销注册、资料资格与提现审批。
|
||||
|
||||
### Modified Capabilities
|
||||
- 无。
|
||||
|
||||
## Impact
|
||||
|
||||
影响代理店铺、H5 注册、附件、佣金钱包、企业微信审批和 Schema。
|
||||
@@ -0,0 +1,26 @@
|
||||
## Purpose
|
||||
|
||||
使代理下级注册和佣金提现均以企业微信审批、资格有效性和不可变业务快照为准，避免代理层级或资金事实因资料变更、重复回调而漂移。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 分销码与下级代理注册
|
||||
系统 SHALL 在每个代理店铺创建时生成全局唯一、不可修改的随机分销码；二维码仅编码 H5 注册入口和该码。代理扫码后以手机号短信验证、设置密码并创建待企业微信审批的下级代理和店铺；仅审批通过时启用，并将新店铺设为分销码所属店铺的直接下级，复制上级当时业务员为初始业务员。代理停用后其码立即不可注册，既有下级和佣金关系不级联变更。
|
||||
|
||||
#### Scenario: 停用代理码注册
|
||||
- **WHEN** 客户使用已停用代理所属店铺的分销码注册
|
||||
- **THEN** 系统拒绝创建下级代理或店铺
|
||||
|
||||
### Requirement: 提现资料资格
|
||||
代理首次提现前 SHALL 提交企业微信资料资格申请；合同和法人身份证正反面必填，企业代理填写统一社会信用代码、个人代理填写法人身份证号。合同资格主体必须填写统一社会信用代码或身份证号；营业执照、门头照可选，发票仅企业可选且其抬头/统一社会信用代码必须与合同主体一致。审批通过且资料未过期才有效；合同和身份证通过后长期有效，直到代理替换资料、超级管理员作废或代理停用。
|
||||
|
||||
#### Scenario: 资料替换后提现
|
||||
- **WHEN** 有效资格的代理替换合同或法人身份证资料
|
||||
- **THEN** 原资格失效，代理必须重新审批通过后才可提现
|
||||
|
||||
### Requirement: 提现冻结与企业微信终审
|
||||
提现申请 SHALL 冻结可提现余额、金额、手续费、收款信息和可选发票快照，并创建企业微信审批。本地不得人工通过或驳回；企业微信通过即视为已到账，驳回时释放本申请冻结余额。驳回后代理可修改金额、收款信息和本次发票重新提交，每次新建审批实例；资料资格保持有效。发票为申请级材料，若上传必须按当时有效合同主体校验并冻结。
|
||||
|
||||
#### Scenario: 提现审批驳回
|
||||
- **WHEN** 企业微信最终驳回一笔提现申请
|
||||
- **THEN** 系统仅一次释放其冻结佣金余额，保留审批快照，并允许在资格仍有效时修改后重提
|
||||
@@ -0,0 +1,13 @@
|
||||
## 1. 分销与资格
|
||||
- [ ] 1.1 追踪代理/店铺创建、H5 短信注册、佣金提现、附件、企微审批和钱包冻结链路。
|
||||
- [ ] 1.2 新增分销码、资格申请/资料版本、提现审批快照的成对迁移、模型、状态与唯一约束。
|
||||
- [ ] 1.3 实现分销注册、停用门禁、审批后下级归属/业务员快照及审计。
|
||||
- [ ] 1.4 实现资格提交、主体/附件/发票校验、失效和企微回调。
|
||||
|
||||
## 2. 提现
|
||||
- [ ] 2.1 实现有效资格校验、钱包锁定冻结、申请快照、企微终审、驳回释放和新实例重提。
|
||||
- [ ] 2.2 注册后台/H5 路由及 OpenAPI，保障附件和数据范围。
|
||||
|
||||
## 3. 验证
|
||||
- [ ] 3.1 隔离库验证迁移、分销码停用、资格替换、冻结/释放和重复回调。
|
||||
- [ ] 3.2 运行 `gofmt -w`、`go build ./cmd/api ./cmd/worker`、`go run cmd/gendocs/main.go`、`openspec validate add-agent-distribution-withdrawal-qualification --strict` 与 `openspec doctor --json`；自动化测试按项目决策为 N/A。
|
||||
Reference in New Issue
Block a user