{
  "openapi": "3.0.3",
  "info": {
    "title": "Rubric 样本标注 API",
    "version": "2.1",
    "description": "当前数据为 6 条 Console 历史样本快照，并非实时或全部任务。使用 Emorika 登录会话和 Rubric 授权；尚无 API Key 或跨域支持。写入请求需发送与 Host 匹配的 Origin，JSON 请求体不超过 6000000 字节。"
  },
  "servers": [{"url": "/", "description": "当前服务"}],
  "security": [{"sessionCookie": []}],
  "paths": {
    "/api/v1/member-operations": {
      "get": {"summary": "管理员按成员查询操作日志", "description": "包含已有标注、复核、权限变更、规则发布，以及新记录的草稿保存。历史浏览和早期草稿保存没有完整记录。每页 50 条。", "parameters": [{"name": "subject", "in": "query", "required": true, "schema": {"type": "string"}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "maximum": 100000, "default": 0}}], "responses": {"200": {"description": "成员操作记录", "content": {"application/json": {"schema": {"type": "object", "properties": {"subject": {"type": "string"}, "total": {"type": "integer"}, "offset": {"type": "integer"}, "limit": {"type": "integer"}, "events": {"type": "array", "items": {"type": "object", "additionalProperties": true}}}}}}}, "400": {"$ref": "#/components/responses/Error"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}}
    },
    "/api/v1/members": {
      "get": {"summary": "管理员读取成员、角色和权限审计", "description": "仅工作空间管理员可用。统一登录的 Rubric 授权仍是前置条件。", "responses": {"200": {"description": "成员和角色", "content": {"application/json": {"schema": {"type": "object", "properties": {"members": {"type": "array", "items": {"type": "object", "additionalProperties": true}}, "owner_subject": {"type": "string"}, "roles": {"type": "object", "additionalProperties": true}, "audit": {"type": "array", "items": {"type": "object", "additionalProperties": true}}}}}}}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "503": {"$ref": "#/components/responses/Error"}}}
    },
    "/api/v1/members/role": {
      "post": {"summary": "管理员修改现有成员角色", "description": "下一次请求生效，不能移除固定管理员 loopwangzi 的权限；不能授权未知账号。所有角色都不能复核自己的标注。", "parameters": [{"$ref": "#/components/parameters/Origin"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["subject","role","previous_role"], "properties": {"subject": {"type": "string"}, "role": {"type": "string", "enum": ["admin","contributor","annotator","reviewer","viewer","disabled"]}, "previous_role": {"type": "string", "description": "读取时的旧角色，用于避免覆盖并发修改。"}}}}}}, "responses": {"200": {"description": "角色已更新", "content": {"application/json": {"schema": {"type": "object", "properties": {"subject": {"type": "string"}, "role": {"type": "string"}, "updated_at": {"type": "string"}}}}}}, "400": {"$ref": "#/components/responses/Error"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}, "409": {"$ref": "#/components/responses/Error"}, "413": {"$ref": "#/components/responses/Error"}, "503": {"$ref": "#/components/responses/Error"}}}
    },
    "/api/v1/rubric": {
      "get": {"summary": "读取当前规则、共享草稿和历史版本", "responses": {"200": {"description": "规则版本", "content": {"application/json": {"schema": {"type": "object", "properties": {"current": {"$ref": "#/components/schemas/Rubric"}, "versions": {"type": "array", "items": {"$ref": "#/components/schemas/Rubric"}}, "draft": {"type": "object", "nullable": true, "additionalProperties": true}}}}}}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "503": {"$ref": "#/components/responses/Error"}}}
    },
    "/api/v1/rubric/draft": {
      "post": {"summary": "管理员保存共享规则草稿", "description": "可增加、删除、修改维度和适用范围。草稿不改变当前规则。至少保留图片和视频各一个适用维度。", "parameters": [{"$ref": "#/components/parameters/Origin"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RubricEdit"}}}}, "responses": {"200": {"description": "草稿已保存", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RubricEdit"}}}}, "400": {"$ref": "#/components/responses/Error"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "409": {"$ref": "#/components/responses/Error"}, "413": {"$ref": "#/components/responses/Error"}, "503": {"$ref": "#/components/responses/Error"}}}
    },
    "/api/v1/rubric/publish": {
      "post": {"summary": "发布新的不可变规则版本", "description": "影响后续新标注；旧标注保留原版本，不自动重新评分。base_version 过期返回 409。", "parameters": [{"$ref": "#/components/parameters/Origin"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RubricEdit"}}}}, "responses": {"201": {"description": "版本已发布", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Rubric"}}}}, "400": {"$ref": "#/components/responses/Error"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "409": {"$ref": "#/components/responses/Error"}, "413": {"$ref": "#/components/responses/Error"}, "503": {"$ref": "#/components/responses/Error"}}}
    },
    "/api/v1/health": {
      "get": {"summary": "检查服务状态", "security": [], "responses": {"200": {"description": "服务状态", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string"}, "version": {"type": "string"}, "samples": {"type": "integer"}}}}}}}}
    },
    "/api/v1/session": {
      "get": {"summary": "查看登录状态", "security": [], "responses": {"200": {"description": "登录状态及登录、注册、退出地址", "content": {"application/json": {"schema": {"type": "object", "properties": {"authenticated": {"type": "boolean"}, "actor": {"type": "object", "nullable": true, "additionalProperties": true}, "auth_status": {"type": "integer"}, "login_url": {"type": "string"}, "registration_url": {"type": "string"}, "logout_url": {"type": "string"}}}}}}}}
    },
    "/api/v1/samples": {
      "get": {"summary": "读取样本列表", "description": "列表不含完整输入、模型提示词、翻译与性能数据。无分页或筛选。", "responses": {"200": {"description": "样本摘要、评分规则和快照日期", "content": {"application/json": {"schema": {"type": "object", "properties": {"samples": {"type": "array", "items": {"$ref": "#/components/schemas/Sample"}}, "rubric": {"type": "object", "additionalProperties": true}, "data_mode": {"type": "string"}, "review_mode": {"type": "string"}, "snapshot_date": {"type": "string"}}}}}}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "503": {"$ref": "#/components/responses/Error"}}}
    },
    "/api/v1/samples/{task_id}": {
      "get": {"summary": "读取完整样本", "parameters": [{"$ref": "#/components/parameters/TaskId"}], "responses": {"200": {"description": "完整样本与最新标注", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Sample"}}}}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}, "503": {"$ref": "#/components/responses/Error"}}}
    },
    "/api/v1/training/samples": {
      "get": {"summary": "读取已复核通过的训练候选", "description": "仅返回已批准的最新标注；未执行训练。无分页。", "parameters": [{"name": "label", "in": "query", "required": false, "description": "可用 positive 或 negative 筛选。", "schema": {"type": "string", "enum": ["positive", "negative"]}}], "responses": {"200": {"description": "候选及评分规则", "content": {"application/json": {"schema": {"type": "object", "properties": {"schema_version": {"type": "string"}, "count": {"type": "integer"}, "samples": {"type": "array", "items": {"type": "object", "properties": {"task": {"$ref": "#/components/schemas/Sample"}, "annotation": {"$ref": "#/components/schemas/Annotation"}, "rubric": {"type": "object", "additionalProperties": true}, "review_mode": {"type": "string"}}}}, "training_executed": {"type": "boolean"}, "scope": {"type": "string"}}}}}}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "503": {"$ref": "#/components/responses/Error"}}}
    },
    "/api/v1/monitor": {
      "get": {"summary": "查看监控状态", "responses": {"200": {"description": "当前和后台检查状态", "content": {"application/json": {"schema": {"type": "object", "properties": {"current": {"type": "object", "additionalProperties": true}, "background": {"type": "object", "nullable": true, "additionalProperties": true}, "interval_seconds": {"type": "integer"}}}}}}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "503": {"$ref": "#/components/responses/Error"}}}
    },
    "/api/v1/evidence": {
      "post": {"summary": "上传截图证据", "description": "PNG、JPEG 或 WebP data URL；解码后最多 3000000 字节、1600 万像素，保存为 PNG。每账号最多 40 张、25 MB。", "parameters": [{"$ref": "#/components/parameters/Origin"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"type": "string", "description": "图片 data URL"}, "name": {"type": "string"}}}}}}, "responses": {"201": {"description": "证据已保存", "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "string"}, "url": {"type": "string"}, "sha256": {"type": "string"}, "name": {"type": "string"}}}}}}, "400": {"$ref": "#/components/responses/Error"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "413": {"$ref": "#/components/responses/Error"}, "503": {"$ref": "#/components/responses/Error"}}}
    },
    "/api/v1/evidence/{evidence_id}": {
      "get": {"summary": "读取截图证据", "description": "未提交截图仅上传者可见；提交后授权用户可读取。", "parameters": [{"name": "evidence_id", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "PNG 图片", "content": {"image/png": {"schema": {"type": "string", "format": "binary"}}}}, "206": {"description": "图片部分内容"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}, "416": {"description": "范围无效"}, "503": {"$ref": "#/components/responses/Error"}}}
    },
    "/api/v1/samples/{task_id}/annotation": {
      "post": {"summary": "提交样本标注", "description": "账号由服务端确定。正例需要所有适用维度通过；负例至少一个维度失败并提供理由或证据，视频失败还需起止秒数。待确认或排除需要理由或证据。已提交或批准的标注不能覆盖。", "parameters": [{"$ref": "#/components/parameters/TaskId"}, {"$ref": "#/components/parameters/Origin"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AnnotationRequest"}}}}, "responses": {"201": {"description": "标注已保存", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Annotation"}}}}, "400": {"$ref": "#/components/responses/Error"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}, "409": {"$ref": "#/components/responses/Error"}, "413": {"$ref": "#/components/responses/Error"}, "503": {"$ref": "#/components/responses/Error"}}}
    },
    "/api/v1/annotations/{annotation_id}/review": {
      "post": {"summary": "复核标注", "description": "必须由不同于标注者的授权账号复核；退回需填写理由。", "parameters": [{"name": "annotation_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/Origin"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["action"], "properties": {"action": {"type": "string", "enum": ["approve", "return"]}, "reason": {"type": "string", "description": "退回时必填，截取前 2000 字符"}}}}}}, "responses": {"200": {"description": "复核结果", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Annotation"}}}}, "400": {"$ref": "#/components/responses/Error"}, "401": {"$ref": "#/components/responses/Error"}, "403": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}, "409": {"$ref": "#/components/responses/Error"}, "413": {"$ref": "#/components/responses/Error"}, "503": {"$ref": "#/components/responses/Error"}}}
    }
  },
  "components": {
    "securitySchemes": {"sessionCookie": {"type": "apiKey", "in": "cookie", "name": "__Host-EmorikaUnified", "description": "现有登录会话 Cookie，并非 API Key；账号还需 Rubric 权限。"}},
    "parameters": {"TaskId": {"name": "task_id", "in": "path", "required": true, "schema": {"type": "string"}}, "Origin": {"name": "Origin", "in": "header", "required": true, "description": "来源的 host 必须与请求 Host 匹配。", "schema": {"type": "string"}}},
    "responses": {"Error": {"description": "请求失败，详情见 error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}, "login_url": {"type": "string"}}}}}}},
    "schemas": {
      "Rubric": {"type": "object", "properties": {"version": {"type": "string"}, "name": {"type": "string"}, "criteria": {"type": "array", "items": {"$ref": "#/components/schemas/Rule"}}, "published_at": {"type": "string"}, "published_by": {"type": "string"}}},
      "Rule": {"type": "object", "required": ["id", "title", "pass", "fail"], "properties": {"id": {"type": "string", "pattern": "^[a-z][a-z0-9_]{1,63}$", "description": "稳定且不重复的维度 ID；新增维度使用新的 ID，保留维度不更换 ID。"}, "title": {"type": "string", "maxLength": 100, "description": "纯文本名称，不能包含 <、> 或 &。"}, "pass": {"type": "string", "maxLength": 1000}, "fail": {"type": "string", "maxLength": 1000}, "scope": {"type": "string", "enum": ["all","image","video","reference"], "description": "图片和视频、仅图片、仅视频或有参考时。"}}},
      "RubricEdit": {"type": "object", "required": ["base_version", "criteria"], "properties": {"base_version": {"type": "string", "description": "编辑时的当前版本；过期返回 409。"}, "criteria": {"type": "array", "minItems": 1, "maxItems": 20, "description": "下一版本的完整维度列表。删除项只影响新版本；旧记录不变。", "items": {"$ref": "#/components/schemas/Rule"}}}},
      "Sample": {
        "type": "object",
        "description": "Console 样本。列表不返回 input、calls、compiled_prompt、translations、performance；详情和训练候选中的 task 包含这些原始字段。缺失值保留为 null。",
        "properties": {
          "task_id": {"type": "string", "description": "生成任务 ID，不是模型 Trace ID。"},
          "media_type": {"type": "string", "enum": ["image", "video"], "description": "样本类型：图片或视频。"},
          "title": {"type": "string", "description": "样本标题。"},
          "submitted_by": {"type": "string", "nullable": true, "description": "原始生成任务的提交者，不是标注者。"},
          "created_at": {"type": "string", "nullable": true, "description": "生成任务的原始创建时间。"},
          "completed_at": {"type": "string", "nullable": true, "description": "生成任务的原始完成时间。"},
          "status": {"type": "string", "description": "原始生成任务状态，与 annotation.status 分开。"},
          "source": {"type": "string", "description": "原始任务来源。"},
          "source_url": {"type": "string", "description": "控制台原始来源地址。"},
          "snapshot_evidence": {"type": "object", "description": "快照的来源证据。", "additionalProperties": true},
          "user_prompt": {"type": "string", "nullable": true, "description": "用户原话；未保存时为空，不用模型提示词替代。"},
          "user_language": {"type": "string", "description": "用户原话的语言。"},
          "context_summary": {"type": "object", "description": "人工整理的中文上下文摘录及字段来源。", "additionalProperties": true},
          "traces": {"type": "array", "description": "已记录的模型 Trace ID 等标识。", "items": {"type": "object", "additionalProperties": true}},
          "input": {"type": "object", "description": "完整生成参数，包括原始请求和参考素材地址。仅详情返回。", "additionalProperties": true},
          "compiled_prompt": {"type": "string", "nullable": true, "description": "实际模型提示词，与用户原话不同。仅详情返回。"},
          "translations": {"type": "object", "description": "对应原文的中文翻译。仅详情返回。", "additionalProperties": true},
          "reference": {"type": "array", "description": "生成时使用的参考素材。", "items": {"type": "object", "properties": {"role": {"type": "string", "description": "素材用途。"}, "url": {"type": "string", "description": "原始素材 URL。"}, "local": {"type": "string", "description": "需登录授权的本地预览路径。"}}, "additionalProperties": true}},
          "output": {"type": "object", "nullable": true, "description": "生成结果及地址；任务失败时可能为 null。", "properties": {"url": {"type": "string", "description": "提供商返回的原始结果 URL，可能已过期。"}, "local": {"type": "string", "description": "需授权的本地结果路径。"}, "preview": {"type": "string", "description": "需授权的视频兼容预览路径。"}, "poster": {"type": "string", "description": "预览封面路径。"}}, "additionalProperties": true},
          "performance": {"type": "object", "description": "记录的生成耗时、费用等数据。仅详情返回。", "additionalProperties": true},
          "calls": {"type": "array", "description": "逐次模型调用，包含原始 request、response、interactions 和 metadata。仅详情返回。", "items": {"type": "object", "additionalProperties": true}},
          "annotation": {"allOf": [{"$ref": "#/components/schemas/Annotation"}], "nullable": true, "description": "当前工作空间的最新标注；尚未标注为 null。"},
          "precheck": {"type": "object", "description": "技术预检，不用于自动通过或判负。score 为通过项 / 已核实项 × 100，未知项不计入；不是内容质量分。", "properties": {"kind": {"type": "string"}, "checked_at": {"type": "string"}, "score": {"type": "integer", "nullable": true, "minimum": 0, "maximum": 100}, "score_basis": {"type": "object", "properties": {"passed": {"type": "integer"}, "known": {"type": "integer"}, "unknown": {"type": "integer"}}}, "semantic_review": {"type": "string"}, "checks": {"type": "array", "items": {"type": "object", "additionalProperties": true}}, "evidence": {"type": "array", "items": {"type": "object", "additionalProperties": true}}, "note": {"type": "string"}}}
        },
        "additionalProperties": true
      },
      "Criterion": {"type": "object", "properties": {"result": {"type": "string", "enum": ["pass", "fail", "unassessed"]}, "reason": {"type": "string", "description": "截取前 3000 字符"}, "evidence_ids": {"type": "array", "items": {"type": "string"}}, "evidence_time": {"type": "array", "nullable": true, "description": "视频问题的起止秒数，满足 0 ≤ 开始 < 结束 ≤ 已记录的请求时长", "minItems": 2, "maxItems": 2, "items": {"type": "number"}}}},
      "AnnotationRequest": {"type": "object", "required": ["label"], "properties": {
        "rubric_version": {"type": "string", "description": "必须与当前版本相同。省略时视为 2.1；版本不符返回 409。"},
        "label": {"type": "string", "enum": ["positive", "negative", "uncertain", "excluded"]},
        "reason": {"type": "string", "description": "截取前 6000 字符"},
        "issues": {"type": "array", "description": "使用当前规则中的维度 ID；服务端也会从失败维度推导。", "items": {"type": "string"}},
        "attachments": {"type": "array", "maxItems": 4, "items": {"type": "object", "required": ["id"], "properties": {"id": {"type": "string"}, "name": {"type": "string"}}}},
        "confirmed": {"type": "boolean"},
        "criteria": {"type": "object", "description": "键为当前适用的维度 ID，包括新增维度。", "additionalProperties": {"$ref": "#/components/schemas/Criterion"}},
        "previous_id": {"type": "string", "nullable": true, "description": "最新标注 ID；首次提交为 null 或省略。"}
      }},
      "Annotation": {"type": "object", "description": "服务端保存的标注，账号由登录会话确定。", "properties": {"id": {"type": "string"}, "task_id": {"type": "string"}, "label": {"type": "string"}, "reason": {"type": "string"}, "issues": {"type": "array", "items": {"type": "string"}}, "attachments": {"type": "array", "items": {"type": "object", "additionalProperties": true}}, "criteria": {"type": "object", "additionalProperties": {"$ref": "#/components/schemas/Criterion"}}, "confirmed": {"type": "boolean"}, "actor": {"type": "object", "additionalProperties": true}, "reviewer": {"type": "string"}, "rubric_version": {"type": "string"}, "status": {"type": "string"}, "created_at": {"type": "string"}, "history": {"type": "array", "items": {"type": "object", "additionalProperties": true}}, "review_mode": {"type": "string"}, "previous_id": {"type": "string", "nullable": true}, "review_actor": {"type": "string"}, "review_note": {"type": "string"}, "reviewed_at": {"type": "string"}}, "additionalProperties": true}
    }
  }
}
