gfast-module-dev 技能使用说明

让 AI 按照本项目代码生成器的规范手写业务模块，并正确调用现有组件库（富文本、上传、选择器、字典、权限），产出与 tools_gen_table 代码生成器风格完全一致的 GoFrame 后端 + Vue3 前端代码。

1. 这是什么

gfast-module-dev 是一个 Claude Code / opencode 项目级技能，沉淀自 gfast-v3 代码生成器（internal/app/system/logic/toolsGenTable + resource/template/vm 模板）与 gfast3.2-ui 前端组件库的真实用法。

它解决的问题：AI 直接手写业务模块时容易"自由发挥"——分层结构不对、多文件存储格式随手写、忘记路由三层注册、组件用法凭印象。本技能把这些工程约定固化为可执行的开发流程，使手写代码能无缝融入现有工程。

实测效果（3 个测试用例 × 有/无技能对照评估）：

差距集中在多附件 JSON 存储、garray.StrArray 多选入库、字典 props 下发、菜单 SQL 完整性等细节惯例上。

2. 适用场景

只要在本项目中提出以下类型的需求，技能就应被触发：

3. 目录结构与内容导览

gfast-module-dev/
├── SKILL.md                        # 入口：开发流程总览 + 字段决策表 + 红线清单
├── README.md                       # 本文件
└── references/                     # 参考文档（按需加载，不必一次读完）
    ├── db-conventions.md           # 建表规范：审计字段、雪花ID、字段命名启发式、类型映射
    ├── backend-guide.md            # 后端骨架：model/service/logic/api/controller/router 全套示例
    ├── frontend-guide.md            # 前端骨架：api.ts/model.ts/列表页/编辑弹窗 + 回显转换规则 + 菜单SQL
    ├── components-guide.md          # 组件用法：gf-ueditor/uploadImg/uploadFile/selectUser/selectDept(含后端回显)/useDict/v-auth 等
    └── data-permission.md           # 数据权限：两种模式选型、范围档位、List/Edit/Delete 接入模板

AI 的工作方式：先读 SKILL.md 掌握流程与决策表 → 写到哪一层再翻对应 reference。例如写编辑弹窗时查 frontend-guide 的回显转换规则，用上传组件时查 components-guide 的 props 表。

4. 安装

方式一：随项目分发（团队推荐）

技能已位于项目仓库 .claude/skills/gfast-module-dev/，克隆即用，版本随代码演进。

方式二：手动安装

将 gfast-module-dev 整个文件夹拷贝到：

方式三：.skill 文件

拿到 gfast-module-dev.skill（zip 格式）后解压到上述任一位置；claude.ai 网页版可在 Settings → Capabilities 中直接上传。

5. 如何使用

5.1 自动触发（默认方式）

无需任何手动操作。在项目根目录启动 Claude Code / opencode，直接像平时一样提需求即可：

> 在 demo 模块下新增一个公告管理功能，
  表 demo_notice：标题、内容(富文本)、封面图(单张)、附件(多个)、状态(字典开关)、排序。
  要完整的后端+前端+菜单权限SQL。

AI 会自动加载 SKILL.md 并按以下标准流程工作：

1. 核对/设计表结构 —— 按 db-conventions 校验审计字段与命名启发式

2. 后端五层 —— model → service → logic → api → controller，参照 backend-guide 骨架

3. 路由三层注册 —— <module>/router/{Biz}.go + internal/router/<module>.go + internal/app/boot/<module>.go

4. 前端三件套 —— api/<module>/<biz>.ts + views/<module>/<biz>/list/index.vue + list/component/edit.vue + list/component/model.ts

5. 菜单权限 SQL —— 三级 sys_auth_rule 记录，权限串 = API 路径

5.2 显式调用

如果某次没有自动触发（表述过于含糊时可能发生），在提问中点名技能：

> 使用 gfast-module-dev 技能，给文章模块增加讲师多选、学院单选、课件上传字段。

5.3 提问技巧（让产出更准）

提供越多的"表配置信息"，产出越接近代码生成器结果：

• ✅ 给出表名、业务名、所属模块：“demo 模块、表 demo_notice、业务 Notice”

• ✅ 给出每个字段的意图而非只给字段名：“cover 存封面图单张”（→ imagefile 单图模式）而不是只说"cover varchar(255)"

• ✅ 说明特殊需求：是否需要 Excel 导入导出、是否树表、主键是否雪花 ID、列表要不要开关列

• ❌ 避免"帮我写个模块"这种无字段的笼统需求——AI 会自行假设字段，返工概率高

5.4 三个典型会话示例

例 A：全新 CRUD 模块

> 用 gfast 规范写一个"文章管理"：表 demo_article(id,title,cate_id 关联分类表,
  tags 多选字典 sys_tag,content 富文本,cover 单图,status 开关列)，
  demo 模块，需要列表搜索(title 模糊)和分页。

预期产出：后端 6 类文件 + 路由三层 + 前端三件套 + 菜单 SQL，其中 tags 用 el-checkbox-group+garray.StrArray 逗号串存储、cover 用头像式单图上传、content 用 gf-ueditor。

例 B：已有模块加字段

> 给文章编辑表单加五个字段：讲师(用户多选)、学院(部门单选)、
  课程介绍(富文本)、课件(多文件)、标签(字典多选)，前后端都要改。

预期产出：正确的组件选型（select-user/select-dept/gf-ueditor/upload-file/checkbox-group）、openDialog 回显转换（JSON.parse / split）、后端模型类型（[]uint64 / uint64 / string / []*UpFile / garray.StrArray）及 logic 入库处理。

例 C：只做表设计

> 设计商品表 goods：名称模糊搜索、上下架、字典类型、富文本详情、
  9 张轮播图、单个视频、软删、部门数据权限、雪花 ID。

预期产出：符合规范的 CREATE TABLE + 每个字段的 htmlType/存储格式/Go 类型三元组说明。

6. 核心约定速览（详见 SKILL.md 与 references）

字段类型 → 组件 → 存储（最容易出错的部分）

五条红线

1. logic 必须 init() 注册服务且 boot 文件 blank import，否则启动 panic

2. Insert/Update 一律用 do 对象；时间/软删字段交给 ORM，禁止手动赋值

3. 新控制器必须补 router/{Biz}.go 的 Bind 方法（RouterAutoBind 只认 Bind*Controller 方法签名）

4. 前端 defineOptions({name}) 必须符合 keep-alive 命名规则（apiV1{Module}{Biz}List/Edit），否则页面不缓存

5. v-auth 权限串 = API 路径去开头斜杠，必须与 sys_auth_rule.name 完全一致；数据权限需在 List/Edit/Delete 显式接入 GetAuthDeptWhere，不会自动生效

7. 前置环境要求

8. 生成后的人工检查清单

技能产出后建议快速核对（也是 code review 要点）：

•  启动无 implement not found panic（init 注册 + boot import 齐全）

•  Swagger（/swagger）中能看到新接口，路径与方法符合 get/post/put/delete 约定

•  执行菜单 SQL 后重新登录，页面能打开且按钮按权限显隐

•  上传类字段实际上传一张验证存储格式与回显

•  多选字典字段保存→重开弹窗确认回显正常（split/JSON.parse 正确）