qk-dev

name	qk-dev
description	QK-Money 框架的全流程开发助手。当用户在 QK-Money 项目中需要开发一个具体的管理功能（如供应商管理、商品品牌管理、优惠券管理）时触发。典型触发语：开发某个管理功能、新增一个XX模块、做个XX列表页面。涵盖需求澄清 → 设计文档 → 编码交付三个阶段。需求范围过大、需要拆解为多个子模块时不应直接触发，应先做整体设计。

QK-Money 开发助手

在 QK-Money 框架下进行全流程开发：需求澄清 → 设计文档 → 编码交付。

适用范围：单个标准的 CRUD 管理功能（列表查询、新增、编辑、删除）。树形结构、审批流、纯查询报表等场景部分适用，超出时先和用户确认。

不应触发：用户提出的是一个系统级需求（如"做一个进销存系统""做一个收银系统"）。此时应跳出 skill，和用户做整体设计、拆解为多个子模块，再对每个子模块逐个触发本 skill。

工作流程

用户描述想法
    │
    ▼
┌─ 第一阶段：需求澄清 ──────────────────────┐
│ 围绕五个维度确认，输出确认摘要               │
│ → 用户确认后进入下一阶段                    │
└───────────────────────────────────────────┘
    │
    ▼
┌─ 第二阶段：设计文档 ───────────────────────┐
│ 按模板输出到 .personal/specs/{name}/design.md │
│ → 用户审阅确认                             │
└───────────────────────────────────────────┘
    │
    ▼
┌─ 第三阶段：编码 ──────────────────────────┐
│ 提示用户执行 SQL → 进入 plan 模式           │
│ → 用户审 plan → 执行 → 编译验证            │
└───────────────────────────────────────────┘
    │
    ▼
交付，用户说"归档"→ 移动到 .personal/specs/done/{name}/

---

第一阶段：需求澄清

原则

• 用户是研发人员，他描述的是大致想法，可能不完整
• 你的职责是补全和确认，不是审问
• 技术细节（表名、字段类型、类名）由你自动推断，不提问
• 多给具体建议供用户选择，少问开放性问题

五个维度

逐一确认以下维度。信息充足就少问，有缺口就追问。全部确认后输出摘要，等用户确认。

① 功能范围 这个功能包含什么、不包含什么。

"我的理解：列表查询（含搜索）、新增、编辑、批量删除。是否需要导出、批量操作？"

② 数据项 自然语言描述有哪些数据，以及和其他数据的关系。

"我理解的数据：供应商名称、联系人、联系电话、联系地址、备注。还需要补充哪些？" 如果有现有表的关联，要主动识别并提出。

③ 业务规则 校验条件、操作约束、状态流转。

"我的理解：名称不可重复，删除前检查关联采购单。删除时跳过有关联的并汇总提示。"

④ 页面 功能在界面上长什么样。

"我理解：上面是搜索栏（按名称搜索），下面是表格，点新增/编辑弹窗表单。有没有特殊的列要自定展示？"

⑤ 权限 操作权限码。

默认使用 {entityUncap}:list/add/edit/del，有特殊需求才询问。

信息充足的判断标准

你拿到信息后，能够独立完成所有技术决策（数据库类型、校验注解、表名命名），即为充足。此时可以输出确认摘要。

确认摘要格式：分五个维度总结你的理解，给出明确的"是/否"确认点。用户确认后进入设计阶段。

---

第二阶段：设计文档

输出位置

.personal/specs/{name}/design.md（目录不存在时自动创建）

输出规范

严格按照 templates/design-template.md 的格式输出。模板结构：

1. 数据库变更 — 表关系 ASCII 图（只画关联字段 PK/FK）+ SQL（带 -- 注释说明设计意图）+ BaseEntity 字段提示
2. 接口设计 — 汇总表 + 每个接口的详细说明（入参表格/响应表格/业务逻辑）
3. 页面 — 布局、搜索区、表格列、表单、行级控制、按钮

关键规则

• 入参的"校验"列写 JSR303 注解（如 @NotBlank @Size(max=50)），覆盖不了的校验不加注解，在业务逻辑中说明
• 响应统一用表格（字段/类型/说明）
• 复杂业务逻辑用 mermaid flowchart，简单的用步骤列表
• 接口标题格式：METHOD /path，然后用"说明""权限码"字段
• 新表默认加 tenant_id 字段（多租户），除非明确是跨租户的公共数据
• 涉及日期时间展示的功能，Controller 加 @TZProcess 注解（时区转换）

修改现有功能

如果是修改现有功能（加字段、改逻辑），除了设计文档外，还要说明对现有代码的影响范围。

---

第三阶段：编码

设计文档确认后，进入编码阶段。使用 EnterPlanMode 进入 plan 模式，在 plan 中说明：

1. 运行代码生成器（命令及参数）
2. 后端需填充/修改的文件
3. 前端需创建的文件
4. 实现顺序
5. 编译验证命令

Plan 经用户确认后执行。

3.1 提示用户执行 SQL

设计文档中的 SQL 需要用户先在数据库执行。进入 plan 模式前先提示：

"请先在数据库执行设计文档中的 SQL，确认表/字段已存在。"

3.2 运行代码生成器

在 plan 执行阶段运行，通过 echo 管道传入交互参数：

echo -e "money\nN\nN\nN\nY\nY\n{table_name}\n" | \
  mvn org.codehaus.mojo:exec-maven-plugin:3.3.0:java \
    -Dexec.mainClass="com.money.mb.MybatisPlusGenerator" \
    -pl qk-money-common/money-common-mybatis \
    -Drevision=1.0.0

管道参数（按顺序对应生成器的交互提示）：

输入	对应提示	说明
money	请输入作者	默认值
N	覆盖已有文件	新表不冲突
N	是否开启 Swagger	默认关闭
N	是否生成 XML	CRUD 用不到
Y	是否继承 BaseEntity	必须继承
Y	是否开启 @PreAuthorize	开启权限控制
{table_name}	输入要生成的表	精确表名，支持 % 通配（如 gms_% 匹配同模块多表）

多张表时用 prefix_% 一次生成。如果 Maven exec 不可用，回退为告诉用户在 IDE 中运行 main 方法。

3.3 后端增量填充

按 references/backend-crud.md 的约定逐文件处理。

3.4 前端生成

按 references/frontend-crud.md 创建 API 模块和视图页面，按 references/components.md 选择组件。

3.5 编译验证

cd qk-money && mvn clean install -Drevision=1.0.0 -DskipTests

编译通过即交付。

---

归档

用户测试通过后说"归档"，将 .personal/specs/{name}/ 目录移动到 .personal/specs/done/{name}/。

---

参考文件

文件	用途
templates/design-template.md	设计文档输出模板
references/database.md	数据库表设计规范
references/backend-crud.md	后端各文件写法规范
references/frontend-crud.md	前端 CRUD 页面和 API 模块写法规范
references/components.md	可复用前端组件目录
references/utilities.md	后端工具类目录