csxj2026/junhong_cmp_fiber

Fork 0

Files

break 072ec1db7e

构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 8m15s

Details

修复企微的问题

2026-07-27 17:04:32 +08:00

24 KiB

Raw Blame History

代理充值管理 API 规范

Purpose

定义代理钱包在线扫码自充、平台线下代充、第三方支付确认、异步钱包入账、状态查询、异常恢复与多租户权限控制的统一业务契约，确保充值资金事实可核对、可恢复且不会重复入账。

Requirements

Requirement: 创建代理充值订单

系统 SHALL 通过 POST /api/admin/agent-recharges 保留同一代理充值资源，并按登录账号类型与 payment_method 执行严格分流。

代理在线请求 MUST 仅接受 amount、payment_method 与 request_id：

payment_method MUST 为 wechat 或 alipay。
amount MUST 使用分为单位，范围 MUST 为 10000～100000000。
目标店铺与主钱包 MUST 从当前认证上下文确定；请求 MUST NOT 接受或信任 shop_id、支付凭证或运营备注。
每次新的主动提交 MUST 创建新的代理充值单和 tb_payment 支付单，不得按金额或待支付记录复用旧单。
同一提交账号与 request_id MUST 形成持久化幂等作用域；相同指纹重放 MUST 返回原业务结果，不同指纹重放 MUST 返回统一冲突错误。

平台或超级管理员的 offline 线下代充 MUST 继续使用现有目标 shop_id、付款凭证和企业微信审批契约，在线充值 100 元最低金额 MUST NOT 改变线下代充金额规则。平台、超级管理员和企业账号 MUST NOT 创建代理在线扫码充值单。

在线创建 MUST 在同一 GORM 事务中保存充值单、支付单及请求幂等事实，再调用创建时选定的支付 Adapter：微信 MUST 使用 Native 支付，支付宝 MUST 使用 alipay.trade.precreate。成功响应 MUST 使用统一 {code,msg,data,timestamp} 格式，并在 data 中至少返回 recharge_id、recharge_no、payment_no、payment_method、recharge_source、recharge_source_name、amount、qr_content、status 与 status_name。后端 MUST 返回支付渠道原始付款字符串，不得生成或保存二维码图片。

充值订单创建、列表、详情和在线支付状态响应 MUST 使用稳定来源枚举区分创建路径：platform_offline 表示平台线下代充，agent_online 表示代理在线自充。列表 MUST 支持使用 recharge_source 筛选；来源可由受控创建方式推导，不要求新增重复数据库字段。

支付单 MUST 同时保存创建时的收款身份快照：微信记录商户号，支付宝记录应用 ID，并保留支付方式与 payment_config_id，供后续导出对账。创建响应 MUST NOT 返回该内部收款身份快照。

第三方预下单失败时，系统 MUST 记录 Integration Log，并将本次支付单标记为失败、充值单标记为已关闭；不得返回缺少有效 qr_content 的成功响应。

Scenario: 代理创建微信 Native 扫码充值

WHEN 代理提交 amount=10000、payment_method=wechat 和新的 request_id
THEN 系统从登录上下文确定当前店铺主钱包，创建充值单和支付单，调用微信 Native 预下单，并将 code_url 映射为 qr_content
THEN 响应不得包含支付配置 ID、商户密钥或其他店铺信息

Scenario: 代理创建支付宝当面付扫码充值

WHEN 代理提交有效金额、payment_method=alipay 和新的 request_id
THEN 系统创建充值单和支付单，调用 alipay.trade.precreate，并将 qr_code 映射为 qr_content

Scenario: 区分平台代充与代理自充

WHEN 调用方查询充值订单列表、详情或在线支付状态
THEN 平台线下代充 MUST 返回 recharge_source=platform_offline，代理微信或支付宝在线自充 MUST 返回 recharge_source=agent_online

Scenario: 在线充值金额边界

WHEN 代理提交的在线充值金额小于 10000 分或大于 100000000 分
THEN 系统 MUST 返回 CodeInvalidParam，且不得创建充值单、支付单或调用第三方支付

Scenario: 代理请求携带目标店铺

WHEN 代理在线请求携带 shop_id 或其他仅线下代充允许的字段
THEN 系统 MUST 拒绝请求，不得允许代理选择本店、下级店铺或其他店铺作为受益方

Scenario: 相同请求重放

WHEN 同一提交账号使用相同 request_id 和相同业务字段重试
THEN 系统 MUST 返回首次创建的充值单、支付单和付款内容，不得再次创建业务单或再次向第三方预下单

Scenario: 幂等请求载荷冲突

WHEN 同一提交账号使用已有 request_id 但改变金额或支付方式
THEN 系统 MUST 返回 CodeConflict，不得改变原充值单或创建新单

Scenario: 支付方式不可用

WHEN 所选支付方式缺少完整配置、扫码预下单能力或回调验签能力
THEN 系统 MUST 返回统一支付配置不可用错误，且不得创建只有本地记录而无法付款的待支付订单

Requirement: 线下充值确认

接口描述：平台账号确认线下转账已到账，完成充值并为代理钱包增加余额。

系统 SHALL 仅允许平台账号对符合条件的存量线下充值记录执行确认，并在校验操作密码后完成一次性钱包入账。

HTTP 方法与路径

POST /api/admin/agent-recharges/:id/offline-pay

鉴权

需要登录态（Bearer Token）
仅平台账号可调用，其他账号类型返回 1005 CodeForbidden

请求体示例

{
  "operation_password": "Abc123456"
}

请求字段说明

字段名	类型	必填	说明
operation_password	string	是	操作密码，用于二次身份验证

路径参数说明

参数名	类型	说明
id	integer	充值记录 ID

业务规则

操作密码验证失败返回 1043 CodeInvalidOldPassword
充值记录必须存在且 payment_method=offline，否则返回 1121 CodeRechargeNotFound
充值记录状态必须为 1（待支付），否则返回 1050 CodeInvalidStatus
确认成功后：
1. 充值记录状态更新为 2（已完成），记录 paid_at 和 completed_at
2. 代理主钱包余额增加对应金额（使用乐观锁 version 字段防并发）
3. 创建钱包流水记录
4. 记录审计日志（操作人、操作前后数据）

成功响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 88,
    "recharge_no": "ARCH20260316100001",
    "shop_id": 101,
    "amount": 200000,
    "payment_method": "offline",
    "payment_channel": "offline",
    "payment_config_id": null,
    "status": 2,
    "paid_at": "2026-03-16T11:00:00+08:00",
    "completed_at": "2026-03-16T11:00:00+08:00",
    "created_at": "2026-03-16T10:00:00+08:00"
  },
  "timestamp": "2026-03-16T11:00:00+08:00"
}

错误响应示例

操作密码错误：

{
  "code": 1043,
  "msg": "操作密码错误",
  "data": null,
  "timestamp": "2026-03-16T11:00:00+08:00"
}

充值记录不存在：

{
  "code": 1121,
  "msg": "充值记录不存在",
  "data": null,
  "timestamp": "2026-03-16T11:00:00+08:00"
}

充值记录状态不允许操作：

{
  "code": 1050,
  "msg": "当前充值记录状态不允许此操作",
  "data": null,
  "timestamp": "2026-03-16T11:00:00+08:00"
}

非平台账号调用：

{
  "code": 1005,
  "msg": "只有平台账号可以使用线下充值",
  "data": null,
  "timestamp": "2026-03-16T11:00:00+08:00"
}

Scenario: 平台确认存量线下充值

WHEN 平台账号对待支付的线下充值记录提交正确操作密码
THEN 系统 MUST 完成充值记录、主钱包余额和唯一钱包流水更新，重复操作不得重复入账

Requirement: 代理充值查询

系统 SHALL 按当前账号数据范围提供代理充值列表与详情查询，并返回稳定的充值来源、状态和时间字段。

接口一：充值记录列表

接口描述：分页查询代理充值记录，支持按店铺、状态、充值来源、日期范围过滤。

HTTP 方法与路径

GET /api/admin/agent-recharges

鉴权

需要登录态（Bearer Token）
代理账号：只能查看自己所属店铺的充值记录
平台账号：可查看所有店铺的充值记录

请求参数（Query String）

GET /api/admin/agent-recharges?page=1&page_size=20&shop_id=101&status=3&recharge_source=agent_online&start_date=2026-03-01&end_date=2026-03-31

请求参数说明

参数名	类型	必填	说明
page	integer	否	页码，默认 1
page_size	integer	否	每页条数，默认 20，最大 100
shop_id	integer	否	按店铺 ID 过滤（平台账号可用）
status	integer	否	按状态过滤：1=待支付，2=已支付，3=已完成，4=已关闭
recharge_source	string	否	按充值来源过滤：`platform_offline`=平台线下代充，`agent_online`=代理在线自充
start_date	string	否	创建时间起始日期，格式 `YYYY-MM-DD`
end_date	string	否	创建时间截止日期，格式 `YYYY-MM-DD`

成功响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 56,
    "page": 1,
    "page_size": 20,
    "list": [
      {
        "id": 88,
        "recharge_no": "ARCH20260316100001",
        "shop_id": 101,
        "shop_name": "测试店铺A",
        "amount": 50000,
        "payment_method": "wechat",
        "payment_channel": "wechat_direct",
        "payment_config_id": 3,
        "recharge_source": "agent_online",
        "recharge_source_name": "代理在线自充",
        "status": 3,
        "paid_at": "2026-03-16T10:05:00+08:00",
        "completed_at": "2026-03-16T10:05:00+08:00",
        "created_at": "2026-03-16T10:00:00+08:00"
      },
      {
        "id": 87,
        "recharge_no": "ARCH20260315090001",
        "shop_id": 101,
        "shop_name": "测试店铺A",
        "amount": 200000,
        "payment_method": "offline",
        "payment_channel": "offline",
        "payment_config_id": null,
        "recharge_source": "platform_offline",
        "recharge_source_name": "平台线下代充",
        "status": 3,
        "paid_at": "2026-03-15T11:00:00+08:00",
        "completed_at": "2026-03-15T11:00:00+08:00",
        "created_at": "2026-03-15T09:00:00+08:00"
      }
    ]
  },
  "timestamp": "2026-03-16T12:00:00+08:00"
}

列表项字段说明

字段名	类型	说明
id	integer	充值记录 ID
recharge_no	string	充值单号
shop_id	integer	店铺 ID
shop_name	string	店铺名称
amount	integer	充值金额（分）
payment_method	string	支付方式
payment_channel	string	实际支付通道
payment_config_id	integer\|null	关联支付配置 ID
recharge_source	string	充值来源：`platform_offline` 或 `agent_online`
recharge_source_name	string	充值来源中文名称
status	integer	状态：1=待支付，2=已支付，3=已完成，4=已关闭
paid_at	string\|null	支付时间
completed_at	string\|null	完成时间
created_at	string	创建时间

错误响应示例

参数错误：

{
  "code": 1001,
  "msg": "参数验证失败",
  "data": null,
  "timestamp": "2026-03-16T12:00:00+08:00"
}

接口二：充值记录详情

接口描述：查询单条充值记录的完整详情。

HTTP 方法与路径

GET /api/admin/agent-recharges/:id

鉴权

需要登录态（Bearer Token）
代理账号：只能查看自己所属店铺的充值记录，否则返回 1121 CodeRechargeNotFound
平台账号：可查看任意充值记录

路径参数说明

参数名	类型	说明
id	integer	充值记录 ID

成功响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 88,
    "recharge_no": "ARCH20260316100001",
    "shop_id": 101,
    "shop_name": "测试店铺A",
    "agent_wallet_id": 55,
    "amount": 50000,
    "payment_method": "wechat",
    "payment_channel": "wechat_direct",
    "payment_config_id": 3,
    "payment_transaction_id": "wx_txn_20260316_abc123",
    "recharge_source": "agent_online",
    "recharge_source_name": "代理在线自充",
    "status": 3,
    "paid_at": "2026-03-16T10:05:00+08:00",
    "completed_at": "2026-03-16T10:05:00+08:00",
    "created_at": "2026-03-16T10:00:00+08:00",
    "updated_at": "2026-03-16T10:05:00+08:00"
  },
  "timestamp": "2026-03-16T12:00:00+08:00"
}

详情字段说明

字段名	类型	说明
id	integer	充值记录 ID
recharge_no	string	充值单号
shop_id	integer	店铺 ID
shop_name	string	店铺名称
agent_wallet_id	integer	代理钱包 ID
amount	integer	充值金额（分）
payment_method	string	支付方式
payment_channel	string	实际支付通道
payment_config_id	integer\|null	关联支付配置 ID
payment_transaction_id	string\|null	第三方支付流水号
recharge_source	string	充值来源：`platform_offline` 或 `agent_online`
recharge_source_name	string	充值来源中文名称
status	integer	状态：1=待支付，2=已支付，3=已完成，4=已关闭
paid_at	string\|null	支付时间
completed_at	string\|null	完成时间
created_at	string	创建时间
updated_at	string	最后更新时间

错误响应示例

充值记录不存在或无权限：

{
  "code": 1121,
  "msg": "充值记录不存在",
  "data": null,
  "timestamp": "2026-03-16T12:00:00+08:00"
}

Scenario: 按数据范围查询充值记录

WHEN 已认证账号查询充值列表或详情
THEN 系统 MUST 仅返回其数据范围内的记录，并使用 recharge_source 区分平台线下代充与代理在线自充

Requirement: 代理充值回调处理

现有微信和支付宝异步回调入口 MUST 在完成渠道验签后，按 tb_payment.payment_no 和 order_type=agent_recharge 分发到代理充值支付确认用例，不得仅依赖 ARCH 单号前缀判断业务类型。旧代理充值支付单可在迁移期保留受控兼容分支，但新支付单 MUST 走统一支付记录分发。

支付确认 MUST 校验支付方式、创建时的 payment_config_id、回调商户或应用身份、支付单金额、充值单金额、支付单与充值单关联以及第三方交易号唯一性。校验失败 MUST 不改变支付单、充值单或钱包事实，并写入中文安全日志和 Integration Log；日志不得记录密钥或完整敏感正文。

成功确认 MUST 在同一 GORM 事务中：

条件更新支付单为已支付并保存第三方交易号与支付时间；
条件更新代理充值单从 1=待支付 为 2=已支付；
写入稳定版本的代理充值入账 Outbox。

支付渠道成功响应 MUST 在上述事务提交后返回。钱包入账不得继续作为支付回调事务中的同步步骤。

Outbox 消费者 MUST 在独立事务中复用统一代理主钱包入账能力，锁定目标主钱包、增加余额、创建唯一成功流水、将充值单从 2=已支付 更新为 3=已完成，并写入现有钱包入账事件。消费者 MUST 以充值记录 ID 作为业务幂等引用；重复回调、重复 Outbox 或 Worker 重试不得重复增加余额。

Scenario: 微信支付成功回调

WHEN 微信回调验签通过，支付单类型为 agent_recharge，且金额、配置、商户身份和业务关联全部一致
THEN 系统 MUST 固化支付成功事实和入账 Outbox，并向微信返回渠道成功响应
THEN 钱包余额由独立消费者完成，不得在回调事务中同步增加

Scenario: 支付宝支付成功回调

WHEN 支付宝通知验签通过，交易状态为成功，支付单类型为 agent_recharge，且金额、配置、应用身份和业务关联全部一致
THEN 系统 MUST 固化支付成功事实和入账 Outbox，并向支付宝返回 success

Scenario: 回调金额或关联不一致

WHEN 回调金额与支付单或充值单不一致，或支付单未关联该代理充值记录
THEN 系统 MUST 拒绝处理并保留原状态，钱包余额和流水 MUST NOT 改变

Scenario: 重复支付回调

WHEN 同一第三方交易号对同一已支付或已完成充值单重复回调
THEN 系统 MUST 幂等返回渠道成功响应，不得重复写支付事实、入账 Outbox 或钱包流水

Scenario: 第三方交易号被其他支付单占用

WHEN 回调中的第三方交易号已绑定另一张支付单或代理充值单
THEN 系统 MUST 返回冲突并记录不含敏感信息的严重错误，任何钱包 MUST NOT 入账

Scenario: 钱包入账暂时失败

WHEN 支付事实已提交但钱包入账消费者因锁冲突或暂时性基础设施错误失败
THEN 充值单 MUST 保持 2=已支付，Outbox/Worker MUST 重试，且支付成功事实不得回滚或要求代理再次付款

Scenario: 重复执行钱包入账

WHEN 同一代理充值入账任务被重复消费
THEN 数据库唯一流水约束和状态条件更新 MUST 保证余额最多增加一次，并最终将充值单收敛为 3=已完成

Requirement: 权限控制

系统 MUST 使用以下权限边界：

操作	平台/超级管理员	代理账号	企业账号
创建在线扫码充值	禁止	仅当前所属店铺主钱包	禁止
创建线下代充	按现有权限指定目标店铺	禁止	禁止
线下充值确认	允许	禁止	禁止
查询可用在线支付方式	禁止	允许	禁止
查询充值列表与详情	按既有数据范围	按既有店铺层级与查看权限	禁止
查询在线支付状态	按既有数据范围	按既有店铺层级与查看权限	禁止

路由层 MUST 对企业账号执行粗粒度拦截；Application/Query MUST 执行创建角色、当前店铺、资源归属和查看权限校验；GORM 数据范围过滤保持启用。越权与资源不存在 MUST 统一返回 CodeForbidden 和“无权限操作该资源或资源不存在”，不得泄露资源是否存在。

线下充值确认继续使用既有平台操作密码契约；密码验证失败返回 CodeInvalidOldPassword，响应和日志均不得记录密码明文。

Scenario: 代理为当前店铺充值

WHEN 代理账号创建在线扫码充值且当前店铺主钱包可用
THEN 系统 MUST 以认证上下文中的店铺和主钱包作为唯一受益方

Scenario: 平台尝试创建在线扫码充值

WHEN 平台或超级管理员提交 wechat 或 alipay 代理充值请求
THEN 系统 MUST 返回 CodeForbidden，并引导其使用既有线下代充审批路径

Scenario: 无权读取支付状态

WHEN 登录账号查询其数据范围外充值单的支付状态
THEN 系统 MUST 返回统一禁止访问错误，不得返回支付状态、付款内容或钱包余额

Requirement: 查询代理在线充值可用支付方式

系统 SHALL 提供 GET /api/admin/agent-recharges/payment-methods，仅根据当前生效支付配置返回真正具备扫码预下单、回调验签和查单能力的在线支付方式。路由 MUST 注册在 /:id 动态路由之前。

成功响应 MUST 使用统一 {code,msg,data,timestamp} 格式；data.methods MUST 为按 wechat、alipay 固定顺序排列的字符串数组，并同时返回 min_amount=10000 与 max_amount=100000000。接口不得返回支付配置 ID、商户号、应用 ID、密钥或具体缺失的敏感配置。

Scenario: 微信与支付宝均可用

WHEN 当前支付配置完整支持微信 Native 和支付宝 PreCreate
THEN 接口 MUST 返回 methods=["wechat","alipay"] 及在线金额上下限

Scenario: 没有可用扫码支付方式

WHEN 当前配置不支持任何已约定的扫码支付方式
THEN 接口 MUST 成功返回空数组，不得伪造可用渠道

Requirement: 查询代理在线充值支付状态

系统 SHALL 提供 GET /api/admin/agent-recharges/:id/payment-status 供桌面端轮询本地事实。接口 MUST 仅查询 PostgreSQL 本地支付单、充值单及必要的钱包入账结果，不得在每次轮询时调用第三方支付渠道。

响应 MUST 使用统一 {code,msg,data,timestamp} 格式，并至少返回 status、status_name、payment_status、payment_status_name、paid_at 与 completed_at。1=待支付 MUST 表示尚未确认收款，2=已支付 MUST 表示第三方收款已确认但钱包仍在入账，3=已完成 MUST 表示钱包余额和唯一流水已经提交。

接口 MUST NOT 返回 qr_content、支付密钥、签名参数、内部重试错误或其他店铺余额。第一期 MUST NOT 提供主动取消、支付方式切换、在线退款或本地推算的精确二维码倒计时。

Scenario: 等待扫码支付

WHEN 充值单仍为待支付且支付单未确认成功
THEN 接口 MUST 返回待支付状态，不得调用第三方查单

Scenario: 已支付等待钱包入账

WHEN 支付单已支付且充值单状态为 2=已支付
THEN 接口 MUST 明确返回支付成功、入账处理中，不得显示支付失败

Scenario: 钱包已经到账

WHEN 充值单状态为 3=已完成 且唯一钱包流水存在
THEN 接口 MUST 返回已完成和完成时间

Requirement: 待支付订单受控收敛

系统 MUST 通过后台受控任务查询长期待支付的代理在线充值支付单，以弥补第三方回调丢失。任务 MUST 使用创建支付单时记录的支付方式和 payment_config_id 调用对应查单 Adapter，并为每次外部尝试记录 Integration Log。

查单确认成功 MUST 复用与回调相同的支付确认用例；查单确认关闭或失效 MUST 条件关闭仍为待支付的支付单与充值单；未知、超时或渠道异常 MUST 保持原业务状态并按任务策略重试。迟到的真实成功通知经完整校验后 MUST 仍能固化支付事实并入账，不得因本地曾判断待支付或关闭而吞掉已收款资金。

Scenario: 回调丢失但查单成功

WHEN 待支付收敛任务从第三方查询到交易成功且金额与配置校验通过
THEN 系统 MUST 调用统一支付确认用例，写入支付事实和钱包入账 Outbox

Scenario: 第三方明确订单关闭

WHEN 查单结果明确表示订单关闭或失效，且本地支付单仍为待支付
THEN 系统 MUST 条件更新支付单为失败并将充值单关闭，不得增加钱包余额

Scenario: 查单结果未知

WHEN 第三方超时、返回未知状态或暂时不可用
THEN 系统 MUST 保持本地待支付状态并重试，不得猜测支付失败

数据模型补充说明

tb_agent_recharge_record 新增字段

字段名	类型	可空	说明
payment_config_id	bigint	是	关联支付配置 ID，线下充值为 NULL，在线充值记录实际使用的支付配置

充值状态枚举

值	含义
1	待支付（订单已创建，等待支付）
2	已支付（第三方收款已确认，钱包入账处理中）
3	已完成（钱包余额和唯一流水已提交）
4	已关闭（第三方预下单失败或确认订单已关闭）

支付方式枚举

值	含义
wechat	微信 Native 扫码支付
alipay	支付宝当面付扫码支付
offline	线下转账（仅平台账号可用）

支付通道枚举

值	含义
wechat_direct	微信直连通道
alipay	支付宝通道
offline	线下转账

24 KiB Raw Blame History Unescape Escape

代理充值管理 API 规范

Purpose

Requirements

Requirement: 创建代理充值订单

Scenario: 代理创建微信 Native 扫码充值

Scenario: 代理创建支付宝当面付扫码充值

Scenario: 区分平台代充与代理自充

Scenario: 在线充值金额边界

Scenario: 代理请求携带目标店铺

Scenario: 相同请求重放

Scenario: 幂等请求载荷冲突

Scenario: 支付方式不可用

Requirement: 线下充值确认

Scenario: 平台确认存量线下充值

Requirement: 代理充值查询

接口一：充值记录列表

接口二：充值记录详情

Scenario: 按数据范围查询充值记录

Requirement: 代理充值回调处理

Scenario: 微信支付成功回调

Scenario: 支付宝支付成功回调

Scenario: 回调金额或关联不一致

Scenario: 重复支付回调

Scenario: 第三方交易号被其他支付单占用

Scenario: 钱包入账暂时失败

Scenario: 重复执行钱包入账

Requirement: 权限控制

Scenario: 代理为当前店铺充值

Scenario: 平台尝试创建在线扫码充值

Scenario: 无权读取支付状态

Requirement: 查询代理在线充值可用支付方式

Scenario: 微信与支付宝均可用

Scenario: 没有可用扫码支付方式

Requirement: 查询代理在线充值支付状态

Scenario: 等待扫码支付

Scenario: 已支付等待钱包入账

Scenario: 钱包已经到账

Requirement: 待支付订单受控收敛

Scenario: 回调丢失但查单成功

Scenario: 第三方明确订单关闭

Scenario: 查单结果未知

数据模型补充说明

24 KiB

Raw Blame History