用途:为所有进入系统的数据在信任边界处定义校验模式,前端用 Zod、后端用 Pydantic,确保未经校验的数据不跨越信任边界。
主要能力:前端表单校验(Zod + react-hook-form,配合 zodResolver,类型用 z.infer 推断);API 请求/响应模式(Pydantic 模型);类型安全契约;模式组合(由可复用基础模式拼装复杂模式);澳大利亚专用校验器,包括 ABN(11 位含校验和)、澳大利亚电话、4 位邮编、DD/MM/YYYY 日期;后端约束类型(如 PositiveInt、PageSize、ShortString)与字段校验器。
使用方式:前端定义 camelCase + Schema 后缀的 Zod 模式,用 z.infer 推断类型,通过 zodResolver 接入 react-hook-form;发送请求前用 schema.parse 校验。后端在路由文件或 apps/backend/src/api/schemas/ 定义 PascalCase + 用途后缀的 Pydantic 模型,路由参数直接声明模型即可自动校验。字段名前后端保持一致。校验失败可配合 error-taxonomy 使用 DATA_VALIDATION_* 错误码。
适用场景:创建或修改含用户数据的表单输入、定义 API 请求/响应模式、添加前端 Zod 校验、审查缺失输入校验的代码、构建接受 POST/PUT/PATCH 数据的新 API 端点。
限制与边界:不用于实现认证逻辑、错误响应格式设计或数据库模型定义(ORM 模式)。内部代码信任已校验数据,不做冗余重复校验。错误信息应面向用户、使用 en-AU 拼写。具体安装命令与版本信息暂未提供。