3、接口协议基础：RESTful API设计原则、HTTP方法、状态码、认证方式（OAuth2.0/Basic Auth）

在供应商CAPA接口调用场景中，追溯平台与OA系统之间的整改任务同步，本质上是两个系统通过HTTP协议进行资源状态的对账与流转。理解RESTful API的设计原则、HTTP方法、状态码以及认证方式，是确保接口稳定、安全、可维护的基础。

3.1 RESTful API 设计原则

REST（Representational State Transfer）是一种基于资源的架构风格，强调通过统一的接口对资源进行无状态操作。在CAPA同步场景中，我们将“整改任务”视为核心资源，每个任务拥有唯一的URI。

3.2 HTTP 方法与CAPA操作映射

每个HTTP方法对应一种标准操作。在追溯平台与OA系统的任务同步中，方法选择直接影响接口的幂等性与安全性。

3.3 HTTP 状态码与错误处理

状态码是接口调用结果的直接反馈。在CAPA同步中，合理使用状态码可以大幅降低排查问题的成本。

{
  "errorCode": "TASK_NOT_FOUND",
  "message": "未找到指定的整改任务",
  "details": "taskId: CAPA-2025-00123"
}

3.4 认证方式：Basic Auth 与 OAuth2.0

在系统间接口调用中，认证是安全的第一道防线。Basic Auth适用于内部信任环境，OAuth2.0适用于需要细粒度权限控制的场景。

3.4.1 Basic Auth

将用户名和密码以 Base64 编码后放入 Authorization 请求头。由于仅编码未加密，必须搭配HTTPS使用。

// 请求头示例
Authorization: Basic base64(username:password)

// 示例：用户名为 "capa_sync"，密码为 "secret@2025"
// 拼接后为 "capa_sync:secret@2025"
// Base64编码后为 "Y2FwYV9zeW5jOnNlY3JldEAyMDI1"
Authorization: Basic Y2FwYV9zeW5jOnNlY3JldEAyMDI1

3.4.2 OAuth2.0 客户端凭证模式

在系统间集成（M2M，Machine-to-Machine）场景中，客户端凭证模式是最常用的方式。追溯平台作为客户端，使用自己的 client_id 和 client_secret 向授权服务器获取 access_，后续请求携带该令牌。

// 第一步：获取令牌
POST /oauth/
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=capa_trace_platform
&client_secret=your_client_secret

// 响应示例
{
  "access_": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "_type": "Bearer",
  "expires_in": 3600
}

// 第二步：携带令牌调用API
GET /api/v1/capa-tasks
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

3.5 认证方式对比与选择