one-pipe-system/openspec/changes/update-role-default-credit-and-shop-credit-limit/specs/commission-management/spec.md

ADDED Requirements

Requirement: Agent Fund Summary Actual Credit Display

The agent fund overview page SHALL display shop actual credit and fund summary fields from GET /api/admin/shops/fund-summary without recalculating monetary values on the frontend.

Scenario: Display fund summary credit fields

• GIVEN 用户进入代理商资金概况页
• WHEN GET /api/admin/shops/fund-summary 返回资金概况记录
• THEN 页面 MUST 展示现金余额 balance
• AND 页面 MUST 展示冻结金额 frozen_balance
• AND 页面 MUST 展示实际信用额度 credit_limit
• AND 页面 MUST 展示可用金额 available_balance
• AND 页面 MUST 展示欠款金额 debt_amount
• AND 页面 MUST 展示版本 version

Scenario: Display credit disabled state

• GIVEN 资金概况记录返回 credit_enabled=false
• WHEN 页面渲染该记录
• THEN 页面 MUST 将实际信用显示为关闭状态
• AND 页面 MUST display credit limit as 0 or backend-provided formatted value

Scenario: Do not recalculate fund amounts on frontend

• GIVEN 资金概况接口返回 available_balance、is_in_debt 和 debt_amount
• WHEN 页面渲染资金概况
• THEN 前端 MUST 使用接口返回的 available_balance
• AND 前端 MUST 使用接口返回的 is_in_debt
• AND 前端 MUST 使用接口返回的 debt_amount
• AND 前端 MUST NOT 根据现金余额、冻结金额或信用额度重新计算这些字段

Requirement: Shop Actual Credit Adjustment Dialog

The agent fund overview page SHALL provide an independent dialog for adjusting a shop's actual credit limit and previewing the before/after amount.

Scenario: Open actual credit adjustment dialog

• GIVEN 用户正在代理商资金概况页查看店铺资金记录
• WHEN 用户点击调整实际信用额度入口
• THEN 页面 MUST 打开独立调整弹框
• AND 弹框 MUST 展示修改前信用启用状态和信用额度
• AND 弹框 MUST 展示修改后信用启用状态和信用额度预览

Scenario: Submit actual credit adjustment

• GIVEN 用户已经在调整弹框内修改实际信用配置
• WHEN 用户确认提交
• THEN 前端 MUST submit credit_enabled、credit_limit and version to PUT /api/admin/shops/{id}/credit-limit
• AND 保存成功后页面 MUST 关闭弹框
• AND 页面 MUST 刷新代理商资金概况列表

Scenario: Disable credit in adjustment dialog

• GIVEN 用户正在调整弹框内修改实际信用配置
• WHEN 用户关闭信用开关
• THEN 弹框 MUST 将额度输入归零
• AND 修改后金额预览 MUST reflect disabled credit with zero credit limit

Scenario: Handle concurrent credit update conflict

• GIVEN 用户打开调整弹框时记录了资金概况 version
• AND 该店铺资金概况已被其他操作更新
• WHEN 用户提交旧版本的实际信用调整
• THEN 页面 MUST 展示并发冲突提示
• AND 页面 MUST 刷新最新代理商资金概况
• AND 页面 MUST NOT keep showing stale version as current data

Requirement: Agent Fund Summary Credit Response Contract

The frontend SHALL read actual credit fields from GET /api/admin/shops/fund-summary response records.

Scenario: Read actual credit response fields

• WHEN 前端请求 GET /api/admin/shops/fund-summary
• THEN 前端 MUST read balance
• AND 前端 MUST read frozen_balance
• AND 前端 MUST read credit_enabled
• AND 前端 MUST read credit_limit
• AND 前端 MUST read available_balance
• AND 前端 MUST read is_in_debt
• AND 前端 MUST read debt_amount
• AND 前端 MUST read version