ykt_server_hnswdx/.workbuddy/skills/ruoyi-backend/references/requirements-template.md

功能需求规格文档模板

本模板用于描述业务功能需求，技能将根据此文档生成后端 + 前端代码。 请按此格式填写，结构化描述越完整，代码生成质量越高。

---

1. 基础信息

属性	值
功能中文名	{功能中文名}
功能简写	{功能简写}
所属模块	{ruoyi-modules/xxx}
主表名	{t_xxx}
从表名	{t_xxx}（如无主从结构则填"无"）
是否多租户	是/否
描述	{一句话功能描述}

---

2. 接口清单

2.1 主表接口

接口	HTTP	路径（后端）	前端路径	权限字符
列表	GET	/{简写}/list	/{模块}/{简写}/list	{模块}:{简写}:list
详情	GET	/{简写}/{id}	/{模块}/{简写}/{id}	{模块}:{简写}:query
新增	POST	/{简写}/	/{模块}/{简写}/	{模块}:{简写}:add
编辑	PUT	/{简写}/	/{模块}/{简写}/	{模块}:{简写}:edit
删除	DELETE	/{简写}/{ids}	/{模块}/{简写}/{ids}	{模块}:{简写}:remove
导出模板	POST	/{简写}/exportTemplate	/{模块}/{简写}/exportTemplate	{模块}:{简写}:export
导入数据	POST	/{简写}/importData	/{模块}/{简写}/importData	{模块}:{简写}:import
导出数据	POST	/{简写}/export	/{模块}/{简写}/export	{模块}:{简写}:export

2.2 补充接口（如有）

接口	HTTP	路径（后端）	前端路径	权限字符
...	...	...	...	...

---

3. 字段属性速查表

属性	含义	可选值	说明
fieldName	字段名（驼峰）	—	代码变量名
columnName	列名（下划线）	—	数据库列名
fieldType	Java类型	String/Long/Integer/BigDecimal/LocalDateTime
inDb	是否在表中存在	true/false	false=纯前端计算字段
inTable	列表是否显示	true/false	生成表格列
inQuery	是否查询字段	true/false	生成搜索条件
queryType	查询方式	eq/like/between	精确/模糊/范围
inForm	是否表单字段	true/false	生成表单项
inAdd	新增表单显示	true/false
inEdit	编辑表单显示	true/false
required	是否必填	true/false	生成校验注解
dictType	字典类型	字典标识	有值=字典下拉，否则普通输入
relation	关联选择配置	对象	有值=弹出选择框
component	前端组件类型	input/select/inputNumber/datetime/textarea	默认根据类型推断
width	表格列宽	数字(px)	默认auto
sort	排序	数字	越小越靠前
excelExport	Excel导出	true/false	默认true

关联选择 relation 格式

relation:
  table: {关联表名}
  idField: {回填ID字段}
  nameField: {显示名称字段}
  title: 选择{实体名}
  path: /{模块}/{实体}/{路径}

---

4. 字段清单

4.1 主表 {t_xxx}

fields:
  # ---------- 主键 ----------
  - fieldName: {xxxId}
    columnName: {xxx_id}
    fieldType: Long
    inDb: true
    inTable: false
    inForm: false
    remark: 主键，编辑时传递

  # ---------- 业务字段 ----------
  - fieldName: {fieldName}
    columnName: {column_name}
    fieldType: String
    inDb: true
    inTable: true           # 列表是否显示
    inQuery: true           # 是否为查询条件
    queryType: like         # eq/like/between
    inForm: true            # 是否在表单中
    inAdd: true             # 新增表单是否显示
    inEdit: true            # 编辑表单是否显示
    required: true          # 是否必填
    dictType: {dict_type}   # 字典类型（有则下拉，否则输入）
    relation:               # 关联弹出选择（如有）
      table: t_xxx
      idField: xxx_id
      nameField: xxx_name
      title: 选择xxx
      path: /xxx/xxx/selectXxx
    component: input       # 前端组件：input/select/inputNumber/datetime/textarea
    width: 150              # 表格列宽
    sort: 1                 # 排序
    excelExport: true
    remark: 字段说明

  # ---------- VO承载字段（仅返回，不展示不维护） ----------
  - fieldName: {fieldName}
    columnName: {column_name}
    fieldType: String
    inDb: true
    inTable: false
    inQuery: false
    inForm: false
    excelExport: false
    remark: VO承载字段，不展示不维护

  # ---------- 公共字段 ----------
  - fieldName: delFlag
    columnName: del_flag
    fieldType: Integer
    inDb: true
    inTable: false
    inForm: false

  - fieldName: createTime
    columnName: create_time
    fieldType: LocalDateTime
    inDb: true
    inTable: true
    inQuery: false
    inForm: false
    component: datetime
    width: 180
    sort: 99
    excelExport: true

4.2 从表 {t_xxx}

仅主从结构时填写。

fields:
  - fieldName: id
    columnName: id
    fieldType: Long
    inDb: true
    inTable: false
    inForm: false

  - fieldName: {mainId}
    columnName: {main_id}
    fieldType: Long
    inDb: true
    inTable: false
    inForm: false

  - fieldName: {fieldName}
    columnName: {column_name}
    fieldType: String
    inDb: true
    inTable: true
    inQuery: false
    inForm: true
    inAdd: true
    inEdit: false           # 编辑时是否允许修改
    required: true
    relation:
      table: t_xxx
      idField: xxx_id
      nameField: xxx_name
      title: 选择xxx
      path: /xxx/xxx/selectXxx
    component: xxxSelect
    sort: 1

  - fieldName: createTime
    columnName: create_time
    fieldType: LocalDateTime
    inDb: true
    inTable: true
    inQuery: false
    inForm: false
    component: datetime
    width: 180
    sort: 99

---

5. VO 结构

5.1 主表列表 VO

{xxx}Vo:
  - {xxx}Id
  - {field1}
  - {field2}
  # ... 按字段清单中 inTable=true 的字段填写
  - createTime

5.2 主表明细 VO（如有从表）

{xxx}DetailVo:
  includes: {xxx}Vo
  additional:
    - {subList}: List<{xxx}{Sub}Vo>   # 从表列表

5.3 从表 VO

{xxx}{Sub}Vo:
  - id
  - {mainId}
  - {field1}
  - {field2}
  - createTime

---

6. 特殊需求

special:
  excelImport: true/false
  excelExport: true/false

  importRules:
    - fieldName: {fieldName}
      required: true/false
      unique: true/false    # 唯一性校验
      min: 数值
      max: 数值

  # 从表是否参与导入导出
  subTableImport: true/false
  subTableExport: true/false

  dubboExpose: true/false
  dubboServiceName: Remote{xxx}Service

---

7. 字典项（如有）

字典类型	枚举值	说明
{dict_type}	0=选项1, 1=选项2	{说明}

---

8. 备注

1. {补充说明1}
2. {补充说明2}