API 分层、错误与权限

请求链路复制标题链接

页面 / Hook
  → features/<feature>/api/client.ts
  → app/api/**/route.ts
  → features/<feature>/api/handlers.ts
  → validation.ts + service.ts
  → 数据库 / 模型 / 外部服务

Route 文件只导出 HTTP Handler。契约和 API 路径由 contracts.ts 共享，Handler 适配 HTTP，Service 实现业务规则和数据库访问。

输入与认证复制标题链接

共享 readJsonBody 返回 unknown，功能校验模块收窄为可用 DTO。withAuthenticatedApi 解析真实会话，将 userId 传给服务，不信任载荷中的所有者声明。

读取、更新、删除均按账户限定。简历服务的查询同时匹配资源 ID 和当前账户；不能只在列表中过滤而让详情接口越权。

错误处理复制标题链接

使用 ApiError 表达 HTTP 状态、稳定错误码和用户可读信息，再由共享错误响应函数转为 HTTP 响应。客户端按错误码决定重新登录、重载冲突数据或保留草稿。

AI 上游错误通过安全映射后返回，不能把完整供应商请求、密钥或响应直接暴露给客户端。

并发与取消复制标题链接

编辑或会话更新涉及版本时，客户端提交版本，服务端拒绝旧快照。AI 调用传递 AbortSignal，生成完成后还要检查取消及写入状态，不能让迟到结果覆盖新内容。

实现入口复制标题链接

• src/lib/api/route.ts、src/lib/api/errors.ts：JSON 解析、通用异常与响应适配。
• src/features/auth/api/route.ts：认证上下文与 withAuthenticatedApi，直接使用请求 headers 读取会话。
• src/features/resume/api：账户隔离示例。
• src/features/career/api/session-service.ts：会话预留与版本检查。

规则原文位于 docs/agent-rules/api.md。