{"openapi":"3.0.0","info":{"title":"Blog Admin API","version":"1.0.0","description":"独立部署的 Admin REST API（`api` Worker / `server-api` 包）。\n\n**鉴权**：所有业务路由需要 `Authorization: Bearer <supabase access_token>`（本地 JWKS 验签）。\n\n**约定**：校验失败返回 `{ error }`；列表/详情多为 `{ data }`；写操作常用 `{ ok: true }`。\n\n可在 Scalar 文档顶部切换到 **Public API** 规范；Servers 列表可在 `/api/admin` 与 `/api/public` 间切换试调基址。"},"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":{"RbacNavNodeV1":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"稳定节点 ID"},"kind":{"type":"string","enum":["group","view"]},"title":{"type":"string","minLength":1},"viewId":{"type":"string","format":"uuid"},"icon":{"type":"string","description":"Iconify 名，如 lucide:book-open"},"breadcrumb":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"patterns":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"相对 view.path 的 React Router 路径，空字符串表示列表页"},"crumbs":{"type":"array","items":{"type":"object","properties":{"labelTemplate":{"type":"string","minLength":1,"description":"面包屑文案模板"},"hrefTemplate":{"type":"string","minLength":1,"description":"可点链接的 URL template"}},"required":["labelTemplate"]},"minItems":1}},"required":["path","crumbs"]}}},"required":["version","patterns"]},"children":{"type":"array","items":{"$ref":"#/components/schemas/RbacNavNodeV1"}}},"required":["id","kind","title","children"]}},"parameters":{}},"paths":{"/me":{"get":{"operationId":"getMe","summary":"获取当前管理员信息","tags":["me"],"security":[{"Bearer":[]}],"responses":{"200":{"description":"当前管理员：permissions + views + nav","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","description":"Supabase Auth 用户 ID"},"email":{"type":"string","description":"登录邮箱"},"role":{"type":"string","description":"站点角色 code（= rbac_roles.code）"},"roleId":{"type":"string","format":"uuid","description":"本库 rbac_roles.id，仅用于本环境菜单/权限查询"},"bypassAll":{"type":"boolean","description":"是否跳过全部权限校验"},"permissions":{"type":"array","items":{"type":"string"},"description":"有效权限码列表"}},"required":["id","role","bypassAll","permissions"]},"views":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"View ID"},"code":{"type":"string","description":"View code"},"path":{"type":"string","description":"路由路径"},"name":{"type":"string","description":"显示名"}},"required":["id","code","path","name"]}},"nav":{"type":"object","properties":{"tree":{"type":"array","items":{"$ref":"#/components/schemas/RbacNavNodeV1"},"description":"侧栏/顶栏菜单树（已按权限过滤）"},"ui":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"suggestedPlacement":{"type":"string","enum":["side","top"]}},"required":["version"],"description":"导航 UI 建议"},"ungrouped":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"View ID"},"code":{"type":"string","description":"View code"},"path":{"type":"string","description":"路由路径"},"name":{"type":"string","description":"显示名"}},"required":["id","code","path","name"]},"description":"已勾选但未排进角色菜单树的页面"}},"required":["tree","ui","ungrouped"]}},"required":["user","views","nav"]}}}},"403":{"description":"非站点管理员","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/skills":{"get":{"tags":["skills"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","description":"按首页展示分组筛选（字典 skill_group_labels 的 key；省略则返回全部）"},"required":false,"description":"按首页展示分组筛选（字典 skill_group_labels 的 key；省略则返回全部）","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":"技能名称，例如 TypeScript、Astro"},"category":{"type":"string","nullable":true,"description":"技能分类，例如 前端、后端、全栈；用于分组展示与筛选"},"level":{"type":"string","nullable":true,"description":"熟练度等级，例如 熟练、了解"},"iconSlug":{"type":"string","nullable":true,"description":"Simple Icons 的 slug；常用拼接：https://cdn.simpleicons.org/{iconSlug}/ffffff"},"skillGroup":{"type":"string","enum":["base","library","framework"],"description":"首页展示分组：base（基础）/ library（库与生态）/ framework（框架）"},"sortOrder":{"type":"integer","description":"展示排序，越小越靠前"},"isEnabled":{"type":"boolean","description":"是否启用；false 时前端不展示"}},"required":["id","name","category","level","iconSlug","skillGroup","sortOrder","isEnabled"]},"description":"技能列表"}},"required":["data"]}}}}}},"post":{"tags":["skills"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"技能名称"},"skillGroup":{"type":"string","minLength":1,"description":"首页展示分组 key（对应字典 skill_group_labels）"},"category":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"技能分类"},"level":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"熟练度等级"},"iconSlug":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"Simple Icons slug"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"展示排序，越小越靠前"},"isEnabled":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"description":"是否启用"}},"required":["name","skillGroup"]}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"},"skillGroup":{"type":"string","description":"所属展示分组 key"}},"required":["ok","skillGroup"]}}}},"400":{"description":"创建失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/skills/{id}":{"get":{"tags":["skills"],"security":[{"Bearer":[]}],"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":"主键"},"name":{"type":"string","description":"技能名称，例如 TypeScript、Astro"},"category":{"type":"string","nullable":true,"description":"技能分类，例如 前端、后端、全栈；用于分组展示与筛选"},"level":{"type":"string","nullable":true,"description":"熟练度等级，例如 熟练、了解"},"iconSlug":{"type":"string","nullable":true,"description":"Simple Icons 的 slug；常用拼接：https://cdn.simpleicons.org/{iconSlug}/ffffff"},"skillGroup":{"type":"string","enum":["base","library","framework"],"description":"首页展示分组：base（基础）/ library（库与生态）/ framework（框架）"},"sortOrder":{"type":"integer","description":"展示排序，越小越靠前"},"isEnabled":{"type":"boolean","description":"是否启用；false 时前端不展示"}},"required":["id","name","category","level","iconSlug","skillGroup","sortOrder","isEnabled"],"description":"技能详情"}},"required":["data"]}}}},"404":{"description":"技能不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"patch":{"tags":["skills"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"技能 ID"},"required":true,"description":"技能 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"技能名称"},"skillGroup":{"type":"string","minLength":1,"description":"首页展示分组 key（对应字典 skill_group_labels）"},"category":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"技能分类"},"level":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"熟练度等级"},"iconSlug":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"Simple Icons slug"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"展示排序，越小越靠前"},"isEnabled":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"description":"是否启用"}},"required":["name","skillGroup"]}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"},"skillGroup":{"type":"string","description":"所属展示分组 key"}},"required":["ok","skillGroup"]}}}},"400":{"description":"更新失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"delete":{"tags":["skills"],"security":[{"Bearer":[]}],"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":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"删除失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/career":{"get":{"tags":["career"],"security":[{"Bearer":[]}],"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","description":"公司名称"},"position":{"type":"string","description":"职位"},"businessScope":{"type":"string","description":"工作内容/范围"},"city":{"type":"string","description":"城市"},"region":{"type":"string","description":"城市区域"},"startDate":{"type":"string","format":"date","description":"开始任职日期（ISO date，精确到天）"},"endDate":{"type":"string","nullable":true,"format":"date","description":"结束任职日期（ISO date；null 表示至今）"},"lat":{"type":"number","nullable":true,"description":"地图纬度（高德 GCJ-02，组件内会转为 WGS-84 供 Leaflet/OSM 使用）"},"lng":{"type":"number","nullable":true,"description":"地图经度（高德 GCJ-02）"},"sortOrder":{"type":"integer","description":"展示排序，越小越靠前（首页列表顺序）"},"hidden":{"type":"boolean","description":"是否隐藏该经历"},"description":{"type":"string","nullable":true,"description":"工作经历描述"},"skills":{"type":"array","nullable":true,"items":{"type":"string"},"description":"使用技术栈"}},"required":["id","company","position","businessScope","city","region","startDate","endDate","lat","lng","sortOrder","hidden","description","skills"]},"description":"职业经历列表"}},"required":["data"]}}}}}},"post":{"tags":["career"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"string","minLength":1,"description":"公司名称"},"position":{"type":"string","minLength":1,"description":"职位"},"businessScope":{"type":"string","minLength":1,"description":"工作内容/范围"},"city":{"type":"string","minLength":1,"description":"城市"},"region":{"type":"string","minLength":1,"description":"城市区域"},"startDate":{"type":"string","format":"date","description":"开始任职日期（YYYY-MM-DD）"},"endDate":{"anyOf":[{"type":"string","format":"date"},{"type":"string","enum":[""]},{"nullable":true}],"description":"结束任职日期（YYYY-MM-DD；空/null 表示至今）"},"lat":{"anyOf":[{"type":"number","nullable":true},{"type":"string","enum":[""]},{"nullable":true}],"description":"地图纬度（高德 GCJ-02）"},"lng":{"anyOf":[{"type":"number","nullable":true},{"type":"string","enum":[""]},{"nullable":true}],"description":"地图经度（高德 GCJ-02）"},"hidden":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"description":"是否隐藏该经历"},"description":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"工作经历描述"},"skills":{"type":"string","description":"使用技术栈（逗号分隔）"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"展示排序，越小越靠前"}},"required":["company","position","businessScope","city","region","startDate"]}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"创建失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/career/{id}":{"get":{"tags":["career"],"security":[{"Bearer":[]}],"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":"主键"},"company":{"type":"string","description":"公司名称"},"position":{"type":"string","description":"职位"},"businessScope":{"type":"string","description":"工作内容/范围"},"city":{"type":"string","description":"城市"},"region":{"type":"string","description":"城市区域"},"startDate":{"type":"string","format":"date","description":"开始任职日期（ISO date，精确到天）"},"endDate":{"type":"string","nullable":true,"format":"date","description":"结束任职日期（ISO date；null 表示至今）"},"lat":{"type":"number","nullable":true,"description":"地图纬度（高德 GCJ-02，组件内会转为 WGS-84 供 Leaflet/OSM 使用）"},"lng":{"type":"number","nullable":true,"description":"地图经度（高德 GCJ-02）"},"sortOrder":{"type":"integer","description":"展示排序，越小越靠前（首页列表顺序）"},"hidden":{"type":"boolean","description":"是否隐藏该经历"},"description":{"type":"string","nullable":true,"description":"工作经历描述"},"skills":{"type":"array","nullable":true,"items":{"type":"string"},"description":"使用技术栈"}},"required":["id","company","position","businessScope","city","region","startDate","endDate","lat","lng","sortOrder","hidden","description","skills"],"description":"职业经历详情"}},"required":["data"]}}}},"404":{"description":"职业经历不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"patch":{"tags":["career"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"职业经历 ID"},"required":true,"description":"职业经历 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"string","minLength":1,"description":"公司名称"},"position":{"type":"string","minLength":1,"description":"职位"},"businessScope":{"type":"string","minLength":1,"description":"工作内容/范围"},"city":{"type":"string","minLength":1,"description":"城市"},"region":{"type":"string","minLength":1,"description":"城市区域"},"startDate":{"type":"string","format":"date","description":"开始任职日期（YYYY-MM-DD）"},"endDate":{"anyOf":[{"type":"string","format":"date"},{"type":"string","enum":[""]},{"nullable":true}],"description":"结束任职日期（YYYY-MM-DD；空/null 表示至今）"},"lat":{"anyOf":[{"type":"number","nullable":true},{"type":"string","enum":[""]},{"nullable":true}],"description":"地图纬度（高德 GCJ-02）"},"lng":{"anyOf":[{"type":"number","nullable":true},{"type":"string","enum":[""]},{"nullable":true}],"description":"地图经度（高德 GCJ-02）"},"hidden":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"description":"是否隐藏该经历"},"description":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"工作经历描述"},"skills":{"type":"string","description":"使用技术栈（逗号分隔）"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"展示排序，越小越靠前"}},"required":["company","position","businessScope","city","region","startDate"]}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"更新失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"delete":{"tags":["career"],"security":[{"Bearer":[]}],"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":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"删除失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/projects":{"get":{"tags":["projects"],"security":[{"Bearer":[]}],"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","description":"项目标题"},"techStack":{"type":"string","description":"技术栈（展示用文本）"},"description":{"type":"string","description":"项目描述"},"ctaText":{"type":"string","description":"行动按钮文案"},"ctaLink":{"type":"string","description":"行动按钮链接"},"iconKey":{"type":"string","nullable":true,"description":"图标 key（可空）"},"sortOrder":{"type":"integer","description":"展示排序，越小越靠前"},"isEnabled":{"type":"boolean","description":"是否启用；false 时前端不展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","title","techStack","description","ctaText","ctaLink","iconKey","sortOrder","isEnabled","createdAt","updatedAt"]},"description":"项目列表"}},"required":["data"]}}}}}},"post":{"tags":["projects"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"项目标题"},"techStack":{"type":"string","minLength":1,"description":"技术栈（展示用文本）"},"description":{"type":"string","minLength":1,"description":"项目描述"},"ctaText":{"type":"string","minLength":1,"default":"查看详情","description":"行动按钮文案"},"ctaLink":{"type":"string","minLength":1,"default":"#","description":"行动按钮链接"},"iconKey":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"图标 key"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"展示排序，越小越靠前"},"isEnabled":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"description":"是否启用"}},"required":["title","techStack","description"]}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"创建失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/projects/{id}":{"get":{"tags":["projects"],"security":[{"Bearer":[]}],"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","description":"项目标题"},"techStack":{"type":"string","description":"技术栈（展示用文本）"},"description":{"type":"string","description":"项目描述"},"ctaText":{"type":"string","description":"行动按钮文案"},"ctaLink":{"type":"string","description":"行动按钮链接"},"iconKey":{"type":"string","nullable":true,"description":"图标 key（可空）"},"sortOrder":{"type":"integer","description":"展示排序，越小越靠前"},"isEnabled":{"type":"boolean","description":"是否启用；false 时前端不展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","title","techStack","description","ctaText","ctaLink","iconKey","sortOrder","isEnabled","createdAt","updatedAt"],"description":"项目详情"}},"required":["data"]}}}},"404":{"description":"项目不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"patch":{"tags":["projects"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"项目 ID"},"required":true,"description":"项目 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"项目标题"},"techStack":{"type":"string","minLength":1,"description":"技术栈（展示用文本）"},"description":{"type":"string","minLength":1,"description":"项目描述"},"ctaText":{"type":"string","minLength":1,"default":"查看详情","description":"行动按钮文案"},"ctaLink":{"type":"string","minLength":1,"default":"#","description":"行动按钮链接"},"iconKey":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"图标 key"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"展示排序，越小越靠前"},"isEnabled":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"description":"是否启用"}},"required":["title","techStack","description"]}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"更新失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"delete":{"tags":["projects"],"security":[{"Bearer":[]}],"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":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"删除失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/projects/delete-many":{"post":{"tags":["projects"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"description":"待删除的项目 ID 列表"}},"required":["ids"]}}}},"responses":{"200":{"description":"批量删除成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"},"count":{"type":"number","description":"删除条数"}},"required":["ok","count"]}}}},"400":{"description":"删除失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/posts":{"get":{"tags":["posts"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","enum":["draft","published","hidden","archived"],"description":"按状态筛选；省略则返回全部"},"required":false,"description":"按状态筛选；省略则返回全部","name":"status","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":"主键"},"title":{"type":"string","nullable":true,"description":"标题（可空）"},"summary":{"type":"string","nullable":true,"description":"摘要，用于列表页显示"},"content":{"type":"string","description":"正文（Markdown）"},"status":{"type":"string","enum":["draft","published","hidden","archived"],"description":"状态：draft / published / hidden / archived"},"publishedAt":{"type":"string","nullable":true,"format":"date-time","description":"发布时间（ISO 8601 UTC；草稿可为 null）"},"coverImageUrl":{"type":"string","nullable":true,"description":"封面图 URL（external 或解析后的绝对地址）"},"coverStorageProvider":{"type":"string","nullable":true,"enum":["external","r2","supabase","minio",null],"description":"封面存储后端：external / r2 / supabase / minio"},"coverStorageKey":{"type":"string","nullable":true,"description":"封面对象 key（R2 等）"},"tags":{"type":"array","nullable":true,"items":{"type":"string"},"description":"标签列表"},"externalProvider":{"type":"string","nullable":true,"description":"外部动态提供商"},"externalId":{"type":"string","nullable":true,"description":"外部提供商侧用户/内容 ID"},"syncedAt":{"type":"string","nullable":true,"format":"date-time","description":"从外部平台同步到本站的时间（ISO 8601 UTC）"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","title","summary","content","status","publishedAt","coverImageUrl","coverStorageProvider","coverStorageKey","tags","externalProvider","externalId","syncedAt","sortOrder","createdAt","updatedAt"]},"description":"动态列表"}},"required":["data"]}}}}}},"post":{"tags":["posts"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"动态 ID（创建时可省略）"},"title":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"标题"},"summary":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"摘要"},"content":{"type":"string","minLength":1,"description":"正文（Markdown）"},"status":{"type":"string","enum":["draft","published","hidden","archived"],"description":"状态：draft / published / hidden / archived"},"publishedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","enum":[""]},{"nullable":true}],"description":"发布时间（ISO 8601 UTC；通常由服务端按状态推导）"},"coverImageUrl":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"封面图 URL"},"coverStorageProvider":{"type":"string","nullable":true,"enum":["external","r2","supabase","minio",null],"description":"封面存储后端"},"coverStorageKey":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"封面对象 key"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":30},"maxItems":20,"default":[],"description":"标签列表"},"sortOrder":{"type":"integer","nullable":true,"description":"排序值，越小越靠前"}},"required":["content","status"]}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"创建失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/posts/{id}":{"get":{"tags":["posts"],"security":[{"Bearer":[]}],"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,"description":"标题（可空）"},"summary":{"type":"string","nullable":true,"description":"摘要，用于列表页显示"},"content":{"type":"string","description":"正文（Markdown）"},"status":{"type":"string","enum":["draft","published","hidden","archived"],"description":"状态：draft / published / hidden / archived"},"publishedAt":{"type":"string","nullable":true,"format":"date-time","description":"发布时间（ISO 8601 UTC；草稿可为 null）"},"coverImageUrl":{"type":"string","nullable":true,"description":"封面图 URL（external 或解析后的绝对地址）"},"coverStorageProvider":{"type":"string","nullable":true,"enum":["external","r2","supabase","minio",null],"description":"封面存储后端：external / r2 / supabase / minio"},"coverStorageKey":{"type":"string","nullable":true,"description":"封面对象 key（R2 等）"},"tags":{"type":"array","nullable":true,"items":{"type":"string"},"description":"标签列表"},"externalProvider":{"type":"string","nullable":true,"description":"外部动态提供商"},"externalId":{"type":"string","nullable":true,"description":"外部提供商侧用户/内容 ID"},"syncedAt":{"type":"string","nullable":true,"format":"date-time","description":"从外部平台同步到本站的时间（ISO 8601 UTC）"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","title","summary","content","status","publishedAt","coverImageUrl","coverStorageProvider","coverStorageKey","tags","externalProvider","externalId","syncedAt","sortOrder","createdAt","updatedAt"],"description":"动态详情"}},"required":["data"]}}}},"404":{"description":"动态不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"patch":{"tags":["posts"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"动态 ID"},"required":true,"description":"动态 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"动态 ID（创建时可省略）"},"title":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"标题"},"summary":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"摘要"},"content":{"type":"string","minLength":1,"description":"正文（Markdown）"},"status":{"type":"string","enum":["draft","published","hidden","archived"],"description":"状态：draft / published / hidden / archived"},"publishedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","enum":[""]},{"nullable":true}],"description":"发布时间（ISO 8601 UTC；通常由服务端按状态推导）"},"coverImageUrl":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"封面图 URL"},"coverStorageProvider":{"type":"string","nullable":true,"enum":["external","r2","supabase","minio",null],"description":"封面存储后端"},"coverStorageKey":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"封面对象 key"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":30},"maxItems":20,"default":[],"description":"标签列表"},"sortOrder":{"type":"integer","nullable":true,"description":"排序值，越小越靠前"}},"required":["content","status"]},{"type":"object","properties":{"status":{"type":"string","enum":["draft","published","hidden","archived"],"description":"目标状态"}},"required":["status"]}]}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"更新失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"delete":{"tags":["posts"],"security":[{"Bearer":[]}],"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":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"删除失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/dictionary/types":{"get":{"tags":["dictionary"],"security":[{"Bearer":[]}],"responses":{"200":{"description":"字典类型列表","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"code":{"type":"string","description":"字典类型编码（小写蛇形，机器可读）"},"name":{"type":"string","description":"字典类型名称（面向业务/后台）"},"description":{"type":"string","nullable":true,"description":"业务描述"},"isBuiltin":{"type":"boolean","description":"是否系统内置（不建议直接删除）"},"isEnabled":{"type":"boolean","description":"是否启用"},"sortOrder":{"type":"integer","description":"展示排序，越小越靠前"},"remark":{"type":"string","nullable":true,"description":"备注"},"meta":{"nullable":true,"description":"扩展元信息（JSON）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","code","name","description","isBuiltin","isEnabled","sortOrder","remark","createdAt","updatedAt"]},"description":"字典类型列表"}},"required":["data"]}}}}}},"post":{"tags":["dictionary"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"pattern":"^[a-z][a-z0-9_]*$","description":"字典类型编码"},"name":{"type":"string","minLength":1,"description":"字典类型名称"},"description":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"业务描述"},"isBuiltin":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"description":"是否系统内置"},"isEnabled":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"description":"是否启用"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"展示排序"},"remark":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"备注"}},"required":["code","name"]}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"创建失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/dictionary/types/{id}":{"patch":{"tags":["dictionary"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"资源 ID"},"required":true,"description":"资源 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"pattern":"^[a-z][a-z0-9_]*$","description":"字典类型编码"},"name":{"type":"string","minLength":1,"description":"字典类型名称"},"description":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"业务描述"},"isBuiltin":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"description":"是否系统内置"},"isEnabled":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"description":"是否启用"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"展示排序"},"remark":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"备注"}},"required":["code","name"]}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"更新失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"delete":{"tags":["dictionary"],"security":[{"Bearer":[]}],"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":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"删除失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/dictionary/items":{"get":{"tags":["dictionary"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"字典类型 ID"},"required":true,"description":"字典类型 ID","name":"typeId","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":"主键"},"typeId":{"type":"string","format":"uuid","description":"所属字典类型 ID"},"itemKey":{"type":"string","description":"字典项键（同 typeId 下唯一，机器可读）"},"itemLabel":{"type":"string","description":"字典项标签（展示文案）"},"itemValue":{"type":"string","nullable":true,"description":"字典项值（可对接外部编码）"},"itemExtra":{"nullable":true,"description":"扩展展示信息（颜色/图标等 JSON）"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父节点 ID（扁平字典为 null）"},"nodeKind":{"type":"string","enum":["group","value"],"description":"节点种类：group=仅组织；value=可引用叶子"},"path":{"type":"string","description":"物化路径，如 /skilled/"},"isDefault":{"type":"boolean","description":"是否默认项"},"isEnabled":{"type":"boolean","description":"是否启用"},"sortOrder":{"type":"integer","description":"展示排序，越小越靠前"},"effectiveFrom":{"type":"string","nullable":true,"format":"date-time","description":"生效开始时间（ISO 8601 UTC）"},"effectiveTo":{"type":"string","nullable":true,"format":"date-time","description":"生效结束时间（ISO 8601 UTC）；null 表示长期有效"},"remark":{"type":"string","nullable":true,"description":"备注"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","typeId","itemKey","itemLabel","itemValue","parentId","nodeKind","path","isDefault","isEnabled","sortOrder","effectiveFrom","effectiveTo","remark","createdAt","updatedAt"]},"description":"字典项列表"}},"required":["data"]}}}},"400":{"description":"缺少 typeId","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"post":{"tags":["dictionary"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true},"description":"单条创建用 dictItemFormSchema 字段；批量可用 items 数组，或 itemsJson/bulkText（dictItemsBulkFormSchema）"}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"count":{"type":"number"}},"required":["ok"]}}}},"400":{"description":"创建失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/dictionary/items/{id}":{"patch":{"tags":["dictionary"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"资源 ID"},"required":true,"description":"资源 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"typeId":{"type":"string","format":"uuid","description":"所属字典类型 ID"},"itemKey":{"type":"string","minLength":1,"description":"字典项键"},"itemLabel":{"type":"string","minLength":1,"description":"字典项标签"},"itemValue":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"字典项值"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父节点 ID"},"nodeKind":{"type":"string","enum":["group","value"],"default":"value","description":"节点种类"},"path":{"type":"string","description":"物化路径；省略时默认 /{itemKey}/"},"isDefault":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"description":"是否默认项"},"isEnabled":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"description":"是否启用"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"展示排序"},"remark":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"备注"}},"required":["typeId","itemKey","itemLabel"]}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"更新失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"delete":{"tags":["dictionary"],"security":[{"Bearer":[]}],"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":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"删除失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/dictionary/export":{"get":{"tags":["dictionary"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","enum":["json","jsonc","csv"]},"required":true,"name":"format","in":"query"},{"schema":{"type":"string"},"required":false,"name":"codes","in":"query"}],"responses":{"200":{"description":"导出文件"},"400":{"description":"参数错误","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/dictionary/import/preview":{"post":{"tags":["dictionary"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","enum":["json","jsonc","csv"],"description":"导入文件格式"},"content":{"type":"string","minLength":1,"maxLength":10485760,"description":"文件文本内容"}},"required":["format","content"]}}}},"responses":{"200":{"description":"导入预览","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"nullable":true,"description":"响应数据（导入预览/结果等）"}}}}}},"400":{"description":"预览失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/dictionary/import/confirm":{"post":{"tags":["dictionary"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","enum":["json","jsonc","csv"],"description":"导入文件格式"},"content":{"type":"string","minLength":1,"maxLength":10485760,"description":"文件文本内容"}},"required":["format","content"]}}}},"responses":{"200":{"description":"导入完成","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"nullable":true,"description":"响应数据（导入预览/结果等）"}}}}}},"400":{"description":"导入失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/dictionary/by-code/{code}/items":{"get":{"tags":["dictionary"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"字典类型编码，如 skill_group_labels"},"required":true,"description":"字典类型编码，如 skill_group_labels","name":"code","in":"path"}],"responses":{"200":{"description":"按类型编码列出启用的字典项（仅 value 叶子）","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"]},"description":"启用中的字典选项"}},"required":["data"]}}}}}}},"/todos/lists":{"get":{"tags":["todos"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","description":"传 \"true\" 时包含已归档列表"},"required":false,"description":"传 \"true\" 时包含已归档列表","name":"includeArchived","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":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"]},"description":"待办列表清单"}},"required":["data"]}}}}}},"post":{"tags":["todos"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"列表名称"},"description":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"列表描述"},"color":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"颜色标识"},"icon":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"图标 slug"},"sortOrder":{"type":"integer","nullable":true,"description":"排序值"},"isArchived":{"type":"boolean","nullable":true,"description":"是否归档"},"isPublic":{"type":"boolean","nullable":true,"description":"是否公开展示"}},"required":["title"]}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"},"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID；null 为一级分组，非空为二级分组"},"title":{"type":"string","description":"分组名称"},"isFolder":{"type":"boolean","description":"是否为逻辑分组文件夹（不可挂任务）"},"sortOrder":{"type":"integer","description":"排序值"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","listId","parentId","title","isFolder","sortOrder","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","description":"步骤描述"},"isCompleted":{"type":"boolean","description":"是否已完成"},"sortOrder":{"type":"integer","description":"同任务内排序值"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","taskId","title","isCompleted","sortOrder","completedAt","createdAt"]}],"description":"写入后的实体（部分接口返回）"}},"required":["ok"]}}}},"400":{"description":"创建失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/todos/lists/{id}":{"get":{"tags":["todos"],"security":[{"Bearer":[]}],"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":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"],"description":"待办列表详情"}},"required":["data"]}}}},"404":{"description":"列表不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"patch":{"tags":["todos"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"资源 ID"},"required":true,"description":"资源 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"列表名称"},"description":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"列表描述"},"color":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"颜色标识"},"icon":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"图标 slug"},"sortOrder":{"type":"integer","nullable":true,"description":"排序值"},"isArchived":{"type":"boolean","nullable":true,"description":"是否归档"},"isPublic":{"type":"boolean","nullable":true,"description":"是否公开展示"}},"required":["title"]}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"},"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID；null 为一级分组，非空为二级分组"},"title":{"type":"string","description":"分组名称"},"isFolder":{"type":"boolean","description":"是否为逻辑分组文件夹（不可挂任务）"},"sortOrder":{"type":"integer","description":"排序值"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","listId","parentId","title","isFolder","sortOrder","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","description":"步骤描述"},"isCompleted":{"type":"boolean","description":"是否已完成"},"sortOrder":{"type":"integer","description":"同任务内排序值"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","taskId","title","isCompleted","sortOrder","completedAt","createdAt"]}],"description":"写入后的实体（部分接口返回）"}},"required":["ok"]}}}},"400":{"description":"更新失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"delete":{"tags":["todos"],"security":[{"Bearer":[]}],"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":{"ok":{"type":"boolean","description":"是否成功"},"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID；null 为一级分组，非空为二级分组"},"title":{"type":"string","description":"分组名称"},"isFolder":{"type":"boolean","description":"是否为逻辑分组文件夹（不可挂任务）"},"sortOrder":{"type":"integer","description":"排序值"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","listId","parentId","title","isFolder","sortOrder","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","description":"步骤描述"},"isCompleted":{"type":"boolean","description":"是否已完成"},"sortOrder":{"type":"integer","description":"同任务内排序值"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","taskId","title","isCompleted","sortOrder","completedAt","createdAt"]}],"description":"写入后的实体（部分接口返回）"}},"required":["ok"]}}}},"400":{"description":"删除失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/todos/groups":{"get":{"tags":["todos"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"所属列表 ID"},"required":true,"description":"所属列表 ID","name":"listId","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":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID；null 为一级分组，非空为二级分组"},"title":{"type":"string","description":"分组名称"},"isFolder":{"type":"boolean","description":"是否为逻辑分组文件夹（不可挂任务）"},"sortOrder":{"type":"integer","description":"排序值"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","listId","parentId","title","isFolder","sortOrder","createdAt","updatedAt"]},"description":"分组列表（扁平，含两级）"}},"required":["data"]}}}},"400":{"description":"查询失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"post":{"tags":["todos"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"父分组 ID；空表示一级；非空时父级须为文件夹"},"title":{"type":"string","minLength":1,"description":"分组名称"},"isFolder":{"type":"boolean","nullable":true,"description":"是否为文件夹"},"sortOrder":{"type":"integer","nullable":true,"description":"排序值"}},"required":["listId","title"]}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"},"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID；null 为一级分组，非空为二级分组"},"title":{"type":"string","description":"分组名称"},"isFolder":{"type":"boolean","description":"是否为逻辑分组文件夹（不可挂任务）"},"sortOrder":{"type":"integer","description":"排序值"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","listId","parentId","title","isFolder","sortOrder","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","description":"步骤描述"},"isCompleted":{"type":"boolean","description":"是否已完成"},"sortOrder":{"type":"integer","description":"同任务内排序值"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","taskId","title","isCompleted","sortOrder","completedAt","createdAt"]}],"description":"写入后的实体（部分接口返回）"}},"required":["ok"]}}}},"400":{"description":"创建失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/todos/groups/{id}":{"patch":{"tags":["todos"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"资源 ID"},"required":true,"description":"资源 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"分组名称"},"sortOrder":{"type":"integer","nullable":true,"description":"排序值"}},"required":["title"]}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"},"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID；null 为一级分组，非空为二级分组"},"title":{"type":"string","description":"分组名称"},"isFolder":{"type":"boolean","description":"是否为逻辑分组文件夹（不可挂任务）"},"sortOrder":{"type":"integer","description":"排序值"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","listId","parentId","title","isFolder","sortOrder","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","description":"步骤描述"},"isCompleted":{"type":"boolean","description":"是否已完成"},"sortOrder":{"type":"integer","description":"同任务内排序值"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","taskId","title","isCompleted","sortOrder","completedAt","createdAt"]}],"description":"写入后的实体（部分接口返回）"}},"required":["ok"]}}}},"400":{"description":"更新失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"delete":{"tags":["todos"],"security":[{"Bearer":[]}],"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":{"ok":{"type":"boolean","description":"是否成功"},"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID；null 为一级分组，非空为二级分组"},"title":{"type":"string","description":"分组名称"},"isFolder":{"type":"boolean","description":"是否为逻辑分组文件夹（不可挂任务）"},"sortOrder":{"type":"integer","description":"排序值"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","listId","parentId","title","isFolder","sortOrder","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","description":"步骤描述"},"isCompleted":{"type":"boolean","description":"是否已完成"},"sortOrder":{"type":"integer","description":"同任务内排序值"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","taskId","title","isCompleted","sortOrder","completedAt","createdAt"]}],"description":"写入后的实体（部分接口返回）"}},"required":["ok"]}}}},"400":{"description":"删除失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/todos/tasks":{"get":{"tags":["todos"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"叶子分组 ID"},"required":true,"description":"叶子分组 ID","name":"groupId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"completed","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":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"]},"description":"任务列表"}},"required":["data"]}}}},"400":{"description":"查询失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"post":{"tags":["todos"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"title":{"type":"string","minLength":1,"description":"任务标题"},"notes":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"备注"},"isImportant":{"type":"boolean","nullable":true,"description":"是否重要"},"dueDate":{"anyOf":[{"type":"string","format":"date"},{"type":"string","enum":[""]},{"nullable":true}],"description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"截止时刻"},"reminderAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","enum":[""]},{"nullable":true}],"description":"提醒时间（ISO 8601 UTC）"},"sortOrder":{"type":"integer","nullable":true,"description":"排序值"},"isPublic":{"type":"boolean","nullable":true,"description":"是否公开展示"},"recurrenceRule":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"重复规则（RRULE）"},"recurrenceMasterId":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"重复系列主任务 ID"}},"required":["groupId","title"]}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"},"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID；null 为一级分组，非空为二级分组"},"title":{"type":"string","description":"分组名称"},"isFolder":{"type":"boolean","description":"是否为逻辑分组文件夹（不可挂任务）"},"sortOrder":{"type":"integer","description":"排序值"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","listId","parentId","title","isFolder","sortOrder","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","description":"步骤描述"},"isCompleted":{"type":"boolean","description":"是否已完成"},"sortOrder":{"type":"integer","description":"同任务内排序值"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","taskId","title","isCompleted","sortOrder","completedAt","createdAt"]}],"description":"写入后的实体（部分接口返回）"}},"required":["ok"]}}}},"400":{"description":"创建失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/todos/tasks/{id}":{"get":{"tags":["todos"],"security":[{"Bearer":[]}],"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":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"],"description":"任务详情"}},"required":["data"]}}}},"404":{"description":"任务不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"patch":{"tags":["todos"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"资源 ID"},"required":true,"description":"资源 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"title":{"type":"string","minLength":1,"description":"任务标题"},"notes":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"备注"},"isImportant":{"type":"boolean","nullable":true,"description":"是否重要"},"dueDate":{"anyOf":[{"type":"string","format":"date"},{"type":"string","enum":[""]},{"nullable":true}],"description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"截止时刻"},"reminderAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","enum":[""]},{"nullable":true}],"description":"提醒时间（ISO 8601 UTC）"},"sortOrder":{"type":"integer","nullable":true,"description":"排序值"},"isPublic":{"type":"boolean","nullable":true,"description":"是否公开展示"},"recurrenceRule":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"重复规则（RRULE）"},"recurrenceMasterId":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"重复系列主任务 ID"}},"required":["groupId","title"]}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"},"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID；null 为一级分组，非空为二级分组"},"title":{"type":"string","description":"分组名称"},"isFolder":{"type":"boolean","description":"是否为逻辑分组文件夹（不可挂任务）"},"sortOrder":{"type":"integer","description":"排序值"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","listId","parentId","title","isFolder","sortOrder","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","description":"步骤描述"},"isCompleted":{"type":"boolean","description":"是否已完成"},"sortOrder":{"type":"integer","description":"同任务内排序值"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","taskId","title","isCompleted","sortOrder","completedAt","createdAt"]}],"description":"写入后的实体（部分接口返回）"}},"required":["ok"]}}}},"400":{"description":"更新失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"delete":{"tags":["todos"],"security":[{"Bearer":[]}],"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":{"ok":{"type":"boolean","description":"是否成功"},"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID；null 为一级分组，非空为二级分组"},"title":{"type":"string","description":"分组名称"},"isFolder":{"type":"boolean","description":"是否为逻辑分组文件夹（不可挂任务）"},"sortOrder":{"type":"integer","description":"排序值"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","listId","parentId","title","isFolder","sortOrder","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","description":"步骤描述"},"isCompleted":{"type":"boolean","description":"是否已完成"},"sortOrder":{"type":"integer","description":"同任务内排序值"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","taskId","title","isCompleted","sortOrder","completedAt","createdAt"]}],"description":"写入后的实体（部分接口返回）"}},"required":["ok"]}}}},"400":{"description":"删除失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/todos/tasks/{id}/complete":{"post":{"tags":["todos"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"资源 ID"},"required":true,"description":"资源 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"completed":{"type":"boolean"}},"required":["completed"]}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"},"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID；null 为一级分组，非空为二级分组"},"title":{"type":"string","description":"分组名称"},"isFolder":{"type":"boolean","description":"是否为逻辑分组文件夹（不可挂任务）"},"sortOrder":{"type":"integer","description":"排序值"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","listId","parentId","title","isFolder","sortOrder","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","description":"步骤描述"},"isCompleted":{"type":"boolean","description":"是否已完成"},"sortOrder":{"type":"integer","description":"同任务内排序值"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","taskId","title","isCompleted","sortOrder","completedAt","createdAt"]}],"description":"写入后的实体（部分接口返回）"}},"required":["ok"]}}}},"400":{"description":"更新失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/todos/steps":{"get":{"tags":["todos"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"taskId","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":"主键"},"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","description":"步骤描述"},"isCompleted":{"type":"boolean","description":"是否已完成"},"sortOrder":{"type":"integer","description":"同任务内排序值"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","taskId","title","isCompleted","sortOrder","completedAt","createdAt"]},"description":"步骤列表"}},"required":["data"]}}}},"400":{"description":"查询失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"post":{"tags":["todos"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","minLength":1,"description":"步骤描述"},"isCompleted":{"type":"boolean","nullable":true,"description":"是否已完成"},"sortOrder":{"type":"integer","nullable":true,"description":"排序值"}},"required":["taskId","title"]}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"},"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID；null 为一级分组，非空为二级分组"},"title":{"type":"string","description":"分组名称"},"isFolder":{"type":"boolean","description":"是否为逻辑分组文件夹（不可挂任务）"},"sortOrder":{"type":"integer","description":"排序值"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","listId","parentId","title","isFolder","sortOrder","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","description":"步骤描述"},"isCompleted":{"type":"boolean","description":"是否已完成"},"sortOrder":{"type":"integer","description":"同任务内排序值"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","taskId","title","isCompleted","sortOrder","completedAt","createdAt"]}],"description":"写入后的实体（部分接口返回）"}},"required":["ok"]}}}},"400":{"description":"创建失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/todos/steps/{id}":{"patch":{"tags":["todos"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"资源 ID"},"required":true,"description":"资源 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"步骤描述"},"isCompleted":{"type":"boolean","nullable":true,"description":"是否已完成"},"sortOrder":{"type":"integer","nullable":true,"description":"排序值"}},"required":["title"]}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"},"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID；null 为一级分组，非空为二级分组"},"title":{"type":"string","description":"分组名称"},"isFolder":{"type":"boolean","description":"是否为逻辑分组文件夹（不可挂任务）"},"sortOrder":{"type":"integer","description":"排序值"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","listId","parentId","title","isFolder","sortOrder","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","description":"步骤描述"},"isCompleted":{"type":"boolean","description":"是否已完成"},"sortOrder":{"type":"integer","description":"同任务内排序值"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","taskId","title","isCompleted","sortOrder","completedAt","createdAt"]}],"description":"写入后的实体（部分接口返回）"}},"required":["ok"]}}}},"400":{"description":"更新失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"delete":{"tags":["todos"],"security":[{"Bearer":[]}],"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":{"ok":{"type":"boolean","description":"是否成功"},"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户（Supabase Auth uid）"},"title":{"type":"string","description":"列表名称"},"description":{"type":"string","nullable":true,"description":"列表描述"},"color":{"type":"string","nullable":true,"description":"颜色标识"},"icon":{"type":"string","nullable":true,"description":"图标 slug"},"sortOrder":{"type":"integer","description":"排序值，越小越靠前"},"isArchived":{"type":"boolean","description":"是否归档"},"isPublic":{"type":"boolean","description":"是否公开展示"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","title","description","color","icon","sortOrder","isArchived","isPublic","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"listId":{"type":"string","format":"uuid","description":"所属列表 ID"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID；null 为一级分组，非空为二级分组"},"title":{"type":"string","description":"分组名称"},"isFolder":{"type":"boolean","description":"是否为逻辑分组文件夹（不可挂任务）"},"sortOrder":{"type":"integer","description":"排序值"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","userId","listId","parentId","title","isFolder","sortOrder","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"groupId":{"type":"string","format":"uuid","description":"所属叶子分组 ID"},"userId":{"type":"string","format":"uuid","description":"所属用户"},"title":{"type":"string","description":"任务标题"},"notes":{"type":"string","nullable":true,"description":"备注（Markdown）"},"isImportant":{"type":"boolean","description":"是否标记为重要"},"dueDate":{"type":"string","nullable":true,"format":"date","description":"截止日期（ISO date YYYY-MM-DD）"},"dueTime":{"type":"string","nullable":true,"description":"截止时刻，如 09:00"},"reminderAt":{"type":"string","nullable":true,"format":"date-time","description":"提醒时间（ISO 8601 UTC）"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）；非空即已完成"},"sortOrder":{"type":"integer","description":"排序值"},"isPublic":{"type":"boolean","description":"是否公开展示"},"recurrenceRule":{"type":"string","nullable":true,"description":"重复规则（iCal RRULE）"},"recurrenceMasterId":{"type":"string","nullable":true,"format":"uuid","description":"重复系列主任务 ID"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","groupId","userId","title","notes","isImportant","dueDate","dueTime","reminderAt","completedAt","sortOrder","isPublic","recurrenceRule","recurrenceMasterId","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"taskId":{"type":"string","format":"uuid","description":"所属任务 ID"},"title":{"type":"string","description":"步骤描述"},"isCompleted":{"type":"boolean","description":"是否已完成"},"sortOrder":{"type":"integer","description":"同任务内排序值"},"completedAt":{"type":"string","nullable":true,"format":"date-time","description":"完成时间（ISO 8601 UTC）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","taskId","title","isCompleted","sortOrder","completedAt","createdAt"]}],"description":"写入后的实体（部分接口返回）"}},"required":["ok"]}}}},"400":{"description":"删除失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/comments":{"get":{"tags":["comments"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","description":"按资源类型筛选"},"required":false,"description":"按资源类型筛选","name":"resourceType","in":"query"},{"schema":{"type":"string","description":"按资源 ID 筛选"},"required":false,"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","description":"主键"},"resourceType":{"type":"string","description":"被评论资源类型，例如 blog / feed"},"resourceId":{"type":"string","description":"被评论资源 ID（blog 用 slug）"},"userId":{"type":"string","format":"uuid","description":"评论作者（Supabase Auth uid）"},"body":{"type":"string","description":"评论正文"},"status":{"type":"string","enum":["pending","approved","hidden"],"description":"审核状态：pending / approved / hidden"},"anchorExact":{"type":"string","nullable":true,"description":"划词原文；空=整篇评论"},"anchorPrefix":{"type":"string","nullable":true,"description":"选区前缀"},"anchorSuffix":{"type":"string","nullable":true,"description":"选区后缀"},"oauthClientId":{"type":"string","nullable":true,"description":"OAuth 客户端 ID；空=站内发表"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","resourceType","resourceId","userId","body","status","anchorExact","anchorPrefix","anchorSuffix","oauthClientId","createdAt"]},"description":"评论列表"}},"required":["data"]}}}}}},"patch":{"tags":["comments"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"评论 ID"},"status":{"type":"string","enum":["pending","approved","hidden"],"description":"目标审核状态"}},"required":["id","status"]}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"更新失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"delete":{"tags":["comments"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"评论 ID"},"required":true,"description":"评论 ID","name":"id","in":"query"}],"responses":{"200":{"description":"删除成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"删除失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/access-grants":{"get":{"description":"获取访问授权列表","tags":["access-grants"],"security":[{"Bearer":[]}],"responses":{"200":{"description":"访问授权列表","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"token":{"type":"string","description":"访问令牌（用于生成分享链接）"},"resourceType":{"type":"string","description":"资源类型，例如 resume"},"resourceId":{"type":"string","description":"资源 ID"},"secretLevel":{"type":"integer","description":"密级 0–3"},"allowedUserIds":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"允许访问的用户 ID 列表；null 表示不限制登录用户"},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"过期时间（ISO 8601 UTC；null 表示不过期）"},"maxViews":{"type":"integer","nullable":true,"description":"最大访问次数；null 表示不限"},"viewCount":{"type":"integer","description":"已访问次数"},"createdBy":{"type":"string","nullable":true,"format":"uuid","description":"创建者管理员 userId"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","token","resourceType","resourceId","secretLevel","allowedUserIds","expiresAt","maxViews","viewCount","createdBy","createdAt"]},"description":"访问授权列表"}},"required":["data"]}}}}}},"post":{"tags":["access-grants"],"description":"创建访问授权","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"},"secretLevel":{"type":"integer","nullable":true,"minimum":0,"maximum":3,"default":2,"description":"密级 0–3，默认 2"},"allowedUserIds":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"允许访问的用户 ID 列表"},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","enum":[""]},{"nullable":true}],"description":"过期时间（ISO 8601 UTC，须带 Z；空表示不过期）"},"maxViews":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"description":"最大访问次数"}},"required":["resourceType","resourceId"]}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"},"grant":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"token":{"type":"string","description":"访问令牌（用于生成分享链接）"},"resourceType":{"type":"string","description":"资源类型，例如 resume"},"resourceId":{"type":"string","description":"资源 ID"},"secretLevel":{"type":"integer","description":"密级 0–3"},"allowedUserIds":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"允许访问的用户 ID 列表；null 表示不限制登录用户"},"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"过期时间（ISO 8601 UTC；null 表示不过期）"},"maxViews":{"type":"integer","nullable":true,"description":"最大访问次数；null 表示不限"},"viewCount":{"type":"integer","description":"已访问次数"},"createdBy":{"type":"string","nullable":true,"format":"uuid","description":"创建者管理员 userId"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","token","resourceType","resourceId","secretLevel","allowedUserIds","expiresAt","maxViews","viewCount","createdBy","createdAt"],"description":"新建的访问授权"},"url":{"type":"string","description":"分享访问路径，如 /s/{token}"}},"required":["ok","grant","url"]}}}},"400":{"description":"创建失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/admins":{"get":{"tags":["admins"],"security":[{"Bearer":[]}],"responses":{"200":{"description":"站点管理员列表","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","format":"uuid","description":"Supabase Auth 用户 ID"},"role":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"角色 code（= rbac_roles.code）"},"note":{"type":"string","nullable":true,"description":"授权备注"},"grantedAt":{"type":"string","format":"date-time","description":"授权时间（ISO 8601 UTC）"},"grantedBy":{"type":"string","nullable":true,"format":"uuid","description":"执行授权的管理员 userId"}},"required":["userId","role","note","grantedAt","grantedBy"]},"description":"站点管理员列表"}},"required":["data"]}}}},"403":{"description":"需要 admin 角色","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"post":{"tags":["admins"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","format":"uuid","description":"待授权用户 ID"},"role":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","default":"admin","description":"授予的角色"},"note":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"授权备注"}},"required":["userId"]}}}},"responses":{"201":{"description":"授权成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"授权失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}},"403":{"description":"需要 admin 角色","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/admins/{userId}":{"patch":{"tags":["admins"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"站点管理员用户 ID"},"required":true,"description":"站点管理员用户 ID","name":"userId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"更新后的角色"},"note":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"授权备注"}},"required":["role"]}}}},"responses":{"200":{"description":"更新授权成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"更新授权失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}},"403":{"description":"需要 admin 角色","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"delete":{"tags":["admins"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"站点管理员用户 ID"},"required":true,"description":"站点管理员用户 ID","name":"userId","in":"path"}],"responses":{"200":{"description":"撤销成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"description":"撤销失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}},"403":{"description":"需要 admin 角色","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/users":{"get":{"tags":["users"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","description":"页码（字符串数字，从 1 开始）"},"required":false,"description":"页码（字符串数字，从 1 开始）","name":"page","in":"query"},{"schema":{"type":"string","description":"每页条数（字符串数字，最大 100）"},"required":false,"description":"每页条数（字符串数字，最大 100）","name":"perPage","in":"query"}],"responses":{"200":{"description":"用户列表","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Supabase Auth 用户 ID"},"email":{"type":"string","description":"登录邮箱"},"phone":{"type":"string","description":"手机号"},"createdAt":{"type":"string","format":"date-time","description":"账号创建时间（ISO 8601 UTC）"},"lastSignInAt":{"type":"string","format":"date-time","description":"最近登录时间（ISO 8601 UTC）"},"emailConfirmedAt":{"type":"string","format":"date-time","description":"邮箱确认时间（ISO 8601 UTC）"},"bannedUntil":{"type":"string","format":"date-time","description":"封禁截止时间（ISO 8601 UTC）；未封禁时省略"},"isBanned":{"type":"boolean","description":"当前是否处于封禁状态"},"userMetadata":{"type":"object","additionalProperties":{"nullable":true},"description":"user_metadata"},"appMetadata":{"type":"object","additionalProperties":{"nullable":true},"description":"app_metadata"},"providers":{"type":"array","items":{"type":"string"},"description":"已绑定的登录提供商"},"siteAdmin":{"type":"object","nullable":true,"properties":{"role":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"站点角色 code（= rbac_roles.code）"},"note":{"type":"string","nullable":true,"description":"授权备注"},"grantedAt":{"type":"string","format":"date-time","description":"授权时间（ISO 8601 UTC）"},"grantedBy":{"type":"string","nullable":true,"format":"uuid","description":"执行授权的管理员 userId"}},"required":["role","note","grantedAt","grantedBy"],"description":"站点管理员授权摘要"}},"required":["id","createdAt","isBanned","userMetadata","appMetadata","providers","siteAdmin"]},"description":"当前页用户"},"page":{"type":"integer","description":"当前页码（从 1 开始）"},"perPage":{"type":"integer","description":"每页条数"},"hasMore":{"type":"boolean","description":"是否可能还有下一页"}},"required":["users","page","perPage","hasMore"],"description":"分页用户列表"}},"required":["data"]}}}},"400":{"description":"获取用户列表失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}},"403":{"description":"需要 admin 角色","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}},"503":{"description":"Supabase Admin 未配置","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/users/{userId}":{"get":{"tags":["users"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"用户 ID"},"required":true,"description":"用户 ID","name":"userId","in":"path"}],"responses":{"200":{"description":"用户详情","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Supabase Auth 用户 ID"},"email":{"type":"string","description":"登录邮箱"},"phone":{"type":"string","description":"手机号"},"createdAt":{"type":"string","format":"date-time","description":"账号创建时间（ISO 8601 UTC）"},"lastSignInAt":{"type":"string","format":"date-time","description":"最近登录时间（ISO 8601 UTC）"},"emailConfirmedAt":{"type":"string","format":"date-time","description":"邮箱确认时间（ISO 8601 UTC）"},"bannedUntil":{"type":"string","format":"date-time","description":"封禁截止时间（ISO 8601 UTC）；未封禁时省略"},"isBanned":{"type":"boolean","description":"当前是否处于封禁状态"},"userMetadata":{"type":"object","additionalProperties":{"nullable":true},"description":"user_metadata"},"appMetadata":{"type":"object","additionalProperties":{"nullable":true},"description":"app_metadata"},"providers":{"type":"array","items":{"type":"string"},"description":"已绑定的登录提供商"},"siteAdmin":{"type":"object","nullable":true,"properties":{"role":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"站点角色 code（= rbac_roles.code）"},"note":{"type":"string","nullable":true,"description":"授权备注"},"grantedAt":{"type":"string","format":"date-time","description":"授权时间（ISO 8601 UTC）"},"grantedBy":{"type":"string","nullable":true,"format":"uuid","description":"执行授权的管理员 userId"}},"required":["role","note","grantedAt","grantedBy"],"description":"站点管理员授权摘要"}},"required":["id","createdAt","isBanned","userMetadata","appMetadata","providers","siteAdmin"],"description":"用户详情"}},"required":["data"]}}}},"400":{"description":"获取用户失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}},"403":{"description":"需要 admin 角色","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}},"503":{"description":"Supabase Admin 未配置","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"patch":{"tags":["users"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"用户 ID"},"required":true,"description":"用户 ID","name":"userId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"新邮箱"},"phone":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"手机号；空串视为清除"},"fullName":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"显示名（写入 user_metadata.full_name）"},"banned":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}],"description":"是否封禁；true/false 或字符串 \"true\"/\"false\""}}}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Supabase Auth 用户 ID"},"email":{"type":"string","description":"登录邮箱"},"phone":{"type":"string","description":"手机号"},"createdAt":{"type":"string","format":"date-time","description":"账号创建时间（ISO 8601 UTC）"},"lastSignInAt":{"type":"string","format":"date-time","description":"最近登录时间（ISO 8601 UTC）"},"emailConfirmedAt":{"type":"string","format":"date-time","description":"邮箱确认时间（ISO 8601 UTC）"},"bannedUntil":{"type":"string","format":"date-time","description":"封禁截止时间（ISO 8601 UTC）；未封禁时省略"},"isBanned":{"type":"boolean","description":"当前是否处于封禁状态"},"userMetadata":{"type":"object","additionalProperties":{"nullable":true},"description":"user_metadata"},"appMetadata":{"type":"object","additionalProperties":{"nullable":true},"description":"app_metadata"},"providers":{"type":"array","items":{"type":"string"},"description":"已绑定的登录提供商"},"siteAdmin":{"type":"object","nullable":true,"properties":{"role":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"站点角色 code（= rbac_roles.code）"},"note":{"type":"string","nullable":true,"description":"授权备注"},"grantedAt":{"type":"string","format":"date-time","description":"授权时间（ISO 8601 UTC）"},"grantedBy":{"type":"string","nullable":true,"format":"uuid","description":"执行授权的管理员 userId"}},"required":["role","note","grantedAt","grantedBy"],"description":"站点管理员授权摘要"}},"required":["id","createdAt","isBanned","userMetadata","appMetadata","providers","siteAdmin"],"description":"用户详情"}},"required":["data"]}}}},"400":{"description":"更新用户失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}},"403":{"description":"需要 admin 角色","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}},"503":{"description":"Supabase Admin 未配置","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/rbac/catalog":{"get":{"tags":["rbac"],"security":[{"Bearer":[]}],"responses":{"200":{"description":"View/Action catalog","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"views":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"视图主键"},"code":{"type":"string","description":"视图代码"},"path":{"type":"string","description":"前端路由路径"},"name":{"type":"string","description":"视图显示名"},"description":{"type":"string","nullable":true,"description":"视图说明"},"sortOrder":{"type":"integer","description":"排序值"},"isEnabled":{"type":"boolean","description":"是否启用"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"}},"required":["id","code","path","name","description","sortOrder","isEnabled","createdAt"]},"description":"可分配页面（View）"},"viewPerms":{"type":"array","items":{"type":"object","properties":{"viewId":{"type":"string","format":"uuid","description":"视图 ID"},"permissionCode":{"type":"string","description":"进入该视图所需的权限码"}},"required":["viewId","permissionCode"]},"description":"View 所需权限"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"操作主键"},"viewId":{"type":"string","format":"uuid","description":"所属视图 ID"},"code":{"type":"string","description":"操作代码"},"name":{"type":"string","description":"操作显示名"},"description":{"type":"string","nullable":true,"description":"操作说明"},"sortOrder":{"type":"integer","description":"排序值"},"isEnabled":{"type":"boolean","description":"是否启用"}},"required":["id","viewId","code","name","description","sortOrder","isEnabled"]},"description":"可分配操作（Action）"},"actionPerms":{"type":"array","items":{"type":"object","properties":{"actionId":{"type":"string","format":"uuid","description":"操作 ID"},"permissionCode":{"type":"string","description":"执行该操作所需的权限码"}},"required":["actionId","permissionCode"]},"description":"Action 所需权限"}},"required":["views","viewPerms","actions","actionPerms"],"description":"RBAC View/Action 目录"}},"required":["data"]}}}},"403":{"description":"无权限","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/rbac/roles":{"get":{"tags":["rbac"],"security":[{"Bearer":[]}],"responses":{"200":{"description":"角色列表（role.manage 可管理；user.manage 可读取以便授权）","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"角色主键"},"code":{"type":"string","description":"角色代码，如 admin / editor / trusted"},"name":{"type":"string","description":"角色显示名"},"description":{"type":"string","nullable":true,"description":"角色说明"},"isSystem":{"type":"boolean","description":"是否系统种子角色"},"bypassAll":{"type":"boolean","description":"是否跳过全部权限校验（超管）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","code","name","description","isSystem","bypassAll","createdAt","updatedAt"]},"description":"角色列表"}},"required":["data"]}}}},"403":{"description":"无权限","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"post":{"tags":["rbac"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9_-]*$","description":"角色代码，如 content_editor"},"name":{"type":"string","minLength":1,"maxLength":128,"description":"角色显示名"},"description":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"角色说明"}},"required":["code","name"]}}}},"responses":{"201":{"description":"新建角色","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"角色主键"},"code":{"type":"string","description":"角色代码，如 admin / editor / trusted"},"name":{"type":"string","description":"角色显示名"},"description":{"type":"string","nullable":true,"description":"角色说明"},"isSystem":{"type":"boolean","description":"是否系统种子角色"},"bypassAll":{"type":"boolean","description":"是否跳过全部权限校验（超管）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","code","name","description","isSystem","bypassAll","createdAt","updatedAt"],"description":"新建角色"}},"required":["data"]}}}},"400":{"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"]}}}},"409":{"description":"角色代码已存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}}},"/rbac/roles/{id}":{"get":{"tags":["rbac"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"角色 ID"},"required":true,"description":"角色 ID","name":"id","in":"path"}],"responses":{"200":{"description":"角色详情含 permissions 与菜单树","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"role":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"角色主键"},"code":{"type":"string","description":"角色代码，如 admin / editor / trusted"},"name":{"type":"string","description":"角色显示名"},"description":{"type":"string","nullable":true,"description":"角色说明"},"isSystem":{"type":"boolean","description":"是否系统种子角色"},"bypassAll":{"type":"boolean","description":"是否跳过全部权限校验（超管）"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","code","name","description","isSystem","bypassAll","createdAt","updatedAt"],"description":"角色"},"permissions":{"type":"array","items":{"type":"object","properties":{"roleId":{"type":"string","format":"uuid","description":"角色 ID"},"permissionCode":{"type":"string","description":"已授予的权限码"},"grantedAt":{"type":"string","format":"date-time","description":"授权时间（ISO 8601 UTC）"}},"required":["roleId","permissionCode","grantedAt"]},"description":"角色权限绑定行"},"tree":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"roots":{"type":"array","items":{"$ref":"#/components/schemas/RbacNavNodeV1"}}},"required":["version","roots"],"description":"角色菜单树"},"ui":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"suggestedPlacement":{"type":"string","enum":["side","top"]}},"required":["version"],"description":"角色导航建议"}},"required":["role","permissions","tree","ui"],"description":"角色详情（含权限与菜单树）"}},"required":["data"]}}}},"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"]}}}}}}},"/rbac/roles/{id}/draft":{"put":{"tags":["rbac"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"角色 ID"},"required":true,"description":"角色 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assignment":{"type":"object","properties":{"viewIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"勾选的视图 ID 列表（开放进页权限）"},"actionIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"勾选的操作 ID 列表（开放页内按钮权限）"}},"required":["viewIds","actionIds"],"description":"第一步：开放页面与操作（授予 permission）"},"tree":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"roots":{"type":"array","items":{"$ref":"#/components/schemas/RbacNavNodeV1"}}},"required":["version","roots"],"description":"第二步：本角色菜单树（与权限解耦）"},"ui":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"suggestedPlacement":{"type":"string","enum":["side","top"]}},"required":["version"],"description":"第三步：非强制建议"}},"required":["assignment","tree","ui"]}}}},"responses":{"200":{"description":"保存角色草稿：assignment + tree + ui","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"permissions":{"type":"array","items":{"type":"string"},"description":"展开后写入的权限码列表"},"updatedAt":{"type":"string","format":"date-time","description":"服务器保存时间（ISO 8601 UTC）"}},"required":["ok","permissions","updatedAt"]}}}},"400":{"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"]}}}}}}},"/rbac/permissions":{"get":{"tags":["rbac"],"security":[{"Bearer":[]}],"responses":{"200":{"description":"RBAC 权限目录（字典 rbac_permission）","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"主键"},"typeId":{"type":"string","format":"uuid","description":"所属字典类型 ID"},"itemKey":{"type":"string","description":"字典项键（同 typeId 下唯一，机器可读）"},"itemLabel":{"type":"string","description":"字典项标签（展示文案）"},"itemValue":{"type":"string","nullable":true,"description":"字典项值（可对接外部编码）"},"itemExtra":{"nullable":true,"description":"扩展展示信息（颜色/图标等 JSON）"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父节点 ID（扁平字典为 null）"},"nodeKind":{"type":"string","enum":["group","value"],"description":"节点种类：group=仅组织；value=可引用叶子"},"path":{"type":"string","description":"物化路径，如 /skilled/"},"isDefault":{"type":"boolean","description":"是否默认项"},"isEnabled":{"type":"boolean","description":"是否启用"},"sortOrder":{"type":"integer","description":"展示排序，越小越靠前"},"effectiveFrom":{"type":"string","nullable":true,"format":"date-time","description":"生效开始时间（ISO 8601 UTC）"},"effectiveTo":{"type":"string","nullable":true,"format":"date-time","description":"生效结束时间（ISO 8601 UTC）；null 表示长期有效"},"remark":{"type":"string","nullable":true,"description":"备注"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"updatedAt":{"type":"string","format":"date-time","description":"更新时间（ISO 8601 UTC）"}},"required":["id","typeId","itemKey","itemLabel","itemValue","parentId","nodeKind","path","isDefault","isEnabled","sortOrder","effectiveFrom","effectiveTo","remark","createdAt","updatedAt"]},"description":"RBAC 权限目录项"}},"required":["data"]}}}},"400":{"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"]}}}}}},"post":{"tags":["rbac"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"itemKey":{"type":"string","minLength":1,"description":"权限码或分组键"},"itemLabel":{"type":"string","minLength":1,"description":"展示名称"},"nodeKind":{"type":"string","enum":["group","value"],"default":"value","description":"group=分组；value=权限码叶子"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID"},"path":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"物化路径，默认 /{itemKey}/"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"排序"},"isEnabled":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"default":true,"description":"是否启用"}},"required":["itemKey","itemLabel"]}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"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"]}}}}}}},"/rbac/permissions/{id}":{"patch":{"tags":["rbac"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"权限项 ID"},"required":true,"description":"权限项 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"itemKey":{"type":"string","minLength":1,"description":"权限码或分组键"},"itemLabel":{"type":"string","minLength":1,"description":"展示名称"},"nodeKind":{"type":"string","enum":["group","value"],"default":"value","description":"group=分组；value=权限码叶子"},"parentId":{"type":"string","nullable":true,"format":"uuid","description":"父分组 ID"},"path":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"物化路径，默认 /{itemKey}/"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"排序"},"isEnabled":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"default":true,"description":"是否启用"}},"required":["itemKey","itemLabel"]}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"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"]}}}}}},"delete":{"tags":["rbac"],"security":[{"Bearer":[]}],"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":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"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"]}}}}}}},"/rbac/views":{"get":{"tags":["rbac"],"security":[{"Bearer":[]}],"responses":{"200":{"description":"RBAC 视图（页面）目录","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"视图主键"},"code":{"type":"string","description":"视图代码"},"path":{"type":"string","description":"前端路由路径"},"name":{"type":"string","description":"视图显示名"},"description":{"type":"string","nullable":true,"description":"视图说明"},"sortOrder":{"type":"integer","description":"排序值"},"isEnabled":{"type":"boolean","description":"是否启用"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"permissionCodes":{"type":"array","items":{"type":"string"},"description":"进入该视图所需权限码"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"操作主键"},"code":{"type":"string","description":"操作代码"},"name":{"type":"string","description":"操作显示名"},"description":{"type":"string","nullable":true,"description":"说明"},"sortOrder":{"type":"integer","description":"排序"},"isEnabled":{"type":"boolean","description":"是否启用"},"permissionCodes":{"type":"array","items":{"type":"string"},"description":"执行该操作所需权限码"}},"required":["id","code","name","description","sortOrder","isEnabled","permissionCodes"]},"description":"页内操作及所需权限"}},"required":["id","code","path","name","description","sortOrder","isEnabled","createdAt","permissionCodes","actions"]},"description":"RBAC 视图列表"}},"required":["data"]}}}},"403":{"description":"无权限","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"错误信息"}},"required":["error"]}}}}}},"post":{"tags":["rbac"],"security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"pattern":"^[a-z][a-z0-9_.]*$","description":"视图代码，如 views.list"},"path":{"type":"string","minLength":1,"pattern":"^\\/","description":"前端路由"},"name":{"type":"string","minLength":1,"description":"展示名称"},"description":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"说明"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"排序"},"isEnabled":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"default":true,"description":"是否启用"},"permissionCodes":{"type":"array","items":{"type":"string","minLength":1},"default":[],"description":"进入该视图所需权限码（AND）；可为空表示任意已登录管理员可见"},"actions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"pattern":"^[a-z][a-z0-9_.]*$","description":"操作代码，如 skills.list.create"},"name":{"type":"string","minLength":1,"description":"操作显示名"},"description":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"说明"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"排序"},"isEnabled":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"default":true,"description":"是否启用"},"permissionCodes":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"description":"执行该操作所需权限码（AND）"}},"required":["code","name","permissionCodes"]},"default":[],"description":"页内可分配操作；全量同步（创建不自动塞默认按钮）"}},"required":["code","path","name"]}}}},"responses":{"201":{"description":"创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"视图主键"},"code":{"type":"string","description":"视图代码"},"path":{"type":"string","description":"前端路由路径"},"name":{"type":"string","description":"视图显示名"},"description":{"type":"string","nullable":true,"description":"视图说明"},"sortOrder":{"type":"integer","description":"排序值"},"isEnabled":{"type":"boolean","description":"是否启用"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"permissionCodes":{"type":"array","items":{"type":"string"},"description":"进入该视图所需权限码"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"操作主键"},"code":{"type":"string","description":"操作代码"},"name":{"type":"string","description":"操作显示名"},"description":{"type":"string","nullable":true,"description":"说明"},"sortOrder":{"type":"integer","description":"排序"},"isEnabled":{"type":"boolean","description":"是否启用"},"permissionCodes":{"type":"array","items":{"type":"string"},"description":"执行该操作所需权限码"}},"required":["id","code","name","description","sortOrder","isEnabled","permissionCodes"]},"description":"页内操作及所需权限"}},"required":["id","code","path","name","description","sortOrder","isEnabled","createdAt","permissionCodes","actions"],"description":"RBAC 视图详情"}},"required":["data"]}}}},"400":{"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"]}}}}}}},"/rbac/views/{id}":{"get":{"tags":["rbac"],"security":[{"Bearer":[]}],"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":"视图主键"},"code":{"type":"string","description":"视图代码"},"path":{"type":"string","description":"前端路由路径"},"name":{"type":"string","description":"视图显示名"},"description":{"type":"string","nullable":true,"description":"视图说明"},"sortOrder":{"type":"integer","description":"排序值"},"isEnabled":{"type":"boolean","description":"是否启用"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"permissionCodes":{"type":"array","items":{"type":"string"},"description":"进入该视图所需权限码"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"操作主键"},"code":{"type":"string","description":"操作代码"},"name":{"type":"string","description":"操作显示名"},"description":{"type":"string","nullable":true,"description":"说明"},"sortOrder":{"type":"integer","description":"排序"},"isEnabled":{"type":"boolean","description":"是否启用"},"permissionCodes":{"type":"array","items":{"type":"string"},"description":"执行该操作所需权限码"}},"required":["id","code","name","description","sortOrder","isEnabled","permissionCodes"]},"description":"页内操作及所需权限"}},"required":["id","code","path","name","description","sortOrder","isEnabled","createdAt","permissionCodes","actions"],"description":"RBAC 视图详情"}},"required":["data"]}}}},"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"]}}}}}},"patch":{"tags":["rbac"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"视图 ID"},"required":true,"description":"视图 ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"pattern":"^[a-z][a-z0-9_.]*$","description":"视图代码，如 views.list"},"path":{"type":"string","minLength":1,"pattern":"^\\/","description":"前端路由"},"name":{"type":"string","minLength":1,"description":"展示名称"},"description":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"说明"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"排序"},"isEnabled":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"default":true,"description":"是否启用"},"permissionCodes":{"type":"array","items":{"type":"string","minLength":1},"default":[],"description":"进入该视图所需权限码（AND）；可为空表示任意已登录管理员可见"},"actions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"pattern":"^[a-z][a-z0-9_.]*$","description":"操作代码，如 skills.list.create"},"name":{"type":"string","minLength":1,"description":"操作显示名"},"description":{"anyOf":[{"type":"string"},{"nullable":true}],"description":"说明"},"sortOrder":{"type":"integer","nullable":true,"default":0,"description":"排序"},"isEnabled":{"anyOf":[{"type":"boolean","nullable":true},{"nullable":true}],"default":true,"description":"是否启用"},"permissionCodes":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"description":"执行该操作所需权限码（AND）"}},"required":["code","name","permissionCodes"]},"default":[],"description":"页内可分配操作；全量同步（创建不自动塞默认按钮）"}},"required":["code","path","name"]}}}},"responses":{"200":{"description":"更新成功","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"视图主键"},"code":{"type":"string","description":"视图代码"},"path":{"type":"string","description":"前端路由路径"},"name":{"type":"string","description":"视图显示名"},"description":{"type":"string","nullable":true,"description":"视图说明"},"sortOrder":{"type":"integer","description":"排序值"},"isEnabled":{"type":"boolean","description":"是否启用"},"createdAt":{"type":"string","format":"date-time","description":"创建时间（ISO 8601 UTC）"},"permissionCodes":{"type":"array","items":{"type":"string"},"description":"进入该视图所需权限码"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"操作主键"},"code":{"type":"string","description":"操作代码"},"name":{"type":"string","description":"操作显示名"},"description":{"type":"string","nullable":true,"description":"说明"},"sortOrder":{"type":"integer","description":"排序"},"isEnabled":{"type":"boolean","description":"是否启用"},"permissionCodes":{"type":"array","items":{"type":"string"},"description":"执行该操作所需权限码"}},"required":["id","code","name","description","sortOrder","isEnabled","permissionCodes"]},"description":"页内操作及所需权限"}},"required":["id","code","path","name","description","sortOrder","isEnabled","createdAt","permissionCodes","actions"],"description":"RBAC 视图详情"}},"required":["data"]}}}},"400":{"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"]}}}}}},"delete":{"tags":["rbac"],"security":[{"Bearer":[]}],"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":{"ok":{"type":"boolean","description":"是否成功"}},"required":["ok"]}}}},"400":{"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"]}}}}}}}}}