功能需求规格文档模板

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

1. 基础信息

属性	值
功能中文名	{功能中文名}
功能简写	{功能简写}
所属模块	{ruoyi-modules/xxx}
主表名	{t_xxx}
从表名	{t_xxx}（如无主从结构则填"无"）
是否多租户	是/否
数据库类型	{kingbase/mysql/dm/oceanbase}（默认 kingbase）
描述	{一句话功能描述}

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
`lockRule`	操作锁定规则	对象	有值=按此字段值控制行级操作权限

关联选择 relation 格式

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

操作锁定规则 lockRule 格式

当某字段的值决定该行是否允许修改/删除时，使用 lockRule。字段需 inDb=true，通常 inTable=false（不显示列）、inQuery=false（不作为搜索条件），但必须包含在 VO 中供前端判断。

lockRule:
  lockValue: {锁定值}          # 当字段值等于此值时，行操作被锁定
  lockActions:                  # 被锁定的操作列表
    - edit                      # 禁止编辑
    - delete                    # 禁止删除
  tip: {锁定提示文案}           # 锁定时显示的提示（可选）

典型场景：dataSource（数据来源）字段，值为 1（第三方同步）时禁止修改和删除，值为 0（平台录入）时允许操作。

4. 字段清单

4.1 主表 `{t_xxx}`

fields:
  # ---------- 主键 ----------
  - fieldName: {xxxId}
    columnName: {xxx_id}
    fieldType: Long
    inDb: true
    inTable: false
    inForm: false
    excelExport: 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: dataSource
    columnName: data_source
    fieldType: Integer
    inDb: true
    inTable: false          # 不显示列
    inQuery: false          # 不作为查询条件（如需查询可设为 true）
    inForm: true            # 表单中可选
    inAdd: true
    inEdit: true
    required: true
    dictType: data_source
    component: select
    lockRule:               # 操作锁定规则
      lockValue: 1          # dataSource=1 时锁定
      lockActions:
        - edit              # 禁止编辑
        - delete            # 禁止删除
      tip: 第三方数据不可操作
    excelExport: true
    remark: 数据来源：0-平台录入，1-第三方同步

  # ---------- 公共字段（所有表统一包含，多租户表增加 tenant_id） ----------
  # 通用字段定义（无需在字段清单中重复写，建表时自动追加）：
  # | 字段          | Java类型        | 说明               |
  # | ------------- | --------------- | ------------------ |
  # | del_flag      | Integer         | 逻辑删除：0-未删除，1-已删除 |
  # | create_dept   | Long            | 创建部门             |
  # | create_by     | Long            | 创建者              |
  # | create_time   | LocalDateTime   | 创建时间             |
  # | update_by     | Long            | 最后修改者            |
  # | update_time   | LocalDateTime   | 最后修改时间           |
  # | tenant_id     | Long            | 租户ID（仅多租户表包含）    |

  - 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

  # 从表同样包含通用字段（del_flag, create_dept, create_by, create_time, update_by, update_time）
  # 多租户从表也包含 tenant_id

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. 建表语句

根据基础信息中的"数据库类型"和字段清单自动生成建表 DDL。支持的数据库类型：kingbase（人大金仓）、mysql、dm（达梦）、oceanbase。默认为 kingbase。

通用字段：所有表统一包含以下字段（建表语句自动追加，无需在字段清单中重复）：

字段类型说明

del_flag TINYINT/SMALLINT 逻辑删除：0-未删除，1-已删除

create_dept BIGINT 创建部门

create_by BIGINT 创建者

create_time DATETIME/TIMESTAMP 创建时间

update_by BIGINT 最后修改者

update_time DATETIME/TIMESTAMP 最后修改时间

如果指明了多租户，则额外包含：

字段类型说明

tenant_id BIGINT 租户ID

字段	类型	说明
del_flag	TINYINT/SMALLINT	逻辑删除：0-未删除，1-已删除
create_dept	BIGINT	创建部门
create_by	BIGINT	创建者
create_time	DATETIME/TIMESTAMP	创建时间
update_by	BIGINT	最后修改者
update_time	DATETIME/TIMESTAMP	最后修改时间

字段	类型	说明
tenant_id	BIGINT	租户ID

8.1 主表 `{t_xxx}`

-- 根据数据库类型生成对应的 DDL
-- kingbase 示例格式：
-- CREATE TABLE "dbo"."t_xxx" ( ... );
-- ALTER TABLE "dbo"."t_xxx" COMMENT '表注释';
-- ALTER TABLE "dbo"."t_xxx" MODIFY "col" COMMENT '列注释';

8.2 从表 `{t_xxx}`（如有）

-- 同上格式

9. 备注

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

requirements-template.md 11 KB History Raw

功能需求规格文档模板

1. 基础信息

2. 接口清单

2.1 主表接口

2.2 补充接口（如有）

3. 字段属性速查表

关联选择 relation 格式

操作锁定规则 lockRule 格式

4. 字段清单

4.1 主表 {t_xxx}

4.2 从表 {t_xxx}

5. VO 结构

5.1 主表列表 VO

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

5.3 从表 VO

6. 特殊需求

7. 字典项（如有）

8. 建表语句

8.1 主表 {t_xxx}

8.2 从表 {t_xxx}（如有）

9. 备注

requirements-template.md 11 KB

History Raw

4.1 主表 `{t_xxx}`

4.2 从表 `{t_xxx}`

8.1 主表 `{t_xxx}`

8.2 从表 `{t_xxx}`（如有）