# 功能需求规格文档模板

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

---

## 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 格式

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

### 操作锁定规则 lockRule 格式

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

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

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

---

## 4. 字段清单

### 4.1 主表 `{t_xxx}`

```yaml
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}`

> 仅主从结构时填写。

```yaml
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

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

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

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

### 5.3 从表 VO

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

---

## 6. 特殊需求

```yaml
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             |

### 8.1 主表 `{t_xxx}`

```sql
-- 根据数据库类型生成对应的 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}`（如有）

```sql
-- 同上格式
```

---

## 9. 备注

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