one-pipe-system/openspec/changes/update-role-default-credit-and-shop-credit-limit/design.md

Context

信用额度分为两个层级：客户角色上的默认信用只决定未来新建代理店铺的初始值，店铺上的实际信用额度才参与资金页展示和后续额度调整。两者必须解耦，避免角色配置变更影响已有店铺。

Goals / Non-Goals

Goals:

• 明确角色默认信用和店铺实际信用额度的职责边界。
• 明确资金概况页读取后端返回的金额和版本作为展示、调额和并发控制来源。
• 明确关闭信用时额度输入归零。

Non-Goals:

• 不在前端重新计算可用金额、欠款金额或是否欠款。
• 不为平台员工角色提供信用配置。
• 不批量同步历史店铺额度。

Decisions

• 角色默认信用保存到 PUT /api/admin/roles/{id}/default-credit，请求体为 credit_enabled 和 credit_limit。
• 店铺实际信用额度保存到 PUT /api/admin/shops/{id}/credit-limit，请求体为 credit_enabled、credit_limit 和 version。
• 资金概况继续通过 GET /api/admin/shops/fund-summary 获取，前端展示 balance、frozen_balance、credit_enabled、credit_limit、available_balance、is_in_debt、debt_amount 和 version。
• 调整弹框展示修改前后金额预览，但最终可用金额、欠款金额和欠款状态仍以后端刷新后的资金概况为准。

Risks / Trade-offs

• 并发更新可能覆盖他人修改。通过提交 version 并在冲突时刷新资金概况降低风险。
• 用户可能误以为角色默认信用会修改已有店铺。通过固定提示“修改后不会影响已有店铺”降低误解。

Open Questions

• 并发冲突的后端错误码或 HTTP 状态码是否固定为某个值，需要实现时与接口文档对齐。