supply-intelligence/tech/INTERFACE.md

# Supply-Intelligence 核心接口设计

> 状态说明（2026-05 收敛修订）：本文件保留为旧版接口草案，已不再作为当前实现真源。
> 当前接口真源以 /home/long/project/立交桥/projects/supply-intelligence/tech/BASELINE_TECHLEAD_V2.md 为准。
> 以下旧接口定义已废止，不得继续作为实现入口：
> - pricing comparison / recommendations / predictions 相关接口
> - 与新 candidate 状态机不一致的旧状态枚举
> - 未区分 published 与 gateway applied 的旧消费口径

> 版本：v1.0 | 状态：初稿

---

## 1. 内部模块间接口

### 1.1 ProbeService

```go
type ProbeService interface {
    // 执行单次探针
    Probe(ctx context.Context, accountID string) (*ProbeResult, error)
    // 批量探针（按供应商或全量）
    ProbeBatch(ctx context.Context, filter ProbeFilter) (*BatchProbeResult, error)
    // 获取探针结果历史
    GetProbeHistory(ctx context.Context, accountID string, limit int) ([]ProbeResult, error)
    // 手动触发掠针（运营干预）
    TriggerManualProbe(ctx context.Context, accountID string, actorID string) (*ProbeResult, error)
}

type ProbeResult struct {
    AccountID     string
    Status        string // active suspended disabled
    RiskScore     int    // 0-100
    RiskReason    string
    LatencyMs     int
    ResponseCode  int
    CheckedAt     time.Time
    NextCheckAt   time.Time
}

type ProbeFilter struct {
    Platform      *string
    Status        *string
    RiskScoreMin  *int
    RiskScoreMax  *int
}
```

### 1.2 DiscoveryService

```go
type DiscoveryService interface {
    // 执行单次全网扫描
    Scan(ctx context.Context) (*ScanResult, error)
    // 获取最近扫描结果
    GetLastScan(ctx context.Context) (*ScanResult, error)
    // 获取候选模型列表
    ListCandidates(ctx context.Context, filter CandidateFilter) ([]ModelCandidate, error)
    // 手动触发扫描
    TriggerManualScan(ctx context.Context, actorID string) (*ScanResult, error)
    // 忽略候选模型
    IgnoreCandidate(ctx context.Context, candidateID string, reason string, actorID string) error
}

type ScanResult struct {
    ScannedAt     time.Time
    Platforms     []string
    NewModels     int
    RemovedModels int
    Errors        []ScanError
}

type ModelCandidate struct {
    ID            string
    Platform      string
    ModelID       string
    Status        string // discovered queued testing test_passed test_failed ignored
    DiscoveredAt  time.Time
    TestedAt      *time.Time
    TestResult    *TestResult
}
```

### 1.3 AdmissionService

```go
type AdmissionService interface {
    // 执行准入测试
    RunTest(ctx context.Context, candidateID string) (*TestResult, error)
    // 获取测试结果
    GetTestResult(ctx context.Context, candidateID string) (*TestResult, error)
    // 手动确认上架（运营干预）
    Publish(ctx context.Context, candidateID string, actorID string) error
    // 强制上架（测试失败但运营确认）
    ForcePublish(ctx context.Context, candidateID string, reason string, actorID string) error
}

type TestResult struct {
    CandidateID   string
    Status        string // passed failed
    Dimensions    []TestDimension
    FailedReason  *string
    ExecutedAt    time.Time
    DurationMs    int
}

type TestDimension struct {
    Name      string
    Passed    bool
    Detail    string
}
```

### 1.4 AccountService

```go
type AccountService interface {
    // 创建账号（手动或自动）
    CreateAccount(ctx context.Context, req CreateAccountRequest) (*SupplyAccount, error)
    // 获取账号信息
    GetAccount(ctx context.Context, accountID string) (*SupplyAccount, error)
    // 更新账号状态
    UpdateStatus(ctx context.Context, accountID string, status string, reason string) error
    // 轮换密钥
    RotateKey(ctx context.Context, accountID string, actorID string) error
    // 列表账号
    ListAccounts(ctx context.Context, filter AccountFilter) ([]SupplyAccount, error)
}

type SupplyAccount struct {
    ID          string
    Platform    string
    ProxyID     string
    Status      string
    RiskScore   int
    APIKeyHint  string // 密钥前 4 后 4
    CreatedAt   time.Time
    UpdatedAt   time.Time
}
```

### 1.5 HealthBoardService

```go
type HealthBoardService interface {
    // 获取供应商健康大盘
    GetBoard(ctx context.Context, scope BoardScope) (*HealthBoard, error)
    // 获取模型比价报表
    GetPricingComparison(ctx context.Context, modelID string) ([]PricingComparison, error)
    // 获取供应链覆盖率
    GetCoverage(ctx context.Context) (*CoverageReport, error)
    // 获取预测分析
    GetPredictions(ctx context.Context, minConfidence float64) ([]Prediction, error)
}

type HealthBoard struct {
    Accounts      []AccountHealth
    Candidates    []CandidateSummary
    Coverage      float64
    FreshnessIndex float64
}
```

---

## 2. 外部系统集成接口

### 2.1 与 Bridge Gateway 集成

| 方法 | 路径 | 请求 | 响应 | 说明 |
|------|------|------|------|------|
| 查询账号状态 | `GET /internal/supply-intelligence/accounts/{id}/health` | - | `ProbeResult` | Gateway 路由决策时查询 |
| 查询模型定价 | `GET /internal/supply-intelligence/pricing/{model_id}` | - | `PricingInfo` | 动态定价参考 |
| 获取推荐供应商 | `GET /internal/supply-intelligence/recommendations` | `?model={model_id}&strategy=cost` | `[]Recommendation` | 智能路由推荐 |

### 2.2 与 supply-api 集成

| 方法 | 路径 | 请求 | 响应 | 说明 |
|------|------|------|------|------|
| 读取账号列表 | `GET /internal/supply/accounts` | - | `[]SupplyAccount` | 探针器获取待检测账号 |
| 更新账号状态 | `POST /internal/supply/accounts/{id}/status` | `{"status":"suspended","reason":""}` | `{"success":true}` | 探针结果写回 |
| 读取模型列表 | `GET /internal/supply/packages` | - | `[]SupplyPackage` | 扫描比对基准 |
| 创建模型 | `POST /internal/supply/packages` | `SupplyPackage` | `{"id":""}` | 准入测试通过后上架 |
| 获取审计日志格式 | `GET /internal/supply/audit/schema` | - | `{"schema":{}}` | 审计事件格式一致 |

---

## 3. API 接口规范

### 3.1 REST API 基础

- **基础路径**: `/api/v1/supply-intelligence/`
- **内部路径** (集成模式): `/internal/supply-intelligence/`
- **内容类型**: `application/json`
- **错误响应格式**:

```json
{
  "error": {
    "code": "SI_PRB_4001",
    "message": "供应商账号不存在",
    "details": {}
  }
}
```

### 3.2 核心端点

#### 探针管理

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/supply-intelligence/probes` | 列表探针结果 |
| POST | `/api/v1/supply-intelligence/probes/{account_id}` | 手动触发探针 |
| GET | `/api/v1/supply-intelligence/probes/{account_id}/history` | 探针历史 |

#### 扫描与发现

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/v1/supply-intelligence/discovery/scan` | 手动触发全网扫描 |
| GET | `/api/v1/supply-intelligence/discovery/candidates` | 列表候选模型 |
| GET | `/api/v1/supply-intelligence/discovery/candidates/{id}` | 获取候选模型详情 |
| POST | `/api/v1/supply-intelligence/discovery/candidates/{id}/ignore` | 忽略候选模型 |

#### 准入测试

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/v1/supply-intelligence/admission/{candidate_id}/test` | 手动执行准入测试 |
| GET | `/api/v1/supply-intelligence/admission/{candidate_id}/result` | 获取测试结果 |
| POST | `/api/v1/supply-intelligence/admission/{candidate_id}/publish` | 确认上架 |
| POST | `/api/v1/supply-intelligence/admission/{candidate_id}/force-publish` | 强制上架 |

#### 账号管理

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/supply-intelligence/accounts` | 列表账号 |
| POST | `/api/v1/supply-intelligence/accounts` | 创建账号 |
| GET | `/api/v1/supply-intelligence/accounts/{id}` | 获取账号 |
| POST | `/api/v1/supply-intelligence/accounts/{id}/rotate-key` | 轮换密钥 |
| POST | `/api/v1/supply-intelligence/accounts/{id}/status` | 更新状态 |

#### 健康大盘

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/supply-intelligence/health-board` | 获取健康大盘 |
| GET | `/api/v1/supply-intelligence/pricing/{model_id}/comparison` | 模型比价 |
| GET | `/api/v1/supply-intelligence/coverage` | 供应链覆盖率 |
| GET | `/api/v1/supply-intelligence/predictions` | 预测分析 |

### 3.3 错误码定义

| 错误码 | HTTP 状态 | 说明 |
|---------|-----------|------|
| `SI_PRB_4001` | 404 | 供应商账号不存在 |
| `SI_PRB_4002` | 429 | 探针频率过高，请等待 |
| `SI_DIS_4001` | 404 | 候选模型不存在 |
| `SI_DIS_4002` | 409 | 候选模型状态不允许忽略 |
| `SI_ADM_4001` | 404 | 准入测试任务不存在 |
| `SI_ADM_4002` | 409 | 准入测试正在执行中 |
| `SI_ADM_4003` | 400 | 测试未通过，无法上架 |
| `SI_ACC_4001` | 404 | 账号不存在 |
| `SI_ACC_4002` | 409 | 账号状态不允许此操作 |
| `SI_ACC_4003` | 403 | 无权执行此操作 |
| `SI_BRD_4001` | 400 | 查询参数无效 |

### 3.4 WebSocket 接口

**路径**: `/ws/v1/supply-intelligence/board`

- 运营工作台订阅后，实时推送探针结果、候选模型变更、状态变更待办。
- 心跳间隔 30 秒。