app-template/packages/types/AGENTS.md

AGENTS.md — @app/types

职责

对外/跨层输入校验与共享类型的唯一源。只放 Zod schema 与纯类型，不依赖数据库、不跑 IO。

• 账户域：userSchemas（create / update / get / list / delete）、authSchemas
• 媒体域：mountSchemas、librarySchemas、playbackSchemas、scrapeSchemas、danmakuSchemas
• 共享工具：media-fs.ts 的 VIDEO_EXTENSIONS / isVideoFilename
• 输出类型：User、LibraryGroup、SeriesOutput、ContinueItem、BatchResult 等（手写 DTO，供前端与 service 对齐）

结构

src/
  schemas.ts        # 账户域 Zod schema + 输出类型
  media-schemas.ts  # 媒体域 Zod schema + 输出类型
  media-fs.ts       # 视频扩展名常量与判断（纯函数）
  *.test.ts         # schema 单测
  index.ts          # export * 全量重导出

修改指南

• 新实体：在对应 *schemas.ts 增加 xxxSchemas 对象（按 create/update/get/list/delete 分组），并在 index.ts 重导出。
• schema 必须被 @app/trpc 的 procedure 直接使用，不要在 router 里再写一份校验。
• 输出类型若与 Drizzle 行结构一致，可从 @app/models 的 $inferSelect 派生；若 API 形状与表不一致（如 LibraryGroupPage），在此手写 DTO。
• 错误消息用中文（与现有 schema 一致）。
• schema 变更后补/改 *.test.ts，保证 zh 文案与可选字段行为不回退。

约束

• 零运行时依赖除 zod 外的包；禁止 import @app/db / @app/models。
• exactOptionalPropertyTypes：可选字段用 .optional()，TS 侧 ?: T | undefined。
• src/ 下若有 *.js / *.d.ts 产物（历史编译输出），不要手改；真源是 .ts。新增代码只写 .ts。

命令

yarn workspace @app/types typecheck
yarn workspace @app/types lint
yarn workspace @app/types build   # 产出 dist/ 供下游