api

API 开发规范

路由

• 所有路由注册在 main.py，统一 prefix="/v1"
• Router 是薄层：参数解析 → 调用 service → 返回结果
• 分页参数：page: int = Query(1, ge=1)，page_size: int = Query(20, ge=1, le=100)
• 删除操作返回 {"status": "ok"}
• RESTful 命名：GET /list、POST /create、PUT /{id} 全量、PATCH /{id} 部分、DELETE /{id}

Schema 命名

类型	命名模式
列表项 / 详情	{Resource}Summary / {Resource}Detail
列表响应	{Resource}ListResponse（data + total）
创建 / 更新	Create{Resource}Request / Update{Resource}Request

• 主键统一 id，外键 {entity}_id，更新请求所有字段可选
• 列表响应包含 data、total、page、page_size
• 时间字段序列化为 ISO 8601
• 前端 TS 类型从 OpenAPI 生成，禁止手写（单一真相源 = schemas.py）。改 schema 后在仓库根跑 pnpm gen:types 一条命令：它先 dump apps/server/openapi.json，再经 openapi-typescript 生成 packages/contract-rest-types/src/api.generated.ts（各端 src/**/types/api.generated.ts 只是三行透传再导出，没有独立生成脚本）。生成物入仓——CI 跑同一命令后 git diff --exit-code 挡漂移，故改完必须一并提交；*.generated.ts 免 lint（biome ignore），无 postinstall 自动重生成。service 文件用 type X = components["schemas"]["X"] 取别名引用。
• ✅ 已迁移：所有 service 的 REST 类型均用生成类型别名（type X = components["schemas"]["X"]）；新增/改动一律走生成类型，勿新增手写 REST 类型。纯 SSE/事件载荷与客户端域模型（camelCase，经 toX 映射）不受此约束。例外：端点无 response_model（如 /readyz、/version）时生成类型为无类型字典，保留手写并加注。带默认值的字段在生成类型里是可选（?），读取处按需 ?? 兜底。

认证 & 权限

• 注入：AuthUser（必须登录）/ OptionalUser（可选）→ 见 agentcore.deps
• 权限在 service 层校验，不在 router 层

错误处理

• 使用 agentcore.common.errors：not_found / forbidden / bad_request
• 统一响应：{"error": {"code": N, "message": "...", "detail": "..."}}

Service 层

• ID 生成 str(uuid4())
• ORM → Pydantic 转换放 service 私有方法
• 写操作先查再改（验证存在性和权限）
• 软删除检查：if not entity or entity.deleted_at: raise not_found(...)