# require 技能 — 需求规格说明书生成

> 本技能负责分析用户的简要需求描述，基于需求规格说明书模板，生成结构化的需求规格说明书文档。

## 语言要求

**所有对话、说明、注释均使用中文。** 与用户的交互全程中文，代码注释也使用中文。

## 技能定位

- **触发方式**：用户输入 `/require` 指令
- **核心职责**：将自然语言需求转化为结构化需求规格说明书
- **输出产物**：`doc/{模块}-{功能名}-requirements.md`
- **下游依赖**：`/dev` 指令读取需求规格说明书生成代码

---

## 工作流程

### 1. 解析指令

从用户输入中提取：

| 参数 | 提取规则 | 示例 |
|------|----------|------|
| 模块 | 第1个参数 | `ecs` → `ruoyi-modules/ruoyi-ecs` |
| 功能名 | 第2个参数 | `course` |
| 功能中文名 | 自动推断或用户补充 | `课程`、`课程管理` |
| 简要需求 | 第3个参数及之后 | `课程名称、课程类型(字典course_type)、讲师(多对多)` |
| 选项 | `--` 前缀标记 | `--table=t_ecs_course --dubbo --db=kingbase` |

**模块路径映射**：

| 模块名 | 后端路径 | 包名 |
|--------|----------|------|
| ecs | `ruoyi-modules/ruoyi-ecs` | `org.dromara.ecs` |
| backstage | `ruoyi-modules/ruoyi-backstage` | `org.dromara.backstage` |
| system | `ruoyi-modules/ruoyi-system` | `org.dromara.system` |

### 2. 加载需求模板

读取 `references/requirements-template.md`，模板包含以下章节：

1. 基础信息（模块、表名、多租户、数据库类型等）
2. 接口清单（CRUD + 导入导出）
3. 字段属性速查表（字段元数据定义规范）
4. 字段清单（YAML 格式，主表 + 从表）
5. VO 结构（列表 VO、明细 VO、从表 VO）
6. 特殊需求（导入导出、Dubbo 暴露等）
7. 字典项
8. 建表语句（根据数据库类型生成 DDL）
9. 备注

### 3. 分析简要需求

将用户自然语言描述的字段逐个解析，推断字段属性。

#### 字段解析规则

| 用户描述模式 | 推断属性 |
|-------------|----------|
| "XX名称" / "XX名" | `fieldType=String`, `component=input`, `inQuery=true`, `queryType=like` |
| "XX编码" / "XX代码" | `fieldType=String`, `component=input`, `inQuery=true`, `queryType=like`, `required=true` |
| "XX类型(字典xxx)" | `fieldType=String`, `dictType=xxx`, `component=select`, `inQuery=true`, `queryType=eq` |
| "XX状态" | `fieldType=String`, `dictType=status`, `component=select`, `inQuery=true`, `queryType=eq` |
| "学分" / "分数" / "金额" | `fieldType=BigDecimal`, `component=inputNumber` |
| "数量" / "人数" / "学时" | `fieldType=Integer`, `component=inputNumber` |
| "时间" / "日期" | `fieldType=Date`, `component=datetime` |
| "备注" / "描述" / "说明" | `fieldType=String`, `component=textarea`, `inTable=false` |
| "排序" / "序号" | `fieldType=Integer`, `component=inputNumber` |
| "来源" | `fieldType=String`, `dictType=data_source`, `component=select`, `inTable=false`, `inQuery=false`, `lockRule: {lockValue: 1, lockActions: [edit, delete], tip: '第三方数据不可操作'}` |
| "XX(多对多)" / "XX(关联)" | 生成从表配置 + relation |
| "XX(字典xxx)" | `fieldType=String`, `dictType=xxx`, `component=select` |
| "第三方标识" / "otherId" | `fieldType=String`, `inTable=false`, `inForm=false` |

#### 字段通用默认值

| 属性 | 默认值 |
|------|--------|
| `inDb` | `true` |
| `inTable` | `true`（除非备注/描述类） |
| `inQuery` | `false`（除非名称/编码/类型/状态类） |
| `queryType` | `eq` |
| `inForm` | `true`（除非主键/公共字段） |
| `inAdd` | `true` |
| `inEdit` | `true` |
| `required` | `false`（除非编码类） |
| `component` | `input` |
| `excelExport` | `true` |
| `lockRule` | `null`（除非"来源"/"数据来源"类字段） |

#### 主从关系推断

当用户描述包含以下关键词时，自动生成从表：

- **"多对多"**：创建中间表，从表字段包含 `id`、`{mainId}`、关联字段ID + 名称、`createTime`
- **"一对多"**：创建从表，从表包含 `id`、`{mainId}`、业务字段
- **`--sub-table=表名`**：显式指定从表名

从表命名规则：
- 多对多：`t_{模块}_{主表}_{关联实体}`（如 `t_ecs_course_teacher`）
- 一对多：`t_{模块}_{从表实体}`（如 `t_ecs_course_schedule`）

### 4. 填充模板

按照以下顺序填充需求规格说明书：

1. **基础信息**：模块路径、表名推断（`t_{模块}_{功能名}`）、多租户、数据库类型（默认 kingbase）、描述
2. **接口清单**：默认 CRUD 7 个接口 + 导入导出（除非 `--no-import`）
3. **字段清单**：
   - 主键字段（`{功能名}Id`, Long, inTable=false, inForm=false, excelExport=false）
   - 业务字段（按用户描述逐个推断）
   - VO 承载字段（`inDb=false` 的计算字段，如 teacherNames）
   - 第三方同步字段（otherId + dataSource，如有"来源"描述）
   - 公共字段（自动追加，无需手动写，见下方通用字段定义）
4. **VO 结构**：根据 `inTable=true` 字段组装列表 VO，有从表时增加明细 VO。**有 lockRule 的字段必须加入 VO**（前端需此字段判断操作权限）
5. **特殊需求**：根据选项标记填充
5. **特殊需求**：根据选项标记填充
6. **字典项**：根据 `dictType` 字段收集
7. **建表语句**：根据数据库类型和字段清单生成 DDL（见下方 DDL 生成规则）
8. **备注**：特殊设计说明

### 5. 输出文档

将填充后的需求规格说明书写入：

```
d:/dt_ykt/ykt_server/doc/{模块}-{功能名}-requirements.md
```

### 6. 确认与迭代

- 展示生成的需求规格说明书给用户
- 用户可指出需要修改的部分
- 修改后重新生成，覆盖原文件
- 用户也可直接编辑 Markdown 文件

---

## 参考文档索引

| 文档 | 说明 |
|------|------|
| `references/requirements-template.md` | 需求规格说明书模板（字段属性定义规范） |

---

## 注意事项

1. **字典命名不加模块前缀**：`course_type` 而非 `ecs_course_type`
2. **DTO 命名使用 Dto 后缀**：`RemoteCourseDto`
3. **多对多列表展示**：通过 SQL 拼接关联字段（如 GROUP_CONCAT），主表增加 `inDb=false` 的 VO 承载字段
4. **权限字符格式**：`{模块}:{功能}:{操作}`，如 `ecs:course:list`
5. **接口路径格式**：`/{功能名}/{操作}`，如 `/course/list`
6. **字段命名使用驼峰**：Java 端 `courseName`，数据库端 `course_name`
7. **数据库类型选项**：`--db=kingbase`（默认）、`--db=mysql`、`--db=dm`、`--db=oceanbase`
8. **操作锁定规则 lockRule**：当某字段值决定行级操作权限时使用。字段需 `inDb=true`，通常 `inTable=false`（不显示列）、`inQuery=false`（不作为搜索条件），但**必须包含在 VO 中**供前端判断。典型场景：`dataSource=1` 时禁止编辑和删除。前端根据 lockRule 配置，在操作列按字段值动态显示/隐藏编辑、删除按钮
9. **主键不导出 Excel**：主键字段（Long 类型）默认 `excelExport=false`，Vo 中不加 `@ExcelProperty` 注解

---

## 通用字段定义

所有表统一包含以下通用字段，建表 DDL 中自动追加，字段清单中无需重复声明：

| 字段          | Java 类型       | 逻辑删除默认值 | 说明               |
| ------------- | --------------- | -------------- | ------------------ |
| del_flag      | Integer         | 0              | 逻辑删除：0-未删除，1-已删除 |
| create_dept   | Long            | —              | 创建部门             |
| create_by     | Long            | —              | 创建者              |
| create_time   | Date            | —              | 创建时间             |
| update_by     | Long            | —              | 最后修改者            |
| update_time   | Date            | —              | 最后修改时间           |

如果基础信息中"是否多租户"为 **是**，则额外包含：

| 字段          | Java 类型       | 说明               |
| ------------- | --------------- | ------------------ |
| tenant_id     | Long            | 租户ID             |

### 通用字段在各数据库中的 DDL 类型

| 字段          | kingbase                              | mysql             | dm          | oceanbase         |
| ------------- | ------------------------------------- | ----------------- | ----------- | ----------------- |
| del_flag      | character(1 char) NOT NULL DEFAULT '0'::bpchar | char(1) NOT NULL DEFAULT '0' | CHAR(1) DEFAULT '0' | char(1) NOT NULL DEFAULT '0' |
| create_dept   | bigint                                | bigint(20)        | BIGINT      | bigint(20)        |
| create_by     | bigint                                | bigint(20)        | BIGINT      | bigint(20)        |
| create_time   | timestamp                             | datetime          | TIMESTAMP   | datetime          |
| update_by     | bigint                                | bigint(20)        | BIGINT      | bigint(20)        |
| update_time   | timestamp                             | datetime          | TIMESTAMP   | datetime          |
| tenant_id     | bigint                                | bigint(20)        | BIGINT      | bigint(20)        |

---

## DDL 生成规则

### 数据库类型映射

| 选项值 | 数据库 | 方言标识 |
|--------|--------|----------|
| `kingbase` | 人大金仓（默认） | KingbaseES |
| `mysql` | MySQL | MySQL |
| `dm` | 达梦 | DM |
| `oceanbase` | OceanBase | OceanBase |

### 字段类型映射

| Java 类型 | kingbase | mysql | dm | oceanbase |
|-----------|----------|-------|----|-----------|
| Long | bigint | bigint(20) | BIGINT | bigint(20) |
| Integer | integer | int(11) | INT | int(11) |
| String（无长度） | character varying(255 char) | varchar(255) | VARCHAR(255) | varchar(255) |
| **String（字典字段）** | **character varying(16 char)** | **varchar(16)** | **VARCHAR(16)** | **varchar(16)** |
| BigDecimal | numeric(10,2) | decimal(10,2) | DECIMAL(10,2) | decimal(10,2) |
| Date | timestamp | datetime | TIMESTAMP | datetime |

> **⚠️ 字典字段类型规范**：数据字典（dictType）对应的数据库字段类型统一为 `varchar(16)`，Java 类型为 `String`。字典值虽然常为数字（如 "0"、"1"），但存储和传输统一使用字符串。

### DDL 生成规范

#### kingbase（人大金仓）

```sql
-- 建表
CREATE TABLE "dbo"."t_xxx" (
  "id" bigint NOT NULL,
  "column_name" character varying(255 char) NOT NULL DEFAULT ''::varchar,
  "status" integer NOT NULL DEFAULT '0'::bpchar,
  "del_flag" character(1 char) NOT NULL DEFAULT '0'::bpchar,
  "create_dept" bigint,
  "create_by" bigint,
  "create_time" timestamp,
  "update_by" bigint,
  "update_time" timestamp,
  CONSTRAINT "t_xxx_pkey" PRIMARY KEY ("id")
);
-- 多租户表额外包含：
-- "tenant_id" character varying(20 char) NOT NULL DEFAULT ''::varchar,

-- 表注释
ALTER TABLE "dbo"."t_xxx" COMMENT '表注释';

-- 列注释
ALTER TABLE "dbo"."t_xxx" MODIFY "column_name" COMMENT '列注释';
```

#### mysql

```sql
CREATE TABLE `t_xxx` (
  `id` bigint(20) NOT NULL,
  `column_name` varchar(255) NOT NULL DEFAULT '' COMMENT '列注释',
  `status` int(11) NOT NULL DEFAULT '0' COMMENT '状态',
  `del_flag` char(1) NOT NULL DEFAULT '0' COMMENT '删除标志（0-未删除 1-已删除）',
  `create_dept` bigint(20) DEFAULT NULL COMMENT '创建部门',
  `create_by` bigint(20) DEFAULT NULL COMMENT '创建者',
  `create_time` datetime DEFAULT NULL COMMENT '创建时间',
  `update_by` bigint(20) DEFAULT NULL COMMENT '更新者',
  `update_time` datetime DEFAULT NULL COMMENT '更新时间',
  -- 多租户表额外包含：
  -- `tenant_id` bigint(20) DEFAULT NULL COMMENT '租户编号',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='表注释';
```

#### dm（达梦）

```sql
CREATE TABLE "t_xxx" (
  "id" BIGINT NOT NULL,
  "column_name" VARCHAR(255) DEFAULT '',
  "status" INT DEFAULT 0,
  "del_flag" CHAR(1) DEFAULT '0',
  "create_dept" BIGINT,
  "create_by" BIGINT,
  "create_time" TIMESTAMP,
  "update_by" BIGINT,
  "update_time" TIMESTAMP,
  -- 多租户表额外包含：
  -- "tenant_id" BIGINT,
  PRIMARY KEY ("id")
);

COMMENT ON TABLE "t_xxx" IS '表注释';
COMMENT ON COLUMN "t_xxx"."column_name" IS '列注释';
```

#### oceanbase

```sql
CREATE TABLE `t_xxx` (
  `id` bigint(20) NOT NULL,
  `column_name` varchar(255) NOT NULL DEFAULT '' COMMENT '列注释',
  `status` int(11) NOT NULL DEFAULT '0' COMMENT '状态',
  `del_flag` char(1) NOT NULL DEFAULT '0' COMMENT '删除标志（0-未删除 1-已删除）',
  `create_dept` bigint(20) DEFAULT NULL COMMENT '创建部门',
  `create_by` bigint(20) DEFAULT NULL COMMENT '创建者',
  `create_time` datetime DEFAULT NULL COMMENT '创建时间',
  `update_by` bigint(20) DEFAULT NULL COMMENT '更新者',
  `update_time` datetime DEFAULT NULL COMMENT '更新时间',
  -- 多租户表额外包含：
  -- `tenant_id` bigint(20) DEFAULT NULL COMMENT '租户编号',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='表注释';
```

### DDL 生成逻辑

1. 从字段清单中提取 `inDb=true` 的字段
2. 跳过 `inDb=false` 的纯 VO 承载字段
3. 根据数据库类型映射字段类型
4. String 类型默认长度 255，varchar 默认值 `''`，Integer 默认值 `0`
5. **字典字段**（有 dictType）使用 `varchar(16)` 而非 `integer`，Java 类型为 `String`
5. **通用字段自动追加**（无需在字段清单中声明）：
   - 所有表：`del_flag`、`create_dept`、`create_by`、`create_time`、`update_by`、`update_time`
   - 多租户表额外：`tenant_id`
6. 通用字段类型按上方「通用字段在各数据库中的 DDL 类型」表映射
7. 主键约束使用表名 + `_pkey` 命名（kingbase 风格）
8. 从表 DDL 同理生成，额外包含主表关联字段（如 `course_id`）
9. 从表也包含完整的通用字段