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

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

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

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

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

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
• 错误响应格式:

{
  "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 秒。