# SRM 与 STP 数据交换接口方案说明书

| 文档名称 | SRM 与 STP 数据交换接口方案说明书 |
| :--- | :-------------------- |
| 文档版本 | V1.0                  |
| 编制日期 | 2026-06-26            |
| 编制人  | 叶伟文                   |


## 1. 项目背景与目标

### 1.1 背景
当前，供应商关系管理系统与智慧招标平台各自独立运行，存在数据孤岛。供应商需在两套系统中分别维护信息、管理账号，在跨平台操作时需重复登录，严重影响用户体验与业务协同效率。

### 1.2 目标
*   **数据互通**：实现供应商主数据、采购计划、中标资料在两个系统间的实时或准实时同步。
*   **业务协同**：打通从供应商准入、招标到合同签订的全流程，实现业务流程无缝衔接。
*   **体验优化**：构建统一登录认证体系，实现"一次登录，两平台通行"的无感跳转体验。

## 2. 总体架构设计

### 2.1 系统交互架构图

```svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 450" font-family="Microsoft YaHei, sans-serif">
  <defs>
    <marker id="arrowPink" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
      <path d="M0,0 L0,6 L9,3 z" fill="#c2185b"/>
    </marker>
    <marker id="arrowBlue" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
      <path d="M0,0 L0,6 L9,3 z" fill="#1565c0"/>
    </marker>
    <linearGradient id="gradSrm" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0%" stop-color="#1565c0"/>
      <stop offset="100%" stop-color="#1e88e5"/>
    </linearGradient>
    <linearGradient id="gradStp" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0%" stop-color="#c2185b"/>
      <stop offset="100%" stop-color="#e91e63"/>
    </linearGradient>
    <filter id="shadow" x="-5%" y="-5%" width="110%" height="110%">
      <feDropShadow dx="2" dy="3" stdDeviation="3" flood-opacity="0.15"/>
    </filter>
  </defs>

  <!-- 标题 -->
  <text x="400" y="35" text-anchor="middle" font-size="22" font-weight="bold" fill="#333">SRM 与 STP 系统交互架构</text>

  <!-- SRM 系统框 -->
  <rect x="60" y="70" width="280" height="320" rx="12" fill="url(#gradSrm)" filter="url(#shadow)"/>
  <text x="200" y="105" text-anchor="middle" font-size="20" font-weight="bold" fill="#fff">供应商管理系统</text>

  <rect x="80" y="125" width="240" height="40" rx="6" fill="rgba(255,255,255,0.2)"/>
  <text x="200" y="151" text-anchor="middle" font-size="14" fill="#fff">供应商库管理</text>
  <rect x="80" y="175" width="240" height="40" rx="6" fill="rgba(255,255,255,0.2)"/>
  <text x="200" y="201" text-anchor="middle" font-size="14" fill="#fff">采购计划管理</text>
  <rect x="80" y="225" width="240" height="40" rx="6" fill="rgba(255,255,255,0.2)"/>
  <text x="200" y="251" text-anchor="middle" font-size="14" fill="#fff">合同管理</text>
  <rect x="80" y="275" width="240" height="40" rx="6" fill="rgba(255,255,255,0.2)"/>
  <text x="200" y="301" text-anchor="middle" font-size="14" fill="#fff">中标资料归档</text>
  <rect x="80" y="325" width="240" height="40" rx="6" fill="rgba(255,255,255,0.2)"/>
  <text x="200" y="351" text-anchor="middle" font-size="14" fill="#fff">认证与鉴权中心</text>

  <!-- STP 系统框 -->
  <rect x="460" y="70" width="280" height="320" rx="12" fill="url(#gradStp)" filter="url(#shadow)"/>
  <text x="600" y="105" text-anchor="middle" font-size="20" font-weight="bold" fill="#fff">智慧招标平台</text>

  <rect x="480" y="125" width="240" height="40" rx="6" fill="rgba(255,255,255,0.2)"/>
  <text x="600" y="151" text-anchor="middle" font-size="14" fill="#fff">供应商准入审核</text>
  <rect x="480" y="175" width="240" height="40" rx="6" fill="rgba(255,255,255,0.2)"/>
  <text x="600" y="201" text-anchor="middle" font-size="14" fill="#fff">招标项目管理</text>
  <rect x="480" y="225" width="240" height="40" rx="6" fill="rgba(255,255,255,0.2)"/>
  <text x="600" y="251" text-anchor="middle" font-size="14" fill="#fff">AI采购委托书</text>
  <rect x="480" y="275" width="240" height="40" rx="6" fill="rgba(255,255,255,0.2)"/>
  <text x="600" y="301" text-anchor="middle" font-size="14" fill="#fff">定标与资料转交</text>
  <rect x="480" y="325" width="240" height="40" rx="6" fill="rgba(255,255,255,0.2)"/>
  <text x="600" y="351" text-anchor="middle" font-size="14" fill="#fff">认证与鉴权中心</text>

  <!-- 中间接口通道 -->
  <rect x="370" y="195" width="60" height="60" rx="30" fill="#fff" stroke="#666" stroke-width="1.5" filter="url(#shadow)"/>
  <text x="400" y="222" text-anchor="middle" font-size="11" font-weight="bold" fill="#333">API</text>
  <text x="400" y="240" text-anchor="middle" font-size="11" fill="#666">网关</text>

  <!-- 接口连线：SRM -> STP -->
  <line x1="340" y1="145" x2="460" y2="145" stroke="#c2185b" stroke-width="2" marker-end="url(#arrowPink)"/>
  <text x="400" y="138" text-anchor="middle" font-size="10" fill="#c2185b">供应商库查询</text>

  <line x2="340" y2="290" x1="460" y1="290" stroke="#c2185b" stroke-width="2" marker-end="url(#arrowPink)"/>
  <text x="400" y="283" text-anchor="middle" font-size="10" fill="#c2185b">中标资料接收</text>

  <line x1="340" y1="340" x2="460" y2="340" stroke="#c2185b" stroke-width="2" marker-end="url(#arrowPink)"/>
  <line x1="460" y1="340" x2="340" y2="340" stroke="#1565c0" stroke-width="2" marker-end="url(#arrowBlue)"/>
  <text x="400" y="333" text-anchor="middle" font-size="10" fill="#333">登录/票据验证</text>

  <!-- 接口连线：STP -> SRM -->
  <line x1="460" y1="175" x2="340" y2="175" stroke="#1565c0" stroke-width="2" marker-end="url(#arrowBlue)"/>
  <text x="400" y="168" text-anchor="middle" font-size="10" fill="#1565c0">供应商自动注册</text>

  <line x1="460" y1="240" x2="340" y2="240" stroke="#1565c0" stroke-width="2" marker-end="url(#arrowBlue)"/>
  <text x="400" y="233" text-anchor="middle" font-size="10" fill="#1565c0">采购计划查询</text>

  <!-- 技术栈标注 -->
  <rect x="250" y="420" width="300" height="24" rx="12" fill="#f5f5f5"/>
  <text x="400" y="437" text-anchor="middle" font-size="11" fill="#555">协议：HTTPS ｜ 格式：JSON ｜ 认证：私钥签名 + Token</text>
</svg>
```

## 3. 接口详细设计

### 3.1 供应商库信息查询接口
**提供方：** SRM
**消费方：** STP

**接口清单**

| 序号  | 接口名称    | 请求方式  | 接口路径（暂拟）                           | 说明                               |
| :-- | :------ | :---- | :--------------------------------- | :------------------------------- |
| 1   | 供应商名称查询 | `GET` | `/api/v1/supplier/query/by-name`   | 根据供应商名称返回匹配到的供应商对象列表，没有则返回空列表。   |
| 2   | 供应商税号查询 | `GET` | `/api/v1/supplier/query/by-tax-id` | 根据供应商税号返回匹配到的供应商对象，没有则返回空对象。     |
| 3   | 供应商ID查询 | `GET` | `/api/v1/supplier/query/by-id`     | 根据SRM系统内部ID返回对应的供应商对象，没有则返回空对象。  |
| 4   | 供应商标签查询 | `GET` | `/api/v1/supplier/query/by-tags`   | 根据给定的标签集合返回匹配到的供应商对象列表，没有则返回空列表。 |
| 5   | 全量供应商同步 | `GET` | `/api/v1/supplier/sync/full`       | 返回所有供应商对象，用于全量数据同步。              |
| 6   | 增量供应商同步 | `GET` | `/api/v1/supplier/sync/delta`      | 返回从指定时间至今发生变更的供应商对象，用于增量同步。      |

**通用请求头**

| 参数名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `Authorization` | `String` | 是 | 认证令牌，格式为 `Bearer <token>` |
| `Content-Type` | `String` | 是 | `application/json` |

**供应商对象结构(举例)**

| 字段名            | 类型              | 说明                      |
| :------------- | :-------------- | :---------------------- |
| `supplierId`   | `String`        | 系统内ID                   |
| `supplierName` | `String`        | 供应商名称                   |
| `taxId`        | `String`        | 税号                      |
| `score`        | `Integer`       | 综合评分                    |
| `tags`         | `Array[String]` | 标签列表                    |
| `status`       | `String`        | 状态，如"ACTIVE","INACTIVE" |
| `contactInfo`  | `Object`        | 联系方式                    |
| `createTime`   | `String`        | 创建时间                    |
| `updateTime`   | `String`        | 更新时间                    |

---

### 3.2 供应商自动注册接口
**提供方：** SRM
**消费方：** STP

```mermaid
sequenceDiagram
    participant STP as STP
    participant SRM as SRM

    STP->>SRM: POST /api/v1/supplier/register (供应商注册信息)
    SRM-->>SRM: 校验数据完整性与合规性
    alt 注册成功
        SRM-->>SRM: 生成系统内ID
        SRM-->>STP: 200 OK { "code":"0", "supplierId":"SRM_2024001" }
    else 注册失败
        SRM-->>STP: 400 Bad Request { "code":"ERR_001", "message":"税号已存在" }
    end
```

**请求参数(暂定)**

| 参数名              | 类型       | 必填  | 说明     |
| :--------------- | :------- | :-- | :----- |
| `supplierName`   | `String` | 是   | 供应商名称  |
| `taxId`          | `String` | 是   | 税号     |
| `contactInfo`    | `Object` | 是   | 联系方式   |
| `qualifications` | `Array`  | 否   | 资质文件列表 |

**返回参数（成功）**

| 参数名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `code` | `String` | 业务状态码，成功为"0" |
| `supplierId` | `String` | SRM系统内ID |

---

### 3.3 采购计划查询接口
**提供方：** SRM
**消费方：** STP

```mermaid
sequenceDiagram
    participant STP as STP (AI模块)
    participant SRM as SRM

    STP->>SRM: GET /api/v1/purchase-plan/query?account=xxx
    SRM-->>SRM: 查询该采购员关联的采购计划
    alt 存在计划
        SRM-->>STP: 200 OK { "code":"0", "data":[计划对象列表] }
    else 不存在计划
        SRM-->>STP: 200 OK { "code":"0", "data":[] }
    end
```

**请求参数**

| 参数名 | 类型 | 必填 | 位置 | 说明 |
| :--- | :--- | :--- | :--- | :--- |
| `account` | `String` | 是 | `Query` | 采购人员账号 |

**返回数据对象**

| 字段名            | 类型       | 说明     |
| :------------- | :------- | :----- |
| `planId`       | `String` | 计划ID   |
| `planName`     | `String` | 计划名称   |
| `budget`       | `Float`  | 预算金额   |
| `requiredDate` | `String` | 需求日期   |
| `items`        | `Array`  | 采购物料明细 |

---

### 3.4 统一登录与无感跳转接口
本节详细描述如何通过**统一登录**和**无感跳转**实现“一次登录，两平台通行”。

#### 3.4.1 统一登录
统一登录解决供应商在两个平台拥有独立账号、需重复输入密码的问题。任一平台均可作为登录入口，调用对方提供的登录验证接口，验证通过后建立本地会话。

**场景1：供应商在SRM端输入STP的账号密码登录**

```mermaid
sequenceDiagram
    participant User as 供应商
    participant SRM
    participant STP

    User->>SRM: 输入STP用户名/密码，点击登录
    SRM->>STP: POST /api/v1/auth/login/for-srm { username, password, returnUrl }
    STP-->>STP: 校验用户合法性
    alt 校验成功
        STP-->>SRM: 200 { code:0, userInfo:{ stpId, srmId, name, taxId, ... } }
        SRM-->>SRM: 建立本地会话，关联SRM ID
        SRM-->>User: 登录成功，返回SRM首页
    else 校验失败
        STP-->>SRM: 401 { code:ERR_AUTH_001, message:"用户名或密码错误" }
        SRM-->>User: 提示错误
    end
```

**场景2：供应商在STP端输入SRM的账号密码登录（流程对称）**

```mermaid
sequenceDiagram
    participant User as 供应商
    participant STP
    participant SRM

    User->>STP: 输入SRM用户名/密码，点击登录
    STP->>SRM: POST /api/v1/auth/login/for-stp { username, password, returnUrl }
    SRM-->>SRM: 校验用户合法性
    alt 校验成功
        SRM-->>STP: 200 { code:0, userInfo:{ srmId, name, taxId, ... } }
        STP-->>STP: 建立本地会话
        STP-->>User: 登录成功，返回STP首页
    else 校验失败
        SRM-->>STP: 401 错误
        STP-->>User: 提示错误
    end
```

**接口定义：STP登录验证接口（供SRM调用）**

| 项目 | 内容 |
| :--- | :--- |
| **提供方** | STP |
| **路径** | `/api/v1/auth/login/for-srm` |
| **方法** | `POST` |
| **请求体** | `{ "username":"供应商STP账号", "password":"密码" }` |
| **成功响应** | `{ "code":"0", "userInfo":{ "stpId":"STP内部ID", "srmId":"关联的SRM ID", "name":"公司名", "taxId":"税号" } }` |
| **失败响应** | `{ "code":"ERR_AUTH_001", "message":"用户名或密码错误" }` |

**接口定义：SRM登录验证接口（供STP调用）**

| 项目 | 内容 |
| :--- | :--- |
| **提供方** | SRM |
| **路径** | `/api/v1/auth/login/for-stp` |
| **方法** | `POST` |
| **请求体** | `{ "username":"供应商SRM账号", "password":"密码" }` |
| **成功响应** | `{ "code":"0", "userInfo":{ "srmId":"SRM内部ID", "name":"公司名", "taxId":"税号" } }` |
| **失败响应** | `{ "code":"ERR_AUTH_001", "message":"用户名或密码错误" }` |

> **说明：** `returnUrl`参数可选，用于指定验证成功后跳转的目标页面。两个系统在验证通过后，返回的用户信息中必须包含 `srmId`，以便对方建立本地会话并关联供应商身份。

#### 3.4.2 无感跳转（已登录状态下的跨系统切换）
当供应商已在任一方登录，点击指向另一方系统的链接时，通过临时跳转票据实现免密登录。

**STP → SRM 无感跳转流程：**

```mermaid
sequenceDiagram
    participant User as 供应商
    participant STP
    participant SRM

    Note over User,SRM: 前提：供应商已登录STP
    User->>STP: 点击“查看SRM合同”链接
    STP->>STP: 生成Ticket (srmId, stpSessionId, timestamp)
    STP->>STP: 使用STP私钥签名
    STP->>User: 302重定向到SRM，URL中携带Ticket
    User->>SRM: 访问SRM，携带Ticket
    SRM->>SRM: 使用STP公钥验签
    SRM->>STP: POST /api/v1/auth/session/validate { stpSessionId, srmId }
    STP-->>SRM: 200 OK { valid: true }
    SRM-->>SRM: 根据srmId建立本地会话
    SRM-->>User: 登录成功，展示SRM页面
```

**SRM → STP 无感跳转流程（对称，略）**

**跳转票据（Ticket）结构**

| 字段 | 类型 | 说明 |
| :--- | :--- | :--- |
| `srmId` | `String` | 供应商在SRM中的ID（必填） |
| `sessionId` | `String` | 来源系统当前登录会话ID |
| `timestamp` | `Long` | 生成时间戳，有效期建议5分钟 |
| `nonce` | `String` | 随机数，防重放 |
| `signature` | `String` | 对上述字段的签名（来源系统私钥） |

**会话有效性验证接口**

| 项目 | STP会话验证（供SRM调用） | SRM会话验证（供STP调用） |
| :--- | :--- | :--- |
| **提供方** | STP | SRM |
| **路径** | `/api/v1/auth/session/validate` | `/api/v1/auth/session/validate` |
| **方法** | `POST` | `POST` |
| **请求体** | `{ "sessionId":"STP会话ID", "srmId":"SRM ID" }` | `{ "sessionId":"SRM会话ID" }` |
| **成功响应** | `{ "code":"0", "valid": true }` | `{ "code":"0", "valid": true }` |
| **失败响应** | `{ "code":"0", "valid": false }` | `{ "code":"0", "valid": false }` |

---

### 3.5 中标资料转交接口
**提供方：** SRM
**消费方：** STP

```mermaid
sequenceDiagram
    participant STP
    participant SRM

    Note over STP: 定标完成，整理资料
    STP->>SRM: POST /api/v1/bid-result/transfer (中标资料包)
    SRM-->>SRM: 校验数据完整性
    SRM-->>SRM: 归档中标资料、投标过程数据等
    alt 成功
        SRM-->>STP: 200 OK { "code":"0", "recordId":"ARCH_2024001" }
    else 失败
        SRM-->>STP: 500 / 400 { "code":"ERR_002", "message":"资料不完整" }
    end
```

**请求体结构**

| 参数名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `projectId` | `String` | 是 | 招标项目ID |
| `bidResult` | `Object` | 是 | 定标结果 |
| `bidProcessData` | `Object` | 是 | 投标过程数据 |
| `supplierBidFiles` | `Array` | 是 | 供应商投标文件URL列表 |

---

## 4. 接口清单总表

| 模块 | 接口名称 | 请求方 | 提供方 | 协议 |
| :--- | :--- | :--- | :--- | :--- |
| **供应商信息** | 供应商名称查询 | STP | SRM | REST |
| | 供应商税号查询 | STP | SRM | REST |
| | 供应商ID查询 | STP | SRM | REST |
| | 供应商标签查询 | STP | SRM | REST |
| | 全量供应商同步 | STP | SRM | REST |
| | 增量供应商同步 | STP | SRM | REST |
| **供应商注册** | 供应商自动注册 | STP | SRM | REST |
| **采购计划** | 采购计划查询 | STP | SRM | REST |
| **登录认证** | SRM登录验证 | SRM | STP | REST |
| | STP登录验证 | STP | SRM | REST |
| | STP会话有效性验证 | SRM | STP | REST |
| | SRM会话有效性验证 | STP | SRM | REST |
| | STP→SRM无感跳转 | SRM | STP | REST+签名 |
| | SRM→STP无感跳转 | STP | SRM | REST+签名 |
| **中标转交** | 中标资料接收 | STP | SRM | REST |

## 5. 安全设计

| 维度 | 策略 | 说明 |
| :--- | :--- | :--- |
| **传输安全** | HTTPS/TLS 1.2+ | 所有接口通信必须使用HTTPS加密传输。 |
| **身份认证** | Token / 证书 | 系统间API调用采用Token认证；无感跳转采用RSA私钥签名验证。 |
| **防重放** | 时间戳 + 随机数 | 跳转票据和关键请求携带时间戳和随机数，有效期建议5分钟。 |
| **数据脱敏** | 日志脱敏 | 税号、联系方式等敏感信息在日志中必须脱敏处理。 |
| **访问控制** | 最小权限原则 | 接口调用方仅能访问其业务所必需的数据。 |

## 6. 错误码规范

| 错误码 | 说明 | 示例 |
| :--- | :--- | :--- |
| `0` | 成功 | — |
| `ERR_AUTH_001` | 认证失败 | Token无效或已过期 |
| `ERR_AUTH_002` | 签名验证失败 | 跳转票据签名不匹配 |
| `ERR_PARAM_001` | 参数缺失/格式错误 | 必填字段为空 |
| `ERR_BIZ_001` | 供应商已存在 | 注册时税号重复 |
| `ERR_BIZ_002` | 供应商不存在 | ID查询无结果 |
| `ERR_SYS_001` | 系统内部错误 | 数据库连接超时 |