移除史诗004相关文档

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

@@ -1,379 +0,0 @@
-# 史诗004：新增记账（信用额度支付）功能
-
-## 概述
-为多租户电商平台新增信用额度支付功能，允许后台为特定用户设置信用额度，用户可使用额度进行支付，并在小程序个人中心显示累计欠款，与现有微信支付流程并行工作。
-
-## 业务背景
-当前系统仅支持微信支付，缺乏灵活的支付方式。为提升用户体验和业务灵活性，需要引入信用额度支付功能，允许特定用户（如VIP用户、企业用户）使用信用额度进行支付，后台可灵活管理额度。
-
-## 目标
-1. 新增信用额度支付方式，与现有微信支付流程并行
-2. 后台可设置和查看用户信用额度（用户不可见）
-3. 未授权用户额度为0，点击额度支付无效
-4. 小程序个人中心显示累计欠款信息
-5. 实现多租户余额模块和余额管理UI模块
-
-## 范围
-### 包含的功能
-1. **多租户余额模块** (`credit-balance-module-mt`)
-   - 余额实体设计（用户额度、已用额度、可用额度）
-   - 额度变更记录实体
-   - 额度管理服务（设置额度、扣减额度、恢复额度、查询余额）
-   - 额度支付API接口
-   - 额度恢复API接口（结账、取消订单、退款）
-
-2. **多租户余额管理UI模块** (`credit-balance-management-ui-mt`)
-   - 用户额度管理界面
-   - 额度设置和调整功能
-   - 额度使用记录查询
-   - 欠款统计和报表
-
-3. **支付流程集成**
-   - 扩展支付选项，增加"额度支付"
-   - 额度支付订单处理逻辑
-   - 额度检查和验证机制
-   - 额度恢复机制（结账、取消订单、退款）
-   - 小程序个人中心欠款显示
-
-### 不包含的功能
-1. 额度自动审批和风控系统
-2. 额度利息计算和催收功能
-3. 额度分期还款功能
-4. 额度提现功能
-
-## 用户故事
-### 故事1：创建多租户信用额度模块
-**作为** 系统管理员
-**我希望** 能够管理用户的信用额度
-**以便** 控制用户的支付权限和风险
-
-**验收标准：**
-- [x] 创建`credit_balance_mt`表，包含租户ID、用户ID、总额度、已用额度、可用额度等字段
-- [x] 创建`credit_balance_log_mt`表，记录额度变更历史
-- [x] 实现额度管理服务，包含设置额度、扣减额度、查询余额等方法
-- [x] 提供额度查询和管理的API接口
-- [x] 添加数据库迁移脚本（注：迁移脚本在server包集成模块时创建，不在模块包中创建）
-- [x] 编写单元测试覆盖核心逻辑
-
-**实现状态**：✅ 已完成
-**完成时间**：2025-12-02
-**实现详情**：
-- 创建了完整的多租户信用额度模块包：`@d8d/credit-balance-module-mt`
-- 实现了两个实体：`CreditBalanceMt`（信用额度实体）和`CreditBalanceLogMt`（额度变更记录实体）
-- 实现了完整的额度管理服务：`CreditBalanceService`，包含设置额度、调整额度、扣减额度、恢复额度等方法
-- 实现了6个API接口：查询额度、设置额度、调整额度、查询变更记录、额度支付、结账恢复额度
-- 编写了13个单元测试用例和11个集成测试用例，测试通过率100%
-- 修复了多个技术问题：PostgreSQL类型兼容性、路由架构重构、测试认证问题、小数精度问题等
-
-### 故事2：创建多租户信用额度管理UI模块
-**作为** 后台管理员
-**我希望** 有一个界面来管理用户信用额度
-**以便** 方便地设置和调整用户额度
-
-**验收标准：**
-- [ ] 创建用户额度管理页面，显示用户列表和当前额度
-- [ ] 实现额度设置和调整功能
-- [ ] 提供额度使用记录查询界面
-- [ ] 显示用户欠款统计信息
-- [ ] 界面风格与现有后台保持一致
-- [ ] 添加权限控制，只有管理员可访问
-
-### 故事3：集成额度支付到现有支付流程
-**作为** 小程序用户
-**我希望** 可以使用信用额度进行支付
-**以便** 在余额不足时也能完成购买
-
-**验收标准：**
-- [ ] 在支付页面增加"额度支付"选项
-- [ ] 实现额度支付订单处理逻辑
-- [ ] 额度为0的用户无法使用额度支付
-- [ ] 支付成功后更新用户已用额度和可用额度
-- [ ] 实现额度恢复机制：
-  - [ ] 结账时恢复相应额度（订单完成）
-  - [ ] 取消订单时恢复全额额度
-  - [ ] 退款时恢复相应额度
-- [ ] 在小程序个人中心显示累计欠款
-- [ ] 确保与现有微信支付流程并行工作，互不干扰
-
-## 技术设计
-### 数据库设计
-```sql
--- 用户信用额度表
-CREATE TABLE credit_balance_mt (
-  id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
-  tenant_id INT UNSIGNED NOT NULL COMMENT '租户ID',
-  user_id INT UNSIGNED NOT NULL COMMENT '用户ID',
-  total_limit DECIMAL(10,2) DEFAULT 0.00 COMMENT '总额度',
-  used_amount DECIMAL(10,2) DEFAULT 0.00 COMMENT '已用额度',
-  available_amount DECIMAL(10,2) GENERATED ALWAYS AS (total_limit - used_amount) STORED COMMENT '可用额度',
-  is_enabled TINYINT DEFAULT 1 COMMENT '是否启用(0:禁用,1:启用)',
-  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-  UNIQUE KEY uk_tenant_user (tenant_id, user_id),
-  INDEX idx_tenant_id (tenant_id),
-  INDEX idx_user_id (user_id)
-) COMMENT='用户信用额度表';
-
--- 额度变更记录表
-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(支付扣减), 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 '变更前已用额度',
-  after_used DECIMAL(10,2) COMMENT '变更后已用额度',
-  reference_id VARCHAR(100) COMMENT '关联ID(订单号等)',
-  remark VARCHAR(500) COMMENT '备注',
-  operator_id INT UNSIGNED COMMENT '操作人ID',
-  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  INDEX idx_tenant_user (tenant_id, user_id),
-  INDEX idx_reference (reference_id),
-  INDEX idx_created (created_at)
-) COMMENT='额度变更记录表';
-```
-
-**迁移脚本说明**：
-根据项目架构，TypeORM迁移脚本应在server包集成`@d8d/credit-balance-module-mt`模块时创建，而不是在模块包中创建。模块包只包含实体定义，迁移脚本由使用该模块的应用层（server包）负责创建和管理。
-
-### 模块结构
-```
-packages/
-├── @d8d/credit-balance-module-mt/     # 多租户余额模块
-│   ├── src/
-│   │   ├── entities/                  # 实体定义
-│   │   │   ├── credit-balance.mt.entity.ts
-│   │   │   └── credit-balance-log.mt.entity.ts
-│   │   │   └── index.ts
-│   │   ├── services/                  # 服务层
-│   │   │   ├── credit-balance.service.ts
-│   │   │   └── index.ts
-│   │   ├── schemas/                   # 数据验证
-│   │   │   └── index.ts
-│   │   ├── routes/                    # API路由
-│   │   │   └── index.ts
-│   │   ├── types/                     # 类型定义
-│   │   │   └── index.ts
-│   │   └── index.ts                   # 主入口文件
-│   ├── tests/                         # 测试文件
-│   ├── tsconfig.json                  # TypeScript配置
-│   ├── vitest.config.ts               # 测试配置
-│   └── package.json
-└── @d8d/credit-balance-management-ui-mt/   # 余额管理UI模块
-    ├── src/
-    │   ├── api/                       # API客户端
-    │   │   ├── index.ts
-    │   │   └── creditBalanceClient.ts
-    │   ├── components/                # 组件
-    │   │   ├── CreditBalanceManagement.tsx
-    │   │   └── index.ts
-    │   ├── hooks/                     # React hooks
-    │   │   └── index.ts
-    │   ├── types/                     # 类型定义
-    │   │   ├── index.ts
-    │   │   └── creditBalance.ts
-    │   └── index.ts                   # 主入口文件
-    ├── tests/                         # 测试文件
-    ├── eslint.config.js               # ESLint配置
-    ├── tsconfig.json                  # TypeScript配置
-    ├── vitest.config.ts               # 测试配置
-    └── package.json
-```
-
-### 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`字段，新增额度支付类型
-   - 订单模块导入`@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. 支付成功 → 更新订单状态 → 记录额度变更日志（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. **数据库兼容性**：新增表，不影响现有表结构
-3. **UI兼容性**：新增页面和组件，遵循现有UI规范
-4. **支付流程兼容性**：额度支付与微信支付并行，互不干扰
-
-## 风险与缓解
-### 风险1：额度支付逻辑错误导致财务数据不一致
-- **缓解措施**：使用数据库事务处理额度扣减和订单创建
-- **验证机制**：添加额度检查和余额验证
-- **监控**：记录详细的额度变更日志
-
-### 风险2：额度被恶意使用
-- **缓解措施**：后台控制额度启用状态，默认禁用
-- **权限控制**：只有管理员可设置和调整额度
-- **额度限制**：设置单次支付和累计欠款上限
-
-### 风险3：额度恢复逻辑错误导致额度重复恢复
-- **缓解措施**：实现幂等性检查，同一订单只能恢复一次
-- **验证机制**：添加恢复前状态检查，防止重复恢复
-- **日志审计**：详细记录每次恢复操作，便于审计追踪
-
-### 风险4：影响现有支付流程
-- **缓解措施**：额度支付作为可选功能，默认不启用
-- **测试策略**：充分测试与现有支付流程的兼容性
-- **回滚计划**：可禁用额度支付功能，恢复原有流程
-
-## 测试策略
-### 单元测试
-- 额度计算逻辑测试
-- 额度扣减和恢复测试
-- 额度验证测试
-- 额度恢复场景测试：
-  - 结账恢复额度测试
-  - 取消订单恢复额度测试
-  - 退款恢复额度测试
-
-### 集成测试
-- 额度支付流程测试
-- 额度恢复流程测试：
-  - 结账时额度恢复测试
-  - 取消订单时额度恢复测试
-  - 退款时额度恢复测试
-- 与订单模块集成测试
-- 与用户模块集成测试
-
-### E2E测试
-- 后台额度管理流程测试
-- 小程序额度支付流程测试
-- 额度恢复场景测试：
-  - 结账后额度恢复验证
-  - 取消订单后额度恢复验证
-  - 退款后额度恢复验证
-- 欠款显示功能测试
-
-## 部署计划
-### 阶段1：开发环境部署
-1. 创建数据库迁移脚本
-2. 部署余额模块和UI模块
-3. 配置额度支付功能（默认禁用）
-
-### 阶段2：测试环境验证
-1. 功能测试和集成测试
-2. 性能测试和压力测试
-3. 安全测试和权限测试
-
-### 阶段3：生产环境部署
-1. 执行数据库迁移
-2. 部署新模块
-3. 灰度启用额度支付功能
-4. 监控系统运行状态
-
-## 成功指标
-1. **功能指标**：
-   - 后台可成功设置和调整用户额度
-   - 用户可使用额度完成支付
-   - 额度恢复功能正常工作：
-     - 结账时正确恢复额度
-     - 取消订单时正确恢复额度
-     - 退款时正确恢复额度
-   - 小程序正确显示欠款信息
-   - 额度为0的用户无法使用额度支付
-
-2. **性能指标**：
-   - 额度查询响应时间 < 100ms
-   - 额度支付处理时间 < 500ms
-   - 系统可用性 > 99.9%
-
-3. **业务指标**：
-   - 额度支付成功率 > 95%
-   - 用户满意度提升
-   - 支付方式多样性增加
-
-## 后续优化建议
-1. 额度自动审批流程
-2. 额度风控和预警系统
-3. 额度分期和还款功能
-4. 额度提现和转账功能
-5. 额度积分和奖励机制
-
----
-**创建时间**：2025-12-01
-**负责人**：产品经理
-**状态**：进行中（故事1已完成）
-**优先级**：高
-
-## 开发进度
-### 已完成
-1. ✅ **故事1：创建多租户信用额度模块**（2025-12-02完成）
-   - 创建了完整的多租户信用额度模块包：`@d8d/credit-balance-module-mt`
-   - 实现了所有核心功能：实体、服务、API接口、测试
-   - 测试通过率100%，代码质量符合项目标准
-
-### 待完成
-1. 🔄 **故事2：创建多租户信用额度管理UI模块**
-2. 🔄 **故事3：集成额度支付到现有支付流程**
-
-### 技术实现亮点
-1. **多租户架构**：严格遵循项目多租户包架构模式，使用`-mt`后缀和租户ID隔离
-2. **路由架构**：参照订单模块采用链式聚合模式，支持RPC风格API调用
-3. **测试策略**：使用测试数据工厂模式，真实JWT令牌认证，确保测试可靠性
-4. **错误处理**：完整的OpenAPI错误响应定义，符合项目标准
-5. **数据库设计**：PostgreSQL兼容性优化，解决tinyint类型和decimal精度问题
-6. **事务处理**：额度扣减和恢复操作使用数据库事务确保数据一致性

docs/stories/004.001.credit-balance-module-mt.story.md

@@ -1,332 +0,0 @@
-# Story 004.001: 创建多租户信用额度模块
-
-## Status
-✅ Completed
-
-## Story
-**As a** 系统管理员，
-**I want** 能够管理用户的信用额度，
-**so that** 控制用户的支付权限和风险
-
-## Acceptance Criteria
-1. 创建`credit_balance_mt`表，包含租户ID、用户ID、总额度、已用额度、可用额度等字段
-2. 创建`credit_balance_log_mt`表，记录额度变更历史
-3. 实现额度管理服务，包含设置额度、扣减额度、查询余额等方法
-4. 提供额度查询和管理的API接口
-5. 添加数据库迁移脚本
-6. 编写单元测试覆盖核心逻辑
-
-## Tasks / Subtasks
-- [x] **创建多租户信用额度模块包结构** (AC: 1, 2, 3, 4, 6)
-  - [x] 创建包目录：`packages/credit-balance-module-mt/` (参考：`packages/advertisements-module-mt/`)
-  - [x] 配置package.json，包名：`@d8d/credit-balance-module-mt` (参考：`packages/advertisements-module-mt/package.json`)
-  - [x] 配置TypeScript和Vitest配置文件 (参考：`packages/advertisements-module-mt/tsconfig.json`, `packages/advertisements-module-mt/vitest.config.ts`)
-  - [x] 创建核心模块结构：`src/entities/`, `src/services/`, `src/schemas/`, `src/routes/`, `src/types/` (参考：`packages/advertisements-module-mt/src/`)
-  - [x] 创建测试目录结构：`tests/unit/`, `tests/integration/` (参考：`packages/advertisements-module-mt/tests/`)
-
-- [x] **实现信用额度实体** (AC: 1)
-  - [x] 创建`CreditBalanceMt`实体类，对应`credit_balance_mt`表 (参考：`packages/advertisements-module-mt/src/entities/advertisement.entity.ts`)
-  - [x] 添加字段：`tenant_id`, `user_id`, `total_limit`, `used_amount`, `available_amount`, `is_enabled`
-  - [x] 添加唯一约束：`uk_tenant_user (tenant_id, user_id)`
-  - [x] 添加索引：`idx_tenant_id`, `idx_user_id`
-  - [x] 使用TypeORM装饰器定义实体关系 (参考：`packages/advertisements-module-mt/src/entities/advertisement.entity.ts`)
-
-- [x] **实现额度变更记录实体** (AC: 2)
-  - [x] 创建`CreditBalanceLogMt`实体类，对应`credit_balance_log_mt`表 (参考：`packages/advertisements-module-mt/src/entities/advertisement-type.entity.ts`)
-  - [x] 添加字段：`tenant_id`, `user_id`, `change_type`, `change_amount`, `before_total`, `after_total`, `before_used`, `after_used`, `reference_id`, `remark`, `operator_id`
-  - [x] 添加索引：`idx_tenant_user`, `idx_reference`, `idx_created`
-  - [x] 定义变更类型枚举：`SET_LIMIT`, `PAYMENT`, `CHECKOUT`, `CANCEL_ORDER`, `REFUND`, `ADJUST`
-
-- [x] **实现额度管理服务** (AC: 3)
-  - [x] 创建`CreditBalanceService`服务类 (参考：`packages/advertisements-module-mt/src/services/advertisement.service.ts`)
-  - [x] 实现方法：`setLimit()`, `adjustLimit()`, `deductAmount()`, `restoreAmount()`, `getBalance()`, `getBalanceByUserId()`
-  - [x] 实现额度恢复方法：`restoreBalanceForCancelOrder()`, `restoreBalanceForRefund()`
-  - [x] 添加事务处理确保数据一致性
-  - [x] 添加额度检查和验证逻辑
-
-- [x] **实现API路由** (AC: 4)
-  - [x] 创建路由文件：`src/routes/index.mt.ts` (参考：`packages/advertisements-module-mt/src/routes/index.ts`)
-  - [x] 实现API端点：
-    - [x] `GET /api/credit-balance/{userId}` - 查询用户额度
-    - [x] `PUT /api/credit-balance/{userId}` - 设置用户额度
-    - [x] `POST /api/credit-balance/{userId}/adjust` - 调整用户额度
-    - [x] `GET /api/credit-balance/{userId}/logs` - 查询额度变更记录
-    - [x] `POST /api/credit-balance/payment` - 额度支付
-    - [x] `POST /api/credit-balance/checkout` - 结账恢复额度
-  - [x] 添加数据验证Schema (参考：`packages/advertisements-module-mt/src/schemas/`)
-  - [x] 添加权限控制和认证中间件
-
-
-- [x] **编写测试** (AC: 6)
-  - [x] **服务测试**：测试额度管理逻辑 (参考：`packages/file-module/tests/unit/file.service.test.ts`)
-  - [x] **API集成测试**：测试端点功能和验证 (参考：`packages/advertisements-module-mt/tests/integration/advertisements.integration.test.ts`)
-  - [x] 添加边界条件测试：额度不足、重复操作等场景
-  - [x] 确保测试覆盖率 ≥ 80%
-
-- [x] **配置包依赖和导出** (AC: 3, 4)
-  - [x] 配置package.json依赖关系（TypeORM、Hono等） (参考：`packages/advertisements-module-mt/package.json`)
-  - [x] 创建主入口文件：`src/index.mt.ts` 导出所有模块接口 (参考：`packages/advertisements-module-mt/src/index.ts`)
-  - [x] 配置TypeScript编译选项 (参考：`packages/advertisements-module-mt/tsconfig.json`)
-  - [x] 配置Vitest测试环境 (参考：`packages/advertisements-module-mt/vitest.config.ts`)
-  - [x] 确保包可以正确导入和使用
-
-## Dev Notes
-
-### 技术栈信息 [Source: architecture/tech-stack.md]
-- **运行时**: Node.js 20.18.3
-- **框架**: Hono 4.8.5 (Web框架和API路由，RPC类型安全)
-- **数据库**: PostgreSQL 17 (通过TypeORM进行数据持久化存储)
-- **ORM**: TypeORM 0.3.25 (数据库操作抽象，实体管理)
-- **测试框架**: Vitest 2.x (单元测试框架，更好的TypeORM支持)
-- **API测试**: hono/testing (内置，API端点测试，更好的类型安全)
-
-### 项目结构信息 [Source: architecture/source-tree.md]
-- **包管理**: 使用pnpm workspace管理多包依赖关系
-- **包架构层次**:
-  - **基础设施层**: shared-types → shared-utils → shared-crud
-  - **测试基础设施**: shared-test-util
-  - **业务模块层**: 多租户模块包（-mt后缀），支持租户数据隔离
-  - **应用层**: server (重构后)
-- **多租户架构**:
-  - **包复制策略**: 基于Epic-007方案，通过复制单租户包创建多租户版本
-  - **租户隔离**: 通过租户ID实现数据隔离，支持多租户部署
-  - **后端包**: 10个多租户模块包，支持租户数据隔离
-- **文件命名**: 保持现有kebab-case命名约定
-- **模块化架构**: 采用分层包结构，支持按需安装和独立开发
-
-### 编码标准 [Source: architecture/coding-standards.md]
-- **代码风格**: TypeScript严格模式，一致的缩进和命名
-- **测试位置**: `__tests__` 文件夹与源码并列（但实际使用`tests/`目录）
-- **覆盖率目标**: 核心业务逻辑 > 80%
-- **测试类型**: 单元测试、集成测试、E2E测试
-- **现有API兼容性**: 确保测试不破坏现有API契约
-- **数据库集成**: 使用测试数据库，避免污染生产数据
-
-### 测试策略 [Source: architecture/testing-strategy.md]
-- **单元测试范围**: 单个函数、类或组件，验证独立单元的正确性
-- **单元测试位置**: `packages/*-module/tests/unit/**/*.test.ts`
-- **集成测试范围**: 多个组件/服务协作，验证模块间集成和交互
-- **集成测试位置**: `packages/*-module/tests/integration/**/*.test.ts`
-- **测试框架**: Vitest + Testing Library + hono/testing + shared-test-util
-- **单元测试覆盖率目标**: ≥ 80%
-- **集成测试覆盖率目标**: ≥ 60%
-- **测试执行频率**: 单元测试每次代码变更，集成测试每次API变更
-
-### 数据模型设计 [Source: docs/prd/epic-004-credit-payment.md#数据库设计]
-**credit_balance_mt表结构**:
-```sql
-CREATE TABLE credit_balance_mt (
-  id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
-  tenant_id INT UNSIGNED NOT NULL COMMENT '租户ID',
-  user_id INT UNSIGNED NOT NULL COMMENT '用户ID',
-  total_limit DECIMAL(10,2) DEFAULT 0.00 COMMENT '总额度',
-  used_amount DECIMAL(10,2) DEFAULT 0.00 COMMENT '已用额度',
-  available_amount DECIMAL(10,2) GENERATED ALWAYS AS (total_limit - used_amount) STORED COMMENT '可用额度',
-  is_enabled TINYINT DEFAULT 1 COMMENT '是否启用(0:禁用,1:启用)',
-  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-  UNIQUE KEY uk_tenant_user (tenant_id, user_id),
-  INDEX idx_tenant_id (tenant_id),
-  INDEX idx_user_id (user_id)
-) COMMENT='用户信用额度表';
-```
-
-**credit_balance_log_mt表结构**:
-```sql
-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(支付扣减), 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 '变更前已用额度',
-  after_used DECIMAL(10,2) COMMENT '变更后已用额度',
-  reference_id VARCHAR(100) COMMENT '关联ID(订单号等)',
-  remark VARCHAR(500) COMMENT '备注',
-  operator_id INT UNSIGNED COMMENT '操作人ID',
-  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  INDEX idx_tenant_user (tenant_id, user_id),
-  INDEX idx_reference (reference_id),
-  INDEX idx_created (created_at)
-) COMMENT='额度变更记录表';
-```
-
-### API设计 [Source: docs/prd/epic-004-credit-payment.md#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` - 结账恢复额度
-
-**服务接口（供其他模块调用）**:
-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`包名导入服务类进行直接调用
-
-### 模块结构 [Source: docs/prd/epic-004-credit-payment.md#模块结构]
-```
-packages/
-├── @d8d/credit-balance-module-mt/     # 多租户余额模块
-│   ├── src/
-│   │   ├── entities/                  # 实体定义
-│   │   │   ├── credit-balance.mt.entity.ts
-│   │   │   └── credit-balance-log.mt.entity.ts
-│   │   │   └── index.ts
-│   │   ├── services/                  # 服务层
-│   │   │   ├── credit-balance.service.ts
-│   │   │   └── index.ts
-│   │   ├── schemas/                   # 数据验证
-│   │   │   └── index.ts
-│   │   ├── routes/                    # API路由
-│   │   │   └── index.ts
-│   │   ├── types/                     # 类型定义
-│   │   │   └── index.ts
-│   │   └── index.ts                   # 主入口文件
-│   ├── tests/                         # 测试文件
-│   ├── tsconfig.json                  # TypeScript配置
-│   ├── vitest.config.ts               # 测试配置
-│   └── package.json
-```
-
-### 文件位置和命名约定
-- **实体文件**: `packages/credit-balance-module-mt/src/entities/credit-balance.mt.entity.ts`
-- **服务文件**: `packages/credit-balance-module-mt/src/services/credit-balance.service.mt.ts`
-- **路由文件**: `packages/credit-balance-module-mt/src/routes/index.mt.ts`
-- **Schema文件**: `packages/credit-balance-module-mt/src/schemas/index.mt.ts`
-- **类型文件**: `packages/credit-balance-module-mt/src/types/index.mt.ts`
-- **主入口文件**: `packages/credit-balance-module-mt/src/index.mt.ts` (导出所有模块接口)
-
-### 多租户实体命名模式
-基于现有多租户模块观察：
-- **实体类名**: 以`Mt`结尾（如`CreditBalanceMt`, `CreditBalanceLogMt`）
-- **表名**: 以`_mt`结尾（如`credit_balance_mt`, `credit_balance_log_mt`）
-- **文件命名**: `*.mt.ts` 或 `*.entity.ts`
-- **必须包含**: `tenant_id`字段用于租户隔离
-
-### 技术约束
-- **数据库**: 使用PostgreSQL 17，支持DECIMAL类型存储金额
-- **事务处理**: 额度扣减和恢复必须使用数据库事务确保数据一致性
-- **幂等性**: 额度恢复操作需要实现幂等性检查，防止重复恢复
-- **金额验证**: 恢复金额不能超过原支付金额
-- **状态检查**: 只有特定订单状态才能触发恢复
-- **日志记录**: 每次额度变更都必须记录详细的变更日志
-
-### 集成点
-1. **用户模块集成**: 通过`user_id`关联用户信息
-2. **订单模块集成**: 订单模块导入`@d8d/credit-balance-module-mt`包，直接调用`CreditBalanceService.restoreBalanceForCancelOrder()`方法
-3. **支付模块集成**: 支付模块导入`@d8d/credit-balance-module-mt`包，直接调用`CreditBalanceService.restoreBalanceForRefund()`方法
-
-### 测试要求
-- **单元测试**: 测试额度计算逻辑、额度扣减和恢复、额度验证
-- **集成测试**: 测试额度支付流程、额度恢复流程、与订单模块集成测试
-- **边界条件测试**: 额度不足、重复操作、无效金额等场景
-- **覆盖率**: 核心业务逻辑必须达到80%以上单元测试覆盖率
-
-### 项目结构注意事项
-- 需要遵循现有的多租户包架构模式
-- 模块应该创建为独立的多租户包：`packages/credit-balance-module-mt/`
-- 包名应为：`@d8d/credit-balance-module-mt`
-- 需要正确配置pnpm workspace依赖关系
-- **注意**：TypeORM迁移脚本将在server包中使用此模块时创建，不在模块包中创建
-- 参考现有的多租户模块包（如`advertisements-module-mt`）的结构和配置
-
-### 没有在架构文档中找到的特定指导
-- 具体的TypeORM实体装饰器配置示例
-- 具体的Hono路由实现示例
-- 具体的测试数据工厂模式实现
-- **迁移脚本创建时机**：根据项目架构，TypeORM迁移脚本应在server包中使用模块时创建，而不是在模块包中创建
-
-## Testing
-### 测试标准 [Source: architecture/testing-strategy.md]
-- **测试文件位置**: `packages/credit-balance-module-mt/tests/` 目录下
-- **单元测试位置**: `tests/unit/**/*.test.ts`
-- **集成测试位置**: `tests/integration/**/*.test.ts`
-- **测试框架**: Vitest + hono/testing + shared-test-util
-- **覆盖率要求**: 单元测试 ≥ 80%，集成测试 ≥ 60%
-- **测试模式**: 使用测试数据工厂模式，避免硬编码测试数据
-- **数据库测试**: 使用专用测试数据库，事务回滚机制
-
-### 测试策略要求
-- **单元测试**: 验证单个服务方法、实体定义、Schema验证
-- **集成测试**: 验证API端点功能、模块间协作、数据库操作
-- **边界测试**: 测试额度不足、无效输入、重复操作等边界条件
-- **错误处理测试**: 测试各种错误场景和异常情况
-- **性能测试**: 确保API响应时间 < 100ms (p95)
-
-### 测试数据管理
-- 使用测试数据工厂模式创建测试数据
-- 每个测试后清理测试数据（事务回滚）
-- 使用唯一标识符确保测试数据隔离
-- 模拟外部依赖（如用户模块、订单模块）
-
-## Change Log
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| 2025-12-01 | 1.0 | 初始故事创建 | Bob (Scrum Master) |
-
-## Dev Agent Record
-*此部分由开发代理在实现过程中填写*
-
-### Agent Model Used
-- Claude Code (d8d-model)
-
-### Debug Log References
-- 修复PostgreSQL不支持tinyint类型问题：将`tinyint`改为`smallint`
-- 集成测试数据库连接问题：使用`IntegrationTestDatabase`类替代`createIntegrationTestDb`函数
-
-### Completion Notes List
-1. ✅ 成功创建多租户信用额度模块包结构
-2. ✅ 实现信用额度实体（CreditBalanceMt）和额度变更记录实体（CreditBalanceLogMt）
-3. ✅ 实现完整的额度管理服务（CreditBalanceService），包含设置额度、调整额度、扣减额度、恢复额度等方法
-4. ✅ 实现API路由，支持查询额度、设置额度、调整额度、查询变更记录、额度支付、结账恢复等功能
-5. ✅ 编写完整的单元测试（13个测试用例）和集成测试（11个测试用例）
-6. ✅ 配置包依赖和导出，确保模块可以正确导入和使用
-7. ✅ 修复PostgreSQL不支持tinyint类型问题：将`tinyint`改为`smallint`
-8. ✅ 修复集成测试数据库连接问题：使用`IntegrationTestDatabase`类替代`createIntegrationTestDb`函数
-9. ✅ 修复路由架构问题：参照订单模块重构为链式聚合模式，使用独立路由文件聚合导出
-10. ✅ 修复测试写法问题：参照订单模块重写集成测试，使用真实JWT令牌和RPC风格API调用
-11. ✅ 修复类型检查错误：修复分页参数类型、枚举使用、referenceId类型等问题
-12. ✅ 修复小数精度问题：TypeORM decimal字段返回字符串，在服务中转换为数字
-13. ✅ 修复数据库索引重复创建问题：CreditBalanceLogMt实体中两个字段使用相同索引名称
-14. ✅ 修复401认证失败问题：创建测试数据工厂，使用真实用户实体生成JWT令牌
-15. ✅ 修复Zod验证错误：将Schema中的`z.number()`改为`z.coerce.number()`
-16. ✅ 单元测试通过率100%，集成测试通过率100%
-
-### File List
-**创建的文件：**
-1. `packages/credit-balance-module-mt/package.json` - 包配置
-2. `packages/credit-balance-module-mt/tsconfig.json` - TypeScript配置
-3. `packages/credit-balance-module-mt/vitest.config.ts` - 测试配置
-4. `packages/credit-balance-module-mt/src/entities/credit-balance.mt.entity.ts` - 信用额度实体
-5. `packages/credit-balance-module-mt/src/entities/credit-balance-log.mt.entity.ts` - 额度变更记录实体
-6. `packages/credit-balance-module-mt/src/entities/index.ts` - 实体导出
-7. `packages/credit-balance-module-mt/src/services/credit-balance.service.ts` - 额度管理服务
-8. `packages/credit-balance-module-mt/src/services/index.ts` - 服务导出
-9. `packages/credit-balance-module-mt/src/schemas/index.ts` - 数据验证Schema
-10. `packages/credit-balance-module-mt/src/routes/index.ts` - API路由聚合文件
-11. `packages/credit-balance-module-mt/src/routes/get-balance.mt.ts` - 查询用户额度路由
-12. `packages/credit-balance-module-mt/src/routes/set-limit.mt.ts` - 设置用户额度路由
-13. `packages/credit-balance-module-mt/src/routes/adjust-limit.mt.ts` - 调整用户额度路由
-14. `packages/credit-balance-module-mt/src/routes/get-balance-logs.mt.ts` - 查询额度变更记录路由
-15. `packages/credit-balance-module-mt/src/routes/payment.mt.ts` - 额度支付路由
-16. `packages/credit-balance-module-mt/src/routes/checkout.mt.ts` - 结账恢复额度路由
-17. `packages/credit-balance-module-mt/src/types/index.ts` - 类型定义
-18. `packages/credit-balance-module-mt/src/index.ts` - 主入口文件
-19. `packages/credit-balance-module-mt/tests/unit/credit-balance.service.test.ts` - 服务单元测试
-20. `packages/credit-balance-module-mt/tests/integration/credit-balance-routes.integration.test.ts` - API集成测试
-21. `packages/credit-balance-module-mt/tests/utils/test-data-factory.ts` - 测试数据工厂
-
-**修改的文件：**
-1. `docs/stories/004.001.credit-balance-module-mt.story.md` - 更新任务状态和开发记录
-
-## QA Results
-*此部分由QA代理在审查完成后填写*