gfast-module-dev 技能使用说明

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 个测试用例 × 有/无技能对照评估）： 测试 用技能 不用技能 公告管理全栈模块 11/11 通过 8/11 表单组件五字段 7/7 通过 4/7 商品表设计 7/7 通过 7/7 差距集中在多附件 JSON 存储、garray.StrArray 多选入库、字典 props 下发、菜单 SQL 完整性等细节惯例上。 2. 适用场景 只要在本项目中提出以下类型的需求，技能就应被触发： 场景 示例提问 新增业务模块 “写一个商品管理的增删改查”、“demo 模块下加个公告管理” 设计业务表 “建一张订单表，要支持软删和数据权限” 列表页 / 编辑弹窗 “加个管理页面”、“写个列表页带搜索和批量删除” 使用公共组件 “这个表单要富文本”、“加个图片上传”、“选人用弹窗那种” 后端接口 “给 xx 加个导出 Excel”、“补一个状态开关接口” 权限菜单 “配上菜单和按钮权限 SQL” 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 整个文件夹拷贝到： 范围 路径 仅某个项目生效 <项目>\.claude\skills\gfast-module-dev\ Claude Code 全局 <用户>\.claude\skills\gfast-module-dev\ opencode 全局 <用户>\.config\opencode\skills\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 并按以下标准流程工作： 核对/设计表结构 —— 按 db-conventions 校验审计字段与命名启发式 后端五层 —— model → service → logic → api → controller，参照 backend-guide 骨架 路由三层注册 —— <module>/router/{Biz}.go + internal/router/<module>.go + internal/app/boot/<module>.go 前端三件套 —— api/<module>/<biz>.ts + views/<module>/<biz>/list/index.vue + list/component/edit.vue + list/component/model.ts 菜单权限 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） 字段类型 → 组件 → 存储（最容易出错的部分） htmlType 前端组件 DB 存储格式 后端模型类型 input / textarea el-input varchar/text string radio / select el-radio-group / el-select 数值或字典值 int/string checkbox / selects el-checkbox-group / 多选 select 逗号分隔串 garray.StrArray ↔ split(",") richtext gf-ueditor longtext HTML string imagefile（单图） 头像式 el-upload 带 token 相对路径字符串 string ↔ getUpFileUrl 回显 images / files upload-img / upload-file JSON 数组串 []*comModel.UpFile ↔ JSON.parse userSelector / deptSelector select-user / select-dept 单值 uint 或 JSON 数组 uint64 / []uint64 switch el-switch tinyint(1) bool dept_id（数据归属） 不上表单，后端注入 bigint uint64（GetDeptId(ctx) 注入 + GetAuthDeptWhere 过滤） 五条红线 logic 必须 init() 注册服务且 boot 文件 blank import，否则启动 panic Insert/Update 一律用 do 对象；时间/软删字段交给 ORM，禁止手动赋值 新控制器必须补 router/{Biz}.go 的 Bind 方法（RouterAutoBind 只认 Bind*Controller 方法签名） 前端 defineOptions({name}) 必须符合 keep-alive 命名规则（apiV1{Module}{Biz}List/Edit），否则页面不缓存 v-auth 权限串 = API 路径去开头斜杠，必须与 sys_auth_rule.name 完全一致；数据权限需在 List/Edit/Delete 显式接入 GetAuthDeptWhere，不会自动生效 7. 前置环境要求 项 说明 后端项目 gfast-v3（GoFrame v2.10+），技能放在其 .claude/skills/ 下使用效果最佳 前端项目 gfast3.2-ui（Vue3 + Element Plus + TS），路径由后端 manifest/config/config.yaml 的 gen.frontDir 指定 goModName 同样取自 config.yaml gen.goModName，跨项目复用时需确认这两项配置正确 gf CLI（可选） 需要 gf gen dao / gf gen service 时安装 8. 生成后的人工检查清单 技能产出后建议快速核对（也是 code review 要点）：  启动无 implement not found panic（init 注册 + boot import 齐全）  Swagger（/swagger）中能看到新接口，路径与方法符合 get/post/put/delete 约定  执行菜单 SQL 后重新登录，页面能打开且按钮按权限显隐  上传类字段实际上传一张验证存储格式与回显  多选字典字段保存→重开弹窗确认回显正常（split/JSON.parse 正确）