# contract/join_meeting.v1.yaml
interface: JoinMeeting
version: "1.2.0"
provider: "RTC_SDK"
consumer: "App_Meeting_Module"
method:
  name: join
  params:
    - name: token
      type: string
      required: true
      pattern: "^[A-Za-z0-9-_=]+.[A-Za-z0-9-_=]+.?[A-Za-z0-9-_.+/=]*$"  # JWT格式约束
    - name: roomId
      type: string
      required: true
      maxLength: 64
    - name: options
      type: object
      properties:
        audioEnabled:
          type: boolean
          default: true
        videoEnabled:
          type: boolean
          default: true
        videoProfile:
          type: string
          enum: ["180p", "360p", "720p", "1080p"]
  returns:
    type: object
    properties:
      code:
        type: integer
        enum: [0, 1001, 1002, 2001, 2002]  # 明确错误码集合
      message:
        type: string
      meetingId:
        type: string
  callbacks:
    - name: onMeetingStateChanged
      params:
        - name: state
          type: string
          enum: ["IDLE", "CONNECTING", "CONNECTED", "RECONNECTING", "DISCONNECTED"]
        - name: reason
          type: integer

# tests/contract/test_join_meeting.py
import pact
from meeting_sdk_adapter import MeetingAdapter

def test_join_meeting_contract_generation():
    # 1. 启动Mock Provider（模拟SDK行为）
    mock_provider = pact.MockProvider("RTC_SDK", port=12345)
    
    # 2. 定义预期交互
    (mock_provider
     .given("有效的会议Token和房间号")
     .upon_receiving("发起入会请求")
     .with_request("POST", "/rtc/v1/join", body={
         "token": pact.Like("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."),
         "roomId": pact.Like("room_12345"),
         "options": {"audioEnabled": True, "videoProfile": "720p"}
     })
     .will_respond_with(200, body={
         "code": 0,
         "meetingId": pact.Like("meeting_abcde"),
         "message": "success"
     }))

    # 3. 执行真实Consumer代码
    adapter = MeetingAdapter(sdk_base_url="http://localhost:12345")
    result = adapter.join_meeting(token="valid_token", room_id="room_12345")
    
    # 4. 断言并自动生成契约文件
    assert result.code == 0
    mock_provider.verify()  # 生成 join_meeting.json 至 contracts/consumer/

// sdk-provider-test/src/test/java/contract/JoinMeetingContractTest.java
@Provider("RTC_SDK")
@PactBroker(url = "${pact.broker.url}", authentication = @PactBrokerAuth(token = "${pact.token}"))
@State("有效的会议Token和房间号")  // 对应Consumer given()
public void validTokenAndRoom() {
    // 1. 初始化测试环境：启动内存Signal Server、Mock媒体引擎
    TestEnvironment.setup();
    
    // 2. 预置数据：生成有效Token、创建房间元数据
    String token = TokenGenerator.generateValidToken("user_001", "room_12345");
    RoomManager.createRoom("room_12345", RoomConfig.defaultConfig());
    
    // 3. 注入SDK上下文（关键：避免污染全局单例）
    SDKContext.injectTestContext(new TestSDKContext(token, "room_12345"));
}

@TestTemplate
@ExtendWith(PactVerificationInvocationContextProvider.class)
void verifyJoinMeetingContract(PactVerificationContext context) {
    // 启用请求过滤器：剔除动态字段（timestamp、nonce、deviceId等）
    context.setRequestFilter(request -> {
        request.getBody().remove("requestId");
        request.getHeaders().remove("X-Client-Trace-Id");
        return request;
    });
    context.verifyInteraction();
}

┌─────────────────────────────────────────────────────────────┐
│ 兼容性矩阵自动化检查流程                                      │
├─────────────────────────────────────────────────────────────┤
│ 1. 拉取所有活跃Consumer契约（按branch/tag过滤）               │
│ 2. 对每个契约执行Provider验证                                 │
│ 3. 统计结果：                                                 │
│    - PASS: 契约完全兼容                                       │
│    - WARN: 存在Deprecated字段使用，建议Consumer升级           │
│    - FAIL: Breaking Change（参数必填变更、错误码删除等）      │
│ 4. FAIL时阻断发版流水线，输出差异报告至PR/IM                  │
└─────────────────────────────────────────────────────────────┘

# 事件契约定义
events:
  - name: onNetworkQualityChanged
    direction: provider->consumer
    payload:
      userId: string
      uplinkQuality:
        type: string
        enum: ["excellent", "good", "poor", "bad", "down"]
      downlinkQuality:
        type: string
        enum: ["excellent", "good", "poor", "bad", "down"]
    timing:
      frequency: "每2秒上报一次"
      trigger: "网络抖动/带宽变化时立即上报"

// sdk/media_capability_snapshot_test.go
func TestMediaCapabilitySnapshot(t *testing.T) {
    // 1. 获取当前SDK支持的编码能力
    caps := sdk.GetMediaCapabilities()
    
    // 2. 读取基线快照（随SDK版本发布）
    baseline := loadSnapshot("media_caps_v3.2.0.json")
    
    // 3. 语义化比对：允许新增Codec，禁止删除/修改现有档位参数
    diff := compareCapabilities(baseline, caps, CompareOptions{
        AllowNewCodecs: true,
        AllowNewProfiles: true,
        ForbidRemove: true,
        ForbidModifyParams: []string{"maxBitrate", "maxFramerate", "scalabilityMode"},
    })
    
    if diff.HasBreakingChange() {
        t.Errorf("媒体能力契约破坏: %s", diff.String())
    }
    // 4. 自动更新快照（仅允许在Major版本发布时手动确认）
    if os.Getenv("UPDATE_SNAPSHOT") == "true" {
        saveSnapshot(caps, "media_caps_v3.2.0.json")
    }
}

graph LR
    A[SDK代码提交] --> B{Provider侧契约验证}
    C[Consumer代码提交] --> D{Consumer侧契约生成}
    B -->|PASS| E[发布SDK Artifact + 契约包]
    D -->|PASS| F[发布Consumer契约至Broker]
    E --> G[兼容性矩阵夜ly扫描]
    F --> G
    G -->|全绿| H[允许发版/合并]
    G -->|红/黄| I[阻断/告警 + 差异报告]

# 契约元数据模型设计 (registry/api/v1/contract.proto)
message ContractArtifact {
  string id = 1;                    // UUID
  string provider = 2;              // "RTC_Core_SDK"
  string consumer = 3;              // "App_Meeting_iOS"
  ContractType type = 4;            // ABI / PROTO / SWIFT_INTERFACE / JVM_BYTECODE / EVENT_STREAM
  string version = 5;               // 语义化版本 3.2.1
  string git_commit = 6;            // 来源代码提交SHA
  map<string, string> labels = 7;   // {platform: "ios", arch: "arm64", build_type: "release"}
  bytes content = 8;                // 契约内容 (JSON/Protobuf/ABI Dump)
  VerificationStatus status = 9;    // VERIFIED / DEPRECATED / BROKEN
  int64 created_at = 10;
  int64 verified_at = 11;
}

// rtc_sdk/runtime_contract_guard.h (C++ 核心层头文件)
namespace rtc {
namespace guard {

// 契约规则定义（随SDK发布，嵌入二进制或随配置下发）
struct ContractRule {
    std::string interface_name;       // "IRtcEngine::joinChannel"
    uint32_t min_sdk_version;         // 0x030200 (v3.2.0)
    uint32_t max_sdk_version;         // 0x0302FF (v3.2.x)
    std::vector<ParamRule> params;    // 参数约束规则
    std::vector<CallbackRule> callbacks; // 回调时序约束
    bool enable_strict_mode = false;  // 严格模式：违规即Crash/上报
};

// 运行时拦截入口（通过Hook/Wrapper/代理模式注入）
class ContractGuard {
public:
    // 初始化：加载本地嵌入规则 + 拉取远程动态规则
    static bool Initialize(const GuardConfig& config);
    
    // 拦截点：所有对外导出接口统一入口
    template<typename Ret, typename... Args>
    static Ret Intercept(const char* func_name, Ret(*origin_func)(Args...), Args... args) {
        if (!enabled_) return origin_func(args...);
        
        // 1. 参数契约校验
        auto violation = ValidateParams(func_name, args...);
        if (violation) HandleViolation(violation, func_name);
        
        // 2. 执行原函数
        Ret result = origin_func(args...);
        
        // 3. 返回值/异步回调契约校验
        ValidateReturn(func_name, result);
        RegisterCallbackGuards(func_name, result); // 包装回调对象
        
        return result;
    }

private:
    static std::atomic<bool> enabled_;
    static std::unordered_map<std::string, ContractRule> rule_cache_;
};

} // namespace guard
} // namespace rtc

-- nginx/kong plugin: rtc_contract_gateway.lua
local cjson = require "cjson.safe"
local schema = require "contract.join_meeting_v1_schema" -- 编译期嵌入

function validate_request(body)
    local ok, err = schema:validate(body)
    if not ok then
        ngx.log(ngx.ERR, "Contract Violation: ", err, " Body: ", cjson.encode(body))
        -- 策略：记录审计日志 + 返回标准错误码(4001) + 标记灰度标签
        ngx.var.contract_violation = "true"
        return false, {code=4001, message="Invalid request contract"}
    end
    return true
end

-- 响应拦截：校验下行推送结构
function validate_response(body)
    -- 校验服务端推送的 onUserList 字段是否符合最新契约
    return schema:validate_response(body)
end

sequenceDiagram
    participant Consumer as 业务方
    participant Registry as 契约注册中心
    participant Provider as SDK团队
    Consumer->>Registry: 提交契约变更需求 (Issue/PR)
    Registry->>Provider: 自动通知 @SDK-Owner
    Provider->>Registry: 评估影响范围 (矩阵分析)
    Provider-->>Consumer: 反馈方案/时间线/替代方案
    alt 达成一致
        Provider->>Provider: 实现 + 生成新契约
        Provider->>Registry: 发布候选契约
        Consumer->>Consumer: 适配验证 (Canary)
        Consumer->>Registry: 确认验证通过
        Registry->>Registry: 标记契约 GENERALLY_AVAILABLE
    else 分歧
        Registry->>Architect: 升级至架构委员会裁决
    end

# CI Job: generate_docs.sh
# 1. 拉取最新契约
buf export registry.internal/contracts/rtc-sdk:v3.2.1 -o /tmp/contracts

# 2. 多格式渲染
# Markdown (给开发看)
protoc --doc_out=markdown,rtc_sdk_v3.2.1.md:/tmp/contracts
# HTML Portal (给QA/产品看)
redocly build-docs /tmp/contracts/openapi.yaml -o /var/www/docs/rtc-sdk/v3.2.1/
# Postman Collection (给联调用)
openapi2postmanv2 -s /tmp/contracts/openapi.yaml -o /tmp/rtc_sdk.postman_collection.json

# 3. 发布制品
aws s3 sync /var/www/docs/ s3://docs.rtc.internal/ --cache-control max-age=3600

# k8s deployment: traffic-mirror-sidecar
apiVersion: apps/v1
kind: Deployment
metadata:
  name: meeting-app-canary
spec:
  template:
    spec:
      containers:
      - name: app
        image: meeting-app:v2.1.0
      - name: traffic-mirror
        image: rtc-contract/mirror-agent:v1
        env:
        - name: MIRROR_TARGET # 目标SDK接口命名空间
          value: "com.company.rtc.sdk.IRtcEngine"
        - name: OUTPUT_TOPIC
          value: "kafka://contract-topic/raw-interactions"
        - name: SAMPLING_RATE
          value: "0.01" # 1%采样
        - name: SCRUB_RULES # 脱敏规则
          value: "token,deviceId,userId,ip"

# tools/infer_contract_from_traffic.py
import json
from collections import defaultdict
from contract_infer import TypeInferencer, SchemaGeneralizer

def build_baseline(kafka_topic, output_dir, sdk_version):
    inferencer = TypeInferencer()
    call_stats = defaultdict(int)
    
    for msg in consume_kafka(kafka_topic, max_records=100000):
        # 1. 结构化解析调用链
        call = parse_invocation(msg)  # {method, args, ret, callbacks, latency, error}
        call_stats[call.method] += 1
        
        # 2. 类型推断与泛化
        schema = inferencer.infer(call)
        SchemaGeneralizer.generalize(schema) # 具体值 -> 类型/约束/枚举
        
        # 3. 语义聚类：识别同一接口的不同调用模式
        inferencer.cluster_patterns(call.method, schema)
    
    # 4. 生成基线契约 (仅保留高频调用 Top 95%)
    for method, patterns in inferencer.patterns.items():
        if call_stats[method] / sum(call_stats.values()) > 0.001: # 过滤噪音
            contract = patterns.merge_to_contract()
            contract.metadata.source = "TRAFFIC_INFERENCE"
            contract.metadata.confidence = calculate_confidence(patterns)
            save_contract(f"{output_dir}/{sdk_version}/{method}.yaml", contract)

# 产出：contracts/v3.1.0/joinChannel.yaml (置信度 0.98)

# contracts/non_functional/performance_v3.2.yaml
performance_contract:
  join_meeting:
    p50_latency_ms: 800      # 入会信令耗时 P50
    p99_latency_ms: 2000     # 入会信令耗时 P99
    first_frame_ms: 1500     # 首帧渲染耗时
    cpu_overhead_percent: 5  # 空闲状态CPU占用上限
    memory_mb: 80            # 进程增量内存上限
    battery_drain_ma: 50     # 单位小时耗电量
  network_adaptation:
    bandwidth_estimation_error: "< 15%" # 带宽估计误差
    fec_redundancy_ratio: "10%-20%"     # FEC冗余比范围

# contracts/compliance/security_privacy_v3.2.yaml
security_contract:
  # 数据流向契约
  data_flows:
    - from: "Microphone"
      to: "Encoder -> Network"
      encryption: "AES-256-GCM (DTLS-SRTP)"
      pii: false
      retention: "session_only"
    - from: "Camera"
      to: "Encoder -> Network"
      encryption: "AES-256-GCM (DTLS-SRTP)"
      pii: true # 人脸生物特征
      retention: "session_only"
      consent_required: true
  
  # 接口安全约束
  api_constraints:
    - interface: "setLogFile"
      forbidden_params: ["absolute_path"] # 禁止任意路径写入
      sandbox_enforced: true
    - interface: "startAudioRecording"
      requires_permission: "RECORD_AUDIO"
      privacy_manifest: "NSMicrophoneUsageDescription"
  
  # 依赖供应链契约
  dependencies:
    - name: "openssl"
      min_version: "3.0.12" # 修复CVE-2023-xxxx
      license: "Apache-2.0"
    - name: "ffmpeg"
      config_flags: ["--disable-everything", "--enable-decoder=h264,opus"] # 最小攻击面