first commit

docs/API在线调试功能说明.md

@@ -0,0 +1,202 @@
+# API在线调试功能说明
+
+## 功能概述
+
+API在线调试功能为用户提供了一个可视化的界面来测试已订阅的API接口，让用户能够：
+
+1. **选择产品**：从已订阅的产品列表中选择要调试的API
+2. **输入参数**：根据产品要求输入测试参数
+3. **查看加密过程**：了解参数如何被加密处理
+4. **获取响应**：查看API的实际响应结果
+5. **分析结果**：了解API调用的完整过程
+
+## 功能特点
+
+### 1. 产品选择
+- 自动加载用户已订阅的产品列表
+- 显示产品名称、代码和价格信息
+- 只显示有效的订阅产品
+
+### 2. 参数输入
+- 统一的参数结构：姓名、身份证号、手机号
+- 实时参数验证
+- 参数示例和说明
+
+### 3. 加密处理
+- 自动使用用户的Secret Key进行AES加密
+- 显示原始参数和加密后的参数
+- 确保参数安全性
+
+### 4. 调试结果
+- 完整的请求信息（产品名称、API代码、交易ID等）
+- 请求时间和响应时间统计
+- 成功/失败状态显示
+- 原始响应数据展示
+
+## 技术实现
+
+### 后端接口
+
+#### 1. 加密接口
+```
+POST /api/v1/encrypt
+Content-Type: application/json
+Authorization: Bearer {token}
+
+{
+  "data": {
+    "name": "张三",
+    "id_card": "110101199001011234",
+    "mobile": "13800138000"
+  }
+}
+```
+
+**响应**：
+```json
+{
+  "success": true,
+  "data": {
+    "encrypted_data": "加密后的Base64字符串"
+  },
+  "message": "加密成功"
+}
+```
+
+#### 2. API调用接口
+```
+POST /api/v1/{api_code}
+Content-Type: application/json
+Access-Id: {access_id}
+
+{
+  "data": "加密后的参数"
+}
+```
+
+### 前端实现
+
+#### 1. 页面结构
+- **调试配置区域**：产品选择、参数输入
+- **调试结果区域**：请求信息、响应数据
+- **使用说明区域**：操作指南和注意事项
+
+#### 2. 核心功能
+- 自动加载用户订阅产品
+- 参数验证和格式化
+- 加密参数调用
+- 结果展示和分析
+
+## 使用流程
+
+### 1. 访问调试页面
+- 登录系统后，进入"开发者中心" → "在线调试"
+- 页面会自动加载用户的API密钥和订阅产品
+
+### 2. 选择产品
+- 从下拉列表中选择要调试的产品
+- 系统会显示产品的详细信息
+
+### 3. 输入参数
+- 填写姓名（必填）
+- 填写身份证号（必填，18位）
+- 填写手机号（必填，11位）
+
+### 4. 开始调试
+- 点击"开始调试"按钮
+- 系统会自动加密参数并调用API
+- 等待响应结果
+
+### 5. 查看结果
+- 查看请求信息（交易ID、响应时间等）
+- 查看原始参数和加密参数
+- 查看API响应结果
+
+## 注意事项
+
+### 1. 费用说明
+- 每次调试都会消耗API调用次数
+- 会按照产品价格扣除相应费用
+- 调试结果会记录在调用记录中
+
+### 2. 数据安全
+- 所有参数都经过AES加密处理
+- 使用用户的专属Secret Key
+- 不会在日志中记录敏感信息
+
+### 3. 使用建议
+- 使用真实的测试数据进行调试
+- 注意参数格式的正确性
+- 调试结果仅供参考
+
+### 4. 错误处理
+- 网络错误会显示相应提示
+- API调用失败会显示错误信息
+- 参数错误会给出具体提示
+
+## 技术架构
+
+### 前端架构
+```
+ApiDebugger.vue
+├── 产品选择组件
+├── 参数输入组件
+├── 加密处理逻辑
+├── 结果展示组件
+└── 使用说明组件
+```
+
+### 后端架构
+```
+API Handler
+├── 加密接口 (EncryptParams)
+├── API调用接口 (HandleApiCall)
+└── 密钥管理接口 (GetUserApiKeys)
+```
+
+### 数据流
+1. 前端获取用户订阅产品
+2. 用户输入参数
+3. 前端调用加密接口
+4. 前端使用加密参数调用API
+5. 后端处理并返回结果
+6. 前端展示调试结果
+
+## 扩展功能
+
+### 1. 参数模板
+- 支持保存常用的参数组合
+- 快速填充测试数据
+- 参数历史记录
+
+### 2. 批量调试
+- 支持多个API同时调试
+- 批量参数输入
+- 结果对比分析
+
+### 3. 调试历史
+- 保存调试记录
+- 结果回放功能
+- 性能统计分析
+
+### 4. 高级功能
+- 自定义参数验证
+- 响应数据解析
+- 错误模式分析
+
+## 常见问题
+
+### Q1: 为什么看不到某些产品？
+A: 只有已订阅且有效的产品才会显示在列表中。
+
+### Q2: 调试失败怎么办？
+A: 检查参数格式是否正确，网络连接是否正常，账户余额是否充足。
+
+### Q3: 如何查看详细的错误信息？
+A: 在调试结果区域会显示完整的错误信息和响应数据。
+
+### Q4: 调试会消耗费用吗？
+A: 是的，每次调试都会按照产品价格扣除相应费用。
+
+### Q5: 如何保护我的API密钥？
+A: Secret Key默认隐藏显示，可以点击"显示"按钮查看，建议不要泄露给他人。 

docs/API调用记录和钱包交易记录前端说明.md

@@ -0,0 +1,512 @@
+# API调用记录和钱包交易记录前端功能说明
+
+## 概述
+
+本文档描述了新增的API调用记录和钱包交易记录前端页面功能，包括页面设计、交互逻辑和技术实现。
+
+## 页面功能
+
+### 1. API调用记录页面 (`/api/usage`)
+
+#### 页面布局
+- **标题**: "调用记录"
+- **副标题**: "查看您的API调用历史记录"
+- **布局组件**: `ListPageLayout`
+
+#### 功能模块
+
+##### 1.1 统计信息区域
+- **总调用次数**: 显示用户的总API调用次数
+- **成功率**: 显示API调用的成功率百分比
+- **样式**: 卡片式设计，带有渐变背景和阴影效果
+
+##### 1.2 筛选功能
+- **搜索调用**: 支持按交易ID或产品名称搜索
+- **调用状态**: 下拉选择（全部/成功/失败/处理中）
+- **时间范围**: 日期时间范围选择器
+- **操作按钮**: 重置筛选、应用筛选
+
+##### 1.3 数据表格
+**列定义**:
+- **交易ID**: 显示API调用的唯一标识
+- **接口名称**: 显示调用的API接口名称和ID
+- **状态**: 状态标签（成功/失败/处理中）
+- **费用**: 显示调用产生的费用
+- **客户端IP**: 显示调用来源IP
+- **调用时间**: 显示API调用的开始时间
+- **完成时间**: 显示API调用的完成时间
+- **操作**: 查看详情按钮
+
+##### 1.4 详情弹窗
+**显示内容**:
+- **基本信息**: 交易ID、状态、接口名称、费用、客户端IP
+- **时间信息**: 调用时间、完成时间
+- **错误信息**: 错误类型和错误消息（如果有）
+- **请求参数**: JSON格式的请求参数
+- **响应数据**: JSON格式的响应数据
+
+##### 1.5 分页功能
+- **分页器**: 支持页码跳转、每页数量选择
+- **统计信息**: 显示总记录数和当前页信息
+
+#### 交互逻辑
+
+##### 搜索功能
+```javascript
+// 防抖搜索，避免频繁请求
+const handleSearch = () => {
+  if (searchTimer) {
+    clearTimeout(searchTimer)
+  }
+  searchTimer = setTimeout(() => {
+    currentPage.value = 1
+    loadApiCalls()
+  }, 500)
+}
+```
+
+##### 筛选功能
+```javascript
+// 处理筛选变化
+const handleFilterChange = () => {
+  currentPage.value = 1
+  loadApiCalls()
+}
+
+// 处理时间范围变化
+const handleDateRangeChange = (range) => {
+  if (range && range.length === 2) {
+    filters.start_time = range[0]
+    filters.end_time = range[1]
+  } else {
+    filters.start_time = ''
+    filters.end_time = ''
+  }
+  currentPage.value = 1
+  loadApiCalls()
+}
+```
+
+##### 数据加载
+```javascript
+// 加载API调用记录
+const loadApiCalls = async () => {
+  loading.value = true
+  try {
+    const params = {
+      page: currentPage.value,
+      page_size: pageSize.value,
+      ...filters
+    }
+
+    const response = await apiApi.getUserApiCalls(params)
+    apiCalls.value = response.data?.items || []
+    total.value = response.data?.total || 0
+  } catch (error) {
+    console.error('加载API调用记录失败:', error)
+    ElMessage.error('加载API调用记录失败')
+  } finally {
+    loading.value = false
+  }
+}
+```
+
+### 2. 钱包交易记录页面 (`/finance/transactions`)
+
+#### 页面布局
+- **标题**: "消费记录"
+- **副标题**: "查看您的钱包消费历史记录"
+- **布局组件**: `ListPageLayout`
+
+#### 功能模块
+
+##### 2.1 统计信息区域
+- **总消费次数**: 显示用户的总消费次数
+- **总消费金额**: 显示用户的总消费金额
+- **样式**: 卡片式设计，金额显示为红色突出
+
+##### 2.2 筛选功能
+- **搜索交易**: 支持按API调用ID搜索
+- **金额范围**: 最小金额和最大金额输入框
+- **时间范围**: 日期时间范围选择器
+- **操作按钮**: 重置筛选、应用筛选
+
+##### 2.3 数据表格
+**列定义**:
+- **交易ID**: 显示钱包交易的唯一标识
+- **API调用ID**: 显示关联的API调用ID
+- **消费金额**: 显示消费金额（红色突出）
+- **消费时间**: 显示交易创建时间
+- **更新时间**: 显示交易最后更新时间
+- **操作**: 查看详情按钮
+
+##### 2.4 详情弹窗
+**显示内容**:
+- **基本信息**: 交易ID、用户ID、API调用ID、消费金额
+- **时间信息**: 创建时间、更新时间
+- **交易说明**: 解释交易记录的用途和含义
+
+##### 2.5 分页功能
+- **分页器**: 支持页码跳转、每页数量选择
+- **统计信息**: 显示总记录数和当前页信息
+
+#### 交互逻辑
+
+##### 数据加载
+```javascript
+// 加载钱包交易记录
+const loadTransactions = async () => {
+  loading.value = true
+  try {
+    const params = {
+      page: currentPage.value,
+      page_size: pageSize.value,
+      ...filters
+    }
+
+    const response = await financeApi.getUserWalletTransactions(params)
+    transactions.value = response.data?.items || []
+    total.value = response.data?.total || 0
+  } catch (error) {
+    console.error('加载钱包交易记录失败:', error)
+    ElMessage.error('加载钱包交易记录失败')
+  } finally {
+    loading.value = false
+  }
+}
+```
+
+##### 统计计算
+```javascript
+// 加载统计数据
+const loadStats = async () => {
+  try {
+    // 计算统计数据
+    const totalAmount = transactions.value.reduce((sum, transaction) => {
+      return sum + Number(transaction.amount || 0)
+    }, 0)
+
+    stats.value = {
+      total_transactions: total.value,
+      total_amount: totalAmount
+    }
+  } catch (error) {
+    console.error('加载统计数据失败:', error)
+  }
+}
+```
+
+## 技术实现
+
+### 1. 组件架构
+
+#### 通用组件
+- **ListPageLayout**: 列表页面布局组件
+- **FilterSection**: 筛选区域组件
+- **FilterItem**: 筛选项组件
+- **LoadingSpinner**: 加载动画组件
+
+#### 页面组件
+- **Usage.vue**: API调用记录页面
+- **Transactions.vue**: 钱包交易记录页面
+
+### 2. API接口
+
+#### API调用记录接口
+```javascript
+// API相关接口
+export const apiApi = {
+  // 用户API调用记录
+  getUserApiCalls: (params) => request.get('/api/v1/my/api-calls', { params })
+}
+```
+
+#### 钱包交易记录接口
+```javascript
+// 财务相关接口
+export const financeApi = {
+  // 钱包交易记录
+  getUserWalletTransactions: (params) => request.get('/finance/wallet/transactions', { params })
+}
+```
+
+### 3. 状态管理
+
+#### 响应式数据
+```javascript
+// 页面数据
+const loading = ref(false)
+const apiCalls = ref([])
+const total = ref(0)
+const currentPage = ref(1)
+const pageSize = ref(10)
+
+// 筛选条件
+const filters = reactive({
+  keyword: '',
+  status: '',
+  start_time: '',
+  end_time: ''
+})
+
+// 统计数据
+const stats = ref({
+  total_calls: 0,
+  success_rate: '0%'
+})
+```
+
+### 4. 工具函数
+
+#### 格式化函数
+```javascript
+// 格式化价格
+const formatPrice = (price) => {
+  if (!price) return '0.00'
+  return Number(price).toFixed(2)
+}
+
+// 格式化日期
+const formatDate = (date) => {
+  if (!date) return '-'
+  return new Date(date).toLocaleDateString('zh-CN')
+}
+
+// 格式化时间
+const formatTime = (date) => {
+  if (!date) return '-'
+  return new Date(date).toLocaleTimeString('zh-CN', {
+    hour: '2-digit',
+    minute: '2-digit'
+  })
+}
+
+// 格式化JSON
+const formatJson = (jsonString) => {
+  try {
+    return JSON.stringify(JSON.parse(jsonString), null, 2)
+  } catch {
+    return jsonString
+  }
+}
+```
+
+#### 状态处理函数
+```javascript
+// 获取状态类型
+const getStatusType = (status) => {
+  switch (status) {
+    case 'success':
+      return 'success'
+    case 'failed':
+      return 'danger'
+    case 'pending':
+      return 'warning'
+    default:
+      return 'info'
+  }
+}
+
+// 获取状态文本
+const getStatusText = (status) => {
+  switch (status) {
+    case 'success':
+      return '成功'
+    case 'failed':
+      return '失败'
+    case 'pending':
+      return '处理中'
+    default:
+      return '未知'
+  }
+}
+```
+
+## 样式设计
+
+### 1. 统计卡片样式
+```css
+.stat-item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  padding: 16px 24px;
+  background: rgba(255, 255, 255, 0.8);
+  backdrop-filter: blur(10px);
+  border: 1px solid rgba(226, 232, 240, 0.6);
+  border-radius: 12px;
+  min-width: 120px;
+}
+
+.stat-value {
+  font-size: 24px;
+  font-weight: 700;
+  color: #1e293b;
+  line-height: 1;
+  margin-bottom: 4px;
+}
+
+.stat-label {
+  font-size: 13px;
+  color: #64748b;
+  font-weight: 500;
+}
+```
+
+### 2. 详情弹窗样式
+```css
+.detail-dialog :deep(.el-dialog) {
+  border-radius: 16px;
+  overflow: hidden;
+}
+
+.detail-dialog :deep(.el-dialog__header) {
+  background: linear-gradient(135deg, #f8fafc 0%, #f1f5f9 100%);
+  border-bottom: 1px solid rgba(226, 232, 240, 0.6);
+  padding: 20px 24px;
+}
+
+.detail-dialog :deep(.el-dialog__body) {
+  padding: 24px;
+}
+```
+
+### 3. 表格样式优化
+```css
+:deep(.el-table) {
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+:deep(.el-table th) {
+  background: #f8fafc !important;
+  border-bottom: 1px solid #e2e8f0;
+}
+
+:deep(.el-table td) {
+  border-bottom: 1px solid #f1f5f9;
+}
+
+:deep(.el-table tr:hover > td) {
+  background: #f8fafc !important;
+}
+```
+
+### 4. 响应式设计
+```css
+/* 响应式设计 */
+@media (max-width: 768px) {
+  .stat-item {
+    padding: 12px 16px;
+    min-width: 100px;
+  }
+
+  .stat-value {
+    font-size: 20px;
+  }
+
+  .stat-label {
+    font-size: 12px;
+  }
+
+  .detail-item {
+    margin-bottom: 16px;
+  }
+
+  .detail-label {
+    font-size: 13px;
+  }
+
+  .detail-value {
+    font-size: 14px;
+  }
+}
+```
+
+## 用户体验优化
+
+### 1. 加载状态
+- **加载动画**: 使用Element Plus的LoadingSpinner组件
+- **骨架屏**: 数据加载时显示占位内容
+- **错误处理**: 友好的错误提示信息
+
+### 2. 交互反馈
+- **防抖搜索**: 避免频繁的API请求
+- **即时反馈**: 操作后立即更新界面状态
+- **确认操作**: 重要操作需要用户确认
+
+### 3. 数据展示
+- **分页加载**: 避免一次性加载大量数据
+- **虚拟滚动**: 大数据量时的性能优化
+- **数据缓存**: 减少重复请求
+
+### 4. 移动端适配
+- **响应式布局**: 适配不同屏幕尺寸
+- **触摸友好**: 按钮和交互元素适合触摸操作
+- **性能优化**: 移动端性能优化
+
+## 错误处理
+
+### 1. 网络错误
+```javascript
+try {
+  const response = await apiApi.getUserApiCalls(params)
+  // 处理成功响应
+} catch (error) {
+  console.error('加载API调用记录失败:', error)
+  ElMessage.error('加载API调用记录失败')
+}
+```
+
+### 2. 数据验证
+```javascript
+// 验证时间格式
+const handleDateRangeChange = (range) => {
+  if (range && range.length === 2) {
+    // 验证时间格式
+    const startTime = new Date(range[0])
+    const endTime = new Date(range[1])
+    
+    if (isNaN(startTime.getTime()) || isNaN(endTime.getTime())) {
+      ElMessage.warning('时间格式不正确')
+      return
+    }
+    
+    filters.start_time = range[0]
+    filters.end_time = range[1]
+  }
+}
+```
+
+### 3. 边界情况
+```javascript
+// 处理空数据
+<div v-else-if="apiCalls.length === 0" class="text-center py-12">
+  <el-empty description="暂无调用记录">
+    <el-button type="primary" @click="$router.push('/api')">
+      前往开发者中心
+    </el-button>
+  </el-empty>
+</div>
+```
+
+## 性能优化
+
+### 1. 组件优化
+- **懒加载**: 路由级别的组件懒加载
+- **缓存**: 使用keep-alive缓存页面状态
+- **虚拟化**: 大数据列表的虚拟滚动
+
+### 2. 请求优化
+- **防抖**: 搜索输入防抖处理
+- **缓存**: API响应数据缓存
+- **预加载**: 关键数据的预加载
+
+### 3. 渲染优化
+- **v-show vs v-if**: 合理使用条件渲染
+- **key属性**: 列表渲染时使用唯一key
+- **计算属性**: 复杂计算的缓存
+
+## 总结
+
+API调用记录和钱包交易记录前端页面提供了完整的用户界面和交互体验，通过合理的组件设计、状态管理和样式优化，确保了良好的用户体验和系统性能。页面支持响应式设计，适配不同设备，并提供了丰富的筛选和查看功能。 

docs/产品API配置管理功能说明.md

@@ -0,0 +1,164 @@
+# 产品API配置管理功能说明
+
+## 功能概述
+
+产品API配置管理功能允许管理员为每个产品配置API接口的请求参数、响应字段和响应示例，这些配置将用于前端的在线调试功能。
+
+## 功能特性
+
+### 1. 请求参数配置
+- **参数名称**: 显示给用户的参数名称（如：姓名）
+- **字段名**: API接口中使用的字段名（如：name）
+- **参数类型**: 支持文本、数字、密码、邮箱、手机号、身份证等类型
+- **是否必填**: 标识该参数是否为必填项
+- **参数示例**: 提供给用户的输入示例
+- **验证规则**: 正则表达式验证规则
+- **参数描述**: 参数的详细说明
+
+### 2. 响应字段配置
+- **字段名称**: 显示给用户的字段名称（如：姓名）
+- **字段路径**: JSON响应中的字段路径（如：data.name）
+- **字段类型**: 支持字符串、数字、布尔值、对象、数组等类型
+- **是否必填**: 标识该字段是否在响应中必填
+- **字段示例**: 字段的示例值
+- **字段描述**: 字段的详细说明
+
+### 3. 响应示例
+- **JSON格式**: 完整的API响应示例
+- **实时验证**: 确保输入的JSON格式正确
+- **格式化显示**: 自动格式化JSON内容
+
+## 使用方法
+
+### 1. 访问产品管理页面
+1. 登录管理员账户
+2. 进入"产品管理"页面
+3. 在产品列表中找到需要配置的产品
+
+### 2. 配置API
+1. 点击产品行的"配置API"按钮
+2. 在弹出的配置窗口中：
+   - 查看产品基本信息
+   - 添加/编辑请求参数
+   - 添加/编辑响应字段
+   - 输入JSON响应示例
+3. 点击"创建"或"更新"保存配置
+
+### 3. 配置示例
+
+#### 请求参数配置示例
+```json
+[
+  {
+    "name": "姓名",
+    "field": "name",
+    "type": "text",
+    "required": true,
+    "description": "用户真实姓名",
+    "example": "张三",
+    "validation": "^[\\u4e00-\\u9fa5]{2,4}$"
+  },
+  {
+    "name": "身份证号",
+    "field": "id_card",
+    "type": "idcard",
+    "required": true,
+    "description": "用户身份证号码",
+    "example": "110101199001011234",
+    "validation": "^[1-9]\\d{5}(18|19|20)\\d{2}((0[1-9])|(1[0-2]))(([0-2][1-9])|10|20|30|31)\\d{3}[0-9Xx]$"
+  }
+]
+```
+
+#### 响应字段配置示例
+```json
+[
+  {
+    "name": "结果",
+    "path": "result",
+    "type": "string",
+    "required": true,
+    "description": "查询结果",
+    "example": "success"
+  },
+  {
+    "name": "数据",
+    "path": "data",
+    "type": "object",
+    "required": false,
+    "description": "查询结果数据",
+    "example": "{}"
+  }
+]
+```
+
+#### 响应示例
+```json
+{
+  "result": "success",
+  "code": 200,
+  "message": "查询成功",
+  "data": {
+    "name": "张三",
+    "id_card": "110101199001011234",
+    "mobile": "13800138000",
+    "status": "正常",
+    "query_time": "2024-01-01 12:00:00"
+  }
+}
+```
+
+## 技术实现
+
+### 后端架构
+- **实体层**: `ProductApiConfig` 实体
+- **仓库层**: `ProductApiConfigRepository` 接口和实现
+- **领域服务层**: `ProductApiConfigService` 业务逻辑
+- **应用服务层**: `ProductApiConfigApplicationService` 业务流程
+- **HTTP层**: `ProductAdminHandler` 接口处理
+
+### 前端架构
+- **组件**: `ProductApiConfigDialog.vue` 配置弹窗
+- **页面**: 集成到产品管理页面
+- **API**: 通过 `productAdminApi` 调用后端接口
+
+### 数据库设计
+```sql
+CREATE TABLE product_api_configs (
+  id VARCHAR(36) PRIMARY KEY,
+  product_id VARCHAR(36) NOT NULL UNIQUE,
+  request_params JSON NOT NULL,
+  response_fields JSON NOT NULL,
+  response_example JSON NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  deleted_at TIMESTAMP NULL,
+  FOREIGN KEY (product_id) REFERENCES products(id)
+);
+```
+
+## 初始化脚本
+
+项目提供了初始化脚本 `scripts/init_product_api_configs.go`，可以为现有产品创建默认的API配置：
+
+```bash
+cd tyapi-server-gin
+go run scripts/init_product_api_configs.go
+```
+
+## 注意事项
+
+1. **唯一性**: 每个产品只能有一个API配置
+2. **JSON格式**: 响应示例必须是有效的JSON格式
+3. **字段路径**: 响应字段路径使用点号分隔（如：data.name）
+4. **验证规则**: 支持正则表达式验证规则
+5. **权限控制**: 只有管理员可以配置API
+
+## 扩展功能
+
+未来可以考虑添加的功能：
+1. **配置模板**: 提供常用的配置模板
+2. **批量导入**: 支持批量导入配置
+3. **版本管理**: 支持配置版本管理
+4. **测试功能**: 集成API测试功能
+5. **文档生成**: 自动生成API文档 

docs/充值功能前端说明.md

@@ -0,0 +1,196 @@
+# 充值功能前端说明
+
+## 概述
+
+前端充值功能包含两个主要页面：
+1. **钱包充值页面** (`/finance/wallet`) - 用户选择充值方式并进行充值
+2. **充值成功页面** (`/finance/wallet/success`) - 支付宝充值成功后的重定向页面
+
+## 页面功能
+
+### 1. 钱包充值页面 (`Wallet.vue`)
+
+#### 功能特性
+- **钱包余额展示** - 显示用户当前钱包余额
+- **充值方式选择** - 支持支付宝充值和对公转账两种方式
+- **支付宝充值** - 输入充值金额，跳转到支付宝支付（待接入）
+- **对公转账** - 显示银行账户信息，支持转账记录提交
+
+#### 页面结构
+```
+钱包充值页面
+├── 页面头部
+│   ├── 标题：钱包充值
+│   └── 返回按钮
+├── 钱包余额信息
+│   ├── 余额图标
+│   └── 当前余额显示
+├── 充值方式选择
+│   ├── 支付宝充值卡片
+│   └── 对公转账卡片
+├── 支付宝充值表单（选中时显示）
+│   ├── 充值金额输入
+│   └── 立即充值按钮
+└── 对公转账信息（选中时显示）
+    ├── 银行账户信息
+    ├── 转账说明
+    └── 转账记录表单
+```
+
+#### 交互流程
+
+**支付宝充值流程：**
+1. 用户选择"支付宝充值"
+2. 输入充值金额（最低1元）
+3. 点击"立即充值"
+4. 确认充值金额
+5. 跳转到支付宝支付页面（待实现）
+6. 支付成功后跳转到充值成功页面
+
+**对公转账流程：**
+1. 用户选择"对公转账"
+2. 查看银行账户信息
+3. 复制银行账号（可选）
+4. 进行银行转账
+5. 填写转账记录表单
+6. 提交转账记录
+7. 等待人工确认（1-2个工作日）
+
+### 2. 充值成功页面 (`WalletSuccess.vue`)
+
+#### 功能特性
+- **成功状态展示** - 显示充值成功图标和标题
+- **充值详情** - 显示充值金额、方式、时间、当前余额
+- **操作按钮** - 提供多个后续操作选项
+- **温馨提示** - 显示相关提示信息
+
+#### 页面结构
+```
+充值成功页面
+├── 成功状态
+│   ├── 成功图标
+│   ├── 成功标题
+│   └── 成功副标题
+├── 充值详情
+│   ├── 充值金额
+│   ├── 充值方式
+│   ├── 充值时间
+│   └── 当前余额
+├── 操作按钮
+│   ├── 返回财务中心
+│   ├── 去订阅产品
+│   └── 开发者中心
+└── 温馨提示
+    └── 相关提示信息
+```
+
+## API接口
+
+### 财务相关接口
+
+```javascript
+// 获取钱包信息
+financeApi.getWallet()
+
+// 对公转账充值
+financeApi.transferRecharge({
+  amount: 100.00,
+  transfer_order_id: 'TR202412010001',
+  bank_account: '6222021234567890123',
+  bank_name: '中国工商银行',
+  notes: '转账备注'
+})
+
+// 赠送充值（管理员使用）
+financeApi.giftRecharge({
+  amount: 50.00,
+  gift_reason: '新用户注册奖励',
+  notes: '系统自动赠送'
+})
+```
+
+## 样式设计
+
+### 设计风格
+- 遵循项目整体设计风格
+- 使用渐变色彩和卡片式布局
+- 响应式设计，支持移动端
+- 统一的颜色和字体规范
+
+### 主要样式特点
+- **渐变背景** - 钱包余额卡片使用紫色渐变
+- **卡片布局** - 充值方式选择使用卡片式设计
+- **悬停效果** - 充值方式卡片支持悬停动画
+- **响应式** - 移动端适配，布局自适应
+
+## 配置信息
+
+### 对公转账信息配置
+```javascript
+const transferInfo = {
+  bankName: '中国工商银行',
+  bankAccount: '6222021234567890123',
+  accountName: '某某科技有限公司'
+}
+```
+
+### 用户信息配置
+```javascript
+const userInfo = {
+  userId: 'USER123456' // 实际应从用户状态获取
+}
+```
+
+## 路由配置
+
+```javascript
+{
+  path: '/finance',
+  component: () => import('@/layouts/MainLayout.vue'),
+  meta: { requiresAuth: true },
+  children: [
+    {
+      path: 'wallet',
+      name: 'Wallet',
+      component: () => import('@/pages/finance/Wallet.vue'),
+      meta: { title: '余额充值' }
+    },
+    {
+      path: 'wallet/success',
+      name: 'WalletSuccess',
+      component: () => import('@/pages/finance/WalletSuccess.vue'),
+      meta: { title: '充值成功' }
+    }
+  ]
+}
+```
+
+## 后续开发计划
+
+### 1. 支付宝支付集成
+- 集成支付宝支付SDK
+- 实现支付页面跳转
+- 处理支付回调
+- 添加支付状态查询
+
+### 2. 充值记录页面
+- 创建充值记录列表页面
+- 支持按类型、状态筛选
+- 显示充值详情和状态
+
+### 3. 实时余额更新
+- 实现WebSocket实时余额更新
+- 添加余额变动通知
+
+### 4. 移动端优化
+- 优化移动端交互体验
+- 添加手势操作支持
+
+## 注意事项
+
+1. **金额验证** - 充值金额必须大于等于1元
+2. **表单验证** - 所有必填字段都有相应的验证规则
+3. **错误处理** - 完善的错误提示和异常处理
+4. **用户体验** - 加载状态、成功提示等交互反馈
+5. **安全性** - 敏感信息（如银行账号）的显示和复制功能
+6. **响应式** - 确保在不同设备上的良好显示效果 

docs/支付宝充值功能说明.md

@@ -0,0 +1,295 @@
+# 支付宝充值功能说明
+
+## 功能概述
+
+本功能实现了完整的支付宝充值流程，从前端用户操作到后端支付处理，再到支付回调确认，形成了完整的闭环。
+
+## 功能特性
+
+### 1. 前端功能
+- **钱包余额显示**：实时显示用户当前钱包余额和状态
+- **充值方式选择**：支持支付宝充值和对公转账两种方式
+- **支付宝充值表单**：用户输入充值金额，系统创建支付订单
+- **支付跳转**：自动跳转到支付宝支付页面
+- **支付结果页面**：
+  - 支付成功页面：显示充值详情和操作按钮
+  - 支付失败页面：显示失败原因和重试选项
+
+### 2. 后端功能
+- **支付宝订单创建**：生成唯一订单号，创建支付宝支付订单
+- **异步回调处理**：处理支付宝支付成功通知，更新钱包余额
+- **同步回调处理**：处理用户支付完成后的页面跳转
+- **充值记录管理**：完整的充值记录创建、查询和管理
+- **事务保护**：确保充值过程的原子性和数据一致性
+
+## 技术架构
+
+### 前端架构
+```
+Wallet.vue (钱包页面)
+├── 余额显示
+├── 充值方式选择
+├── 支付宝充值表单
+└── 支付跳转逻辑
+
+WalletSuccess.vue (支付成功页面)
+├── 成功状态显示
+├── 充值详情展示
+└── 操作按钮
+
+WalletFail.vue (支付失败页面)
+├── 失败状态显示
+├── 失败原因说明
+└── 重试和客服选项
+```
+
+### 后端架构
+```
+FinanceHandler (HTTP处理器)
+├── CreateAlipayRecharge (创建充值订单)
+├── HandleAlipayCallback (异步回调处理)
+└── HandleAlipayReturn (同步回调处理)
+
+FinanceApplicationService (应用服务)
+├── CreateAlipayRechargeOrder (业务流程编排)
+├── HandleAlipayCallback (回调处理)
+└── GetUserRechargeRecords (充值记录查询)
+
+RechargeRecordService (充值记录服务)
+├── CreateAlipayRecharge (创建充值记录)
+├── CreateAlipayOrder (创建支付宝订单)
+└── HandleAlipayPaymentSuccess (支付成功处理)
+
+AliPayService (支付宝服务)
+├── CreateAlipayOrder (创建支付订单)
+├── HandleAliPaymentNotification (回调验证)
+└── GenerateOutTradeNo (生成订单号)
+```
+
+## API接口
+
+### 1. 创建支付宝充值订单
+```
+POST /api/v1/finance/wallet/alipay-recharge
+Content-Type: application/json
+Authorization: Bearer <token>
+
+{
+  "amount": 100.00,
+  "subject": "钱包充值 ¥100.00",
+  "platform": "pc"
+}
+
+Response:
+{
+  "code": 200,
+  "message": "支付宝充值订单创建成功",
+  "data": {
+    "pay_url": "https://openapi.alipay.com/...",
+    "out_trade_no": "202412011234567890",
+    "amount": 100.00,
+    "platform": "pc",
+    "subject": "钱包充值 ¥100.00"
+  }
+}
+```
+
+### 2. 支付宝异步回调
+```
+POST /api/v1/finance/alipay/callback
+Content-Type: application/x-www-form-urlencoded
+
+支付宝回调参数...
+
+Response: "success"
+```
+
+### 3. 支付宝同步回调
+```
+GET /api/v1/finance/alipay/return?out_trade_no=xxx&trade_no=xxx&trade_status=TRADE_SUCCESS&total_amount=100.00
+
+Response: 302 Redirect to frontend success/fail page
+```
+
+### 4. 获取用户充值记录
+```
+GET /api/v1/finance/wallet/recharge-records?page=1&page_size=10&recharge_type=alipay&status=success
+Authorization: Bearer <token>
+
+Response:
+{
+  "code": 200,
+  "message": "获取充值记录成功",
+  "data": {
+    "items": [...],
+    "total": 50,
+    "page": 1,
+    "size": 10
+  }
+}
+```
+
+## 支付流程
+
+### 1. 用户充值流程
+1. 用户进入钱包页面，查看当前余额
+2. 选择"支付宝充值"方式
+3. 输入充值金额（最低1元）
+4. 点击"立即充值"按钮
+5. 前端调用后端创建充值订单接口
+6. 后端生成订单号，创建支付宝支付订单
+7. 返回支付链接给前端
+8. 前端自动跳转到支付宝支付页面
+9. 用户在支付宝完成支付
+10. 支付宝跳转回系统同步回调地址
+11. 后端处理同步回调，跳转到前端成功/失败页面
+12. 支付宝异步通知后端支付结果
+13. 后端处理异步回调，更新钱包余额和充值记录状态
+
+### 2. 支付回调处理
+- **异步回调**：支付宝主动通知支付结果，用于更新订单状态和钱包余额
+- **同步回调**：用户支付完成后页面跳转，用于用户体验优化
+
+## 数据库设计
+
+### 1. 充值记录表 (recharge_records)
+```sql
+CREATE TABLE recharge_records (
+    id VARCHAR(36) PRIMARY KEY,
+    user_id VARCHAR(36) NOT NULL,
+    amount DECIMAL(20,8) NOT NULL,
+    recharge_type VARCHAR(20) NOT NULL,
+    status VARCHAR(20) NOT NULL DEFAULT 'pending',
+    alipay_order_id VARCHAR(64) UNIQUE,
+    transfer_order_id VARCHAR(64) UNIQUE,
+    notes VARCHAR(500),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    deleted_at TIMESTAMP NULL
+);
+```
+
+### 2. 支付宝订单表 (alipay_orders)
+```sql
+CREATE TABLE alipay_orders (
+    id VARCHAR(36) PRIMARY KEY,
+    recharge_id VARCHAR(36) NOT NULL UNIQUE,
+    out_trade_no VARCHAR(64) NOT NULL UNIQUE,
+    trade_no VARCHAR(64) UNIQUE,
+    subject VARCHAR(200) NOT NULL,
+    amount DECIMAL(20,8) NOT NULL,
+    platform VARCHAR(20) NOT NULL,
+    status VARCHAR(20) NOT NULL DEFAULT 'pending',
+    buyer_id VARCHAR(64),
+    seller_id VARCHAR(64),
+    pay_amount DECIMAL(20,8),
+    receipt_amount DECIMAL(20,8),
+    notify_time TIMESTAMP NULL,
+    return_time TIMESTAMP NULL,
+    error_code VARCHAR(64),
+    error_message TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+```
+
+## 配置说明
+
+### 1. 支付宝配置
+```yaml
+alipay:
+  app_id: "2021004181633376"
+  private_key: "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSj..."
+  alipay_public_key: "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."
+  is_production: true
+  notify_url: "https://console.tianyuanapi.com/api/v1/finance/alipay/callback"
+  return_url: "https://console.tianyuanapi.com/api/v1/finance/alipay/return"
+```
+
+### 2. 环境配置
+- **开发环境**：使用沙箱环境，回调地址指向开发服务器
+- **生产环境**：使用正式环境，回调地址指向生产服务器
+
+## 安全考虑
+
+### 1. 支付安全
+- 使用支付宝官方SDK进行签名验证
+- 异步回调验证签名确保数据真实性
+- 订单号唯一性检查防止重复处理
+- 金额验证确保支付金额正确
+
+### 2. 数据安全
+- 所有敏感操作使用事务保护
+- 充值记录状态变更的原子性
+- 钱包余额更新的并发控制
+- 完整的操作日志记录
+
+## 错误处理
+
+### 1. 支付失败处理
+- 网络异常：提示用户重试
+- 余额不足：提示用户检查支付账户
+- 订单超时：自动取消订单，允许重新创建
+- 系统异常：记录错误日志，提供客服支持
+
+### 2. 回调异常处理
+- 签名验证失败：记录异常，不处理回调
+- 重复回调：幂等性处理，避免重复更新
+- 数据不一致：记录异常，人工介入处理
+
+## 监控和日志
+
+### 1. 关键日志点
+- 充值订单创建
+- 支付宝回调接收
+- 支付成功处理
+- 钱包余额更新
+- 异常错误记录
+
+### 2. 监控指标
+- 充值成功率
+- 支付响应时间
+- 回调处理延迟
+- 异常错误率
+
+## 测试建议
+
+### 1. 功能测试
+- 正常充值流程测试
+- 支付失败场景测试
+- 网络异常处理测试
+- 并发充值测试
+
+### 2. 安全测试
+- 回调签名验证测试
+- 重复订单处理测试
+- 金额篡改防护测试
+- 并发安全测试
+
+## 部署注意事项
+
+### 1. 环境配置
+- 确保支付宝配置正确
+- 回调地址可访问性
+- 数据库连接稳定性
+- 日志存储空间充足
+
+### 2. 监控告警
+- 支付成功率监控
+- 系统异常告警
+- 数据库性能监控
+- 网络连接监控
+
+## 后续优化
+
+### 1. 功能增强
+- 支持更多支付方式（微信支付、银行卡等）
+- 充值优惠活动
+- 自动充值功能
+- 充值提醒功能
+
+### 2. 性能优化
+- 支付订单缓存
+- 异步处理优化
+- 数据库查询优化
+- 前端体验优化