{ "openapi": "3.1.2", "info": { "title": "DataFocus Website Support API — not the product data API", "version": "1.0.0-implementation", "description": "Implemented website support contracts. Live identity, payments and other integrations require independently approved deployment gates. These are not DataFocus product API or MCP definitions." }, "servers": [ { "url": "/api/ecosystem/v1" } ], "paths": { "/session": { "get": { "operationId": "getSession", "summary": "读取当前会话能力", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "session" ], "security": [ { "SessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "ID-01", "ID-03" ], "x-phase": "M1", "x-implementation-status": "proposed" } }, "/session/exchange": { "post": { "operationId": "exchangeSession", "summary": "一次性身份码交换", "description": "已实现；是否开放取决于部署门禁。这是拟议适配契约；原身份须G0验证。必须验证绑定浏览器的state、一次性码、可信身份源与回跳；不是匿名授予主体。", "tags": [ "session" ], "security": [], "parameters": [], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "ID-01", "ID-03" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "validated-server-event", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Exchange" } } } } } }, "/session/logout": { "post": { "operationId": "logoutSession", "summary": "撤销当前会话", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "session" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ack" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "ID-03" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required" } }, "/documents": { "get": { "operationId": "listDocuments", "summary": "读取公开版本文档manifest", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "documents" ], "security": [], "parameters": [ { "name": "release", "in": "query", "schema": { "type": "string", "minLength": 0, "maxLength": 64 } }, { "name": "locale", "in": "query", "schema": { "type": "string", "enum": [ "zh", "en" ] } } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentList" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "KN-01", "KN-03" ], "x-phase": "M1", "x-implementation-status": "proposed" } }, "/document-feedback": { "post": { "operationId": "createDocumentFeedback", "summary": "提交结构化公开文档反馈", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "document-feedback" ], "security": [], "parameters": [], "responses": { "202": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ack" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "KN-06" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "validated-server-event", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feedback" } } } } } }, "/community/search": { "get": { "operationId": "searchCommunity", "summary": "显式公共社区搜索", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "community" ], "security": [], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunityResults" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "KN-05", "CM-06" ], "x-phase": "M1", "x-implementation-status": "proposed" } }, "/services": { "get": { "operationId": "listServices", "summary": "读取已批准服务范围", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "services" ], "security": [], "parameters": [], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceCatalog" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "SV-01" ], "x-phase": "M2", "x-implementation-status": "proposed" } }, "/cases": { "post": { "operationId": "createCase", "summary": "保存私密申请草稿", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "cases" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "TK-01", "ID-02", "API-01" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDraftInput" } } } } }, "get": { "operationId": "listCases", "summary": "列出有权查看的案件", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "cases" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseList" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "ID-02", "SEC-01" ], "x-phase": "M1", "x-implementation-status": "proposed" } }, "/cases/{caseId}": { "get": { "operationId": "getCase", "summary": "读取案件客户可见视图", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "cases" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "ID-02", "TK-04" ], "x-phase": "M1", "x-implementation-status": "proposed" }, "patch": { "operationId": "updateCaseDraft", "summary": "更新自己的草稿", "description": "已实现；是否开放取决于部署门禁。仅DRAFT，状态与服务器字段不接受。", "tags": [ "cases" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "TK-01", "API-01" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseUpdate" } } } } } }, "/cases/{caseId}/submit": { "post": { "operationId": "submitCase", "summary": "提交私密申请", "description": "已实现；是否开放取决于部署门禁。校验已存草稿中所有提交必填字段。", "tags": [ "cases" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "TK-01", "TK-03" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseSubmit" } } } } } }, "/cases/{caseId}/commands": { "post": { "operationId": "commandCase", "summary": "客户关闭、重开或取消", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "cases" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "TK-03", "API-01" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCommand" } } } } } }, "/cases/{caseId}/messages": { "get": { "operationId": "listMessages", "summary": "读取客户会话消息", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "cases" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "TK-04", "ID-02" ], "x-phase": "M1", "x-implementation-status": "proposed" }, "post": { "operationId": "createMessage", "summary": "添加客户会话消息", "description": "已实现；是否开放取决于部署门禁。不接收visibility字段；所有附件须当前case CLEAN。", "tags": [ "cases" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "TK-04", "TK-05" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } } } }, "/cases/{caseId}/participants": { "post": { "operationId": "inviteParticipant", "summary": "邀请明确的case协作者", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "cases" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Participant" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "当前参与者记录rowVersion强ETag" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "ID-02", "TK-06" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationInput" } } } } } }, "/cases/{caseId}/participants/{participantId}/accept": { "post": { "operationId": "acceptInvitation", "summary": "被邀请者接受案件共享", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "cases" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "participantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Participant" } } }, "headers": { "ETag": { "schema": { "type": "string" }, "description": "当前参与者记录rowVersion强ETag" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "ID-02", "TK-06" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required" } }, "/cases/{caseId}/participants/{participantId}": { "delete": { "operationId": "revokeParticipant", "summary": "撤销案件参与者", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "cases" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "participantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ack" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "ID-02", "TK-06" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required" }, "get": { "operationId": "getInvitation", "summary": "读取自己的最小邀请记录", "description": "已实现；是否开放取决于部署门禁。受邀但未接受只能读自己的邀请元数据，不返回case正文。", "tags": [ "cases" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "participantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Participant" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "ID-02", "TK-06" ], "x-phase": "M1", "x-implementation-status": "proposed" } }, "/cases/{caseId}/uploads": { "post": { "operationId": "createUploadIntent", "summary": "申请隔离附件上传", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "cases" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadIntent" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "TK-05" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadInput" } } } } } }, "/attachments/{attachmentId}/complete": { "post": { "operationId": "completeUpload", "summary": "确认上传并进入隔离扫描", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "attachments" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "TK-05" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required" } }, "/attachments/{attachmentId}": { "get": { "operationId": "getAttachment", "summary": "读取有权附件状态", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "attachments" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "TK-05", "ID-02" ], "x-phase": "M1", "x-implementation-status": "proposed" } }, "/attachments/{attachmentId}/content": { "get": { "operationId": "downloadAttachment", "summary": "授权读取CLEAN附件", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "attachments" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "当前案件和消息权限验证后返回CLEAN附件；不得缓存或复用为公开URL。", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "TK-05", "ID-02" ], "x-phase": "M1", "x-implementation-status": "proposed" } }, "/security-reports": { "post": { "operationId": "createSecurityReport", "summary": "匿名安全线索接收", "description": "已实现；是否开放取决于部署门禁。验证码/限流；不回内部caseID，不因邮箱存在与否改变回执；无文件上传。", "tags": [ "security-reports" ], "security": [], "parameters": [], "responses": { "202": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityReceipt" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "SEC-02" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "validated-server-event", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityReport" } } } } } }, "/notifications": { "get": { "operationId": "listNotifications", "summary": "读取自己的站内通知", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "notifications" ], "security": [ { "SessionCookie": [] } ], "parameters": [], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationList" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "OP-01", "TK-04" ], "x-phase": "M1", "x-implementation-status": "proposed" } }, "/notifications/{notificationId}/read": { "post": { "operationId": "markNotificationRead", "summary": "标记站内通知已读", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "notifications" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "notificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ack" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "TK-04" ], "x-phase": "M1", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required" } }, "/quotes/{quoteId}": { "get": { "operationId": "getQuote", "summary": "买方读取报价", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "quotes" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "SV-02", "ID-02" ], "x-phase": "M2", "x-implementation-status": "proposed" } }, "/quotes/{quoteId}/accept": { "post": { "operationId": "acceptQuote", "summary": "接受指定报价并建立唯一服务订单", "description": "已实现；是否开放取决于部署门禁。当前报价ETag；近期认证；不自动扣款。", "tags": [ "quotes" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceOrder" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "SV-02", "SV-03" ], "x-phase": "M2", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteAccept" } } } } } }, "/quotes/{quoteId}/decline": { "post": { "operationId": "declineQuote", "summary": "拒绝报价", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "quotes" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "SV-02" ], "x-phase": "M2", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteDecision" } } } } } }, "/service-orders/{orderId}": { "get": { "operationId": "getServiceOrder", "summary": "读取自己的服务订单", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "service-orders" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceOrder" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "SV-03", "ID-02" ], "x-phase": "M2", "x-implementation-status": "proposed" } }, "/service-orders/{orderId}/checkout": { "post": { "operationId": "createCheckout", "summary": "显式发起付款尝试", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "service-orders" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "SV-03", "SV-04" ], "x-phase": "M2", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutInput" } } } } } }, "/service-orders/{orderId}/refund-requests": { "post": { "operationId": "requestRefund", "summary": "提出退款申请而非执行退款", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "service-orders" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "SV-05" ], "x-phase": "M2", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundInput" } } } } } }, "/deliveries/{deliveryId}": { "get": { "operationId": "getDelivery", "summary": "读取授权交付物", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "deliveries" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Delivery" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "SV-06", "ID-02" ], "x-phase": "M2", "x-implementation-status": "proposed" } }, "/deliveries/{deliveryId}/accept": { "post": { "operationId": "acceptDelivery", "summary": "客户显式验收当前交付版本", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "deliveries" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Delivery" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "SV-06" ], "x-phase": "M2", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryAccept" } } } } } }, "/deliveries/{deliveryId}/change-requests": { "post": { "operationId": "requestDeliveryChanges", "summary": "对范围内交付提出修改", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "deliveries" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Delivery" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "SV-06" ], "x-phase": "M2", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryChanges" } } } } } }, "/cases/{caseId}/partner-grants": { "post": { "operationId": "createPartnerGrant", "summary": "客户批准伙伴明确资源包", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "cases" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerGrant" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "SV-08", "ID-02" ], "x-phase": "M3", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerGrantInput" } } } } } }, "/cases/{caseId}/partner-grants/{grantId}": { "delete": { "operationId": "revokePartnerGrant", "summary": "客户撤销伙伴资源访问", "description": "已实现；是否开放取决于部署门禁。", "tags": [ "cases" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ack" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "SV-08", "ID-02" ], "x-phase": "M3", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required" } }, "/service-orders/{orderId}/cancel": { "post": { "operationId": "cancelServiceOrder", "summary": "取消尚未付款的服务订单", "description": "已实现；是否开放取决于部署门禁。先查付款attempt；不直接删除已收款订单。", "tags": [ "service-orders" ], "security": [ { "SessionCookie": [], "CsrfToken": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "已持久化；仍按对象ACL裁剪；不代表外部动作完成。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceOrder" } } }, "headers": { "ETag": { "description": "对象rowVersion的强ETag", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "请求无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "身份无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "可见对象上的动作无权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "无权或不存在，不确认私密对象存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "业务/幂等状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "对象版本已变化", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求过大", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "字段或结构无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "缺少If-Match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "依赖不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-requirement-ids": [ "SV-03", "SV-05" ], "x-phase": "M2", "x-implementation-status": "proposed", "x-side-effect": "human-confirmation-and-server-policy-required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCancel" } } } } } } }, "components": { "schemas": { "Session": { "type": "object", "additionalProperties": false, "properties": { "subjectId": { "type": "string", "format": "uuid" }, "emailVerified": { "type": "boolean" }, "capabilities": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 96 }, "maxItems": 100 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "subjectId", "emailVerified", "capabilities", "expiresAt" ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 96 }, "message": { "type": "string", "minLength": 0, "maxLength": 1024 }, "requestId": { "type": "string", "format": "uuid" }, "fieldErrors": { "type": "object", "additionalProperties": { "type": "string", "minLength": 0, "maxLength": 256 } }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "requestId", "retryable" ] }, "Exchange": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "minLength": 16, "maxLength": 256 }, "state": { "type": "string", "minLength": 16, "maxLength": 256 } }, "required": [ "code", "state" ] }, "Ack": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "type": "string", "format": "uuid" }, "accepted": { "const": true }, "status": { "type": "string", "enum": [ "persisted", "queued" ] } }, "required": [ "requestId", "accepted", "status" ] }, "DocumentList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Document" }, "maxItems": 100 }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 512 } }, "required": [ "items", "nextCursor" ] }, "Document": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 96 }, "release": { "type": "string", "minLength": 1, "maxLength": 64 }, "locale": { "type": "string", "enum": [ "zh", "en" ] }, "editions": { "type": "array", "items": { "type": "string", "enum": [ "ot-flash", "ot-heavy", "unknown" ] }, "maxItems": 2 }, "contentType": { "type": "string", "enum": [ "tutorial", "how-to", "reference", "explanation" ] }, "status": { "type": "string", "enum": [ "published", "deprecated" ] }, "url": { "type": "string", "minLength": 1, "maxLength": 1024 }, "markdownUrl": { "type": "string", "minLength": 1, "maxLength": 1024 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "release", "locale", "editions", "contentType", "status", "url", "markdownUrl", "sha256", "updatedAt" ] }, "Feedback": { "type": "object", "additionalProperties": false, "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 96 }, "release": { "type": "string", "minLength": 1, "maxLength": 64 }, "locale": { "type": "string", "enum": [ "zh", "en" ] }, "reason": { "type": "string", "enum": [ "NOT_HELPFUL", "INCORRECT", "MISSING_SCENARIO" ] } }, "required": [ "documentId", "release", "locale", "reason" ] }, "CommunityResults": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CommunityResult" }, "maxItems": 20 }, "source": { "const": "public-community" }, "partial": { "type": "boolean" } }, "required": [ "items", "source", "partial" ] }, "CommunityResult": { "type": "object", "additionalProperties": false, "properties": { "topicId": { "type": "string", "minLength": 1, "maxLength": 64 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "snippet": { "type": "string", "minLength": 0, "maxLength": 500 }, "url": { "type": "string", "minLength": 1, "maxLength": 1024 }, "solutionStatus": { "type": "string", "enum": [ "unresolved", "accepted" ] }, "productVersion": { "type": "string", "minLength": 0, "maxLength": 64 } }, "required": [ "topicId", "title", "snippet", "url", "solutionStatus", "productVersion" ] }, "ServiceCatalog": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceItem" }, "maxItems": 20 } }, "required": [ "items" ] }, "ServiceItem": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "minLength": 1, "maxLength": 96 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "scope": { "type": "string", "minLength": 0, "maxLength": 4000 }, "exclusions": { "type": "string", "minLength": 0, "maxLength": 4000 }, "pricing": { "const": "quote-required" } }, "required": [ "id", "slug", "title", "scope", "exclusions", "pricing" ] }, "Case": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 0, "maxLength": 160 }, "caseType": { "type": "string", "enum": [ "QUESTION", "BUG", "INCIDENT", "SERVICE_REQUEST", "SECURITY" ] }, "edition": { "type": "string", "enum": [ "ot-flash", "ot-heavy", "unknown" ] }, "deployment": { "type": "string", "enum": [ "self-hosted", "cloud", "unknown" ] }, "productVersion": { "type": "string", "minLength": 0, "maxLength": 64 }, "state": { "type": "string", "enum": [ "DRAFT", "SUBMITTED", "TRIAGING", "WAITING_REQUESTER", "WAITING_INTERNAL", "WAITING_EXTERNAL", "IN_PROGRESS", "RESOLVED", "CLOSED", "CANCELLED" ] }, "rowVersion": { "type": "integer", "minimum": 1 }, "requesterId": { "type": "string", "format": "uuid" }, "expected": { "type": "string", "minLength": 0, "maxLength": 4000 }, "actual": { "type": "string", "minLength": 0, "maxLength": 4000 }, "nextOwner": { "type": "string", "enum": [ "REQUESTER", "SUPPORT", "EXTERNAL", "NONE" ] }, "coverage": { "type": "string", "enum": [ "COVERED", "NOT_COVERED", "UNKNOWN" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "caseType", "edition", "deployment", "productVersion", "state", "rowVersion", "requesterId", "expected", "actual", "nextOwner", "coverage", "createdAt", "updatedAt" ] }, "CaseDraftInput": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 0, "maxLength": 160 }, "caseType": { "type": "string", "enum": [ "QUESTION", "BUG", "INCIDENT", "SERVICE_REQUEST" ] }, "edition": { "type": "string", "enum": [ "ot-flash", "ot-heavy", "unknown" ] }, "deployment": { "type": "string", "enum": [ "self-hosted", "cloud", "unknown" ] }, "productVersion": { "type": "string", "minLength": 0, "maxLength": 64 }, "environment": { "type": "string", "minLength": 0, "maxLength": 2000 }, "expected": { "type": "string", "minLength": 0, "maxLength": 4000 }, "actual": { "type": "string", "minLength": 0, "maxLength": 4000 }, "reproduction": { "type": "string", "minLength": 0, "maxLength": 4000 }, "attempts": { "type": "string", "minLength": 0, "maxLength": 4000 }, "impact": { "type": "string", "enum": [ "NONE", "BLOCKED_TEST", "DEGRADED", "PRODUCTION_STOP" ] }, "helpKind": { "type": "string", "enum": [ "ADVICE", "INSTALL", "DIAGNOSE", "INTEGRATE", "TRAIN", "OTHER" ] }, "sourceTopicId": { "type": "string", "minLength": 0, "maxLength": 64 }, "sourceDocumentId": { "type": "string", "minLength": 0, "maxLength": 96 }, "requestedDueAt": { "type": "string", "format": "date-time" }, "budgetNote": { "type": "string", "minLength": 0, "maxLength": 500 }, "privacyNoticeVersion": { "type": "string", "minLength": 0, "maxLength": 64 }, "orgContextId": { "type": "string", "format": "uuid" } }, "required": [] }, "CaseList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Case" }, "maxItems": 100 }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 512 } }, "required": [ "items", "nextCursor" ] }, "CaseUpdate": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 0, "maxLength": 160 }, "caseType": { "type": "string", "enum": [ "QUESTION", "BUG", "INCIDENT", "SERVICE_REQUEST" ] }, "edition": { "type": "string", "enum": [ "ot-flash", "ot-heavy", "unknown" ] }, "deployment": { "type": "string", "enum": [ "self-hosted", "cloud", "unknown" ] }, "productVersion": { "type": "string", "minLength": 0, "maxLength": 64 }, "environment": { "type": "string", "minLength": 0, "maxLength": 2000 }, "expected": { "type": "string", "minLength": 0, "maxLength": 4000 }, "actual": { "type": "string", "minLength": 0, "maxLength": 4000 }, "reproduction": { "type": "string", "minLength": 0, "maxLength": 4000 }, "attempts": { "type": "string", "minLength": 0, "maxLength": 4000 }, "impact": { "type": "string", "enum": [ "NONE", "BLOCKED_TEST", "DEGRADED", "PRODUCTION_STOP" ] }, "helpKind": { "type": "string", "enum": [ "ADVICE", "INSTALL", "DIAGNOSE", "INTEGRATE", "TRAIN", "OTHER" ] }, "sourceTopicId": { "type": "string", "minLength": 0, "maxLength": 64 }, "sourceDocumentId": { "type": "string", "minLength": 0, "maxLength": 96 }, "requestedDueAt": { "type": "string", "format": "date-time" }, "budgetNote": { "type": "string", "minLength": 0, "maxLength": 500 }, "privacyNoticeVersion": { "type": "string", "minLength": 0, "maxLength": 64 }, "orgContextId": { "type": "string", "format": "uuid" } }, "required": [] }, "CaseSubmit": { "type": "object", "additionalProperties": false, "properties": { "privacyNoticeVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "confirmPrivateRequest": { "const": true } }, "required": [ "privacyNoticeVersion", "confirmPrivateRequest" ] }, "CaseCommand": { "type": "object", "additionalProperties": false, "properties": { "command": { "type": "string", "enum": [ "CANCEL", "REOPEN", "CLOSE" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "command", "reason" ] }, "MessageList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "maxItems": 100 }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 512 } }, "required": [ "items", "nextCursor" ] }, "Message": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "caseId": { "type": "string", "format": "uuid" }, "authorId": { "type": "string", "format": "uuid" }, "visibility": { "const": "CUSTOMER_THREAD" }, "body": { "type": "string", "minLength": 0, "maxLength": 10000 }, "attachmentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 10 }, "revision": { "type": "integer", "minimum": 1 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "caseId", "authorId", "visibility", "body", "attachmentIds", "revision", "createdAt" ] }, "MessageInput": { "type": "object", "additionalProperties": false, "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000 }, "attachmentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 10 } }, "required": [ "body" ] }, "Participant": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "caseId": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "COLLABORATOR", "BUYER" ] }, "state": { "type": "string", "enum": [ "INVITED", "ACTIVE", "REVOKED" ] }, "subjectId": { "type": "string", "format": "uuid" }, "rowVersion": { "type": "integer", "minimum": 1 } }, "required": [ "id", "caseId", "role", "state", "rowVersion" ] }, "InvitationInput": { "type": "object", "additionalProperties": false, "properties": { "subjectReference": { "type": "string", "minLength": 1, "maxLength": 128 }, "role": { "type": "string", "enum": [ "COLLABORATOR", "BUYER" ] } }, "required": [ "subjectReference", "role" ] }, "UploadIntent": { "type": "object", "additionalProperties": false, "properties": { "attachmentId": { "type": "string", "format": "uuid" }, "uploadUrl": { "type": "string", "minLength": 1, "maxLength": 2048 }, "expiresAt": { "type": "string", "format": "date-time" }, "state": { "const": "PENDING_UPLOAD" } }, "required": [ "attachmentId", "uploadUrl", "expiresAt", "state" ] }, "UploadInput": { "type": "object", "additionalProperties": false, "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 160 }, "contentType": { "type": "string", "enum": [ "text/plain", "application/json", "text/csv", "image/png", "image/jpeg", "application/pdf" ] }, "bytes": { "type": "integer", "minimum": 1, "maximum": 20971520 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "filename", "contentType", "bytes", "sha256" ] }, "Attachment": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "PENDING_UPLOAD", "QUARANTINED", "CLEAN", "REJECTED", "DELETED" ] }, "filename": { "type": "string", "minLength": 0, "maxLength": 160 }, "bytes": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "rowVersion": { "type": "integer", "minimum": 1 } }, "required": [ "id", "state", "filename", "bytes", "sha256", "rowVersion" ] }, "SecurityReceipt": { "type": "object", "additionalProperties": false, "properties": { "received": { "const": true }, "message": { "type": "string", "minLength": 0, "maxLength": 512 }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "received", "message", "requestId" ] }, "SecurityReport": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 10, "maxLength": 160 }, "description": { "type": "string", "minLength": 20, "maxLength": 10000 }, "contact": { "type": "string", "minLength": 0, "maxLength": 256 } }, "required": [ "title", "description" ] }, "NotificationList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" }, "maxItems": 100 }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 512 } }, "required": [ "items", "nextCursor" ] }, "Notification": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "eventType": { "type": "string", "minLength": 0, "maxLength": 96 }, "objectId": { "type": "string", "format": "uuid" }, "read": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "eventType", "objectId", "read", "createdAt" ] }, "Quote": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "caseId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "rowVersion": { "type": "integer", "minimum": 1 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "DRAFT", "SENT", "ACCEPTED", "DECLINED", "EXPIRED", "SUPERSEDED", "WITHDRAWN" ] }, "buyerId": { "type": "string", "format": "uuid" }, "merchantId": { "type": "string", "minLength": 1, "maxLength": 96 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amountMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "最小币种单位的整数字符串；按币种元数据校验，不使用浮点" }, "lineItems": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 512 }, "quantity": { "type": "integer", "minimum": 1 }, "unitAmountMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "最小币种单位的整数字符串；按币种元数据校验，不使用浮点" }, "totalAmountMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "最小币种单位的整数字符串；按币种元数据校验，不使用浮点" } }, "required": [ "description", "quantity", "unitAmountMinor", "totalAmountMinor" ] }, "maxItems": 100 }, "scope": { "type": "string", "minLength": 1, "maxLength": 8000 }, "exclusions": { "type": "string", "minLength": 1, "maxLength": 8000 }, "deliverables": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxItems": 100 }, "acceptanceCriteria": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxItems": 100 }, "schedule": { "type": "string", "minLength": 1, "maxLength": 4000 }, "customerResponsibilities": { "type": "string", "minLength": 1, "maxLength": 4000 }, "cancellationRefundTerms": { "type": "string", "minLength": 1, "maxLength": 8000 }, "termsVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "validUntil": { "type": "string", "format": "date-time" } }, "required": [ "id", "caseId", "version", "rowVersion", "sha256", "state", "buyerId", "merchantId", "currency", "amountMinor", "lineItems", "scope", "exclusions", "deliverables", "acceptanceCriteria", "schedule", "customerResponsibilities", "cancellationRefundTerms", "termsVersion", "validUntil" ] }, "ServiceOrder": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "businessType": { "const": "PROFESSIONAL_SERVICE" }, "quoteId": { "type": "string", "format": "uuid" }, "quoteVersion": { "type": "integer", "minimum": 1 }, "buyerId": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amountMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "最小币种单位的整数字符串；按币种元数据校验，不使用浮点" }, "state": { "type": "string", "enum": [ "CREATED", "ACTIVE", "PAYMENT_REVIEW", "CANCELLED", "COMPLETED" ] }, "paymentState": { "type": "string", "enum": [ "UNPAID", "PENDING", "PAID", "REVIEW", "PARTIALLY_REFUNDED", "REFUNDED" ] }, "rowVersion": { "type": "integer", "minimum": 1 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "businessType", "quoteId", "quoteVersion", "buyerId", "currency", "amountMinor", "state", "paymentState", "rowVersion", "createdAt" ] }, "QuoteAccept": { "type": "object", "additionalProperties": false, "properties": { "quoteVersion": { "type": "integer", "minimum": 1 }, "quoteSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "termsVersion": { "type": "string", "minLength": 1, "maxLength": 64 }, "accepted": { "const": true } }, "required": [ "quoteVersion", "quoteSha256", "termsVersion", "accepted" ] }, "QuoteDecision": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "reason" ] }, "Checkout": { "type": "object", "additionalProperties": false, "properties": { "attemptId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "PENDING", "REVIEW" ] }, "checkoutUrl": { "type": [ "string", "null" ], "maxLength": 2048 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "attemptId", "state", "checkoutUrl", "expiresAt" ] }, "CheckoutInput": { "type": "object", "additionalProperties": false, "properties": { "confirmProceedToPayment": { "const": true } }, "required": [ "confirmProceedToPayment" ] }, "Refund": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "serviceOrderId": { "type": "string", "format": "uuid" }, "amountMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "最小币种单位的整数字符串；按币种元数据校验，不使用浮点" }, "state": { "type": "string", "enum": [ "REQUESTED", "APPROVED", "REJECTED", "PROCESSING", "SUCCEEDED", "FAILED" ] }, "rowVersion": { "type": "integer", "minimum": 1 } }, "required": [ "id", "serviceOrderId", "amountMinor", "state", "rowVersion" ] }, "RefundInput": { "type": "object", "additionalProperties": false, "properties": { "amountMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "最小币种单位的整数字符串；按币种元数据校验，不使用浮点" }, "reason": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "amountMinor", "reason" ] }, "Delivery": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "serviceOrderId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 1 }, "rowVersion": { "type": "integer", "minimum": 1 }, "manifestSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "WAITING_ACCEPTANCE", "CHANGES_REQUESTED", "ACCEPTED", "TERMINATED" ] }, "summary": { "type": "string", "minLength": 0, "maxLength": 8000 }, "attachmentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 10 } }, "required": [ "id", "serviceOrderId", "revision", "rowVersion", "manifestSha256", "state", "summary", "attachmentIds" ] }, "DeliveryAccept": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "manifestSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "accepted": { "const": true } }, "required": [ "revision", "manifestSha256", "accepted" ] }, "DeliveryChanges": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "reason": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "revision", "reason" ] }, "PartnerGrant": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "caseId": { "type": "string", "format": "uuid" }, "partnerSubjectId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "ACTIVE", "REVOKED", "EXPIRED" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "rowVersion": { "type": "integer", "minimum": 1 } }, "required": [ "id", "caseId", "partnerSubjectId", "state", "expiresAt", "rowVersion" ] }, "PartnerGrantInput": { "type": "object", "additionalProperties": false, "properties": { "partnerSubjectId": { "type": "string", "format": "uuid" }, "resourceIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 4000 }, "expiresAt": { "type": "string", "format": "date-time" }, "confirmed": { "const": true } }, "required": [ "partnerSubjectId", "resourceIds", "purpose", "expiresAt", "confirmed" ] }, "OrderCancel": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "reason" ] } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 128 }, "description": "subject+method+path范围24h；同键异请求409；仍校验永久业务唯一约束" }, "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 0, "maxLength": 512 } }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "IfMatch": { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "description": "读取对象返回的ETag；缺失428、过期412" } }, "securitySchemes": { "SessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-df_helpdesk", "description": "服务器端会话；Secure/HttpOnly；不是原控制台cookie直接共享" }, "CsrfToken": { "type": "apiKey", "in": "header", "name": "X-CSRF-Token", "description": "会话绑定，写操作同时验证同源Origin" }, "InternalMtls": { "type": "mutualTLS", "description": "私有网络内批准工作负载证书身份，不接受用户转发身份头" }, "DiscourseSignature": { "type": "apiKey", "in": "header", "name": "X-Discourse-Event-Signature", "description": "sha256=加HMAC-SHA256原始payload，使用专用secret" } } }, "x-source-spec-sha256": "c034f437d6a2955a7087219deee0b83803d248f06620cae8d9f14aaaaba5f915" }