72 lines
6.5 KiB
Markdown
72 lines
6.5 KiB
Markdown
# 按接口拆分的 JSON Schema
|
||
|
||
此目录提供五类 HTTP 响应和六类 MQ 消息的独立校验入口，使用 JSON Schema Draft 2020-12。重复且约束相同的结构通过相对 `$ref` 引用 `common.schema.json`，仅单个入口使用的结构保留在该入口的 `$defs` 中。
|
||
|
||
本次仅新增文件，不替换或删除 `contracts/local/` 的原文件，不修改现有程序的校验入口、嵌入资源或来源清单。程序仍使用原有 Schema；此目录尚未接入运行或发布流程，不构成外部 SaaS 签收。
|
||
|
||
## HTTP 响应
|
||
|
||
下列入口校验响应 JSON 正文，不校验请求路径、查询参数或 HTTP 状态码。每个入口仅接受自己的成功响应或公共错误响应。
|
||
|
||
| 接口 | Schema | 现有示例（相对本目录） |
|
||
| --- | --- | --- |
|
||
| `GET /internal/v1/dispatcher/sip` | [`http-sip.schema.json`](http-sip.schema.json) | [`config-read-sip.json`](../local/examples/config-read-sip.json)、[`config-read-sip-no-revision.json`](../local/examples/config-read-sip-no-revision.json) |
|
||
| `GET /internal/v1/dispatcher/task/:task_id` | [`http-task-detail.schema.json`](http-task-detail.schema.json) | [`config-read-task-full.json`](../local/examples/config-read-task-full.json)、[`config-read-task-asr.json`](../local/examples/config-read-task-asr.json) |
|
||
| `GET /internal/v1/dispatcher/tasks` | [`http-task-list.schema.json`](http-task-list.schema.json) | [`task-discovery-page.json`](../local/examples/task-discovery-page.json)、[`task-discovery-end.json`](../local/examples/task-discovery-end.json) |
|
||
| `GET /internal/v1/dispatcher/tenant/:tenant_id/quota` | [`http-tenant-quota.schema.json`](http-tenant-quota.schema.json) | [`config-read-quota.json`](../local/examples/config-read-quota.json) |
|
||
| `GET /internal/v1/dispatcher/ai-providers` | [`http-ai-providers.schema.json`](http-ai-providers.schema.json) | [`config-read-providers.json`](../local/examples/config-read-providers.json)、[`config-read-bailian-providers.json`](../local/examples/config-read-bailian-providers.json) |
|
||
|
||
公共错误响应示例：[`config-read-error.json`](../local/examples/config-read-error.json)。
|
||
|
||
## MQ 消息
|
||
|
||
按消息类型和方向选择入口。`task.control` 的请求和回执共用事件名称，`call.execute` 的请求和派发回执也共用事件名称，不能仅依据 `event_type` 选择 Schema。
|
||
|
||
| 消息 | 方向 | Schema | 现有示例（相对本目录） |
|
||
| --- | --- | --- | --- |
|
||
| `sip.config` | SaaS → Dispatcher | [`mq-sip-config.schema.json`](mq-sip-config.schema.json) | [`mq-sip-change.json`](../local/examples/mq-sip-change.json) |
|
||
| `task.control` 请求 | SaaS → Dispatcher | [`mq-task-control-request.schema.json`](mq-task-control-request.schema.json) | [`mq-control.json`](../local/examples/mq-control.json)、[`mq-control-start.json`](../local/examples/mq-control-start.json)、[`mq-control-edit.json`](../local/examples/mq-control-edit.json) |
|
||
| `task.control` 回执 | Dispatcher → SaaS | [`mq-task-control-receipt.schema.json`](mq-task-control-receipt.schema.json) | [`mq-control-ack.json`](../local/examples/mq-control-ack.json) |
|
||
| `call.execute` 请求 | SaaS → Dispatcher | [`mq-call-execute-request.schema.json`](mq-call-execute-request.schema.json) | [`mq-execute.json`](../local/examples/mq-execute.json) |
|
||
| `call.execute` 派发/拒绝回执 | Dispatcher → SaaS | [`mq-call-execute-receipt.schema.json`](mq-call-execute-receipt.schema.json) | [`mq-execute-ack.json`](../local/examples/mq-execute-ack.json)、[`mq-execute-rejected.json`](../local/examples/mq-execute-rejected.json) |
|
||
| `call.execute.result` 最终结果 | Dispatcher → SaaS | [`mq-call-execute-result.schema.json`](mq-call-execute-result.schema.json) | [`mq-result-uploaded.json`](../local/examples/mq-result-uploaded.json)、[`mq-result-no-recording.json`](../local/examples/mq-result-no-recording.json) |
|
||
|
||
## 公共定义与引用
|
||
|
||
[`common.schema.json`](common.schema.json) 仅包含 `$defs`，不是独立消息的校验入口：
|
||
|
||
- `dispatcher_id`、`tenant_id`、`task_id`：公共身份字段约束。
|
||
- `event_id`、`issued_at`：MQ 事件身份和时间约束。
|
||
- `task_status`：任务详情与任务列表共用的任务状态。
|
||
- `error`：公共 HTTP 错误响应。
|
||
- `weekly_windows`、`windows`：任务和线路共用的每周时段。
|
||
|
||
引用示例：
|
||
|
||
```json
|
||
{
|
||
"dispatcher_id": {
|
||
"$ref": "./common.schema.json#/$defs/dispatcher_id"
|
||
}
|
||
}
|
||
```
|
||
|
||
任务时段和线路时段仍分别定义：任务保留有效起止时间和排除日期，线路不包含排除日期。任务详情内的 AI、SIP 线路和最终结果中的录音结构不增加跨入口抽象。
|
||
|
||
## 使用方式
|
||
|
||
1. 根据上表选择一个入口文件，而不是把所有入口合并为一个 `oneOf`。
|
||
2. 向校验器注册所用入口及其公共依赖。各文件的 `$id` 是稳定的资源标识，不是要求联网访问的下载地址；注册时使用文件内的 `$id`；若按本地文件 URI 加载，须将这些 `$id` 映射到对应的本地资源。
|
||
3. 离线解析 `./common.schema.json`。不得静默忽略缺失引用或改为联网下载；缺少依赖必须报错。移动或分发文件时保留相对目录关系。
|
||
4. 开启 `format` 校验，使 `uuid`、`date-time`、`date` 的检查与现有 Go 校验入口一致。现有 `github.com/santhosh-tekuri/jsonschema/v6` 支持 `AddResource`、`Compile` 和 `AssertFormat`，无需新增依赖。
|
||
5. 对响应或消息的 JSON 正文执行校验。资源归属、任务授权、时段关系、线路可用性等业务检查仍由程序执行，Schema 通过不代表业务获准。
|
||
|
||
## 来源及维护边界
|
||
|
||
- 五个配置响应（含公共错误、身份和时段定义）的来源：[`../local/config-read.schema.json`](../local/config-read.schema.json)；任务列表来源：[`../local/task-discovery.schema.json`](../local/task-discovery.schema.json)。
|
||
- 六个 MQ 入口的来源：[`../local/mq.schema.json`](../local/mq.schema.json)。
|
||
- 拆分仅改变定义位置和引用方式，不增加、删除或放宽原有字段约束。任务列表对 `schema_version`、`control_seq` 的现有忽略规则也保持不变。
|
||
- HTTP 入口保留原有公共错误分支；MQ 入口严格区分原有消息分支。MQ 回执字段按原 Schema 保留，不自行补充字段。
|
||
- 此目录不引用旧目录中的 Schema；旧目录只作为拆分来源和现有示例位置。独立分发时仅需所用入口及 `common.schema.json`。
|
||
- 原文件、程序和清单仍保持原样。未来如需接入此目录或改变字段，必须另行确认范围，并同步核验新旧定义，不能假定本次已完成切换。
|