Pydantic 多模型 API 契约

要解决什么问题

REST 或 RPC 接口里，创建、更新、响应和落库字段往往不一致：创建时不能带 id，更新要全可选，响应对外字段和 Mongo/文档库里的 doc_type 结构也不该混在一个 Model 里。手写几套类容易漏字段、Optional 写错，前后端类型也对不齐。

技能如何工作

本技能约定 多模型模式，用 assets/template.py 复制模板后替换占位符：

• {{ResourceName}} → PascalCase（如 Project）
• {{resource_name}} → snake_case（如 project）

各模型分工如下：

| 模型 | 用途 |
|------|------|
| Base | 共享公共字段 |
| Create | 创建请求体（必填字段） |
| Update | 更新请求体（全部可选） |
| Response | 完整 API 响应 |
| InDB | 带 doc_type 的数据库文档 |

文档中还覆盖 camelCase 别名、可选更新字段等常见约定。集成路径固定为三步：在 src/backend/app/models/ 建模型 → 从 src/backend/app/models/__init__.py 导出 → 补对应 TypeScript 类型。非核心能力与生产检查清单见 references/capabilities.md。

适用边界

这是 Pydantic 模型结构与命名 的脚手架指引，不包含路由、鉴权或 ORM 迁移。若项目已有自己的 DTO 分层规范，需对照是否与本技能的 Base/Create/Update 划分一致再套用模板。