# 数字债权服务系统 API 服务文档

## 概述

本文档描述了数字债权服务系统前端的API服务架构和使用方法。系统基于RuoYi-Vue3框架，集成了完整的权限管理体系。

## 目录结构

```
src/api/
├── credit/                    # 债权业务API
│   ├── contract.js           # 合同管理API
│   ├── credit.js             # 债权管理API
│   └── financing.js          # 融资管理API
├── payment/                   # 支付结算API
│   └── payment.js            # 支付结算API
├── blockchain/                # 区块链集成API
│   └── blockchain.js         # 区块链API
├── reports/                   # 报表分析API
│   └── reports.js            # 报表API
├── security/                  # 安全管理API
│   └── security.js           # 安全API
├── notification/              # 通知服务API
│   └── notification.js       # 通知API
├── digitalCredit/             # 数字债权权限API
│   ├── role.js               # 角色权限API
│   └── permission.js         # 权限管理API
├── system/                    # RuoYi系统API (已存在)
│   ├── role.js               # 系统角色API
│   ├── menu.js               # 系统菜单API
│   └── user.js               # 系统用户API
├── index.js                   # 统一API入口
└── README.md                  # 本文档
```

## API 模块说明

### 1. 合同管理API (contract.js)

提供合同的完整生命周期管理功能：

- `listContracts(query)` - 获取合同列表
- `getContract(id)` - 获取合同详情
- `addContract(data)` - 创建新合同
- `updateContract(data)` - 更新合同信息
- `delContract(id)` - 删除合同
- `uploadContract(formData)` - 上传合同文件
- `confirmContract(id, data)` - 确认合同
- `getContractStats()` - 获取合同统计
- `exportContract(query)` - 导出合同列表

### 2. 债权管理API (credit.js)

提供数字债权凭证的管理功能：

- `listCredits(query)` - 获取债权列表
- `getCredit(id)` - 获取债权详情
- `generateCredit(data)` - 生成债权凭证
- `updateCredit(data)` - 更新债权信息
- `delCredit(id)` - 删除债权
- `validateCredit(id, data)` - 验证债权有效性
- `getCreditSignature(id)` - 获取数字签名
- `transferCredit(id, data)` - 转让债权
- `getCreditTransferHistory(id)` - 获取转让历史
- `getCreditStats()` - 获取债权统计
- `exportCredit(query)` - 导出债权列表

### 3. 融资管理API (financing.js)

提供融资申请和审批功能：

- `listFinancing(query)` - 获取融资申请列表
- `getFinancing(id)` - 获取融资申请详情
- `applyFinancing(data)` - 提交融资申请
- `updateFinancing(data)` - 更新融资申请
- `delFinancing(id)` - 删除融资申请
- `approveFinancing(id, data)` - 审批融资申请
- `riskAssessment(id, data)` - 进行风险评估
- `getInterestRate(id)` - 获取利率信息
- `getFinancingStats()` - 获取融资统计
- `getRiskAssessmentHistory(id)` - 获取风险评估历史
- `disburseFinancing(id, data)` - 放款处理
- `exportFinancing(query)` - 导出融资申请列表

### 4. 支付结算API (payment.js)

提供支付处理和资金管理功能：

- `listPaymentHistory(query)` - 获取支付历史
- `getPayment(id)` - 获取支付详情
- `processPayment(data)` - 处理支付
- `cancelPayment(id, data)` - 取消支付
- `createEscrowAccount(data)` - 创建监管账户
- `listEscrowAccounts(query)` - 获取监管账户列表
- `getEscrowAccount(id)` - 获取监管账户详情
- `getEscrowBalance(id)` - 获取账户余额
- `distributeEscrowFunds(id, data)` - 资金分配
- `getDistributionHistory(id)` - 获取分配历史
- `getPaymentStats()` - 获取支付统计
- `getAccountTransactions(id, query)` - 获取账户交易记录
- `exportPayment(query)` - 导出支付记录

### 5. 区块链集成API (blockchain.js)

提供区块链相关功能：

- `listBlockchainEvents(query)` - 获取区块链事件列表
- `getBlockchainStatus()` - 获取区块链网络状态
- `storeDataOnChain(data)` - 数据上链存储
- `verifyChainData(hash)` - 验证链上数据
- `getTransaction(txHash)` - 获取交易详情
- `executeSmartContract(data)` - 执行智能合约
- `listSmartContracts(query)` - 获取智能合约列表
- `getSmartContract(address)` - 获取智能合约详情
- `deploySmartContract(data)` - 部署智能合约
- `getContractExecutionHistory(address, query)` - 获取合约执行历史
- `getBlockchainStats()` - 获取区块链统计
- `getBlockInfo(blockNumber)` - 获取区块信息
- `batchVerifyData(data)` - 批量验证数据

### 6. 报表分析API (reports.js)

提供数据分析和报表功能：

- `getDashboardData(query)` - 获取仪表板数据
- `generateReport(data)` - 生成报表
- `listReports(query)` - 获取报表列表
- `getReport(id)` - 获取报表详情
- `exportReport(id, format)` - 导出报表
- `deleteReport(id)` - 删除报表
- `getFinancialReport(query)` - 获取财务报表
- `performRiskAnalysis(data)` - 进行风险分析
- `getStatistics(query)` - 获取统计数据
- `getTrendAnalysis(query)` - 获取趋势分析
- `getComparisonAnalysis(data)` - 获取对比分析
- `getReportTemplates()` - 获取报表模板
- `createReportTemplate(data)` - 创建报表模板
- `getRealTimeData(query)` - 获取实时数据

### 7. 安全管理API (security.js)

提供安全管理功能：

- `getAuditLogs(query)` - 获取审计日志
- `getAuditLogDetail(id)` - 获取审计日志详情
- `generateMFA(data)` - 生成MFA密钥
- `validateMFA(data)` - 验证MFA令牌
- `disableMFA(data)` - 禁用MFA
- `getMFAStatus(userId)` - 获取MFA状态
- `generateBackupCodes(data)` - 生成MFA备用码
- `encryptData(data)` - 数据加密
- `decryptData(data)` - 数据解密
- `getSecurityPolicies()` - 获取安全策略
- `updateSecurityPolicies(data)` - 更新安全策略
- `getSecurityEvents(query)` - 获取安全事件
- `handleSecurityEvent(id, data)` - 处理安全事件
- `getUserPermissions(userId)` - 获取用户权限
- `updateUserPermissions(userId, data)` - 更新用户权限
- `exportAuditLogs(query)` - 导出审计日志

### 8. 通知服务API (notification.js)

提供通知和消息功能：

- `getNotificationTemplates(query)` - 获取通知模板列表
- `getNotificationTemplate(id)` - 获取通知模板详情
- `createNotificationTemplate(data)` - 创建通知模板
- `updateNotificationTemplate(data)` - 更新通知模板
- `deleteNotificationTemplate(id)` - 删除通知模板
- `sendNotification(data)` - 发送通知
- `batchSendNotification(data)` - 批量发送通知
- `getNotificationHistory(query)` - 获取通知发送历史
- `getNotificationDetail(id)` - 获取通知详情
- `getDeliveryStatus(id)` - 获取投递状态
- `resendNotification(id)` - 重新发送失败的通知
- `cancelNotification(id)` - 取消待发送的通知
- `getNotificationStats(query)` - 获取通知统计
- `getRecipientGroups()` - 获取接收者分组
- `createRecipientGroup(data)` - 创建接收者分组
- `updateRecipientGroup(data)` - 更新接收者分组
- `deleteRecipientGroup(id)` - 删除接收者分组
- `previewNotification(data)` - 预览通知内容

### 9. 数字债权权限API (digitalCredit/)

#### 角色权限API (role.js)
- `getRoleList(query)` - 获取角色权限列表
- `getRoleMenuTreeselect(roleId)` - 获取角色菜单权限树
- `getDigitalCreditPermissions()` - 获取数字债权业务权限
- `checkPermission(permission)` - 验证权限
- `getDigitalCreditRoleMapping()` - 获取角色映射关系
- `getDataScopeByRole(businessRole)` - 获取数据范围权限
- `getUserBusinessRole(userId)` - 获取用户业务角色
- `getRoleModulePermissions(roleId)` - 获取角色模块权限
- `getRoleActionPermissions(roleId)` - 获取角色操作权限
- `refreshUserPermissions(userId)` - 刷新用户权限缓存

#### 权限管理API (permission.js)
- `getCurrentUserPermissions()` - 获取当前用户权限
- `validatePermission(data)` - 验证用户权限
- `getUserMenus()` - 获取用户可访问菜单
- `getRolePermissions(roleId)` - 获取角色权限配置
- `updateRolePermissions(roleId, data)` - 更新角色权限
- `getDataScopePermissions(userId)` - 获取数据范围权限
- `checkButtonPermission(data)` - 检查按钮权限
- `getModulePermissions()` - 获取功能模块权限
- `logPermissionUsage(data)` - 记录权限使用日志

## 使用方法

### 1. 基本使用

```javascript
// 导入API服务
import { contractApi, creditApi, financingApi } from '@/api'

// 使用API
async function loadContracts() {
  try {
    const response = await contractApi.listContracts({
      pageNum: 1,
      pageSize: 10,
      status: 'active'
    })
    console.log('合同列表:', response.data)
  } catch (error) {
    console.error('获取合同列表失败:', error)
  }
}
```

### 2. 权限验证

```javascript
import { digitalCreditRoleApi } from '@/api'
import { PERMISSIONS } from '@/api/digitalCredit/permission'

// 检查权限
async function checkCreatePermission() {
  try {
    const hasPermission = await digitalCreditRoleApi.checkPermission(
      PERMISSIONS.CONTRACT.CREATE
    )
    if (hasPermission) {
      // 显示创建按钮
    }
  } catch (error) {
    console.error('权限检查失败:', error)
  }
}
```

### 3. 数据范围过滤

```javascript
import { DataScopeHelper } from '@/api'

// 应用数据范围过滤
function loadUserData() {
  const userInfo = getUserInfo() // 获取用户信息
  const dataScope = userInfo.dataScope
  
  let query = {
    pageNum: 1,
    pageSize: 10
  }
  
  // 根据数据范围过滤查询参数
  query = DataScopeHelper.filterQueryByDataScope(query, dataScope, userInfo)
  
  return contractApi.listContracts(query)
}
```

### 4. 错误处理

```javascript
import { ResponseHelper } from '@/api'

async function handleApiCall() {
  try {
    const response = await contractApi.listContracts()
    const normalizedData = ResponseHelper.normalize(response)
    
    if (normalizedData.success) {
      // 处理成功响应
      console.log('数据:', normalizedData.data)
    } else {
      // 处理业务错误
      console.error('业务错误:', normalizedData.message)
    }
  } catch (error) {
    // 处理系统错误
    console.error('系统错误:', error.message)
  }
}
```

## 权限体系

### 角色定义

- **security_company**: 安保公司
- **client_company**: 甲方单位
- **financial_institution**: 金融机构
- **administrator**: 系统管理员
- **platform_operator**: 平台运营

### 数据范围权限

- **all**: 全部数据权限
- **own_company**: 本公司数据权限
- **related_contracts**: 相关合同数据权限
- **financing_related**: 融资相关数据权限
- **platform_level**: 平台级数据权限

### 功能权限

每个API接口都有对应的权限要求，系统会自动进行权限验证。权限不足时会返回相应的错误信息。

## 配置说明

### API配置 (API_CONFIG)

```javascript
export const API_CONFIG = {
  BASE_URL: process.env.VUE_APP_BASE_API || '/dev-api',
  TIMEOUT: 30000,
  DIGITAL_CREDIT_PREFIX: '/api',
  RUOYI_SYSTEM_PREFIX: '/dev-api/system',
  UPLOAD_CONFIG: {
    maxSize: 10 * 1024 * 1024, // 10MB
    allowedTypes: ['.pdf', '.doc', '.docx', '.jpg', '.png', '.jpeg'],
    uploadUrl: '/api/common/upload'
  },
  EXPORT_CONFIG: {
    timeout: 60000,
    formats: ['pdf', 'excel', 'csv']
  }
}
```

### 错误处理配置 (ERROR_CONFIG)

系统定义了标准的错误码体系，包括业务错误码和系统错误码，便于统一处理各种异常情况。

## 注意事项

1. **权限验证**: 所有API调用都会进行权限验证，请确保用户有相应的权限
2. **数据范围**: 查询接口会根据用户的数据范围权限自动过滤结果
3. **错误处理**: 建议使用统一的错误处理机制，提供良好的用户体验
4. **缓存机制**: 权限数据会进行缓存，权限变更后需要刷新缓存
5. **日志记录**: 重要操作会自动记录审计日志，便于追踪和审计

## 更新日志

- v1.0.0: 初始版本，包含所有核心API服务
- 后续版本更新将在此记录