zerx-add-module
在 gettopic 端到端新增一个管理模块的完整清单(proto→model→migrate→service→server→前端页→i18n→seed→routeTree→授权)。当用户要新增一个后台管理模块/资源/CRUD 页面(如商品、订单、配置项)时使用。Keywords: 新增模块, 管理模块, 后台模块, CRUD, 资源, 端到端, 完整流程, scaffold, 新建页面, add module, new module, 菜单, seed, 迁移, 全栈新增
Datos de origen
- Repositorio
- zerx-lab/get-topic
- Última actividad en el origen
- 7 de septiembre de 2026 a las 05:17
- Idioma detectado de SKILL.md
- chino
- Estrellas
- 0
- Forks
- 0
Opciones de instalación
De forma predeterminada está seleccionado el prompt que primero revisa el origen. Puedes cambiar a un comando directo o descargar una copia local.
Revisa los archivos de origen
Lee SKILL.md y los archivos complementarios que muestra SkillsMP antes de decidir si quieres instalarlo.
Mostrando SKILL.md
SKILL.md
Instrucciones de origen · Vista previa de solo lectura- name
- zerx-add-module
- description
- 在 gettopic 端到端新增一个管理模块的完整清单(proto→model→migrate→service→server→前端页→i18n→seed→routeTree→授权)。当用户要新增一个后台管理模块/资源/CRUD 页面(如商品、订单、配置项)时使用。Keywords: 新增模块, 管理模块, 后台模块, CRUD, 资源, 端到端, 完整流程, scaffold, 新建页面, add module, new module, 菜单, seed, 迁移, 全栈新增
# gettopic 端到端新增管理模块
> 编排清单;各步细节互链对应 skill,不复制其正文。
## 有序清单(9 步)
1. **proto**:`proto/zerx/v1/<mod>.proto` 加 service + messages(方法名避开 JS 保留字;校验注解写字段上)→ `task gen`。细节 → `skill://zerx-backend`。
2. **model**:`internal/model/<mod>.go`,标准字段块(`ID/CreatedAt/UpdatedAt/DeletedAt`)。在 `internal/database/migrate.go` 的 `0001_baseline` AutoMigrate 快照列表(现 21 个模型)对应位置注册 `&model.<Mod>{}`;如需改列/回填另加 `000N_*` 迁移(`HasColumn` 守卫)。
3. **service**:`internal/service/<mod>_service.go`,照抄 `user_service.go` 范式,**无 `RequireRole`**(授权交 Casbin)→ `skill://zerx-authz`、`skill://zerx-backend`;转换函数加进 `convert.go`。
4. **server**:`internal/server/server.go` 用 `reg(zerxv1connect.New<Mod>ServiceHandler(service.New<Mod>Service(...), opts))` 注册;按需把 procedure 加入 `public` / `selfServe`(`assertServicesRegistered` 会校验挂载)。
5. **前端页**:`web/src/routes/_authed/<mod>.tsx`,复刻 `users.tsx`/`params.tsx` 范式;增删改按钮用 `<Can code="<资源>:<动作>">` 包裹 → `skill://zerx-frontend`。
6. **i18n**:`web/src/lib/i18n.tsx` 的 `en` 与 `zh` **同步**加 key(结构锁,缺 key 编译失败)。
7. **seed**:在 `internal/database/seed.go` 的 `seedMenuTree` 加一节点;Title 存 i18n key,Icon 存 lucide 名,并在 `web/src/lib/menu-icons.ts` 的 `iconByName` 注册图标。
8. **routeTree**:`task frontend:build`(或 dev)让 Vite 插件重生成 `web/src/routeTree.gen.ts` 并提交。
9. **授权**:如需授予非 admin,到「角色管理」页为角色分配菜单 / API procedure / 按钮。
## seed 实测细节(`internal/database/seed.go`)
- 节点类型:`seedMenuNode{ node seedMenu, children []seedMenuNode }`;`seedMenu{ menu model.Menu, buttons []model.MenuButton, userVisible bool }`。
- 顶层菜单(`Path` 非空)或分组标题(`Path == ""`,作 group heading,子项放 `children`)。
- 元素例:
```go
{node: seedMenu{menu: model.Menu{Path: "/dashboard", Name: "dashboard", Title: "nav.dashboard", Icon: "LayoutDashboardIcon", Sort: 1}, userVisible: true}}
```
- 标准 CRUD 按钮用 helper:`crudButtons("<资源>", "<中文标签>")` → 生成 `<资源>:create/update/delete`;额外按钮直接 `append`。
- **幂等键 = Role 表为空**:首次播种 admin/user 角色、DFS 插菜单树、RoleMenu(admin 全 / user 仅 `userVisible`)、RoleButton(仅 admin)、`syncAPIs()` upsert 全量 procedure。
- 已初始化库:每次启动**增量**reconcile——`syncMenus`(按 `menu.Name` 匹配,**仅插入不改不删**)+ `syncAPIs`(按 procedure upsert,会 prune 过期行)。新菜单重启即生效,无需 DB reset。
## procedure 目录来源
`internal/apispec/apispec.go` 的 `Procedures() []Proc{Procedure, Service, Method}` 遍历 `protoregistry.GlobalFiles` 筛 `zerx.v1.` 前缀;`task gen` 后新 service 的 procedure 自动入目录(`syncAPIs` 落库)。
## 源码锚点
`internal/database/seed.go`、`internal/database/migrate.go`、`internal/apispec/apispec.go`、`web/src/routes/_authed/`(范式页)、`web/vite.config.ts`。
Ver en GitHub