ykt_server_hnswdx/.workbuddy/skills/require/SKILL.md

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. 特殊需求：根据选项标记填充
6. 特殊需求：根据选项标记填充
7. 字典项：根据 dictType 字段收集
8. 建表语句：根据数据库类型和字段清单生成 DDL（见下方 DDL 生成规则）
9. 备注：特殊设计说明

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（人大金仓）

-- 建表
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

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（达梦）

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

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
6. 通用字段自动追加（无需在字段清单中声明）：
   • 所有表：del_flag、create_dept、create_by、create_time、update_by、update_time
   • 多租户表额外：tenant_id
7. 通用字段类型按上方「通用字段在各数据库中的 DDL 类型」表映射
8. 主键约束使用表名 + _pkey 命名（kingbase 风格）
9. 从表 DDL 同理生成，额外包含主表关联字段（如 course_id）
10. 从表也包含完整的通用字段