# Analytics API Contract Compatibility Report

Last updated: 2026-03-21

## Scope

This report tracks the Analytics API contract suite under [`/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/analytics_api`](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/analytics_api).

The catalog currently contains 27 endpoint rows across reports, dashboards, and folders. Eight rows still carry `coverage: todo`, and the remaining rows have live contract coverage in the test suite. The legacy `/wave` CRM Analytics surface is out of scope.

## This Run

- Re-read [`/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/AGENTS.md`](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/AGENTS.md), [`/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/analytics_api/catalog.yaml`](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/analytics_api/catalog.yaml), this report, and all analytics API test files.
- Verified the already-running local backend at `http://127.0.0.1:3001/health`.
- Ran compile-only verification for the full `analytics_api` package tree.
- Ran the live contract suite against `CONTRACT_TARGET=local`.
- The live run passed the package root wrapper and `reports` list/validation coverage, but failed in `dashboards`, `folders`, and the report lifecycle setup.

## Compatibility Legend

- `🚫`: explicitly not implemented.
- `⭕`: no test coverage, so it cannot be verified yet.
- `🔴`: implemented but incompatible, unusable, or seriously wrong in behavior or schema.
- `🟡`: implemented and usable, but with tested behavioral or schema deviations.
- `🟢`: fully compatible with the official documented behavior.

## Local Backend Compatibility Assessment

| Area | Endpoint(s) | Compatibility | Evidence |
| --- | --- | --- | --- |
| Reports | `GET /services/data/v63.0/analytics/reports` | `🟢` | [get_reports_test.go](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/analytics_api/reports/get_reports_test.go) passed for both the default list and `?limit=1` variants. |
| Reports | `POST /services/data/v63.0/analytics/reports` | `🟢` | Validation cases in [report_lifecycle_test.go](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/analytics_api/reports/report_lifecycle_test.go) passed for missing envelope, missing `name`, missing `reportType`, and malformed `reportType`. |
| Reports | `GET/POST/PATCH/DELETE /services/data/v63.0/analytics/reports/{reportId}` and `GET /services/data/v63.0/analytics/reports/{reportId}/describe` | `⭕` | The lifecycle suite stops in seed selection: [`PickReportID`](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/analytics_api/internal/arrange/helpers.go) could not decode `/analytics/reports?limit=1` into the expected report-list shape, so the happy-path lifecycle was not fully re-verified in this run. |
| Dashboards | `GET /services/data/v63.0/analytics/dashboards` | `🟢` | [get_dashboards_test.go](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/analytics_api/dashboards/get_dashboards_test.go) passed. |
| Dashboards | `POST /services/data/v63.0/analytics/dashboards`, `GET/PATCH/PUT/DELETE /services/data/v63.0/analytics/dashboards/{dashboardId}`, `POST /services/data/v63.0/analytics/dashboards/{dashboardId}/refresh`, `GET /services/data/v63.0/analytics/dashboards/{dashboardId}/status` | `🟡` | [dashboard_lifecycle_test.go](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/analytics_api/dashboards/dashboard_lifecycle_test.go) and [dashboard_mutations_test.go](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/analytics_api/dashboards/dashboard_mutations_test.go) show working create/get/delete/refresh paths, but PATCH save returns `400` instead of `200`, and not-found semantics diverge for PATCH, DELETE, and status. |
| Folders | `GET /services/data/v63.0/folders` | `🟢` | [get_folders_test.go](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/analytics_api/folders/get_folders_test.go) passed for the default and paginated list variants. |
| Folders | `POST /services/data/v63.0/folders` | `🟡` | [folder_crud_test.go](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/analytics_api/folders/folder_crud_test.go) creates folders successfully, but missing `label` and missing `type` are accepted instead of rejected. |
| Folders | `GET /services/data/v63.0/folders/{id}` | `🟢` | [folder_crud_test.go](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/analytics_api/folders/folder_crud_test.go) passed for the created folder detail path. |
| Folders | `PATCH /services/data/v63.0/folders/{id}` | `🔴` | The update path returns `400` where the contract test expects `200`, and not-found handling diverges from the documented Salesforce-style error path. |
| Folders | `DELETE /services/data/v63.0/folders/{id}`, `GET/POST/PUT /services/data/v63.0/folders/{id}/shares`, `GET /services/data/v63.0/folders/{id}/children` | `⭕` | These endpoints remain cataloged but were not fully closed out by a passing live verification in this run. |

## Compatibility State Changes

- `GET /services/data/v63.0/analytics/reports` is confirmed `🟢` in the local backend.
- `POST /services/data/v63.0/analytics/reports` validation coverage is confirmed `🟢`.
- `GET /services/data/v63.0/analytics/dashboards` remains `🟢`, but the dashboard mutation surface stays `🟡` because save and not-found behavior still drift.
- `GET /services/data/v63.0/folders` and `GET /services/data/v63.0/folders/{id}` remain `🟢`, while folder create/update paths are split between `🟡` and `🔴` because validation and PATCH semantics still diverge.
- The report lifecycle path remains `⭕` because the seed-report setup could not be closed out from the local list response shape in this run.

## Remaining Gaps

- The report lifecycle path still needs a verifiable seed report selection flow before `GET/POST/PATCH/DELETE /analytics/reports/{reportId}` and `GET /analytics/reports/{reportId}/describe` can be classified with full confidence.
- Dashboard PATCH save and dashboard not-found handling still diverge from the documented Salesforce behavior.
- Folder create validation is too permissive, and folder PATCH still returns the wrong status.
- Folder delete, children, and shares remain cataloged but are not yet closed out by passing live coverage.

## Verification

Compile-only:

```bash
cd /Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract
GOCACHE=/tmp/gocache-analytics-local GOMODCACHE=/tmp/gomodcache-analytics-local go test -p 1 ./analytics_api/... -run '^$' -count=1
```

Live local run:

```bash
cd /Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract
GOCACHE=/tmp/gocache-analytics-local GOMODCACHE=/tmp/gomodcache-analytics-local CONTRACT_TARGET=local go test -p 1 ./analytics_api/... -count=1 -json > /tmp/analytics_api_local_test.json
```

Observed local result summary:

- `github.com/nexuscrm/tests/contract/analytics_api`: pass
- `github.com/nexuscrm/tests/contract/analytics_api/dashboards`: fail
- `github.com/nexuscrm/tests/contract/analytics_api/folders`: fail
- `github.com/nexuscrm/tests/contract/analytics_api/reports`: fail