---
id: {INT_ID}
title: {集成名称}
status: draft
version: {v1}
protocol: {协议类型}
external_system: {外部系统名称}
related_features: []
---

# {INT_ID}: {集成名称}

<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
<!-- 插件模板是入门指导，项目本地模板是权威 -->

## 概述

{描述这个集成的目的、业务场景和主要能力}

## 基础信息

- **版本**：{version}
- **协议**：REST / SOAP / gRPC / Message Queue / WebSocket / FTP / SFTP
- **外部系统**：{外部系统名称和版本}
- **环境**：开发 / 测试 / 预生产 / 生产
- **SLA**：{服务等级协议，如"99.9% 可用性"}

## 连接配置

### 端点信息

| 环境 | URL / 地址 | 端口 | 说明 |
|------|-----------|------|------|
| 开发 | {url} | {port} | {说明} |
| 测试 | {url} | {port} | {说明} |
| 生产 | {url} | {port} | {说明} |

### 认证方式

- **类型**：Basic Auth / OAuth2 / API Key / mTLS / JWT
- **凭证管理**：{凭证存储位置，如"Vault / 环境变量"}
- **刷新策略**：{Token 刷新策略，如"过期前 5 分钟自动刷新"}

### 超时配置

| 阶段 | 超时时间 | 说明 |
|------|---------|------|
| 连接建立 | {timeout} | {说明} |
| 读取响应 | {timeout} | {说明} |
| 写入数据 | {timeout} | {说明} |

## 接口列表

### {接口名称}

**描述**：{接口用途}

**请求**：

```json
{
  "field1": "type",
  "field2": "type"
}
```

**响应**：

```json
{
  "success": true,
  "data": {}
}
```

**错误码**：

| 错误码 | 描述 | 处理策略 |
|--------|------|---------|
| {error_code} | {描述} | {重试 / 告警 / 降级} |

## 重试策略

### 重试规则

| 场景 | 最大重试次数 | 重试间隔 | 退避策略 | 说明 |
|------|------------|---------|---------|------|
| {场景名称} | {次数} | {间隔} | 固定 / 指数 / 退避 | {说明} |

### 熔断配置

- **失败阈值**：{连续失败次数触发熔断}
- **熔断时长**：{熔断持续时间}
- **半开状态**：{半开状态下的试探请求数}

## 错误处理

### 错误分类

| 错误类型 | 示例 | 处理策略 |
|---------|------|---------|
| 网络错误 | 连接超时、DNS 解析失败 | 重试 + 告警 |
| 认证错误 | Token 过期、凭证无效 | 刷新凭证 + 重试 |
| 业务错误 | 数据校验失败、状态冲突 | 记录日志 + 人工介入 |
| 系统错误 | 服务不可用、限流 | 重试 + 熔断 + 降级 |

### 降级策略

- **降级触发条件**：{如"外部系统不可用超过 5 分钟"}
- **降级行为**：{如"返回缓存数据 / 返回默认值 / 拒绝请求"}
- **恢复策略**：{如"自动探测恢复 / 人工确认恢复"}

## 幂等性

- **幂等键**：{幂等键的生成规则，如"请求ID + 业务ID"}
- **幂等存储**：{幂等键的存储位置，如"Redis / 数据库"}
- **幂等过期**：{幂等键的过期时间}

## 数据映射

### 字段映射

| 内部字段 | 外部字段 | 类型转换 | 说明 |
|---------|---------|---------|------|
| {internal_field} | {external_field} | {转换规则} | {说明} |

### 数据转换

{描述数据格式转换逻辑，如"日期格式转换、枚举值映射等"}

## 监控与告警

### 监控指标

| 指标名称 | 类型 | 阈值 | 说明 |
|---------|------|------|------|
| 调用成功率 | Gauge | 99% | {说明} |
| 响应时间 | Histogram | P99 < 500ms | {说明} |
| 错误率 | Counter | < 1% | {说明} |

### 告警规则

| 告警名称 | 条件 | 级别 | 通知方式 |
|---------|------|------|---------|
| {告警名称} | {条件} | P0 / P1 / P2 | {钉钉 / 邮件 / 短信} |

## 关联制品

- 功能特性：{related_features}
- 设计文档：{related_designs}
- 决策：{related_decisions}
- 数据契约：{related_data_contracts}

## 变更日志

| 日期 | 版本 | 变更 | 作者 |
|------|------|------|------|
| {YYYY-MM-DD} | v1 | 初始版本 | {作者} |