# 指令规范（CMD）

> 本文件定义了 ykt_server 项目的业务功能开发指令，驱动从需求分析到代码生成的完整流程。

---

## 指令总览

| 指令 | 用途 | 调用技能 | 产物 |
|------|------|----------|------|
| `/require` | 生成需求规格说明书 | require | `doc/{模块}-{功能名}-requirements.md` |
| `/dev` | 基于需求规格说明书生成前后端代码 | ruoyi-backend + ykt-web-dev | 后端 Java 文件 + 前端 Vue/TS 文件 |

---

## 1. `/require` — 需求规格说明书生成

### 语法

```
/require <模块> <功能名> [简要需求描述] [选项]
```

### 参数

| 参数 | 必填 | 说明 | 示例 |
|------|------|------|------|
| 模块 | 是 | 模块名（不含 ruoyi- 前缀） | `ecs`、`backstage`、`system` |
| 功能名 | 是 | 功能简写（英文，驼峰命名） | `course`、`student` |
| 简要需求 | 否 | 自然语言描述字段和特殊要求 | `课程名称、课程类型(字典course_type)、讲师(多对多)` |

### 选项

| 标记 | 说明 | 示例 |
|------|------|------|
| `--table=表名` | 指定主表名（默认 `t_{模块}_{功能名}`） | `--table=t_ecs_course` |
| `--sub-table=表名` | 指定从表名 | `--sub-table=t_ecs_course_teacher` |
| `--no-tenant` | 非多租户表 | `--no-tenant` |
| `--no-import` | 不需要导入导出 | `--no-import` |
| `--dubbo` | 需要暴露 Dubbo 接口 | `--dubbo` |
| `--db=数据库类型` | 指定数据库类型，影响建表语句生成（默认 `kingbase`） | `--db=mysql`、`--db=dm`、`--db=oceanbase` |

### 流程

```
1. 解析指令参数（模块、功能名、简要需求、选项）
2. 调用 require 技能
3. 加载需求规格说明书模板（references/requirements-template.md）
4. 分析简要需求，自动推断字段属性：
   - 字段类型、查询方式、表单组件
   - 字典字段（描述中含"字典"、"下拉"）
   - 关联字段（描述中含"关联"、"选择"、"多对多"）
   - 主从关系（描述中含"多对多"、"一对多"，或指定了 --sub-table）
5. 填充模板，生成初始需求规格说明书（含建表语句）
6. 输出到 doc/{模块}-{功能名}-requirements.md
7. 展示给用户，支持反复沟通修改
8. 用户确认后形成最终需求规格说明书
```

### 需求推断规则

| 用户描述 | 推断结果                                                                           |
|----------|--------------------------------------------------------------------------------|
| "名称" | fieldType=String, component=input, inQuery=true, queryType=like                |
| "类型(字典xxx)" | fieldType=String, dictType=xxx, component=select                               |
| "编码" | fieldType=String, component=input, inQuery=true, queryType=like, required=true |
| "学分/分数" | fieldType=BigDecimal, component=inputNumber                                    |
| "数量/人数" | fieldType=Integer, component=inputNumber                                       |
| "时间/日期" | fieldType=Date, component=datetime                                             |
| "备注/描述" | fieldType=String, component=textarea                                           |
| "状态" | fieldType=String, dictType=status, component=select                            |
| "讲师/教师(多对多)" | 生成从表 + relation 配置                                                             |
| "排序" | fieldType=Integer, component=inputNumber                                       |
| "来源" | fieldType=Integer, dictType=data_source, component=select                      |
| "ID/标识" | fieldType=Long, inTable=false, inForm=false                                    |
| `--db=mysql` | 数据库类型设为 MySQL，生成 MySQL 建表语句                                                    |
| `--db=dm` | 数据库类型设为达梦，生成达盛建表语句                                                             |
| `--db=oceanbase` | 数据库类型设为 OceanBase，生成 OceanBase 建表语句                                            |
| （默认） | 数据库类型为人大金仓（kingbase）                                                           |

### 示例

**基础用法**：
```
/require ecs 课程 课程名称、课程编码、课程类型(字典course_type)、学分、学时、讲师(多对多关联) --sub-table=t_ecs_course_teacher
```

**仅指定模块和功能名，后续逐步补充需求**：
```
/require ecs 教室
```

**指定表名和选项**：
```
/require backstage 房间 房间名称、房间类型(字典FJLX)、容纳人数 --table=t_pt_room --no-import
```

**多行描述**：
```
/require ecs 课程
字段：课程名称、课程编码、课程类型(字典course_type)、学分、学时
特殊：教师为多对多关联，需要Dubbo暴露，需要导入导出
```

---

## 2. `/dev` — 代码生成

### 语法

```
/dev <模块> <功能名> [选项]
```

### 参数

| 参数 | 必填 | 说明 | 示例 |
|------|------|------|------|
| 模块 | 是 | 模块名 | `ecs` |
| 功能名 | 是 | 功能简写 | `course` |

### 选项

| 标记 | 说明 | 示例 |
|------|------|------|
| `--backend=路径` | 后端项目根路径（默认 `d:/dt_ykt/ykt_server`） | `--backend=d:/other/server` |
| `--frontend=路径` | 前端项目根路径（默认 `d:/dt_ykt/ykt_web`） | `--frontend=d:/other/web` |
| `--backend-only` | 仅生成后端代码 | `--backend-only` |
| `--frontend-only` | 仅生成前端代码 | `--frontend-only` |

### 流程

```
1. 解析指令参数（模块、功能名、选项）
2. 读取需求规格说明书 doc/{模块}-{功能名}-requirements.md
   - 如果文件不存在，提示用户先执行 /require
3. 后端代码生成（调用 ruoyi-backend 技能）：
   a. 解析需求文档的字段清单、接口清单、特殊需求
   b. 生成 Domain/Bo/Vo/Mapper/Service/ServiceImpl/Controller
   c. 如有导入需求，生成 ImportVo/ImportListener
   d. 如有 Dubbo 暴露需求，生成 RemoteService/RemoteServiceImpl
   e. 如有从表，生成从表相关文件
4. 前端代码生成（调用 ykt-web-dev 技能）：
   a. 解析需求文档的字段清单、接口清单、VO 结构
   b. 生成 api/{模块}/{功能名}/index.ts + types.ts
   c. 生成 views/{模块}/{功能名}/index.vue（列表页）
   d. 生成 views/{模块}/{功能名}/form.vue（表单页）
   e. 处理字典字段（useDict 引用）
   f. 处理关联字段（关联选择组件）
5. 展示生成结果清单
6. 用户确认后写入文件
```

### 需求规格说明书 → 代码映射

| 需求文档内容 | 后端生成 | 前端生成 |
|-------------|----------|----------|
| 基础信息.模块 | 包路径 `org.dromara.{module}` | 目录 `api/{module}/`、`views/{module}/` |
| 基础信息.主表名 | `@TableName`、Domain 类 | types.ts 表单类型 |
| 基础信息.从表名 | 从表 Domain/Bo/Vo/Mapper/Service | 从表类型定义、子表单组件 |
| 基础信息.是否多租户 | `extends TenantEntity / BaseEntity` | — |
| 字段(inDb=true) | Domain 字段 | — |
| 字段(required=true) | Bo `@NotNull`/`@NotBlank` 校验 | types.ts 必填校验 |
| 字段(inTable=true) | Vo `@ExcelProperty` | index.vue 表格列 |
| 字段(inQuery=true) | Bo 查询字段 | index.vue 搜索栏 |
| 字段(inForm=true) | Bo 表单字段 | form.vue 表单项 |
| 字段(dictType) | Vo `@ExcelDictFormat` | `useDict()` + `el-select` |
| 字段(relation) | — | 关联选择弹窗组件 |
| 字段(inDb=false) | Vo 纯计算字段 | types.ts 只读展示 |
| 字段(component) | — | 对应 Element Plus 组件 |
| 接口清单 | Controller 方法 | api/index.ts 接口函数 |
| VO 结构 | Vo 类定义 | types.ts 类型定义 |
| 特殊需求.excelImport | ImportVo + ImportListener | — |
| 特殊需求.excelExport | Vo `@ExcelProperty` | — |
| 特殊需求.dubboExpose | RemoteService + RemoteServiceImpl | — |

### 示例

**基础用法**：
```
/dev ecs 课程
```
自动查找 `doc/ecs-course-requirements.md`，使用默认路径生成前后端代码。

**仅生成后端**：
```
/dev ecs 课程 --backend-only
```

**指定自定义路径**：
```
/dev ecs 课程 --backend=d:/other/server --frontend=d:/other/web
```

**仅生成前端**：
```
/dev ecs 课程 --frontend-only
```

---

## 3. 完整工作流示例

### 示例：从零创建课程管理功能

**Step 1：生成需求规格说明书**
```
/require ecs 课程 课程名称、课程编码、课程类型(字典course_type)、学分、学时、讲师(多对多关联) --sub-table=t_ecs_course_teacher --dubbo --db=kingbase
```

**Step 2：确认/修改需求规格说明书**

AI 生成 `doc/ecs-course-requirements.md`，用户检查并修改（可多轮对话调整字段、增删接口等）。

**Step 3：生成代码**
```
/dev ecs 课程
```

**Step 4：验证生成结果**

后端文件：
```
ruoyi-modules/ruoyi-ecs/src/main/java/org/dromara/ecs/
├── controller/CourseController.java
├── domain/
│   ├── Course.java
│   ├── CourseTeacher.java
│   ├── bo/CourseBo.java
│   └── vo/CourseVo.java
├── mapper/CourseMapper.java
└── service/
    ├── ICourseService.java
    └── impl/CourseServiceImpl.java
```

前端文件：
```
d:/dt_ykt/ykt_web/src/
├── api/ecs/course/
│   ├── index.ts
│   └── types.ts
└── views/ecs/course/
    ├── index.vue
    └── form.vue
```

---

## 4. 路径约定

| 资源 | 默认路径 | 说明 |
|------|----------|------|
| 需求文档 | `d:/dt_ykt/ykt_server/doc/{模块}-{功能名}-requirements.md` | Markdown 格式 |
| 后端代码 | `d:/dt_ykt/ykt_server/ruoyi-modules/ruoyi-{模块}/` | Java 微服务模块 |
| 前端代码 | `d:/dt_ykt/ykt_web/src/` | Vue 3 + TypeScript |
| require 技能 | `d:/dt_ykt/ykt_server/.workbuddy/skills/require/` | 需求分析技能 |
| 后端技能 | `d:/dt_ykt/ykt_server/.workbuddy/skills/ruoyi-backend/` | 后端代码生成技能 |
| 前端技能 | `d:/dt_ykt/ykt_web/.workbuddy/skills/ykt-web-dev/` | 前端代码生成技能 |

---

## 5. 注意事项

1. **必须先执行 `/require`**：`/dev` 指令依赖需求规格说明书，未找到时会提示先执行 `/require`
2. **需求文档可手工编辑**：生成后用户可直接修改 Markdown 文件，`/dev` 以文件内容为准
3. **增量开发**：如已有部分代码，`/dev` 会提示覆盖风险，由用户决定
4. **字典命名规范**：字典类型（dictType）是全局的，不加模块前缀（如 `course_type` 而非 `ecs_course_type`）
5. **DTO 命名规范**：Dubbo 传输对象统一使用 `Dto` 后缀（如 `RemoteCourseDto`）
6. **多对多关联**：通过中间表实现，列表显示时 SQL 拼接关联字段（如讲师姓名拼接串）