# Metadata API Contract Compatibility Report

Last updated: 2026-03-21

## Scope

This report tracks the Metadata API subset under [`tests/contract/metadata_api`](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/metadata_api). Compatibility status is updated only from three pieces of evidence together:

- official Salesforce documentation indexed in [`catalog.yaml`](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/metadata_api/catalog.yaml)
- the live contract test case that exercises the endpoint
- the latest local backend run result

Current catalog scope:

- `2` tracked endpoints
- `0` rows with `doc: todo`

## This Run

- Re-read the current Metadata API artifacts: [`catalog.yaml`](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/metadata_api/catalog.yaml), all live tests under [`tests/contract/metadata_api`](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/metadata_api), and this report.
- Revalidated the local backend health at `http://127.0.0.1:3001/health` as `{"db":"connected","server":"golang","status":"ok"}` before the live run.
- Ran compile-only validation with `cd /Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract && go test ./metadata_api/... -run '^$'`, which passed.
- Ran the local live suite with `cd /Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract && CONTRACT_TARGET=local go test ./metadata_api/... -count=1`, which failed in `metadata_api/deployment`.
- Route audit against [`backend/cmd/server/routes.go`](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/backend/cmd/server/routes.go) confirms that both cataloged endpoints are mounted locally under `/metadata`.
- Current local split: `1` `🟢` and `1` `🔴`.

## Compatibility Legend

- `🚫` 明确未实现
- `⭕` 无测试覆盖（无法验证）
- `🔴` 不兼容：已实现，但经测试发现无法工作，或者存在严重的功能/schema错误
- `🟡` 部分兼容：已实现，可以工作，但是经测试发现存在偏差
- `🟢` 完全兼容，行为与官方文档一致

## Local Backend Compatibility Assessment

| Endpoint | Method + Path | 兼容性 | Reason |
| --- | --- | ---: | --- |
| Deploy Request | `POST /services/data/v63.0/metadata/deployRequest` | 🟢 | Test: [`deployment/post_deploy_request_test.go`](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/metadata_api/deployment/post_deploy_request_test.go); the live negative cases for missing file and invalid zip payload passed, and the backend returns Salesforce-style error payloads for this endpoint. |
| Get Deploy Status | `GET /services/data/v63.0/metadata/deployRequest/{deployRequestId}` | 🔴 | Test: [`deployment/get_deploy_status_test.go`](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/metadata_api/deployment/get_deploy_status_test.go); the not-found case fails locally because [`metadata_deploy_handler.go`](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/backend/internal/interfaces/rest/metadata_deploy_handler.go) returns HTTP `500` when the stored deploy result is missing instead of a not-found response. |

## Compatibility State Changes

- `POST /services/data/v63.0/metadata/deployRequest` remains `🟢` after the latest local run.
- `GET /services/data/v63.0/metadata/deployRequest/{deployRequestId}` is now confirmed `🔴` in the local backend because the not-found path returns `500`.
- The service remains intentionally narrow: the current catalog only tracks the two deploy-related endpoints.

## Remaining Gaps

- There are no remaining `doc: todo` rows in the current Metadata API catalog scope.
- The deploy-status handler still needs not-found handling that matches the documented contract.

## Verification

```bash
cd /Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract
go test ./metadata_api/... -run '^$'
CONTRACT_TARGET=local go test ./metadata_api/... -count=1
CONTRACT_TARGET=local go test ./metadata_api/deployment -run TestPostDeployRequest -count=1 -v
CONTRACT_TARGET=local go test ./metadata_api/deployment -run TestGetDeployStatus_NotFound -count=1 -v
```