feat: 角色默认信用与店铺实际额度管理

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

@@ -0,0 +1,33 @@
+## 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 状态码是否固定为某个值，需要实现时与接口文档对齐。

openspec/changes/update-role-default-credit-and-shop-credit-limit/proposal.md

@@ -0,0 +1,30 @@
+# Change: 角色默认信用与店铺实际额度管理
+
+## Why
+
+当前角色信用配置容易被理解为会直接影响已有店铺，且代理商资金页缺少单独维护店铺实际信用额度的入口。需要将“未来新建店铺的默认信用”和“已有店铺的实际信用额度”拆分管理，避免修改角色配置误伤存量店铺。
+
+## What Changes
+
+- 客户角色配置页新增“新建代理默认信用”开关和额度输入，并提示“修改后不会影响已有店铺”。
+- 平台员工角色不展示默认信用配置。
+- 店铺创建时使用所选客户角色的默认信用初始化新店铺实际信用额度。
+- 代理商资金概况页展示现金余额、冻结金额、实际信用额度、可用金额、欠款金额和版本。
+- 代理商资金概况页提供独立的店铺实际额度调整弹框，展示修改前后金额预览。
+- 调整店铺实际额度时携带资金概况版本，遇到并发冲突后提示用户并刷新最新资金概况。
+- 前端不重新计算可用金额、欠款金额或资金状态，金额展示以接口返回为准。
+
+## Impact
+
+- Affected specs: `role-management`, `shop-management`, `commission-management`
+- Affected code:
+  - `src/api/modules/role.ts`
+  - `src/api/modules/shop.ts`
+  - `src/api/modules/commission.ts`
+  - `src/types/api/role.ts`
+  - `src/types/api/shop.ts`
+  - `src/types/api/commission.ts`
+  - `src/views/system/role/index.vue`
+  - `src/views/shop-management/list/index.vue`
+  - `src/views/commission-management/agent-fund-overview/index.vue`
+- Source product note: `docs/产品迭代7月份/15- 角色默认信用与店铺实际额度管理.md`

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

@@ -0,0 +1,84 @@
+## 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`

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

@@ -0,0 +1,43 @@
+## ADDED Requirements
+
+### Requirement: Customer Role Default Credit Configuration
+
+The role management page SHALL allow customer roles to configure default credit only for future newly created agent shops.
+
+#### Scenario: Display default credit controls for customer roles
+
+- **GIVEN** 用户正在客户角色配置页编辑客户角色
+- **WHEN** 页面渲染角色表单或配置区域
+- **THEN** 页面 MUST 展示“新建代理默认信用”开关
+- **AND** 页面 MUST 展示信用额度输入框
+- **AND** 页面 MUST 展示提示文案“修改后不会影响已有店铺”
+
+#### Scenario: Hide default credit controls for platform employee roles
+
+- **GIVEN** 用户正在编辑平台员工角色
+- **WHEN** 页面渲染角色表单或配置区域
+- **THEN** 页面 MUST NOT 展示“新建代理默认信用”开关
+- **AND** 页面 MUST NOT 展示信用额度输入框
+
+#### Scenario: Save customer role default credit
+
+- **GIVEN** 用户正在编辑客户角色默认信用
+- **WHEN** 用户提交默认信用配置
+- **THEN** 前端 MUST call `PUT /api/admin/roles/{id}/default-credit`
+- **AND** 请求体 MUST include `credit_enabled: bool` and `credit_limit: int64`
+- **AND** 保存成功后页面 MUST 提示保存成功
+
+#### Scenario: Disable customer role default credit
+
+- **GIVEN** 用户正在编辑客户角色默认信用
+- **WHEN** 用户关闭“新建代理默认信用”开关
+- **THEN** 页面 MUST 将额度输入归零
+- **AND** 提交时请求体 MUST include `credit_enabled=false`
+- **AND** 提交时请求体 MUST include `credit_limit=0`
+
+#### Scenario: Role default credit does not mutate existing shops
+
+- **GIVEN** 已有店铺已经创建并拥有实际信用额度
+- **WHEN** 用户修改该店铺所属客户角色的默认信用配置
+- **THEN** 系统 MUST NOT 修改已有店铺的实际信用额度
+- **AND** 已有店铺的实际额度 MUST 只能通过店铺实际额度调整入口修改

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

@@ -0,0 +1,48 @@
+## ADDED Requirements
+
+### Requirement: New Shop Credit Initialization From Customer Role
+
+The shop creation flow SHALL initialize a newly created agent shop's actual credit from the selected customer role's default credit configuration.
+
+#### Scenario: Create agent shop with enabled role default credit
+
+- **GIVEN** 选中的客户角色已启用默认信用
+- **AND** 该客户角色配置了默认信用额度
+- **WHEN** 用户创建新的代理店铺
+- **THEN** 新店铺的实际信用 MUST 初始化为启用状态
+- **AND** 新店铺的实际信用额度 MUST 使用该客户角色的默认信用额度
+
+#### Scenario: Create agent shop with disabled role default credit
+
+- **GIVEN** 选中的客户角色未启用默认信用
+- **WHEN** 用户创建新的代理店铺
+- **THEN** 新店铺的实际信用 MUST 初始化为关闭状态
+- **AND** 新店铺的实际信用额度 MUST be `0`
+
+#### Scenario: Existing shop keeps actual credit after role default change
+
+- **GIVEN** 店铺已经完成创建
+- **WHEN** 用户修改该店铺所属客户角色的默认信用配置
+- **THEN** 该店铺的实际信用启用状态 MUST NOT change
+- **AND** 该店铺的实际信用额度 MUST NOT change
+
+### Requirement: Shop Actual Credit Limit Update API
+
+The frontend SHALL update an existing shop's actual credit limit through `PUT /api/admin/shops/{id}/credit-limit` with optimistic concurrency versioning.
+
+#### Scenario: Submit shop actual credit update
+
+- **GIVEN** 用户正在调整已有店铺实际信用额度
+- **WHEN** 用户提交调整
+- **THEN** 前端 MUST call `PUT /api/admin/shops/{id}/credit-limit`
+- **AND** 请求体 MUST include `credit_enabled: bool`
+- **AND** 请求体 MUST include `credit_limit: int64`
+- **AND** 请求体 MUST include `version: int64`
+
+#### Scenario: Disable shop actual credit
+
+- **GIVEN** 用户正在调整已有店铺实际信用额度
+- **WHEN** 用户关闭信用开关
+- **THEN** 页面 MUST 将额度输入归零
+- **AND** 提交时请求体 MUST include `credit_enabled=false`
+- **AND** 提交时请求体 MUST include `credit_limit=0`

openspec/changes/update-role-default-credit-and-shop-credit-limit/tasks.md

@@ -0,0 +1,34 @@
+## 1. API And Types
+
+- [x] 1.1 在角色 API 和类型中新增 `PUT /api/admin/roles/{id}/default-credit` 请求类型与服务方法。
+- [x] 1.2 在店铺 API 和类型中新增 `PUT /api/admin/shops/{id}/credit-limit` 请求类型与服务方法。
+- [x] 1.3 扩展代理商资金概况类型，包含 `credit_enabled`、`credit_limit`、`available_balance`、`is_in_debt`、`debt_amount` 和 `version`。
+
+## 2. Role Default Credit
+
+- [x] 2.1 在客户角色配置页展示“新建代理默认信用”开关、额度输入和“修改后不会影响已有店铺”提示。
+- [x] 2.2 平台员工角色不展示信用配置。
+- [x] 2.3 关闭默认信用时将额度输入归零并提交 `credit_limit=0`。
+- [x] 2.4 保存默认信用配置时调用 `PUT /api/admin/roles/{id}/default-credit`。
+
+## 3. Shop Credit Initialization
+
+- [x] 3.1 确认店铺创建页不把角色默认信用表现为会影响已有店铺的配置。
+- [x] 3.2 确认新建店铺实际信用额度由后端按所选客户角色默认信用初始化。
+
+## 4. Agent Fund Overview
+
+- [x] 4.1 在代理商资金概况页展示现金余额、冻结金额、实际信用额度、可用金额、欠款金额和版本。
+- [x] 4.2 金额字段按接口返回值展示，不在前端重新计算可用金额或欠款金额。
+- [x] 4.3 新增店铺实际额度调整弹框，展示当前值、修改后值和关闭信用归零行为。
+- [x] 4.4 提交调额时携带当前 `version` 调用 `PUT /api/admin/shops/{id}/credit-limit`。
+- [x] 4.5 并发冲突时展示提示并刷新最新资金概况。
+
+## 5. Verification
+
+- [ ] 5.1 验证客户角色默认信用保存后不会修改已有店铺展示的实际信用额度。
+- [ ] 5.2 验证新建店铺使用所选客户角色默认信用初始化实际额度。
+- [ ] 5.3 验证资金概况页展示字段与接口返回一致。
+- [ ] 5.4 验证关闭信用时额度输入归零。
+- [ ] 5.5 验证并发冲突后页面提示并刷新最新资金概况。
+- [x] 5.6 运行相关 lint、类型检查或构建命令。