# 功能需求规格文档模板

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

---

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

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

---

## 4. 字段清单

### 4.1 主表 `{t_xxx}`

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

> 仅主从结构时填写。

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

---

## 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. 备注

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