📝 docs(prd): 修正史诗004内部服务接口描述

- 修正模块名为正确的PNPM工作空间格式：@d8d/前缀
- 删除错误的HTTP内部接口描述，改为直接服务调用
- 更新集成点描述：模块间通过导入服务类直接调用
- 修正数据流和额度恢复逻辑描述

🤖 Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

docs/prd/epic-004-credit-payment.md

@@ -18,8 +18,9 @@
 1. **多租户余额模块** (`credit-balance-module-mt`)
    - 余额实体设计（用户额度、已用额度、可用额度）
    - 额度变更记录实体
-   - 额度管理服务（设置额度、扣减额度、查询余额）
+   - 额度管理服务（设置额度、扣减额度、恢复额度、查询余额）
    - 额度支付API接口
+   - 额度恢复API接口（结账、取消订单、退款）
 
 2. **多租户余额管理UI模块** (`credit-balance-management-ui-mt`)
    - 用户额度管理界面
@@ -31,6 +32,7 @@
    - 扩展支付选项，增加"额度支付"
    - 额度支付订单处理逻辑
    - 额度检查和验证机制
+   - 额度恢复机制（结账、取消订单、退款）
    - 小程序个人中心欠款显示
 
 ### 不包含的功能
@@ -76,6 +78,10 @@
 - [ ] 实现额度支付订单处理逻辑
 - [ ] 额度为0的用户无法使用额度支付
 - [ ] 支付成功后更新用户已用额度和可用额度
+- [ ] 实现额度恢复机制：
+  - [ ] 结账时恢复相应额度（订单完成）
+  - [ ] 取消订单时恢复全额额度
+  - [ ] 退款时恢复相应额度
 - [ ] 在小程序个人中心显示累计欠款
 - [ ] 确保与现有微信支付流程并行工作，互不干扰
 
@@ -103,8 +109,8 @@ CREATE TABLE credit_balance_log_mt (
   id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
   tenant_id INT UNSIGNED NOT NULL COMMENT '租户ID',
   user_id INT UNSIGNED NOT NULL COMMENT '用户ID',
-  change_type VARCHAR(20) NOT NULL COMMENT '变更类型: SET_LIMIT, PAYMENT, REFUND, ADJUST',
-  change_amount DECIMAL(10,2) NOT NULL COMMENT '变更金额',
+  change_type VARCHAR(20) NOT NULL COMMENT '变更类型: SET_LIMIT(设置额度), PAYMENT(支付扣减), CHECKOUT(结账恢复), CANCEL_ORDER(取消订单恢复), REFUND(退款恢复), ADJUST(调整额度)',
+  change_amount DECIMAL(10,2) NOT NULL COMMENT '变更金额（正数表示增加额度，负数表示减少额度）',
   before_total DECIMAL(10,2) COMMENT '变更前总额度',
   after_total DECIMAL(10,2) COMMENT '变更后总额度',
   before_used DECIMAL(10,2) COMMENT '变更前已用额度',
@@ -122,7 +128,7 @@ CREATE TABLE credit_balance_log_mt (
 ### 模块结构
 ```
 packages/
-├── credit-balance-module-mt/          # 多租户余额模块
+├── @d8d/credit-balance-module-mt/     # 多租户余额模块
 │   ├── src/
 │   │   ├── entities/                  # 实体定义
 │   │   │   ├── credit-balance.mt.entity.ts
@@ -133,7 +139,7 @@ packages/
 │   │   ├── routes/                    # API路由
 │   │   └── index.ts
 │   └── package.json
-└── credit-balance-management-ui-mt/   # 余额管理UI模块
+└── @d8d/credit-balance-management-ui-mt/   # 余额管理UI模块
     ├── src/
     │   ├── components/                # 组件
     │   ├── pages/                     # 页面
@@ -143,25 +149,76 @@ packages/
 ```
 
 ### API设计
+#### 对外API（供UI调用）
 1. `GET /api/credit-balance/{userId}` - 查询用户额度
 2. `PUT /api/credit-balance/{userId}` - 设置用户额度
 3. `POST /api/credit-balance/{userId}/adjust` - 调整用户额度
 4. `GET /api/credit-balance/{userId}/logs` - 查询额度变更记录
 5. `POST /api/credit-balance/payment` - 额度支付
+6. `POST /api/credit-balance/checkout` - 结账恢复额度（供信用管理UI调用）
+
+#### 服务接口（供其他模块调用）
+1. `CreditBalanceService.restoreBalanceForCancelOrder(orderId, userId, amount)` - 取消订单恢复额度
+2. `CreditBalanceService.restoreBalanceForRefund(orderId, userId, refundAmount)` - 退款恢复额度
+
+**设计说明：**
+- **结账恢复**：需要人工确认，因此通过信用管理UI手动触发，调用`/api/credit-balance/checkout`接口
+- **取消订单恢复**：自动触发，订单模块在取消订单时直接调用`CreditBalanceService.restoreBalanceForCancelOrder()`方法
+- **退款恢复**：自动触发，支付模块在退款处理时直接调用`CreditBalanceService.restoreBalanceForRefund()`方法
+- **模块间调用**：使用PNPM工作空间，通过`@d8d/credit-balance-module-mt`包名导入服务类进行直接调用
 
 ## 集成点
 ### 与现有系统集成
 1. **用户模块集成**：通过`user_id`关联用户信息
-2. **订单模块集成**：扩展`orders_mt`表的`pay_type`字段，新增额度支付类型
-3. **支付模块集成**：在`mini-payment-mt`中新增额度支付处理逻辑
-4. **小程序集成**：更新支付页面和个人中心页面
+2. **订单模块集成**：
+   - 扩展`orders_mt`表的`pay_type`字段，新增额度支付类型
+   - 订单模块导入`@d8d/credit-balance-module-mt`包，直接调用`CreditBalanceService.restoreBalanceForCancelOrder()`方法处理取消订单时的额度恢复
+3. **支付模块集成**：
+   - 在`@d8d/mini-payment-mt`中新增额度支付处理逻辑
+   - 支付模块导入`@d8d/credit-balance-module-mt`包，直接调用`CreditBalanceService.restoreBalanceForRefund()`方法处理退款时的额度恢复
+4. **信用管理UI集成**：
+   - 信用管理UI调用额度模块的`/api/credit-balance/checkout`接口处理结账时的额度恢复
+5. **小程序集成**：更新支付页面和个人中心页面
 
 ### 数据流
+#### 正向流程（支付扣减）
 1. 后台管理员设置用户额度 → 更新`credit_balance_mt`表
 2. 用户选择额度支付 → 检查可用额度 → 创建订单 → 扣减额度
-3. 支付成功 → 更新订单状态 → 记录额度变更日志
+3. 支付成功 → 更新订单状态 → 记录额度变更日志（PAYMENT类型）
 4. 小程序查询欠款 → 调用额度查询接口 → 显示欠款信息
 
+#### 反向流程（额度恢复）
+1. **结账恢复**：订单完成结账 → 信用管理UI调用`/api/credit-balance/checkout` → 恢复相应额度 → 记录日志（CHECKOUT类型）
+2. **取消订单恢复**：用户取消订单 → 订单模块调用`CreditBalanceService.restoreBalanceForCancelOrder()` → 恢复全额额度 → 记录日志（CANCEL_ORDER类型）
+3. **退款恢复**：管理员处理退款 → 支付模块调用`CreditBalanceService.restoreBalanceForRefund()` → 恢复相应额度 → 记录日志（REFUND类型）
+
+## 额度恢复逻辑
+### 恢复场景定义
+1. **结账恢复（CHECKOUT）**
+   - **触发条件**：订单完成所有流程，用户确认收货
+   - **恢复金额**：订单实际支付金额
+   - **业务意义**：订单交易完成，额度占用解除
+   - **实现方式**：信用管理UI手动触发，调用`/api/credit-balance/checkout`接口
+
+2. **取消订单恢复（CANCEL_ORDER）**
+   - **触发条件**：用户在支付后、发货前取消订单
+   - **恢复金额**：订单全额支付金额
+   - **业务意义**：交易未发生，全额恢复额度
+   - **实现方式**：订单模块在取消订单时自动调用`CreditBalanceService.restoreBalanceForCancelOrder()`方法
+
+3. **退款恢复（REFUND）**
+   - **触发条件**：管理员处理用户退款申请
+   - **恢复金额**：实际退款金额（可能部分退款）
+   - **业务意义**：交易撤销，按退款金额恢复额度
+   - **实现方式**：支付模块在退款处理时自动调用`CreditBalanceService.restoreBalanceForRefund()`方法
+
+### 恢复规则
+1. **幂等性保证**：同一订单只能恢复一次额度，防止重复恢复
+2. **金额验证**：恢复金额不能超过原支付金额
+3. **状态检查**：只有特定订单状态才能触发恢复
+4. **日志记录**：每次恢复都记录详细的变更日志
+5. **事务处理**：额度恢复与订单状态更新在同一事务中
+
 ## 兼容性要求
 1. **API兼容性**：新增API端点，不影响现有API
 2. **数据库兼容性**：新增表，不影响现有表结构
@@ -179,7 +236,12 @@ packages/
 - **权限控制**：只有管理员可设置和调整额度
 - **额度限制**：设置单次支付和累计欠款上限
 
-### 风险3：影响现有支付流程
+### 风险3：额度恢复逻辑错误导致额度重复恢复
+- **缓解措施**：实现幂等性检查，同一订单只能恢复一次
+- **验证机制**：添加恢复前状态检查，防止重复恢复
+- **日志审计**：详细记录每次恢复操作，便于审计追踪
+
+### 风险4：影响现有支付流程
 - **缓解措施**：额度支付作为可选功能，默认不启用
 - **测试策略**：充分测试与现有支付流程的兼容性
 - **回滚计划**：可禁用额度支付功能，恢复原有流程
@@ -189,15 +251,27 @@ packages/
 - 额度计算逻辑测试
 - 额度扣减和恢复测试
 - 额度验证测试
+- 额度恢复场景测试：
+  - 结账恢复额度测试
+  - 取消订单恢复额度测试
+  - 退款恢复额度测试
 
 ### 集成测试
 - 额度支付流程测试
+- 额度恢复流程测试：
+  - 结账时额度恢复测试
+  - 取消订单时额度恢复测试
+  - 退款时额度恢复测试
 - 与订单模块集成测试
 - 与用户模块集成测试
 
 ### E2E测试
 - 后台额度管理流程测试
 - 小程序额度支付流程测试
+- 额度恢复场景测试：
+  - 结账后额度恢复验证
+  - 取消订单后额度恢复验证
+  - 退款后额度恢复验证
 - 欠款显示功能测试
 
 ## 部署计划
@@ -221,6 +295,10 @@ packages/
 1. **功能指标**：
    - 后台可成功设置和调整用户额度
    - 用户可使用额度完成支付
+   - 额度恢复功能正常工作：
+     - 结账时正确恢复额度
+     - 取消订单时正确恢复额度
+     - 退款时正确恢复额度
    - 小程序正确显示欠款信息
    - 额度为0的用户无法使用额度支付