# 接口契约 · 前后端与算法服务 v0.1（冻结，2026-09-29）

> **本文是"重构前行为"的对拍基准**（用户令 2026-09-29：前端完全 Vue、后端完全 Java、算法 Python+FastAPI，三条线都要"确保与重构前一致"）。表里的每一行都由 `scripts/http_contract_audit.py` **在线复核**：方法与状态码必须一致，JSON 顶层键集合必须一致（值随数据变，不比）。

* 网关 `http://127.0.0.1:28084`（对外唯一入口）· 分析组件 `:18033` · CMS `:18020` · 算法服务 `:18050`
* 方法列 `GET`/`POST` = 实测返回 200；`GET?`/`POST?` = 该方法有响应但不是 200（多为缺参），`—` = 两法都不通（未实现/仅特定参数下可用）。

## 0 总览

* 路径合计 **53** 条（其中 **42** 条至少一种方法返回 200），由 `scripts/http_contract_probe.py` 实测生成。
* 算法服务端点同时提供 `/docs`（Swagger UI）与 `/openapi.json`（OpenAPI），Java/Vue 可直接据此生成客户端。

| 类别 | 路径 | 方法 | 状态 | 类型 | 字节 | 形状（首个 200 的顶层结构） | 秒 |
|---|---|---|---|---|---|---|---|
| **网关前缀（统一入口）** | | | | | | | |
|  | `/` | GET/POST | 200 | text/html | 300000 | HTML: 观澜中文系统 · 详细分析 | 0.02 |
|  | `/algorithm` | GET | 200 | application/json | 104 | JSON keys: endpoints, ok, service, time, version | 0.03 |
|  | `/cms` | GET | 200 | text/html | 300000 | HTML: 如东海上风电场 振动诊断 · 客户版 | 0.07 |
|  | `/detail` | GET | 200 | text/html | 237214 | HTML: 观澜 · 风电数据分析与决策支持 | 0.07 |
|  | `/sim` | GET | 200 | text/html | 50998 | HTML: 4MW 机组 整机联调仿真台 · 演示 | 0.04 |
|  | `/sim/sys` | GET | 200 | text/html | 123455 | HTML: 观澜 offshore-4-0-platform · 四系统联调 | 0.25 |
|  | `/viewer` | GET | 200 | text/html | 4986 | HTML: 整台风机 · 单元拆装工作台 | 0.02 |
| **分析组件页面** | | | | | | | |
|  | `/v2` | GET | 200 | text/html | 236976 | HTML: 观澜 · 风电数据分析与决策支持 | 0.06 |
|  | `/v2/snapshot` | — | 404 | - | 0 | — | 0.0 |
| **分析组件接口 `/api/*`** | | | | | | | |
|  | `/api/ask` | POST | 200 | application/json | 23 | JSON keys: err | 0.02 |
|  | `/api/ask_models` | GET | 200 | application/json | 137 | JSON keys: models | 0.0 |
|  | `/api/ask_status` | GET | 200 | application/json | 173 | JSON keys: answer, elapsed, err, lang, model, q, review, state | 0.03 |
|  | `/api/channels` | GET | 200 | application/json | 15799 | JSON keys: A.功率, A.状态, A.转速, A.风况, B.偏航, B.冷却执行器, B.变桨, B.润滑液压 | 0.29 |
|  | `/api/curves` | GET | 200 | application/json | 23767 | JSON keys: figs, note, physics | 1.15 |
|  | `/api/dq_findings` | GET | 200 | application/json | 420 | JSON keys: n, note, rows | 0.2 |
|  | `/api/facts` | GET | 200 | application/json | 3521 | JSON keys: cards, contract_sha256, contract_version, generated | 0.0 |
|  | `/api/fleet` | GET | 200 | application/json | 230264 | JSON keys: all_months, control, faults, fus, kpi, m8, m9, m9_pending | 15.73 |
|  | `/api/maint_framework` | GET | 200 | application/json | 7271 | JSON keys: coverage, gaps, records, stages, systems, tiers | 0.82 |
|  | `/api/maint_std` | GET | 200 | application/json | 27035 | JSON keys: batch, closure, discontinuity, recurrence, score | 0.44 |
|  | `/api/maint_survey` | GET | 200 | application/json | 7533 | JSON keys: rows | 0.17 |
|  | `/api/ont_chain` | GET | 200 | application/json | 106 | JSON keys: error, text | 0.01 |
|  | `/api/ont_list` | GET | 200 | application/json | 6081 | JSON keys: rows | 0.01 |
|  | `/api/ont_obj` | GET | 200 | application/json | 39 | JSON keys: err, links, obj | 0.01 |
|  | `/api/ontology` | GET? | 500 | - | 0 | — | 0.02 |
|  | `/api/problem` | GET? | 500 | - | 0 | — | 0.01 |
|  | `/api/query` | GET? | 500 | - | 0 | — | 0.01 |
|  | `/api/reload` | GET | 200 | application/json | 87 | JSON keys: files, ok, old_stamp, stamp | 0.41 |
|  | `/api/rpt_compose` | — | 404 | - | 0 | — | 0.01 |
|  | `/api/rpt_export` | GET | 200 | application/vnd.openxmlformats-officedocument.wordprocessingml.document | 36875 | — | 15.44 |
|  | `/api/snapshot` | — | 404 | - | 0 | — | 0.01 |
|  | `/api/turbine` | GET? | 500 | - | 0 | — | 0.01 |
|  | `/api/vibcms` | GET | 200 | application/json | 6858 | JSON keys: action, date, diff, grades, overall, 时间范围, 窗 | 5.34 |
| **CMS 组件 `/cms`** | | | | | | | |
|  | `/cms/api/agent` | — | 404 | - | 0 | — | 0.03 |
|  | `/cms/api/agent_stream` | POST? | 400 | - | 0 | — | 0.0 |
|  | `/cms/api/ask` | — | 404 | - | 0 | — | 0.04 |
|  | `/cms/api/models` | GET | 200 | application/json | 96 | JSON keys: models, picked | 0.02 |
|  | `/cms/api/plugins` | GET | 200 | application/json | 4857 | JSON list[17] item=desc,name,params | 0.01 |
|  | `/cms/api/run` | POST | 200 | application/json | 290 | JSON keys: kind, text | 0.01 |
|  | `/cms/api/views` | GET | 200 | application/json | 2 | JSON list[0] | 0.01 |
| **算法服务（FastAPI）** | | | | | | | |
|  | `/api/availability_summary` | GET | 200 | application/json | 475 | JSON keys: 台级损失top, 损失MWh, 时长h, 时间可用率_不含调度令, 物理上限核, 零本底 | 0.02 |
|  | `/api/curves` | POST? | 405 | - | 0 | — | 0.04 |
|  | `/api/curves_check` | GET | 200 | application/json | 676 | JSON keys: Betz, λ叶尖速比, 齿比恒等 | 0.63 |
|  | `/api/endpoints` | GET | 200 | application/json | 1929 | JSON keys: count, items | 0.0 |
|  | `/api/fusion` | GET | 200 | application/json | 63235 | JSON list[2] | 3.31 |
|  | `/api/handoff` | GET | 200 | application/json | 44403 | JSON keys: calibration_updates_v1, detectability_prior, field_actions_v1, meta,  | 0.02 |
|  | `/api/matrix` | GET | 200 | application/json | 40555 | JSON keys: WTG01, WTG02, WTG03, WTG04, WTG05, WTG06, WTG07, WTG08 | 9.04 |
|  | `/api/pitch` | GET | 200 | application/json | 34336 | JSON list[2] | 1.17 |
|  | `/api/problems` | GET | 200 | application/json | 4983 | JSON keys: 主控与传感网, 偏航, 发电机, 变桨, 变流器, 齿轮箱 | 9.58 |
|  | `/api/reconcile` | GET | 200 | application/json | 1679 | JSON keys: 主控与传感网, 主轴承, 发电机, 变流器, 齿轮箱 | 18.47 |
|  | `/api/reliability` | GET | 200 | application/json | 3531 | JSON keys: 口径, 外部类停机h, 总停机h, 窗, 表, 设备类停机h | 1.07 |
|  | `/api/systems` | GET | 200 | application/json | 859 | JSON keys: SYSTEMS, TEMP2SYS | 0.01 |
|  | `/docs` | GET | 200 | text/html | 1021 | HTML: 观澜 · 算法服务 - Swagger UI | 0.01 |
|  | `/healthz` | GET | 200 | application/json | 104 | JSON keys: endpoints, ok, service, time, version | 0.01 |