codegen

name	codegen
description	在基于 cupogo/scaffold 脚手架的项目中，根据 docs/ 下的 YAML 定义生成或更新 Go 代码（models/stores/webapi/enums）。当需要新增或修改业务对象、存储接口、Web 接口定义，或运行 scripts/codegen 并核对、修补生成结果时使用。不适用于修改生成器本身及 scripts/sqlgen/beafup 的详细流程。

Codegen

用途

本项目用 docs/ 下的 YAML 文档驱动 Go 代码生成。本 skill 覆盖完整工作流：编辑 YAML 定义 → 运行生成器 → 核对输出 → 人工修补生成器未自动化的部分。字段语义以生成器源码（scripts/codegen/gens/*.go）为权威来源，避免臆造不存在的 schema 字段。

何时使用

• 新增或修改 YAML 中的 models / stores / webapi / enums 定义
• 运行 codegen 生成或更新代码，并核对、修补结果
• 排查与生成相关的报错（如 oidcat 缺失、命名规则不合法）

不适用：修改 scripts/codegen 生成器本身；scripts/sqlgen（权限/API 记录 SQL）与 scripts/beafup 的详细流程。

核心工作流

1. 编辑 YAML 定义。 字段语义见 references/yaml-schema.md；动手前先参考现有示例 templates/docs/demo.yaml 与 docs/cms.yaml。
2. 运行生成器。
   • 单个文档：go run -tags=codegen ./scripts/codegen docs/<file>.yaml
   • 全部文档：make codegen
   • 常用参数：-spec 位掩码（1=models，2=stores，4=webapi，默认 7，可相加）；-drop 表示先删除已存在的生成文件
3. 核对输出。 确认文件落在约定位置（见 references/post-generation.md），不手改 *_gen.go；必要时 go build ./...、go vet ./...。
4. 人工修补。 hooks 等生成器未自动化的部分，按 references/post-generation.md 补充到非生成文件。

关键约束

• 生成的 *_gen.go 文件头部有 "This file is generated - Do Not Edit."，人工逻辑一律写入非生成文件（如 *_x.go、wrap.go 等）。
• 生成的代码依赖 andvari 项目（github.com/cupogo/andvari）的 pkg/models/{comm,oid} 与 pkg/stores/pgx 包；新项目需先在 go.mod 引入该依赖并准备 wrap.go/api.go，否则生成代码无法编译运行。
• hooks 目前不会自动生成实现，需按约定签名手工补充。
• 需要导出的定义（模型、字段、方法、枚举）首字母必须大写；model 缺少 oidcat 会直接报错。

参考资料

• references/yaml-schema.md — YAML 结构、字段语义、query 方法/扩展、命名规则
• references/post-generation.md — 输出位置、验证、人工修补、常见陷阱