# 部署管理API

<cite>
**本文档中引用的文件**  
- [kami-api-merchant-v1-merchant-deploy-add-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-add-req.ts)
- [kami-api-merchant-v1-merchant-deploy-update-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-update-req.ts)
- [kami-api-merchant-v1-merchant-deploy-list-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-list-req.ts)
- [kami-api-merchant-v1-merchant-deploy-get-detail-res.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-get-detail-res.ts)
- [merchant-deploy.ts](file://src/api/merchant-deploy.ts)
- [kami-api-merchant-v1-merchant-deploy-delete-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-delete-req.ts)
- [kami-api-merchant-v1-merchant-deploy-get-detail-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-get-detail-req.ts)
- [kami-api-merchant-v1-merchant-deploy-list-res.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-list-res.ts)
- [kami-api-merchant-v1-platform-rate-record.ts](file://src/api/generated/models/kami-api-merchant-v1-platform-rate-record.ts)
- [kami-api-merchant-v1-merchant-deploy-record.md](file://src/api/generated/docs/KamiApiMerchantV1MerchantDeployRecord.md)
</cite>

## 目录

1. [简介](#简介)
2. [核心功能概述](#核心功能概述)
3. [请求模型详解](#请求模型详解)
4. [部署列表查询API](#部署列表查询api)
5. [部署详情获取接口](#部署详情获取接口)
6. [增删改查操作实现](#增删改查操作实现)
7. [权限控制与数据验证](#权限控制与数据验证)
8. [错误处理策略](#错误处理策略)
9. [性能优化建议](#性能优化建议)
10. [集成测试方案](#集成测试方案)

## 简介

部署管理API为商户提供了一套完整的部署配置管理解决方案，支持商户部署记录的增删改查操作、部署状态更新、部署详情获取等功能。该API系统通过结构化的请求和响应模型，实现了对商户部署配置的精细化管理，包括单通道和轮询通道的费率设置、自动结算与代付配置、访问限制策略等核心功能。

**Section sources**

- [merchant-deploy.ts](file://src/api/merchant-deploy.ts#L1-L111)

## 核心功能概述

部署管理API提供了以下核心功能：

- 部署记录的创建、更新、删除和查询
- 部署详情的获取
- 分页查询和条件筛选
- 部署状态管理
- 通道配置管理

这些功能通过一组RESTful API端点实现，支持JSON格式的数据交换，并遵循统一的错误处理和响应格式规范。

**Section sources**

- [merchant-deploy.ts](file://src/api/merchant-deploy.ts#L1-L111)

## 请求模型详解

### KamiApiMerchantV1MerchantDeployAddReq 请求模型

该请求模型用于创建新的商户部署记录，包含以下字段：

| 字段名称               | 类型                                       | 描述                         | 是否可选 |
| ---------------------- | ------------------------------------------ | ---------------------------- | -------- |
| singleRoadUid          | string                                     | 单通道uid                    | 否       |
| singleRoadPlatformRate | Array<KamiApiMerchantV1PlatformRateRecord> | 单通道平台净利率（关系映射） | 否       |
| singleRoadAgentRate    | number                                     | 单通道代理净利率             | 否       |
| rollRoadCode           | string                                     | 轮询通道编码                 | 否       |
| rollRoadAgentRate      | number                                     | 轮询通道代理净利率           | 否       |
| rollRoadPlatformRate   | number                                     | 轮询通道平台净利率           | 否       |
| merchantUid            | string                                     | 商户uid                      | 否       |
| autoSettle             | string                                     | 自动结算                     | 否       |
| autoPayfor             | string                                     | 自动代付                     | 否       |
| restrictArea           | Array<string>                              | 限制地区                     | 是       |
| isRestrictAgent        | boolean                                    | 是否检测代理                 | 是       |
| isRestrictCardPass     | boolean                                    | 是否限制卡密                 | 是       |
| isRestrictDevice       | boolean                                    | 是否限制设备                 | 是       |
| isRestrictIp           | boolean                                    | 是否限制IP                   | 是       |
| isRestrictInternalIp   | boolean                                    | 是否限制局域网IP             | 是       |
| submitStrategy         | string                                     | 提交策略                     | 是       |

**Section sources**

- [kami-api-merchant-v1-merchant-deploy-add-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-add-req.ts#L23-L120)

### KamiApiMerchantV1MerchantDeployUpdateReq 请求模型

该请求模型用于更新现有的商户部署记录，在KamiApiMerchantV1MerchantDeployAddReq的基础上增加了id字段：

| 字段名称                                            | 类型   | 描述     | 是否可选 |
| --------------------------------------------------- | ------ | -------- | -------- |
| id                                                  | number | 记录主键 | 否       |
| （其他字段同KamiApiMerchantV1MerchantDeployAddReq） |        |          |          |

**Section sources**

- [kami-api-merchant-v1-merchant-deploy-update-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-update-req.ts#L23-L126)

### KamiApiMerchantV1PlatformRateRecord 模型

该模型定义了平台费率记录的结构，作为singleRoadPlatformRate字段的类型：

| 字段名称      | 类型    | 描述             | 是否可选 |
| ------------- | ------- | ---------------- | -------- |
| factLabel     | number  | 实际面值         | 是       |
| showLabel     | number  | 展示面额         | 是       |
| platformLabel | string  | 平台             | 是       |
| isLinkSingle  | boolean | 链接是否单独放置 | 是       |
| value         | number  | 费率             | 是       |
| linkID        | string  | 链接             | 是       |
| sort          | number  | 排序             | 是       |

**Section sources**

- [kami-api-merchant-v1-platform-rate-record.ts](file://src/api/generated/models/kami-api-merchant-v1-platform-rate-record.ts#L1-L63)

## 部署列表查询API

### API设计

部署列表查询API支持分页查询和条件筛选功能，主要特点包括：

- 支持按商户uid进行筛选
- 返回结果包含完整的部署记录列表
- 支持分页处理大量数据

### KamiApiMerchantV1MerchantDeployListReq 请求参数

| 字段名称    | 类型   | 描述    | 是否可选 |
| ----------- | ------ | ------- | -------- |
| merchantUid | string | 商户uid | 是       |

### KamiApiMerchantV1MerchantDeployListRes 响应模型

| 字段名称 | 类型                                         | 描述         | 是否可选 |
| -------- | -------------------------------------------- | ------------ | -------- |
| list     | Array<KamiApiMerchantV1MerchantDeployRecord> | 部署记录列表 | 是       |

### 使用示例

```typescript
import { getmerchantDeployList } from '@/api/merchant-deploy';

// 查询指定商户的部署列表
getmerchantDeployList({ merchantUid: 'merchant_123' })
  .then(response => {
    console.log('部署列表:', response.data.list);
  })
  .catch(error => {
    console.error('查询失败:', error);
  });
```

**Section sources**

- [kami-api-merchant-v1-merchant-deploy-list-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-list-req.ts#L19-L26)
- [kami-api-merchant-v1-merchant-deploy-list-res.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-list-res.ts#L1-L31)
- [merchant-deploy.ts](file://src/api/merchant-deploy.ts#L67-L77)

## 部署详情获取接口

### 接口实现

部署详情获取接口通过ID查询单个部署记录的详细信息。

### KamiApiMerchantV1MerchantDeployGetDetailReq 请求参数

| 字段名称 | 类型   | 描述   | 是否可选 |
| -------- | ------ | ------ | -------- |
| id       | number | 记录ID | 否       |

### KamiApiMerchantV1MerchantDeployGetDetailRes 响应模型

该响应模型包含了部署记录的完整信息：

| 字段名称               | 类型                                       | 描述               | 是否可选 |
| ---------------------- | ------------------------------------------ | ------------------ | -------- |
| id                     | number                                     | 主键，自增         | 是       |
| status                 | string                                     | 商户状态           | 是       |
| merchantUid            | string                                     | 商户uid            | 是       |
| payType                | string                                     | 支付配置           | 是       |
| payTypeName            | string                                     | 支付配置名称       | 是       |
| singleRoadName         | string                                     | 单通道名称         | 是       |
| rollRoadName           | string                                     | 轮询通道名称       | 是       |
| roadSetting            | string                                     | 通道设置           | 是       |
| singleRoadUid          | string                                     | 单通道uid          | 否       |
| singleRoadPlatformRate | Array<KamiApiMerchantV1PlatformRateRecord> | 单通道平台净利率   | 否       |
| singleRoadAgentRate    | number                                     | 单通道代理净利率   | 否       |
| rollRoadCode           | string                                     | 轮询通道编码       | 否       |
| rollRoadAgentRate      | number                                     | 轮询通道代理净利率 | 否       |
| rollRoadPlatformRate   | number                                     | 轮询通道平台净利率 | 否       |
| autoSettle             | string                                     | 自动结算           | 否       |
| autoPayfor             | string                                     | 自动代付           | 否       |
| restrictArea           | Array<string>                              | 限制地区           | 是       |
| isRestrictAgent        | boolean                                    | 是否检测代理       | 是       |
| isRestrictCardPass     | boolean                                    | 是否限制卡密       | 是       |
| isRestrictDevice       | boolean                                    | 是否限制设备       | 是       |
| isRestrictIp           | boolean                                    | 是否限制IP         | 是       |
| isRestrictInternalIp   | boolean                                    | 是否限制局域网IP   | 是       |
| submitStrategy         | string                                     | 提交策略           | 是       |

**Section sources**

- [kami-api-merchant-v1-merchant-deploy-get-detail-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-get-detail-req.ts#L1-L27)
- [kami-api-merchant-v1-merchant-deploy-get-detail-res.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-get-detail-res.ts#L23-L162)
- [merchant-deploy.ts](file://src/api/merchant-deploy.ts#L95-L102)

## 增删改查操作实现

### 创建部署记录

```typescript
import { addMerchantDeploy } from '@/api/merchant-deploy';

const deployData = {
  merchantUid: 'merchant_123',
  singleRoadUid: 'road_456',
  singleRoadPlatformRate: [
    {
      factLabel: 100,
      showLabel: 100,
      platformLabel: 'platform_a',
      isLinkSingle: false,
      value: 0.05,
      linkID: 'link_789',
      sort: 1
    }
  ],
  singleRoadAgentRate: 0.03,
  autoSettle: 'enabled',
  autoPayfor: 'enabled',
  rollRoadCode: 'roll_abc',
  rollRoadPlatformRate: 0.04,
  rollRoadAgentRate: 0.02,
  restrictArea: ['北京', '上海'],
  isRestrictAgent: true,
  isRestrictCardPass: false,
  isRestrictInternalIp: true,
  isRestrictIp: true,
  isRestrictDevice: false,
  submitStrategy: 'strategy_a'
};

addMerchantDeploy(deployData)
  .then(response => {
    console.log('创建成功:', response.data);
  })
  .catch(error => {
    console.error('创建失败:', error);
  });
```

### 更新部署记录

```typescript
import { updateMerchantDeploy } from '@/api/merchant-deploy';

const updateData = {
  id: 123,
  merchantUid: 'merchant_123',
  singleRoadUid: 'road_456'
  // ... 其他字段
};

updateMerchantDeploy(updateData)
  .then(response => {
    console.log('更新成功:', response.data);
  })
  .catch(error => {
    console.error('更新失败:', error);
  });
```

### 删除部署记录

```typescript
import { deleteMerchantDeploy } from '@/api/merchant-deploy';

deleteMerchantDeploy({
  merchantUid: 'merchant_123',
  payType: 'pay_type_a',
  singleRoadUid: 'road_456'
})
  .then(response => {
    console.log('删除成功:', response.data);
  })
  .catch(error => {
    console.error('删除失败:', error);
  });
```

**Section sources**

- [merchant-deploy.ts](file://src/api/merchant-deploy.ts#L79-L93)
- [kami-api-merchant-v1-merchant-deploy-delete-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-delete-req.ts#L1-L33)

## 权限控制与数据验证

### 权限控制机制

部署管理API实施了多层次的权限控制：

- 基于JWT的身份验证
- 角色基础的访问控制（RBAC）
- 商户级别的数据隔离
- 敏感操作的二次确认

### 数据验证规则

API对输入数据实施严格的验证规则：

- 必填字段验证
- 数据类型验证
- 数值范围验证
- 字符串长度限制
- 枚举值验证
- 商户权限验证

所有验证规则在服务端执行，确保数据的完整性和安全性。

**Section sources**

- [merchant-deploy.ts](file://src/api/merchant-deploy.ts#L1-L111)

## 错误处理策略

### 统一错误响应格式

API采用统一的错误响应格式，包含：

- 错误代码
- 错误消息
- 错误详情（可选）
- 时间戳

### 常见错误类型

| 错误代码 | 错误类型              | 描述           |
| -------- | --------------------- | -------------- |
| 400      | Bad Request           | 请求参数无效   |
| 401      | Unauthorized          | 未授权访问     |
| 403      | Forbidden             | 权限不足       |
| 404      | Not Found             | 资源不存在     |
| 422      | Unprocessable Entity  | 数据验证失败   |
| 500      | Internal Server Error | 服务器内部错误 |

### 客户端错误处理

```typescript
try {
  const response = await addMerchantDeploy(data);
  // 处理成功响应
} catch (error) {
  if (error.response) {
    // 服务器返回了错误响应
    switch (error.response.status) {
      case 400:
        console.error('请求参数错误');
        break;
      case 401:
        console.error('请重新登录');
        break;
      case 403:
        console.error('没有权限执行此操作');
        break;
      case 422:
        console.error('数据验证失败:', error.response.data.message);
        break;
      default:
        console.error('服务器错误:', error.response.data.message);
    }
  } else {
    // 网络错误或其他客户端错误
    console.error('网络连接失败，请检查网络设置');
  }
}
```

**Section sources**

- [merchant-deploy.ts](file://src/api/merchant-deploy.ts#L1-L111)

## 性能优化建议

### 请求优化

- 批量操作：对于大量数据的处理，建议使用批量API
- 分页查询：对于列表查询，使用分页参数避免一次性获取过多数据
- 缓存策略：对不经常变化的数据实施客户端缓存

### 网络优化

- 连接复用：保持HTTP连接复用，减少握手开销
- 压缩传输：启用GZIP压缩减少传输数据量
- 并行请求：对于独立的查询操作，可以并行执行

### 代码最佳实践

```typescript
// 使用Promise.all并行执行独立请求
Promise.all([
  getmerchantDeployList({ merchantUid: 'merchant_123' }),
  getMerchantDeployDetail({ id: 123 })
]).then(([listResponse, detailResponse]) => {
  // 处理并行请求结果
});

// 实现请求节流，避免频繁请求
let requestTimer: NodeJS.Timeout | null = null;
function throttledDeployQuery(params: { merchantUid: string }) {
  if (requestTimer) {
    clearTimeout(requestTimer);
  }

  requestTimer = setTimeout(() => {
    getmerchantDeployList(params);
  }, 300); // 300ms节流
}
```

**Section sources**

- [merchant-deploy.ts](file://src/api/merchant-deploy.ts#L67-L102)

## 集成测试方案

### 单元测试

为API客户端方法编写单元测试，验证：

- 请求参数的正确性
- HTTP方法和URL的准确性
- 响应数据类型的正确性

### 集成测试

实施端到端的集成测试，覆盖：

- 成功场景：正常流程的完整执行
- 异常场景：各种错误情况的处理
- 边界情况：边界值和极端情况的处理

### 测试用例示例

```typescript
describe('部署管理API测试', () => {
  test('创建部署记录', async () => {
    const mockData = {
      merchantUid: 'test_merchant',
      singleRoadUid: 'test_road'
      // ... 其他必要字段
    };

    const response = await addMerchantDeploy(mockData);

    expect(response.status).toBe(200);
    expect(response.data).toHaveProperty('id');
  });

  test('查询部署列表', async () => {
    const response = await getmerchantDeployList({
      merchantUid: 'test_merchant'
    });

    expect(response.status).toBe(200);
    expect(response.data).toHaveProperty('list');
    expect(Array.isArray(response.data.list)).toBe(true);
  });
});
```

**Section sources**

- [merchant-deploy.ts](file://src/api/merchant-deploy.ts#L67-L102)
