{"openapi":"3.1.0","info":{"title":"见闲 · 6v1 站点自用接口（说明性文档）","version":"1.0.0","summary":"本站接口为自用：无 API Key、不承诺对外稳定性、不作为公开能力接口。","description":"本站不提供读取或删除作答记录的端点；提交端点无鉴权、无 API Key。本文件为**说明性文档**，不是对外可调用契约（不含 SLA / 试用配额 / 版本兼容承诺）。响应带 Cache-Control: no-store；存在内存态限流。session_id 由客户端生成、不可枚举。"},"paths":{"/api/v1/question-set/current":{"get":{"summary":"题库只读副本","description":"返回当前题库版本、五维、19 题与四档量表；用于提交时的版本校验与服务端复算。","responses":{"200":{"description":"题库只读副本","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuestionSet"}}}},"405":{"description":"该端点不支持此 HTTP 方法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"服务暂时不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/subscriptions":{"post":{"summary":"提交订阅","description":"提交一个邮箱以订阅站点更新。同一邮箱重复提交不新增记录、不重复发送；响应不区分该邮箱是否已在列表中。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeRequest"}}}},"responses":{"200":{"description":"已记录","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeResponse"}}}},"400":{"description":"请求体非法（invalid_request / unknown_field）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"405":{"description":"该端点不支持此 HTTP 方法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"仅接受 application/json 请求体","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"请求过于频繁","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"服务暂时不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/subscriptions/confirmation":{"post":{"summary":"确认订阅","description":"用确认令牌完成订阅。令牌无效、已使用或超期时一律返回同一错误形态，不区分具体原因。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}},"responses":{"200":{"description":"已接受","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeResponse"}}}},"400":{"description":"请求体非法（invalid_request / unknown_field）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"405":{"description":"该端点不支持此 HTTP 方法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"仅接受 application/json 请求体","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"请求过于频繁","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"服务暂时不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/subscriptions/cancellation":{"post":{"summary":"退订","description":"用退订令牌取消订阅，立即生效、无需登录。令牌无效、已使用或超期时返回同一错误形态。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}},"responses":{"200":{"description":"已接受","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeResponse"}}}},"400":{"description":"请求体非法（invalid_request / unknown_field）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"405":{"description":"该端点不支持此 HTTP 方法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"仅接受 application/json 请求体","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"请求过于频繁","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"服务暂时不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/subscriptions/resends":{"post":{"summary":"重新发送订阅邮件","description":"重新发送与该邮箱相关的订阅邮件：尚未确认的补发确认信，已确认的补发退订入口信。响应与提交订阅逐字相同，不区分该邮箱是否存在及其订阅状态；限流比提交更严。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeRequest"}}}},"responses":{"200":{"description":"已记录","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeResponse"}}}},"400":{"description":"请求体非法（invalid_request / unknown_field）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"405":{"description":"该端点不支持此 HTTP 方法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"仅接受 application/json 请求体","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"请求过于频繁","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"服务暂时不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/sessions":{"post":{"summary":"提交一次完整作答","description":"提交 19 题所选项与客户端算得的测评结果。同一 session_id 重复提交不新增记录（幂等），提交时间锚点不刷新。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitSessionRequest"}}}},"responses":{"200":{"description":"已保存","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitSessionResponse"}}}},"400":{"description":"请求体非法（invalid_request / unknown_field）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"405":{"description":"该端点不支持此 HTTP 方法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"仅接受 application/json 请求体","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"请求过于频繁","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"服务暂时不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"schemas":{"ApiError":{"type":"object","properties":{"error":{"type":"string","description":"统一错误码（闭集，7 码）。not_found(404) 的触发条件是请求路径不存在（框架级未匹配路径）。","enum":["invalid_request","unknown_field","not_found","method_not_allowed","unsupported_media_type","rate_limited","unavailable"]},"message":{"type":"string","description":"错误说明（不含堆栈 / SQL / 表列名 / 内部路径）"}},"required":["error","message"]},"SubmitSessionRequest":{"type":"object","properties":{"session_id":{"type":"string","description":"客户端生成的会话标识（不可枚举）；服务端只校验、不生成"},"submitted_at":{"type":"string","description":"客户端提交时间；仅用于一致性比对，可缺省"},"duration_band":{"type":"string","description":"作答耗时分档（四档）"},"question_set_version":{"type":"string","description":"客户端题库版本；存在性不校验，落库并标记"},"client_build":{"type":"string","description":"页面构建版本（非个人信息）"},"answers":{"type":"object","description":"19 题所选项，键为 Q1..Q19，值 0..3；未声明键一律拒绝"},"result":{"$ref":"#/components/schemas/ClientResult"}},"required":["session_id","duration_band","question_set_version","client_build","answers","result"]},"ClientResult":{"type":"object","properties":{"d1":{"type":"number","description":"维度 D1 得分，取值 [0,1]"},"d2":{"type":"number","description":"维度 D2 得分，取值 [0,1]"},"d3":{"type":"number","description":"维度 D3 得分，取值 [0,1]"},"d4":{"type":"number","description":"维度 D4 得分，取值 [0,1]"},"d5":{"type":"number","description":"维度 D5 得分，取值 [0,1]"},"total":{"type":"number","description":"总分，取值 [0,1]"},"grade":{"type":"integer","description":"等级 1..5"},"degraded":{"type":"boolean","description":"是否触发最短木板降级"},"weakest_dims":{"type":"array","items":{"type":"string"},"description":"最弱维（空或 ≤5 个）"}},"required":["d1","d2","d3","d4","d5","total","grade","degraded","weakest_dims"]},"SubmitSessionResponse":{"type":"object","properties":{"status":{"type":"string","description":"恒为 saved"},"submitted_at":{"type":"string","description":"服务端首次接受的落库时间（分钟截断）；重复提交返回同一值"}},"required":["status","submitted_at"]},"SubscribeRequest":{"type":"object","properties":{"email":{"type":"string","description":"邮箱地址；同一邮箱重复提交不新增记录、不重复发送"}},"required":["email"]},"TokenRequest":{"type":"object","properties":{"token":{"type":"string","description":"确认或退订令牌；一次性，仅经请求体提交"}},"required":["token"]},"SubscribeResponse":{"type":"object","properties":{"status":{"type":"string","description":"固定取值：recorded 或 accepted"}},"required":["status"]},"Dimension":{"type":"object","properties":{"id":{"type":"string","description":"维度标识 D1..D5"},"name":{"type":"string","description":"维度中文名"}},"required":["id","name"]},"Question":{"type":"object","properties":{"id":{"type":"string","description":"题目标识 Q1..Q19"},"dim":{"type":"string","description":"所属维度"},"text":{"type":"string","description":"题干"},"evidence":{"type":"string","description":"证据提示"},"order":{"type":"integer","description":"题序"}},"required":["id","dim","text","evidence","order"]},"ScaleOption":{"type":"object","properties":{"value":{"type":"integer","description":"档位 0..3"},"label":{"type":"string","description":"档位文字"}},"required":["value","label"]},"QuestionSet":{"type":"object","properties":{"version":{"type":"string","description":"题库版本"},"dimensions":{"type":"array","items":{"$ref":"#/components/schemas/Dimension"}},"questions":{"type":"array","items":{"$ref":"#/components/schemas/Question"}},"scale":{"type":"array","items":{"$ref":"#/components/schemas/ScaleOption"}}},"required":["version","dimensions","questions","scale"]}}}}