{"openapi":"3.0.0","info":{"title":"Blog Public API","version":"1.0.0","description":"公开站只读 REST（经 Service Binding 由 blog-public 调用）。\n读路径查询 Postgres VIEW；评论创建与 access-grant 兑换为受控写。\n大部分路由无需鉴权；写评论与受信校验需要 Bearer。\n\n可在 Scalar 文档顶部切换到 **Admin API** 规范；Servers 列表可在 `/api/public` 与 `/api/admin` 间切换试调基址。"},"servers":[{"url":"/api/admin","description":"Admin API（Bearer + RBAC）"},{"url":"/api/public","description":"Public API（公开站 / Service Binding）"}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Supabase Auth access_token（访客登录即可，不要求管理员）"}},"schemas":{},"parameters":{}},"paths":{"/skills":{"get":{"tags":["public"],"operationId":"listPublicSkills","parameters":[{"schema":{"type":"string","description":"按 skill_group 筛选"},"required":false,"description":"按 skill_group 筛选","name":"group","in":"query"}],"responses":{"200":{"description":"公开技能列表","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"name":{"type":"string","description":"技能名称"},"category":{"type":"string","nullable":true,"description":"技能分类"},"level":{"type":"string","nullable":true,"description":"熟练度"},"iconSlug":{"type":"string","nullable":true,"description":"Simple Icons slug"},"skillGroup":{"type":"string","enum":["base","library","framework"],"description":"首页展示分组"},"sortOrder":{"type":"integer","description":"排序"}},"required":["id","name","category","level","iconSlug","skillGroup","sortOrder"]}}},"required":["data"]}}}}}}},"/career":{"get":{"tags":["public"],"responses":{"200":{"description":"公开经历列表","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"company":{"type":"string"},"position":{"type":"string"},"businessScope":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","nullable":true,"format":"date"},"lat":{"type":"number","nullable":true},"lng":{"type":"number","nullable":true},"sortOrder":{"type":"integer"},"description":{"type":"string","nullable":true},"skills":{"type":"array","nullable":true,"items":{"type":"string"}}},"required":["id","company","position","businessScope","city","region","startDate","endDate","lat","lng","sortOrder","description","skills"]}}},"required":["data"]}}}}}}},"/projects":{"get":{"tags":["public"],"responses":{"200":{"description":"公开项目列表","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"title":{"type":"string"},"techStack":{"type":"string"},"description":{"type":"string"},"ctaText":{"type":"string"},"ctaLink":{"type":"string"},"iconKey":{"type":"string","nullable":true},"sortOrder":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","title","techStack","description","ctaText","ctaLink","iconKey","sortOrder","createdAt","updatedAt"]}}},"required":["data"]}}}}}}},"/feeds":{"get":{"tags":["public"],"responses":{"200":{"description":"已发布动态列表","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"title":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"content":{"type":"string"},"publishedAt":{"type":"string","nullable":true,"format":"date-time"},"coverImageUrl":{"type":"string","nullable":true},"coverStorageProvider":{"type":"string","nullable":true,"enum":["external","r2","supabase","minio",null]},"coverStorageKey":{"type":"string","nullable":true},"tags":{"type":"array","nullable":true,"items":{"type":"string"}},"sortOrder":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","title","summary","content","publishedAt","coverImageUrl","coverStorageProvider","coverStorageKey","tags","sortOrder","createdAt","updatedAt"]}}},"required":["data"]}}}}}}},"/feeds/{id}":{"get":{"tags":["public"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"资源 ID"},"required":true,"description":"资源 ID","name":"id","in":"path"}],"responses":{"200":{"description":"已发布动态详情","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"title":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"content":{"type":"string"},"publishedAt":{"type":"string","nullable":true,"format":"date-time"},"coverImageUrl":{"type":"string","nullable":true},"coverStorageProvider":{"type":"string","nullable":true,"enum":["external","r2","supabase","minio",null]},"coverStorageKey":{"type":"string","nullable":true},"tags":{"type":"array","nullable":true,"items":{"type":"string"}},"sortOrder":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","title","summary","content","publishedAt","coverImageUrl","coverStorageProvider","coverStorageKey","tags","sortOrder","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"未找到","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/site-plan-tasks":{"get":{"tags":["public"],"responses":{"200":{"description":"公开计划任务","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"notes":{"type":"string","nullable":true},"dueDate":{"type":"string","nullable":true,"format":"date"},"sortOrder":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","title","notes","dueDate","sortOrder","createdAt"]}}},"required":["data"]}}}}}}},"/dictionary/{code}/items":{"get":{"tags":["public"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"字典类型编码"},"required":true,"description":"字典类型编码","name":"code","in":"path"}],"responses":{"200":{"description":"公开字典选项","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"字典项键（itemKey）"},"label":{"type":"string","description":"展示标签（itemLabel）"},"value":{"type":"string","nullable":true,"description":"字典项值（itemValue）"},"isDefault":{"type":"boolean","description":"是否默认项"}},"required":["key","label","value","isDefault"]}}},"required":["data"]}}}}}}},"/comments":{"get":{"tags":["public"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"资源类型"},"required":true,"description":"资源类型","name":"resourceType","in":"query"},{"schema":{"type":"string","minLength":1,"description":"资源 ID"},"required":true,"description":"资源 ID","name":"resourceId","in":"query"}],"responses":{"200":{"description":"已通过评论","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"userId":{"type":"string","format":"uuid"},"body":{"type":"string"},"anchorExact":{"type":"string","nullable":true},"anchorPrefix":{"type":"string","nullable":true},"anchorSuffix":{"type":"string","nullable":true},"oauthClientId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","resourceType","resourceId","userId","body","anchorExact","anchorPrefix","anchorSuffix","oauthClientId","createdAt"]}}},"required":["data"]}}}}}},"post":{"tags":["public"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resourceType":{"type":"string","minLength":1,"description":"资源类型"},"resourceId":{"type":"string","minLength":1,"description":"资源 ID"},"body":{"type":"string","minLength":1,"maxLength":5000,"description":"评论正文"},"anchor":{"type":"object","properties":{"exact":{"type":"string","minLength":1,"maxLength":500,"description":"被选中的原文"},"prefix":{"type":"string","maxLength":64,"description":"选区前约 32 字符"},"suffix":{"type":"string","maxLength":64,"description":"选区后约 32 字符"}},"required":["exact"],"description":"可选划词锚点"}},"required":["resourceType","resourceId","body"]}}}},"responses":{"201":{"description":"提交成功（pending）","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"comment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"userId":{"type":"string","format":"uuid"},"body":{"type":"string"},"anchorExact":{"type":"string","nullable":true},"anchorPrefix":{"type":"string","nullable":true},"anchorSuffix":{"type":"string","nullable":true},"oauthClientId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","resourceType","resourceId","userId","body","anchorExact","anchorPrefix","anchorSuffix","oauthClientId","createdAt"]}},"required":["ok","comment"]}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}},"401":{"description":"未登录","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/auth/trusted":{"get":{"tags":["public"],"security":[{"Bearer":[]}],"responses":{"200":{"description":"当前 Bearer 是否为 site_admins 受信账号","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"trusted":{"type":"boolean","description":"是否为 site_admins 中的受信账号"},"userId":{"type":"string","nullable":true,"format":"uuid"}},"required":["trusted","userId"]}},"required":["data"]}}}},"401":{"description":"无效凭证","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/access-grants/{token}/redeem":{"post":{"tags":["public"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"分享令牌"},"required":true,"description":"分享令牌","name":"token","in":"path"}],"responses":{"200":{"description":"兑换成功","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"resourceType":{"type":"string"},"resourceId":{"type":"string"},"secretLevel":{"type":"integer"}},"required":["resourceType","resourceId","secretLevel"]}},"required":["data"]}}}},"401":{"description":"需要登录/受信","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}},"403":{"description":"无权访问","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}},"404":{"description":"无效链接","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}},"410":{"description":"过期或次数用尽","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}}}}