---
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 管道传入交互参数：

```bash
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 编译验证

```bash
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` | 后端工具类目录 |