supply-intelligence/tech/HLD.md

Supply-Intelligence 高层技术设计文档（HLD）

状态说明（2026-05 收敛修订）：本文件保留为旧版高层设计草案，已不再作为当前实现真源。 当前技术真源为 /home/long/project/立交桥/projects/supply-intelligence/tech/BASELINE_TECHLEAD_V2.md。 若本文件与 BASELINE_TECHLEAD_V2.md 冲突，一律以后者为准。 以下旧设计项已明确废止，不得作为 Engineer/QA 的实施与验收依据：

• PricingDB / 模型比价 / 预测分析 / 社区情报源
• 向量数据库 / 向量检索主路径
• 以独立 API/Worker 集群为默认前提的重部署架构
• Playwright 自动注册作为本期主路径
• gateway 强耦合自动编排替代 package event + ack 闭环

文档版本：v1.0 撰写日期：2026-04-27 撰写人：TechLead 评审状态：待开发排期确认

---

1. 设计目标与范围

1.1 设计目标

为 Supply-Intelligence（供应链智能增强系统）建立可生产落地的技术方案，支撑以下业务目标的达成：

目标编号	目标描述	技术侧支撑
BG-01	供应商账号异常状态标记平均时间 ≤ 15 分钟	探针调度周期 5 分钟 + 状态机自动迁移
BG-02	新模型从发布到可售卖平均时间 ≤ 4 小时	每小时全网扫描 + 30 分钟内完成准入测试
BG-03	供应商账号失效导致的用户可见错误率下降 80%	探针实时标记 + Gateway 状态查询接口 P99 < 50ms
BG-04	人工维护供应商基础信息工作量减少 70%	自动发现 + 自动测试 + 自动注册

1.2 设计范围

In Scope（按 Phase 交付）：

• Phase 1：供应商品质探针（模块 A）+ 运营工作台观测视图
• Phase 2：全网模型发现（模块 B）+ 模型准入测试（模块 C）
• Phase 3：账号自动注册（模块 D）+ 运营工作台完整干预能力

Out of Scope：

• 供应商侧计费系统对接与自动充值（OOS-01）
• 动态定价算法（OOS-02）
• TOS 法律合规性自动审查（OOS-03）
• 不支持公开注册接口的供应商自动注册（OOS-04）
• 模型版本语义级差异分析（OOS-05）
• 跨供应商模型能力等价性判定（OOS-06）

---

2. 系统架构总览

2.1 架构图（逻辑分层）

┌─────────────────────────────────────────────────────────────────────────────┐
│                              消费层                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐ │
│  │   Gateway    │  │  运营工作台   │  │ NewAPI/Sub2 │  │   告警通知       │ │
│  │  (路由决策)   │  │  (Dashboard) │  │   API 适配层 │  │ (钉钉/企微/邮件) │ │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └─────────────────┘ │
└─────────┼─────────────────┼─────────────────┼──────────────────────────────┘
          │                 │                 │
          │ GET /health     │ REST/WebSocket  │ gRPC/REST
          │ (P99<50ms)      │                 │
┌─────────┼─────────────────┼─────────────────┼──────────────────────────────┐
│         │                 │                 │                              │
│  ┌──────▼─────────────────▼─────────────────▼──────────────────────────┐  │
│  │                     API Gateway Layer                               │  │
│  │  /api/v1/supply-intelligence/*  (独立运行)                          │  │
│  │  /internal/supply-intelligence/* (集成运行)                         │  │
│  └──────┬──────────────────────────────────────────────────────────────┘  │
│         │                                                                  │
│  ┌──────▼──────────────────────────────────────────────────────────────┐  │
│  │                     Application Service Layer                        │  │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────────┐  │  │
│  │  │ProbeService │ │DiscoverySvc │ │AdmissionSvc │ │AutoRegSvc    │  │  │
│  │  │ (品质探针)   │ │(模型发现)   │ │(准入测试)   │ │(自动注册)    │  │  │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └──────────────┘  │  │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────────┐  │  │
│  │  │StateMachine │ │PricingDB    │ │HealthBoard │ │OpsWorkBench │  │  │
│  │  │ (状态机)    │ │(定价数据库)  │ │(健康大盘)   │ │(运营工作台)   │  │  │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └──────────────┘  │  │
│  └──────┬──────────────────────────────────────────────────────────────┘  │
│         │                                                                  │
│  ┌──────▼──────────────────────────────────────────────────────────────┐  │
│  │                     Domain & Infrastructure Layer                    │  │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────────┐  │  │
│  │  │ProbeExecutor│ │Scanner      │ │TestRunner   │ │BrowserEngine │  │  │
│  │  │ (探针执行器) │ │(扫描器)     │ │(测试执行器)  │ │(浏览器自动化) │  │  │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └──────────────┘  │  │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────────┐  │  │
│  │  │Scheduler    │ │AuditEmitter │ │KMSClient    │ │RateLimiter   │  │  │
│  │  │ (任务调度)   │ │(审计发射器)  │ │(KMS 客户端) │ │(限流器)      │  │  │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └──────────────┘  │  │
│  └──────┬──────────────────────────────────────────────────────────────┘  │
│         │                                                                  │
├─────────┼──────────────────────────────────────────────────────────────────┤
│         │                    外部依赖层                                   │
│  ┌──────▼──────┐ ┌─────────────┐ ┌─────────────┐ ┌────────────────────┐ │
│  │ PostgreSQL  │ │   Redis     │ │ Job Scheduler│ │ 供应商 API / Web    │ │
│  │ (主存储)    │ │  (缓存/队列) │ │ (Temporal/   │ │ (OpenAI/Anthropic/ │ │
│  │             │ │             │ │ 内部 Cron)   │ │  阿里云/百度等)     │ │
│  └─────────────┘ └─────────────┘ └─────────────┘ └────────────────────┘ │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                        │
│  │  KMS 服务   │ │SMS/邮件网关  │ │  supply-api │                        │
│  │ (凭证加密)   │ │(验证码)     │ │ (现有服务)   │                        │
│  └─────────────┘ └─────────────┘ └─────────────┘                        │
└──────────────────────────────────────────────────────────────────────────┘

2.2 部署形态

本系统支持两种运行模式，对应两套构建产物：

模式	构建产物	数据库 Schema	HTTP 前缀	适用场景
独立运行	cmd/supply-intelligence/main.go → 独立二进制/容器	supply_intelligence_* + 独立连接池	/api/v1/supply-intelligence/	外部用户仅需供应链管理能力
集成运行	pkg/supplyintelligence/plugin.go → Go module	supply_intelligence_* + 共享连接池	/internal/supply-intelligence/	立交桥用户一体化供应链能力

集成运行时：主进程通过 IntegrationPlugin 接口注册各模块 Handler 与 Background Worker，通过配置开关 supply_intelligence.enabled_modules 控制子模块挂载。

2.3 核心组件职责

组件	职责	对应 PRD 模块
ProbeService	调度探针任务、解析结果、驱动状态机	模块 A
DiscoveryService	扫描供应商模型列表、比对差异、生成候选	模块 B
AdmissionService	调度准入测试、评估结果、生成 package 草稿	模块 C
AutoRegistrationService	触发注册流程、编排验证步骤、凭证加密存储	模块 D
HealthBoardService	聚合探针/测试/注册数据，生成健康大盘指标	模块 E（数据）
OpsWorkbenchService	处理人工干预请求、权限校验、审计记录	模块 E（操作）
PricingDBService	维护模型定价数据库、支持远程更新与本地 fallback	竞品对标
StateMachine	统一状态迁移规则、校验、乐观锁冲突处理	通用
AuditEmitter	异步发射审计事件、脱敏、批量写入	通用

---

3. 核心模块设计

3.1 供应商品质探针（Supply Health Probe）

3.1.1 探针类型与判定规则

探针类型	请求方式	成功判定	失败判定	inconclusive
connectivity	HEAD /models 或等效端点	HTTP 2xx，latency ≤ 10s	HTTP 401/403，TCP/DNS 失败，latency > 10s	HTTP 429，HTTP 5xx，响应体解析失败
quota	调用额度查询接口（若供应商支持）	返回可用额度 > 0	返回额度 = 0 或接口报错	接口不存在或返回非预期格式
key_validity	发送一条低成本 completion 请求	HTTP 2xx，响应体合规	HTTP 401/403，响应格式不合法	HTTP 429，超时

3.1.2 状态机规则

                    ┌──────────────┐
                    │   active     │
                    └──────┬───────┘
                           │ 1次明确失败
                           ▼
                    ┌──────────────┐
         ┌─────────│  suspended   │◄────────┐
         │ 恢复成功 └──────┬───────┘         │
         │               │ 连续3次失败      │ 429 inconclusive
         ▼               ▼                  │ (不计入失败)
┌──────────────┐  ┌──────────────┐         │
│   active     │  │  disabled    │─────────┘
│ (人工恢复)   │  │              │
└──────────────┘  └──────────────┘

规则约束：

• active → suspended：需 1 次明确失败（HTTP 401/403/超时 > 10s / TCP 不可达）。
• suspended → disabled：需连续 3 次探针失败，每次间隔 ≥ 5 分钟。
• suspended → active：1 次探针成功即可恢复。
• disabled → active：仅允许人工操作触发，系统不自动恢复。
• active → disabled 的直接迁移被禁止，必须经过 suspended。

3.1.3 探针调度策略

• 周期：默认 5 分钟/账号，可通过配置 probe.interval_seconds 热更新（60 秒内生效）。
• 并发：使用 Worker Pool 模型，默认池大小 = 50，单账号探针超时 = 15 秒。
• 退避：遇到 429 时，指数退避 1min → 2min → 4min，最多重试 3 次，仍 429 则本次跳过。
• 分批：按 platform 分组错峰，避免同时冲击同一供应商。

3.1.4 风险评分模型

type RiskAssessment struct {
    Score       int    // 0-100
    Reason      string // 机器可读原因码
    Severity    string // info / warning / critical
    SuggestedAction string // none / suspend / disable / investigate
}

评分规则（示例）：

• 连通性失败 + 额度正常 = 60 分，warning
• 连通性失败 + 密钥无效 = 80 分，critical，建议 suspend
• 连续 2 次 warning = 提升至 critical

3.2 全网模型发现（Model Discovery）

3.2.1 扫描源与适配器

每个供应商实现 ModelListScanner 接口：

type ModelListScanner interface {
    // 返回当前供应商所有 model_id 列表
    Scan(ctx context.Context) ([]ModelInfo, error)
    // 供应商唯一标识
    Platform() string
    // 扫描器健康检查
    HealthCheck(ctx context.Context) error
}

扫描源类型：

类型	示例供应商	实现方式	优先级
REST API	OpenAI, Anthropic	HTTP GET /models，解析 JSON	高
文档页面	部分国内供应商	Playwright / colly 抓取 HTML	中
RSS/变更日志	HuggingFace	RSS 订阅 + 解析	中
社区监控	HN, Twitter	外部数据源接入（Phase 2 后）	低

3.2.2 发现比对算法

1. 获取供应商侧当前 model_id 集合 S_current。
2. 查询本平台 supply_packages 中 platform = X 且 status ∈ {active, paused, draft} 的 model 集合 S_platform。
3. 差集计算：
   • S_current - S_platform → 新增模型，插入 model_candidates（discovered）。
   • S_platform - S_current → 疑似下架模型，生成告警待办，但 不自动变更 supply_packages.status。
4. 重命名检测（边缘场景 B1）：旧 ID 消失 + 新 ID 出现 + 能力描述相似度 > 0.85 → 生成运营待办，不做自动关联。

3.2.3 扫描周期与容错

• 周期：默认 1 小时，配置项 discovery.interval_seconds。
• 分页容错：若某页返回 500，已获取页正常处理，失败页在下一周期重试（FP-07）。
• 缓存 TTL：扫描结果在 Redis 缓存 30 分钟，避免重复请求供应商接口。

3.3 模型准入测试（Model Admission Test）

3.3.1 测试流水线

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  discovered │───►│   queued    │───►│   testing   │───►│ test_passed │
│  (发现)     │    │  (入队列)   │    │  (执行中)   │    │ (测试通过)  │
└─────────────┘    └─────────────┘    └──────┬──────┘    └─────────────┘
                                             │
                                    ┌────────▼────────┐
                                    │   test_failed   │
                                    │   (测试失败)     │
                                    └─────────────────┘

3.3.2 测试维度与通过标准

维度	检查项	通过标准	权重
接口可用性	HTTP 状态码	200	必须
响应格式合规	JSON Schema 校验（OpenAI-compatible）	100% 通过	必须
延迟	P50 / P99	P50 < 5s, P99 < 30s	必须
Token 计数一致性	请求 token 数 vs 响应 usage 字段	误差 ≤ 5%	必须
错误码映射	发送无效参数，验证错误码	返回 4xx 且 body 含 error 字段	必须
功能覆盖	chat / completion / embedding	按模型类型选择对应 endpoint	必须

通过定义：所有“必须”维度通过，且无任何测试用例超时（超时阈值 60 秒/用例）。

3.3.3 测试隔离

• 准入测试必须使用 独立测试账号（supply_accounts 中 usage_type = test），禁止触碰生产账号。
• 测试账号被探针标记为 suspended 时，准入测试流水线立即失败，原因写入 test_account_unavailable（FP-04）。
• 测试请求添加 X-Supply-Intelligence-Test: true 头部，便于供应商侧识别（如支持）。

3.3.4 测试用例集管理

• 测试用例由 QA 团队维护，存储于 configs/admission_tests/ 目录下，按模型类型分组。
• 用例格式：YAML 定义请求模板 + 预期响应断言（JSONPath）。
• 每类模型最少 5 个用例，覆盖正常请求、超长输入、特殊字符、空输入、错误参数。
• 用例变更后，系统 60 秒内热加载，不重启进程（AC-12）。

3.4 账号自动注册（Account Auto-Registration）

3.4.1 注册流程状态机

┌─────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│ pending │──►│registering│──►│verifying │──►│ applying │──►│completed │
│ (触发)  │   │ (注册中)  │   │ (验证中)  │   │ (申请Key) │   │ (完成)   │
└─────────┘   └────┬─────┘   └────┬─────┘   └────┬─────┘   └────┬─────┘
                   │              │              │              │
                   ▼              ▼              ▼              ▼
            ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
            │  failed  │   │  failed  │   │  failed  │   │ dead_letter│
            │ (注册失败)│   │ (验证失败)│   │ (申请失败)│   │ (死信)    │
            └──────────┘   └──────────┘   └──────────┘   └──────────┘

3.4.2 供应商注册适配器

每个供应商实现 RegistrationAdapter 接口：

type RegistrationAdapter interface {
    // 是否支持自动注册
    IsSupported() bool
    // 执行注册，返回临时凭证
    Register(ctx context.Context, req RegistrationRequest) (*RegistrationResult, error)
    // 验证账号（邮件/SMS）
    Verify(ctx context.Context, accountID string, code string) error
    // 申请 API Key
    ApplyAPIKey(ctx context.Context, accountID string) (string, error)
    // 平台标识
    Platform() string
}

实现策略：

• 优先使用官方注册 API（REST）。
• 无官方 API 时，使用 Playwright 浏览器自动化作为 fallback。
• 浏览器自动化流程需记录 DOM 选择器版本，供应商前端改版时触发告警。

Playwright Fallback 的运维复杂度说明

• 额外依赖：需要 Playwright 浏览器二进制（Chromium/ Firefox/WebKit），Docker 镜像体积增加约 200MB
• DOM版本管理：每个供应商的注册表单需维护独立的选择器配置文件，供应商前端改版后需手动更新
• CI/CD要求：浏览器测试需要在有头模式下运行，CI 需配置--headed模式或使用 playwright-chromium
• 备选方案：若 Playwright 维护成本过高，可考虑将自动注册范围缩小至仅有官方 API 的供应商，自动注册模块降级为"手动注册辅助"（仅生成注册任务工单，不自动执行）

3.4.3 Fail-Closed 设计

• SMS/邮件网关返回 503 或超时 → 注册任务整体标记 failed，审计日志记录 auto_register_failed，不向任何上游返回成功状态（AC-09）。
• KMS 服务不可用时，明文凭证不得落盘；注册流程在加密步骤阻塞 60 秒，超时后任务标记 failed（FP-10）。
• 死信队列：失败任务 24 小时后自动重试，最多重试 3 次，最终进入 dead_letter 状态，触发人工告警。

3.5 供应商健康大盘（Health Board）

3.5.1 指标聚合

指标	计算方式	刷新周期
账号健康度	active 账号数 / (active + suspended) 账号数	实时（基于探针结果）
模型覆盖率	平台 active 模型数 / 全网 discovered 模型数	每小时
探针成功率	最近 1 小时 success / total	5 分钟
平均延迟	最近 1 小时探针 latency P50/P99	5 分钟
风险账号数	risk_score ≥ 60 的账号数	实时
待处理候选数	status = discovered 的 candidate 数	实时

3.5.2 北极星指标（SFI）

SFI = (过去1小时成功探针账号数 / 应探针账号总数) ×
      (过去24小时进入active的新模型数 / 过去24小时发现的新模型总数)

• 目标值：SFI ≥ 0.95
• 采集周期：每小时计算一次，写入时序数据库（Prometheus 或独立 TSDB）。
• 连续 7 天 SFI < 0.70 触发项目失败判定线（止损条件 3）。

3.6 模型比价（Pricing Comparison）

3.6.1 定价数据库设计

参考 LiteLLM model_prices_and_context_window_backup.json，维护以下字段：

字段	类型	说明
model_id	VARCHAR(100)	全局模型标识
platform	VARCHAR(50)	供应商
input_cost_per_token	DECIMAL(18,12)	输入 token 单价（美元）
output_cost_per_token	DECIMAL(18,12)	输出 token 单价（美元）
context_window	INT	上下文长度
max_tokens	INT	最大输出 token 数
supports_vision	BOOLEAN	是否支持视觉
supports_function_calling	BOOLEAN	是否支持函数调用
supports_batch	BOOLEAN	是否支持批量定价
tiered_pricing	JSONB	分层定价规则
updated_at	TIMESTAMPTZ	更新时间
source_hash	VARCHAR(64)	数据源 SHA256

更新机制：

• 主数据源：远程拉取 LiteLLM 镜像（可配置镜像源），SHA256 校验完整性（参考 Sub2API）。
• Fallback：本地缓存文件 data/model_prices_fallback.json，启动时若远程失败则加载本地。
• 自定义覆盖：平台可通过 pricing_overrides 表对特定供应商-模型组合设置覆盖价格。

3.6.2 模型家族回退

参考 Sub2API 设计，对未知模型按命名规则回退到已知模型定价：

// 回退规则（按优先级）
1. 精确匹配 model_id
2. 前缀匹配：gpt-4-turbo-2024-04-09 → gpt-4-turbo
3. 家族匹配：gpt-5.3-unknown → gpt-5.1
4. 能力匹配：claude-unknown-vision → claude-sonnet (若 supports_vision=true)
5. 默认回退：unknown → 平台默认定价（需人工审核）

回退决策记录到 pricing_fallback_log，供运营人员定期审查。

3.7 预测分析（Predictive Analytics）

3.7.1 模型下线预测

基于以下信号生成预测：

• 供应商模型列表中该模型连续 3 个扫描周期未出现。
• 该模型近期（7 天）用量趋势下降 > 50%。
• 供应商官方发布 deprecation 公告（如有 RSS/公告源）。

预测结果写入 predictions 表，置信度 ≥ 0.7 时触发运营告警。

3.7.2 供应商变动预测

• 监控供应商 API 文档变更频率、Rate Limit 调整、定价变更。
• 高频变动标记为 unstable，健康大盘中展示风险标签。

3.8 运营工作台（Operations Dashboard）

3.8.1 核心视图

视图	内容	数据刷新
待处理候选模型	discovered / test_failed candidate 列表	实时（WebSocket 推送）
账号健康列表	全部账号状态、最近探针时间、risk_score	5 分钟轮询
状态变更待确认	系统建议的 suspend / disable 操作 + 人工确认按钮	实时
自动注册队列	pending / running / failed 任务列表	实时
供应链覆盖率	覆盖率百分比、趋势图、竞品对比（如数据可用）	每小时

3.8.2 人工干预操作

操作	权限要求	效果	审计记录
一键确认上架	supply:ops:publish	draft → active	action=manual_publish
忽略此模型	supply:ops:ignore	discovered → ignored，ignored_until = NOW() + 7d	action=manual_ignore
手动触发探针	supply:ops:probe	立即执行单次探针	action=manual_probe
强制上架（测试失败）	supply:ops:force_publish	draft + manually_forced=true，需填写理由	action=manual_force_publish
暂停自动探针	supply:ops:pause_probe	auto_probe_enabled = false	action=pause_auto_probe

并发控制：所有干预操作使用乐观锁或幂等键（IdempotencyKey），重复操作返回 409 Conflict（FP-09）。

---

4. 数据模型设计

4.1 ER 关系图

┌────────────────────┐       ┌────────────────────┐       ┌────────────────────┐
│  supply_accounts   │       │ supply_intelligence│       │  supply_packages   │
│   (已有表，只读)    │◄──────│  _model_candidates │──────►│   (已有表，读写)   │
└────────────────────┘       └────────────────────┘       └────────────────────┘
         │                            │                            │
         │                            │                            │
         ▼                            ▼                            ▼
┌────────────────────┐       ┌────────────────────┐       ┌────────────────────┐
│si_probe_execution  │       │ si_pricing_db      │       │ si_predictions     │
│_logs               │       │                    │       │                    │
└────────────────────┘       └────────────────────┘       └────────────────────┘
         │
         │
         ▼
┌────────────────────┐       ┌────────────────────┐       ┌────────────────────┐
│si_auto_registration│       │ si_audit_events    │       │ si_health_metrics  │
│_tasks              │       │ (扩展字段)          │       │                    │
└────────────────────┘       └────────────────────┘       └────────────────────┘

4.2 核心表结构

4.2.1 supply_intelligence_model_candidates

CREATE TABLE supply_intelligence_model_candidates (
    id              BIGSERIAL PRIMARY KEY,
    platform        VARCHAR(50) NOT NULL,
    model_id        VARCHAR(100) NOT NULL,
    model_name      VARCHAR(200),
    status          VARCHAR(20) NOT NULL DEFAULT 'discovered'
                    CHECK (status IN ('discovered','testing','test_passed','test_failed','ignored','expired')),
    discovered_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    tested_at       TIMESTAMPTZ,
    failure_reason  TEXT,
    ignored_until   TIMESTAMPTZ,
    test_log_url    TEXT,               -- 测试日志对象存储路径
    package_draft_id BIGINT,            -- 关联 supply_packages.id (draft)
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    version         INT NOT NULL DEFAULT 1,  -- 乐观锁

    UNIQUE(platform, model_id)
);

CREATE INDEX idx_candidates_status ON supply_intelligence_model_candidates(status);
CREATE INDEX idx_candidates_discovered_at ON supply_intelligence_model_candidates(discovered_at);
CREATE INDEX idx_candidates_platform ON supply_intelligence_model_candidates(platform);

4.2.2 supply_intelligence_auto_registration_tasks

CREATE TABLE supply_intelligence_auto_registration_tasks (
    id                  BIGSERIAL PRIMARY KEY,
    platform            VARCHAR(50) NOT NULL,
    task_type           VARCHAR(20) NOT NULL
                        CHECK (task_type IN ('register','verify','rotate_key')),
    status              VARCHAR(20) NOT NULL DEFAULT 'pending'
                        CHECK (status IN ('pending','running','completed','failed','dead_letter')),
    context             JSONB NOT NULL DEFAULT '{}',
    result_account_id   BIGINT,         -- 关联 supply_accounts.id
    failure_reason      TEXT,
    retry_count         INT NOT NULL DEFAULT 0,
    next_retry_at       TIMESTAMPTZ,
    credential_fingerprint VARCHAR(64),  -- API Key 哈希指纹，非明文
    created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    version             INT NOT NULL DEFAULT 1
);

CREATE INDEX idx_reg_tasks_status ON supply_intelligence_auto_registration_tasks(status, next_retry_at);
CREATE INDEX idx_reg_tasks_platform ON supply_intelligence_auto_registration_tasks(platform);

4.2.3 supply_intelligence_probe_execution_logs

CREATE TABLE supply_intelligence_probe_execution_logs (
    id              BIGSERIAL PRIMARY KEY,
    account_id      BIGINT NOT NULL,    -- supply_accounts.id
    probe_type      VARCHAR(20) NOT NULL
                    CHECK (probe_type IN ('connectivity','quota','key_validity')),
    result          VARCHAR(20) NOT NULL
                    CHECK (result IN ('success','failure','inconclusive')),
    http_status     INT,
    latency_ms      INT,
    error_code      VARCHAR(50),
    error_message   TEXT,
    risk_score      INT,
    risk_reason     VARCHAR(100),
    executed_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    request_id      VARCHAR(64) NOT NULL
);

CREATE INDEX idx_probe_logs_account_executed
    ON supply_intelligence_probe_execution_logs(account_id, executed_at DESC);
CREATE INDEX idx_probe_logs_executed_at
    ON supply_intelligence_probe_execution_logs(executed_at)
    WHERE executed_at < NOW() - INTERVAL '30 days';  -- 用于清理

保留策略：30 天自动清理，使用 PostgreSQL 分区表按 executed_at 月分区。

4.2.4 supply_intelligence_pricing_db

CREATE TABLE supply_intelligence_pricing_db (
    id                      BIGSERIAL PRIMARY KEY,
    model_id                VARCHAR(100) NOT NULL,
    platform                VARCHAR(50) NOT NULL,
    input_cost_per_token    DECIMAL(18,12) NOT NULL,
    output_cost_per_token   DECIMAL(18,12) NOT NULL,
    context_window          INT,
    max_tokens              INT,
    supports_vision         BOOLEAN DEFAULT FALSE,
    supports_function_calling BOOLEAN DEFAULT FALSE,
    supports_batch          BOOLEAN DEFAULT FALSE,
    tiered_pricing          JSONB,
    source_hash             VARCHAR(64),
    is_fallback             BOOLEAN DEFAULT FALSE,  -- 是否为回退定价
    fallback_reason         TEXT,
    updated_at              TIMESTAMPTZ NOT NULL DEFAULT NOW(),

    UNIQUE(model_id, platform)
);

CREATE INDEX idx_pricing_model ON supply_intelligence_pricing_db(model_id);
CREATE INDEX idx_pricing_platform ON supply_intelligence_pricing_db(platform);

4.2.5 supply_intelligence_health_metrics

CREATE TABLE supply_intelligence_health_metrics (
    id              BIGSERIAL PRIMARY KEY,
    metric_name     VARCHAR(50) NOT NULL,
    platform        VARCHAR(50),        -- NULL 表示全局
    account_id      BIGINT,
    value           DECIMAL(18,6) NOT NULL,
    labels          JSONB,
    recorded_at     TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_health_metrics_name_time
    ON supply_intelligence_health_metrics(metric_name, recorded_at DESC);
CREATE INDEX idx_health_metrics_platform
    ON supply_intelligence_health_metrics(platform, recorded_at DESC);

4.2.6 supply_intelligence_predictions

CREATE TABLE supply_intelligence_predictions (
    id              BIGSERIAL PRIMARY KEY,
    object_type     VARCHAR(20) NOT NULL  -- model / account / platform
                    CHECK (object_type IN ('model','account','platform')),
    object_id       VARCHAR(100) NOT NULL,
    prediction_type VARCHAR(20) NOT NULL  -- deprecation / failure / price_change
                    CHECK (prediction_type IN ('deprecation','failure','price_change')),
    confidence      DECIMAL(3,2) NOT NULL CHECK (confidence >= 0 AND confidence <= 1),
    predicted_at    TIMESTAMPTZ NOT NULL,
    reason          TEXT NOT NULL,
    status          VARCHAR(20) DEFAULT 'open'
                    CHECK (status IN ('open','confirmed','dismissed','expired')),
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_predictions_object ON supply_intelligence_predictions(object_type, object_id);
CREATE INDEX idx_predictions_confidence ON supply_intelligence_predictions(confidence) WHERE status = 'open';

4.3 实体关系说明

• supply_accounts（已有表）：本系统只读（探针、注册写入状态），不修改已有 schema。
• supply_packages（已有表）：准入测试通过时生成 draft 记录，运营确认后更新为 active。
• model_candidates → supply_packages：通过 package_draft_id 外键关联（可空）。
• probe_execution_logs → supply_accounts：逻辑外键，不建立物理 FK（避免已有表变更耦合）。

候选模型数据量估算（供 TechLead 参考）

假设：

• 目标供应商：10 个
• 全网模型扫描周期：每小时 1 次
• 新模型发现率：每个供应商每周平均新增 2 个 model_id
• 测试失败重试：平均每个候选模型测试 2 次才确定最终状态

则：

• 每日新增候选：10 供应商 × 2 模型 × 7 天 = 140 条
• 每月候选记录增量：约 4200 条（其中约 60% 最终变为 test_passed/test_failed，约 40% 处于 discovered/testing 状态）
• 每条记录大小：约 2KB（含 metadata 和状态）
• 30 天保留数据量：约 126KB × 30 天 ≈ 12MB（不含探针日志）

结论：30 天清理策略是合理的，但探针执行日志（每账号每天约 288 条）需单独控制。

建议：probe_execution_logs 表独立设置 30 天清理策略；model_candidates 表对 test_failed 和 ignored 状态单独设置 90 天保留。

---

5. 关键流程设计

5.1 发现 → 测试 → 准入 → 上线 → 监控 → 下线 全自动化闭环

┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│  发现    │──►│  测试    │──►│  准入    │──►│  上线    │──►│  监控    │──►│  下线    │
│ Discovery│   │ Admission│   │ Approve  │   │ Publish  │   │ Monitor  │   │ Deprecate│
└────┬─────┘   └────┬─────┘   └────┬─────┘   └────┬─────┘   └────┬─────┘   └────┬─────┘
     │              │              │              │              │              │
  每小时扫描    标准化测试用例   运营一键确认    Gateway路由    探针周期检测   下架模型告警
  生成candidate  生成draft包    或自动上架(配置)  表更新        状态自动迁移   运营人工确认

全自动模式（配置开启时）：

• test_passed → 无需人工确认，直接 draft → active（仅限白名单供应商）。
• deprecated 告警后 24 小时无运营响应 → 自动 active → paused（可配置）。

5.2 探针执行与状态变更流程

Scheduler -> ProbeService: TriggerProbe(accountID)
ProbeService -> ProbeExecutor: Execute(ctx, account)
ProbeExecutor -> SupplierAPI: Health Check Request (timeout=15s)
SupplierAPI --> ProbeExecutor: Response
ProbeExecutor -> ProbeService: ProbeResult
ProbeService -> StateMachine: EvaluateTransition(account, result)
StateMachine -> StateMachine: Check rules & version
StateMachine -> PostgreSQL: UPDATE supply_accounts SET status=?, version=version+1 WHERE version=?
PostgreSQL --> StateMachine: RowsAffected
StateMachine -> AuditEmitter: EmitStateTransitionEvent
StateMachine -> AlertNotifier: SendAlert if status degraded

乐观锁冲突处理（FP-03）：

• 若 version 不匹配，RowsAffected = 0。
• 探针记录冲突日志，放弃本次状态变更，由下次探针或运营人员覆盖。
• 不无限重试，避免活锁。

5.3 自动注册端到端流程

OpsConfig -> AutoRegService: EnableAutoReg(platform=Y, threshold=2)
AutoRegService -> AccountStore: CountActive(platform=Y)
AccountStore --> AutoRegService: count=1 (< threshold)
AutoRegService -> RegistrationTaskStore: CreateTask(register)
Scheduler -> AutoRegService: PollPendingTasks()
AutoRegService -> RegistrationAdapter: Register(ctx, req)
RegistrationAdapter -> SupplierAPI: POST /register
SupplierAPI --> RegistrationAdapter: {user_id: "..."}
RegistrationAdapter -> SMSGateway: RequestVerificationCode(phone)
SMSGateway --> RegistrationAdapter: 503 Service Unavailable
RegistrationAdapter --> AutoRegService: ErrSMSUnavailable
AutoRegService -> RegistrationTaskStore: UpdateStatus(failed, retry_count+1, next_retry_at=NOW()+24h)
AutoRegService -> AuditEmitter: Emit(auto_register_failed)
AutoRegService -> AlertNotifier: NotifyOps(注册失败)

---

6. 技术选型理由及备选方案

6.1 技术栈选型

层级	选型	理由	备选方案	不选原因
语言	Go 1.22+	与立交桥主项目一致；高并发性能好；静态编译易部署	Python	与 gateway/ supply-api 技术栈不一致，增加运维复杂度
HTTP 框架	标准库 net/http + 自定义中间件	PRD 明确约束；与 gateway/ supply-api 保持一致	Gin, Echo	PRD 禁止引入第三方框架
数据库	PostgreSQL 15+	已有基础设施；JSONB 支持灵活 schema；分区表支持日志清理	MySQL 8	已有 schema 和团队经验在 PG
驱动	jackc/pgx/v5	性能优；支持批量 Copy；与 supply-api 一致	lib/pq	维护状态差，功能不足
缓存/队列	Redis (go-redis/v9)	已有基础设施；支持 List/Stream 做轻量队列	Kafka	引入过重，当前数据量 Redis 足够
配置	YAML + Viper	支持热更新、环境变量覆盖	etcd/consul	当前规模无需外部配置中心
调度器	平台统一 Job Scheduler (Temporal/内部 Cron)	PRD 依赖假设 ASP-05；分布式定时任务可靠性高	自研 Cron	不重新造调度器
浏览器自动化	Playwright (Go 社区版)	现代浏览器支持好；供应商前端改版易适配	Selenium	API 较旧，社区活跃度下降
时序数据	Prometheus + Grafana	已有监控基础设施；与 SFI 指标天然契合	InfluxDB	增加额外存储成本

6.2 设计模式选型

模式	来源	应用场景	选型理由
Strategy（策略）	通用	探针类型、扫描器、注册适配器、路由策略	每供应商行为差异大，策略模式隔离变化
State（状态）	通用	账号状态机、candidate 状态机、注册任务状态机	状态迁移规则集中管理，避免散落的 if/else
Pipeline（管道）	通用	准入测试流水线	测试阶段可插拔，支持并行与串行组合
Circuit Breaker（熔断）	LiteLLM	供应商 API 调用	连续失败时快速失败，保护供应商侧和本系统资源
Cooldown（冷却）	LiteLLM	探针失败后的临时跳过	避免对已故障账号的无效重试
Proxy + Account 关联	Sub2API	供应商代理与账号管理	网络代理与账号解耦，支持多代理池
UsageLog + CleanupTask	Sub2API	探针日志、审计日志	定时清理过期数据，控制存储成本

---

7. 与立交桥主系统的集成点

7.1 与 Bridge Token Gateway 的集成

集成方向	接口	契约	SLA
SI → Gateway	GET /internal/supply-intelligence/accounts/health	返回账号实时状态（active/suspended/disabled），JSON 数组	P99 < 50ms，可用性 ≥ 99.9%
SI → Gateway	GET /internal/supply-intelligence/packages/active	返回平台当前 active 的 supply_packages 列表（含模型元数据）	P99 < 100ms
Gateway → SI	WebHook POST /internal/supply-intelligence/events/routing-failure	Gateway 路由失败时上报，SI 用于辅助风险评分	异步，容忍延迟 < 5s

Gateway 路由决策流程（边缘场景 B3）：

1. Gateway 收到用户请求，需要选择供应商账号。
2. Gateway 查询本地缓存（Redis）中的账号状态，缓存 TTL = 30 秒。
3. 缓存 miss 或过期时，调用 SI 健康查询接口。
4. 若账号为 suspended 或 disabled，从候选池移除。

7.2 与 Channel Manager（supply-api）的集成

集成方向	接口	契约	说明
SI → supply-api	AccountStore.GetByID / AccountStore.List	读取 supply_accounts 记录	只读，不修改已有表
SI → supply-api	PackageStore.CreateDraft / PackageStore.UpdateStatus	创建/更新 supply_packages	通过 supply-api 内部接口，不直接写表
SI → supply-api	AuditStore.Emit	审计事件写入	复用 supply-api 审计基础设施
SI → supply-api	VerifyService.Verify	新注册账号验证	自动注册成功后调用已有验证流程
supply-api → SI	IntegrationPlugin.Register(mux)	集成运行时挂载 Handler	编译时依赖，运行时开关控制

7.3 与 NewAPI / Sub2API 的集成

集成方向	接口	契约
SI → NewAPI/Sub2API	POST /v1/suppliers/status	推送供应商健康状态
SI → NewAPI/Sub2API	POST /v1/models/sync	推送新发现的模型列表
NewAPI/Sub2API → SI	GET /api/v1/supply-intelligence/models	查询平台模型库
NewAPI/Sub2API → SI	GET /api/v1/supply-intelligence/pricing	查询定价数据库

适配层设计：

• NewAPIAdapter 和 Sub2APIAdapter 实现统一 ExternalPlatformAdapter 接口。
• 鉴权：API Key + HMAC-SHA256 签名，密钥通过 KMS 管理。
• 独立部署时，适配器通过配置文件中的 external_platforms 数组启用。

---

8. 安全设计

8.1 账号安全

措施	实现
凭证加密	所有 API Key 经 KMS 加密后存储，supply_accounts.credential 字段为密文。KMS 不可用时，明文不落盘（FP-10）。
凭证指纹	credential_fingerprint 存储 SHA256 哈希，用于快速比对和审计追踪，不存明文。
最小权限	探针账号、测试账号、注册账号分离，测试账号仅有最低 API 调用权限。
轮换提醒	密钥有效期 < 30 天时， health board 显示黄色警告；< 7 天时红色警告。

8.2 测试隔离

• 准入测试网络隔离：测试流量走独立出口 IP 池（如有），或至少使用独立账号。
• 测试数据隔离：测试请求添加标识头部，供应商侧可识别。
• 资源限制：单测试任务 CPU 限制 1 core，内存 512MB，超时 60 秒/用例。

8.3 数据同步一致性

• 最终一致性：探针状态变更到 Gateway 感知，最大延迟 = 探针周期(5min) + 缓存 TTL(30s) + 网络延迟 < 6 分钟。
• 审计一致性：所有状态变更先写审计日志，再写业务表，同一事务内完成。
• 跨服务一致性：SI 与 supply-api 之间的操作通过内部接口 + 乐观锁保证，无分布式事务（2PC），失败时人工介入。

8.4 访问控制

资源	操作	所需权限
探针配置	查看/修改	supply:intelligence:config:read/write
账号状态	手动变更	supply:ops:account:manage
模型上架	确认/强制上架	supply:ops:publish / supply:ops:force_publish
自动注册	启用/禁用	supply:intelligence:autoreg:admin
审计日志	查询	supply:audit:read

---

9. 性能考量

9.1 数据量估算

指标	Phase 1	Phase 2	Phase 3
供应商数量	10	20	30
账号总数	100	300	500
模型候选数/月	0	50	100
探针日志/天	28,800 (100×288)	86,400	144,000
探针日志/月	~86万	~260万	~430万

9.2 扫描并发

• 探针并发：Worker Pool = 50，每账号 15 秒超时，理论最大吞吐量 = 50 × (60/15) × 60 = 12,000 次/小时。
• 实际负载：500 账号 × 每 5 分钟 = 6,000 次/小时，池大小充足。
• 扫描并发：每供应商串行扫描，供应商间并行，最大并发 = 供应商数（≤ 30），对平台出口带宽要求低。

9.3 测试队列

• 队列实现：Redis List + 消费者 Worker。
• 最大并行测试数：10（可配置），避免对供应商测试账号的过度并发。
• 队列深度告警：discovered 状态堆积 > 20 个且持续 24 小时触发 P2 告警（AC-05 关联）。

9.4 数据库性能

• 探针日志表：按 executed_at 月分区，查询最近 30 天数据走分区裁剪。
• 索引策略：所有查询字段均有索引，无全表扫描查询。
• 连接池：独立运行时池大小 = 20（max_open），集成运行时共享 supply-api 连接池。

9.5 缓存策略

数据	缓存位置	TTL	更新触发
账号状态	Redis	30 秒	探针状态变更时失效
供应商模型列表	Redis	30 分钟	扫描任务完成时写入
定价数据库	本地内存 + Redis	1 小时	远程拉取成功时更新
健康大盘	Redis + 前端缓存	5 分钟	定时聚合任务写入

---

10. 风险评估与缓解策略

10.1 技术风险

风险编号	风险描述	概率	影响	缓解措施
R-01	探针频率过高导致供应商封禁平台 IP	中	高	1. 频率可配置（默认 5 分钟）；2. 使用平台统一出口 IP 池；3. 遵守供应商 Rate Limit；4. 每家供应商独立限流器（令牌桶，rate=10/min）
R-02	供应商模型列表返回缓存旧数据，导致下架误判	中	中	1. 列表响应加 TTL 校验；2. 结合官方文档 RSS 交叉验证；3. 不自动下架，只生成告警
R-03	浏览器自动化因供应商前端改版失效	高	中	1. 优先官方 API；2. Playwright 流程版本化；3. 前端改版监控（DOM 签名校验）；4. 失效时自动降级为人工注册
R-04	准入测试用例不足，test_passed 但上线后用户报错	中	高	1. QA 维护并定期评审用例；2. 上线后 24h 内对新模型增加采样监控（Gateway 侧）；3. 运营可一键回退
R-05	model_candidates 表数据膨胀	低	中	1. test_failed 超过 30 天自动清理；2. ignored 超过 7 天自动恢复或清理；3. 按 discovered_at 分区
R-06	本系统故障导致状态误标记	低	极高	1. 灰度三阶段上线；2. 回滚条件：1h 内误报率 > 5% 立即关闭自动变更；3. 生产环境首次只告警不改状态（Phase 2）
R-07	调度器（Temporal/内部 Cron）不可用	低	中	1. 调度失败时探针/扫描延迟，不引入错误状态；2. 独立运行时内置 fallback 本地 cron（最小功能）

10.2 合规风险

风险	缓解
自动注册收集个人信息（邮箱/手机）	符合平台隐私政策；数据最小化原则；注册完成后脱敏存储；90 天审计日志保留
审计日志泄露凭证	审计日志中的请求/响应摘要经 Sanitizer 脱敏；API Key 只存指纹；完整请求体不写入日志
跨供应商数据聚合的法律风险	定价数据为公开信息；模型列表为公开信息；不涉及用户隐私数据跨境

10.3 威胁建模

威胁场景	攻击/故障路径	影响	控制措施	验证要求
凭证明文泄露	注册/探针流程在日志、DB、内存 dump 中输出明文凭证	供应商账号被接管	KMS 加密、日志脱敏、指纹比对替代明文、KMS 不可用 fail-closed	安全测试必须覆盖日志/DB/异常路径无明文
自动注册滥用	注册模块被批量滥用触发垃圾注册或封号	供应商封禁、资产损失	频控、验证码、审批开关、人工兜底、账号生命周期审计	并发重复注册与风控场景必须稳定阻断
错误状态传播	Probe/Admission 误判后将错误状态同步给 gateway 或外部系统	错误下架/错误上架，影响真实流量	三阶段灰度、人工确认、状态机乐观锁、告警不直接改状态	首次生产阶段只告警不自动变更状态
外部适配接口越权	NewAPI/Sub2API 拉取超出授权的数据或触发敏感操作	数据泄露、越权控制	最小字段暴露、鉴权、幂等、只读/读写接口分离、审计	合同测试覆盖字段边界、鉴权失败、重放请求
调度器或浏览器自动化失效	Scheduler/Playwright 失效导致发现/注册链路静默坏掉	模型发现停滞、注册失败积压	健康告警、fallback 本地 cron、人工接管、失败队列可见	必须验证故障时不会静默标记成功

10.4 设计阶段门控结论

结论：REQUEST_CHANGES（补齐威胁与阻断门禁后，方可进入开发）

放行前必须满足：

• 探针、发现、准入、注册、运营干预五条主链路都要提供真实实现落点和后续测试阻断项。
• 凭证保护、状态同步、自动注册、外部适配四类高风险点必须在测试设计中有独立安全/异常回归用例。
• 独立运行 / 集成运行 / IntegrationPlugin / OpenAPI / 适配层要求必须进入统一验收矩阵。
• 对首次生产放量场景必须明确“只告警不自动变更”的保护边界和撤销条件。

阻断条件：

• 凭证保护不能证明 fail-closed。
• 状态机迁移与审计写入无法形成同事务或等价可追踪闭环。
• 无法证明集成模式中的路由、worker、内部接口全部真实挂载。

---

11. 可重用的设计模式

11.1 模块内复用

模式	应用位置	说明
Adapter 模式	供应商扫描器、注册适配器、外部平台适配器	统一接口隔离供应商差异
Pipeline 模式	准入测试、注册流程	阶段可配置、可观测、可回滚
Worker Pool 模式	探针执行、测试执行	控制并发、支持背压
Outbox 模式	审计事件发射	本地事务写 outbox 表，异步消费保证最终一致性
Circuit Breaker + Cooldown	供应商 API 调用	连续失败时进入冷却期，保护双方

11.2 跨项目复用

模式	来源	本系统应用	可被复用到
IntegrationPlugin	本系统设计	集成运行时挂载到 supply-api	gateway/ 等其他需要插件化集成的模块
PricingDB + Fallback	LiteLLM/Sub2API	模型定价数据库与回退算法	任何需要模型成本计算的模块（如 billing-engine）
Risk Score Model	本系统设计	账号风险评分	用户侧风控、支付风控
State Machine with Optimistic Lock	supply-api	账号状态迁移	任何需要状态机的业务（结算、订单）

---

12. 技术栈与集成约束

12.1 统一技术栈

本项目必须与立交桥主项目保持一致：

• 语言: Go 1.22+
• HTTP框架: 标准库 net/http + 自定义中间件（禁止引入 Gin/Echo 等第三方框架，保持与 gateway/ 和 supply-api/ 的一致性）
• 数据库: PostgreSQL 15+ ，驱动 jackc/pgx/v5
• 缓存: Redis，客户端 redis/go-redis/v9
• 配置: YAML + Viper，环境变量覆盖敏感字段
• 日志/审计: 结构化日志，审计事件模型与 supply-api/ 一致
• 错误码: {SOURCE}_{CATEGORY}_{CODE} 格式，例如 SUP_INT_4001
• 健康检查: /actuator/health 、 /actuator/health/live 、 /actuator/health/ready
• 测试: Go testing + testify，覆盖率门槛 domain ≥ 70%、service/handler ≥ 80%

12.2 独立运行与集成运行

本系统必须同时支持两种运行模式：

模式	特征	部署方式	适用场景
独立运行	自有 cmd/supply-intelligence/main.go，独立数据库 schema，独立 docker-compose	docker-compose up 或单独容器	外部用户只需要供应链管理能力，不想接入立交桥全套
集成运行	作为 Go module 被 supply-api/ 引入，共享数据库连接池和配置，通过内部接口注册	编译时作为子模块编译，运行时挂载到 supply-api 主进程	立交桥用户希望获得一体化供应链能力

集成约束:

• 独立运行时，系统必须提供完整的 HTTP API 和运营工作台。
• 集成运行时，系统必须提供 IntegrationPlugin 接口，允许主程序通过配置开关启用/禁用各模块。
• 数据库 schema 必须使用独立的 supply_intelligence_ 前缀，避免与主项目表名冲突。
• 配置文件必须支持分离加载：独立运行时读取自己的 config.yaml，集成运行时合并到主项目配置。

12.3 NewAPI / Sub2API 适配支持

本系统的核心能力必须能够对接 NewAPI 和 Sub2API 系统：

• 供应商状态同步: 提供标准化的供应商健康状态接口，NewAPI/Sub2API 可定期获取供应商可用性状态。
• 模型列表推送: 提供 /models 接口返回平台已发现、已测试通过的模型列表，NewAPI/Sub2API 可消费此数据自动补充自己的模型库。
• 账号注册适配: 自动注册模块通过适配层支持 NewAPI/Sub2API 的账号管理 API，实现跨平台账号生命周期管理。
• 独立部署时: 通过配置文件指定 NewAPI/Sub2API 的管理端点地址和鉴权信息，本系统通过适配层（Adapter）与之交互。
• 集成部署时: 若立交桥 gateway/ 已接入 NewAPI/Sub2API，本系统通过 supply-api/ 的内部接口操作上游状态。

12.4 对外接口契约

• 必须提供 OpenAPI 3.0 接口文档，确保 NewAPI/Sub2API 开发者可以独立接入。
• 接口路径前缀默认为 /api/v1/supply-intelligence/，集成运行时可通过配置改为 /internal/supply-intelligence/。

---

13. 变更日志

版本	日期	变更内容	作者
v1.0	2026-04-27	初始版本：系统架构、模块设计、数据模型、流程设计、技术选型、集成点、安全、性能、风险	TechLead

---

附录 A：术语表

术语	说明
SI	Supply-Intelligence，本系统
SFI	Supply Freshness Index，供应链接新鲜度指数
Candidate	候选模型（model_candidates 记录）
Probe	品质探针，检测供应商账号健康状态
Admission Test	准入测试，验证新模型是否符合平台标准
Fail-Closed	依赖条件不满足时显式关闭功能，不静默降级
KMS	Key Management Service，密钥管理服务

附录 B：参考文档

1. PRD.md — 产品需求文档
2. competitor-analysis.md — 竞品分析报告
3. INTERFACE.md — 核心接口设计
4. DEPLOYMENT.md — 部署设计
5. supply-api/CLAUDE.md — supply-api 项目规范

---

附录 Y：参考文档与外部依赖

参考项目	版本/日期	URL	用途
LiteLLM	v1.40.0 (2026-03)	https://docs.litellm.ai/	模型接口标准化、健康检查设计
Sub2API	main分支 (2026-04)	https://github.com/WeI-Shaw/sub2api	公告系统、用户体系参考
Intercom	-	https://www.intercom.com/	客服体验对标
Prometheus	3.x (2026-Q1)	https://prometheus.io/	时序数据存储
VictoriaMetrics	1.100.x (2026-Q1)	https://victoriametrics.com/	时序数据备选存储
Playwright	1.50.x (2026-Q1)	https://playwright.dev/	浏览器自动化
Qdrant	1.12.x (2026-Q1)	https://qdrant.tech/	向量数据库备选
PGVector	0.8.x (2026-Q1)	https://github.com/pgvector/pgvector	PostgreSQL向量扩展

注：以上版本号为评审时（2026-04-28）的最新稳定版，随着项目开发应定期更新。