开发规范、设计原则、数据库规范、平台规范、AI 规范

# 一、用户界面

# 1、设计原则

# 1）对齐

• 层次结构清晰，观察 1 像素，引导视觉流向，让用户更流畅地接收信息
• 如果页面的字段或段落较短、较散时，需要确定一个统一的视觉起点

# 2）多元化

• 根据不同的用户体验，可快速进行界面色调切换
• 点击侧边栏头像，扩大工作区域显示，可快速折叠侧边栏和顶部导航栏
• 根据用户喜好，可折叠侧边栏，默认折叠侧边栏，取消页签模式，表单弹窗模式
• 弹窗的表单，关闭表单后，自动刷新列表数据，保留列表查询条件
• 列表操作体验清晰，不太实用的操作进行折叠隐藏
• 列表查询区域隐藏，扩大列表显示区域

# 3）布局色彩

• 响应式样式，12 列栅格化布局，根据屏幕大小进行自适应布局，支持平板或手机操作
• 色彩源于『自然』的设计价值观，设计师通过对自然场景的抽象捕捉

# 4）导航设计

• 在广义上，任何告知用户他在哪里，他能去什么地方以及如何到达那里的方式，都可以称之为导航
• 支持侧边栏全部导航；或者顶部一级导航，二级以下导航在侧边栏

# 2、数据列表

# 1）列对齐方式

• 短小字符居中，比较长的字符居左，日期居中，货币或带小数点的数字居右
• 数值位数相等的字段，如：编码、编号：居中
• 字典类，如：分类、类型、类别、状态：居中
• 不规则长度，5个字符以上，名称、标题：居左
• 日期时间：居中
• 与货币相关的，金额、单价：居右
• 带小数点的数字，数量、百分数：居右
• 整数型数字，年龄，个数：居中
• 合计，与合计列对齐方式相同

# 2）列显示格式

• 与货币相关，金额或单价：保留两位小数，如无特殊要求，不加货币符号，不使用千分位符号，默认单位“元”，如果单位不是“元”，则必须在列标题或当前页标明单位，如：金额（万元）
• 长字符列，名称、标题、备注等：当列宽不足时，用 … 号表示无法显示的字符
• 日期：yyyy-MM-dd，日期时间：yyyy-MM-dd HH:mm，如业务无特别要求，不带秒，如需要时分秒，格式为： yyyy-MM-dd HH:mm:ss 采用24小时制
• 列宽要适中，根据内容调整列宽大小

# 3）其他要求

• 列表中存在与金额相关的列，或者与数量相关的列，根据业务要求，列表底部增加合计，如果列表是分页列表，合计默认为查询结果的合计，而不是当前页合计
• 合计校验：明细行合计值，与合计行值相同，不要出现明细与合计的数值不对的情况
• 汇总与明细校验：汇总值与钻取的明细合计值相同，同上
• 根据业务要求，比较大或比较耗时的页面，第一次打开时，如没有特殊要求，默认不执行查询显示数据，需要点击查询，执行显示数据，并提示“点击查询显示数据”信息
• 对于列与数字相关的，如：金额、数量、证件号码（如：身份证）或其它由长数字组成的字段，不能出现科学计数法格式
• 明细行中不能存在重复记录

# 4）查询条件

• 数据字典字段作为查询条件，无特殊要求，信息内容相对固定少于20行时，采用下拉选择方式，否则采用弹出对话框选择方式；有特别要求时，可以采用输入方式，进行模糊查询，除此之外，必须采用选择方式
• 查询条件为多行时，标签需要上下两端对齐，标签单行右对齐，注意美观
• 输入框或选择框，上下两端对齐，宽度适中

# 3、编辑表单

# 1）表单控件

• 必填信息，必须明确区分，标签前增加红色星号，醒目显示，必填信息在保存时必须增加必填验证
• 数值类型，必须增加数值验证
• 日期类型，必须增加日期格式验证
• 边界验证，录入信息的长度不得多于数据库字段长度，input标签必须包含增加maxlength属性
• 无特殊情况，如：电话、身份证、邮箱，能用正则表达式验证的字段必须启用验证
• 界面录入信息与列表显示信息保持一致，避免字段张冠李戴
• 界面显示信息与数字相关的，如：金额、数量、证件号码（如：身份证）或其它由长数字组成的字段，不能出现科学计数法格式
• 必须避免提交类型按钮多次执行，出现多条相同信息，在未成功之前，不能多次点击

# 2）其它要求

• 对整个项目进行跨浏览器的测试（必须兼容IE10+、360、Chrome、Firefox浏览器）
• 界面大小应该适合美学观点，感觉协调舒适，能在有效的范围内吸引用户的注意力，注意细节（观察1像素距离、列表文字对齐）
• 必须保证在最小分辨率1024x768的可视性（不允许错版），在高分辨率下页面要自适应，不能出现标题背景空白，错位情况
• 每一步操作，如保存、更新、审核，都要有提示，如：保存xx成功！
• 检查界面是否有文字错误，避免出现看不懂的文字
• 手机端或PC端图标及标题内容显示不全的，应尽量减少文字，不显示…，让文字显示全

# 3）Vue 分离版设计

• 共享 Ant Design of React (opens new window) 设计工具体系。
• 提炼自企业级中后台产品的交互语言和视觉风格。

# 4）AI 前端代码约束（分端约束，不通用）

Vue 和 Beetl 前端组件体系完全不同，约束不可混用。

AI 生成前端代码时：先确认目标端（Vue / Beetl），然后加载对应 Skill 读取对应文档：

• Vue 端 → 加载 frontend-vue Skill，读取 /vue-crud-view/、/vue-basic-form/、/vue-basic-table/
• Beetl 端 → 加载 frontend-beetl Skill，读取 /views-beetl/、/datagrid/

Vue 分离端约束要点（详细规则见上述文档）：

Beetl 经典端约束要点（详细规则见上述文档）：

Vue & Beetl 共有的后端约束 → 后端验证注解 Hibernate Validator 查看文档 (opens new window)

# 二、数据库设计规范

# 1、命名规范

• 数据库对象，如：表、列、索引、视图、存储过程、自定义函数，的命名的原则是简、短，易懂好记，有意义的英文单词、常用缩写，多个单词组成的，当长度比较大时应使用缩写，特殊情况使用拼音或首字母
• 数据表命名：必须带有模块前缀，如财务总账：js_fin_
• 如果命名由多个词汇组成，词汇之间加 _ 下划线，如：js_sys_office_company

# 2、设计规范

• 通常情况下每张表必须有主键，对于非主键，具有唯一性质的，必须加，唯一索引
• 每张表，每个字段都必须有正确的中文描述说明，以便快速生成数据字典
• 业务数据表必要时冗余基础信息表的核心字段，如：部门编码、部门名称，需要成对出现在业务数据表中
• 对于字符类型（VERCHAR）字段，确定数据值仅是数字、字母并无其它特殊字符的情况下使用VERCHAR字段，其它必须使用NVARCHAR类型，避免使用VARCHAR类型
• 表字段的长度要统一，尤其基础数据在业务数据中的引用，如：部门编码、部门名称，在任何业务数据表中的长度务必保持一致
• 存储过程、自定义函数、视图，以及调度，必须要有详细的注释说明
• 统一入口，统一出口原则：相同意义的数据存储、提取，使用同一过程和方法
• 不要盲目的加入其他索引，根据需要统一加索引
• 必须使用内置通用字段组，不要自行定义相同含义的字段。详细字段定义参见：内置通用字段组
  • 主键：必须使用 varchar(64) 类型，字段名为 id （来自 BaseEntity）或者其它自定义的业务名称，使用 _code 结尾，如：office_code
  • 状态：必须使用 char(1) 类型，字段名统一为 status（来自 DataEntity）
  • 创建者：必须使用 varchar(64) 类型，字段名统一为 create_by（来自 DataEntity）
  • 更新者：必须使用 varchar(64) 类型，字段名统一为 update_by（来自 DataEntity）
  • 创建时间 / 更新时间：必须使用 datetime 类型（来自 DataEntity）
  • 备注：必须使用 nvarchar(500) 类型，字段名统一为 remarks（来自 DataEntity）
  • 树结构相关：父级编号 parent_code varchar(64)、排序号 tree_sort decimal(10)、末级标识 tree_leaf char(1) 等（来自 TreeEntity）
  • 多租户：租户代码 corp_code varchar(64)、租户名称 corp_name nvarchar(100)（来自 DataEntity）

# 数据库字段类型 → Java 类型强制映射（AI 必须遵守）

# 3、使用规范

• 在指定用户下，只有项目经理具有数据表对象的设计权限，其他开发人员不得调整表结构
• 作业调度需要有详细的登记台账（也是项目管理要求的一部分）
• SQL书写采用：关键字大写，表名，列名小写
• 变更数据库必须同步 erm 模型

# 4、数据库设计

JeeSite核心模块数据库设计 ER 图

# 三、平台开发规范

AI 注意：生成代码前，必须先读取以下目录的模板文件，严格按其结构输出，不可凭记忆生成：

• modules/core/src/main/resources/templates/modules/gen/config.xml（模板注册中心，入口）
• modules/core/src/main/resources/templates/modules/gen/crud/（实体/DAO/Service/Controller 模板）
• modules/core/src/main/resources/templates/modules/gen/crud_cloud/（微服务生成模板）
• modules/core/src/main/resources/templates/modules/gen/vue/（Vue 前端模板）
• modules/core/src/main/resources/templates/modules/gen/view/（Beetl 前端模板）
• modules/core/src/main/resources/templates/modules/gen/app/（手机端前端模板）
• 禁止 AI 生成模块代码，应该通过：模块管理 - 新建模块 - 生成代码（包括 Java 后端模块、Vue 前端模块、微服务模块）
• 代码生成后对照 四.9 AI 修订清单 逐项检查

# 1、JeeSite 包的命名规范

设有公司统一包名如：com.jeesite 包（根据项目单位命名），不允许直接在此包下直接建立模块，要先创建一个 modules 包。

• 模块格式：com.jeesite.modules.模块名.分层.子模块名.功能类
  • 分层为 entity、dao、service、web、utils、config
  • 若模块下只有几个功能，没有子模块，就不需要再建立子模块了
• Spring Boot 自动配置文件格式：com.jeesite.autoconfigure.模块名.配置类
  • 自动配置的类，在 /META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 里指定
• 通用封装包或工具类：com.jeesite.common.大类.小类.封装类

# 2、JeeSite 分层命名规范

# Controller

四名保持命名联系： Controller类名、映射路径、方法名、视图文件名，举例如下：

遵循一定的命名规范，可快速根据映射路径找到对应的源代码。

# Service

以上方法，参数应该使用 Entity 类型，返回值应该使用 Entity 或 List<Entity> 类型，更新返回 void 类型。

# Dao

以上方法，参数应该使用 Entity 类型，查询返回值应该使用 Entity 或 List<Entity> 类型，更新返回 long 类型。

# Entity

# 3、Beetl 视图文件规范

所有视图文件均放在：模块项目 /src/main/resources/views 目录下，尽量不放在web项目下，约束如下：

# 4、Static 静态文件规范

所有静态文件均放在：模块项目/src/main/resources/static 目录下，尽量不放在web项目下，约束如下：

# 5、Vue 分离端规范

AI 注意：生成 Vue 前端代码前，加载 frontend-vue Skill 读取对应文档：/vue-crud-view/（CRUD视图）、/vue-basic-form/（BasicForm 组件）、/vue-basic-table/（BasicTable 组件）、/vue-auth/（前端权限）、/vue-comp/（通用组件）。

开发辅助工具：

目录结构规范（详细：/vue-install-deploy/）：

核心组件体系（基于 Antdv Next 或 Ant Design Vue 4.x）：

showType → Vue 控件和 gridRowCol → 布局的详细映射表见本文 六.4 节。

# 6、注解驱动 SQL 规范

JeeSite 采用 @Table + @Column 注解驱动 MyBatis 动态 SQL，不再为 CRUD 操作手写 XML 映射。XML 仅用于自定义复杂查询。

# @Table 注解约束

// 关键结构（完整代码参见 crud/entity.xml 模板）
@Table(name = "${_prefix}test_data", alias = "a", label = "测试数据", columns = {
        @Column(includeEntity = BaseEntity.class),   // 当包含 corp_code、corp_name 时，必须使用。
        @Column(includeEntity = DataEntity.class),   // 当包含 create_by、create_date、update_by、update_date、remarks、status 时，必须使用。
        @Column(name = "id", attrName = "id", label = "编号", isPK = true),
        // ...
    },
    joinTable = {
        @JoinTable(type = Type.LEFT_JOIN, entity = Office.class, alias = "o",
            on = "o.office_code = a.office_code",
            columns = {@Column(includeEntity = Office.class)}),
    },
    orderBy = "a.update_date DESC"
)

规则：表名必须带 ${_prefix} 多租户前缀；主表别名固定 "a"。

# @Column 规范

• name：数据库列名（下划线命名），必须与数据库表一致
• attrName：Java 属性名（驼峰命名），必须与 getter/setter 对应
• label：中文描述，用于数据字典和 Excel 标题
• isPK：是否为主键（isPK=true 的列自动与 getId()/setId() 绑定）
• isQuery：是否作为查询条件（默认 true，可显式关闭无关字段的查询能力）
• queryType：查询运算符类型，可选：EQ, NE, GT, GTE, LT, LTE, BETWEEN, LIKE, LEFT_LIKE, RIGHT_LIKE
• isUpdateForce：更新时是否总是更新此字段（默认 false）
• isInsert / isUpdate：控制字段是否参与插入/更新

# @JoinTable 规范

• 关联 User：@JoinTable(type = Type.LEFT_JOIN, entity = User.class, alias = "u", on = "u.user_code = a.user_code", columns = {@Column(includeEntity = User.class)})
• 关联 Office：同上模式，on = "o.office_code = a.office_code"
• 关联 Company：on = "c.company_code = a.company_code"
• 关联 Area：on = "ar.area_code = a.area_code"
• attrName 务必与属性名一致，否则关联查询结果无法赋值

# 范围查询字段规范

Entity 中定义 gte/lte 范围查询字段（非表字段，必须注释说明用途）：

public void setCreateDate_gte(Date createDate){
    createDate = DateUtils.getOfDayFirst(createDate);
    sqlMap.getWhere().and("create_date", QueryType.GTE, createDate);
}
@Schema(description = "小于等于创建时间")
public Date getCreateDate_lte(){
    return sqlMap.getWhere().getValue("create_date", QueryType.LTE);
}

关键点：getter 中通过 sqlMap.getWhere().getValue("数据库列名", QueryType.XXX) 实现范围查询，不赋值时就忽略该条件。

# MyBatis XML Mapper 规范

仅当注解无法满足时才编写 XML。标准格式（详细参见 crud/mapper.xml 模板）：

存放位置：/src/main/resources/mappings/modules/<模块名>/<Dao名>.xml

# 7、实体字段类型规范（基于代码生成模板）

根据代码生成模板 config.xml 中定义的字段类型，新增实体字段时必须遵循以下类型映射：

注解位置约束：验证注解（@NotBlank, @Size 等）优先写在 get 方法上，不写在字段上。

# 8、Service 层两种模式约束

使用原则：

• 子表批量操作必须在 save() 中处理（使用 executeBatch()）
• 写操作必须标注 @Transactional
• 依赖注入统一使用构造器注入

# 9、文件路径与命名约束

# 后端 Java 文件

# 前端视图文件

# 10、完整代码模板（AI 必须读取实际模板文件）

AI 生成各层代码时，必须先去读取以下实际模板文件，不要凭记忆生成。模板目录：

modules/core/src/main/resources/templates/modules/gen/
├── crud/entity.xml       → Entity 模板
├── crud/mapper.xml       → MyBatis Mapper XML 模板
├── crud/dao.xml          → DAO 接口模板
├── crud/service.xml      → Service 模板
├── crud/controller.xml   → Controller 模板
├── config.xml            → 模板分类注册中心（入口配置）
├── vue/                  → Vue 前端模板（vueApi/vueList/vueForm/vueIndex/vueImport）
├── crud_cloud/           → 微服务架构模板
└── query/                → 仅查询功能模板

生成步骤：

1. 先读 config.xml 确认模板分类（crud/crud_vue/treeGrid/service/dao/query）
2. 按分类找到对应的 .xml 模板文件并读入
3. 严格按模板结构输出代码，替换其中的 ${...} 变量
4. 生成后对照 四.9 AI 修订清单 逐项检查

关键约束摘要（详细格式见模板文件）：

• Entity：@Table 注解声明表映射，columns 中 includeEntity 引入父类字段，验证注解写在 get 方法上
• DAO：@MyBatisDao + extends CrudDao<T>，不声明基础 CRUD 方法，只声明自定义查询
• Mapper XML：仅自定义查询需要，namespace 与 DAO 全类名一致，基础 CRUD 由 @Table 注解自动生成
• Service：extends CrudService<Dao, Entity>，写操作加 @Transactional，构造器注入依赖
• Controller：extends BaseController，@RequestMapping("${adminPath}/模块/功能")，方法按 get→list→listData→form→save→disable→enable→delete 顺序

# 11、树结构实体规范

树结构实体继承 TreeEntity<T> 而非 DataEntity<T>。AI 生成时读取 treeGrid_* 模板文件。

关键差异（与普通 CRUD 对比）：

• columns 中用 @Column(includeEntity = TreeEntity.class) 引入树形字段
• 树名字段标记 isTreeName = true
• orderBy 使用 a.tree_sorts 排序
• 必须重写 getParent() / setParent() 返回具体类型
• Service 继承 TreeService<Dao, Entity> 而非 CrudService
• Controller 增加 treeData 方法返回 List<Map<String, Object>> 供前端树组件使用

# 12、主子表（子表）处理规范

AI 生成时读取 config.xml 中模板的 <childTable> 节点，以及 vue/vueFormChildList.xml。

关键规则：

executeBatch 批量处理模式（三条分支）：

STATUS_DELETE  → dao.delete(child)       // 标记删除的行
isNewRecord()  → dao.insert(child)       // 新增行
其他            → dao.update(child)       // 修改行

# 13、导入导出规范

Entity 导出字段声明（@ExcelFields + @ExcelField）：

Controller 导出：new ExcelExport("标题", XxxEntity.class).setDataList(list).write(response, "文件名.xlsx") Controller 导入：xxxService.importData(file, updateSupport)，实际逻辑在 Service 中实现。

# 14、代码注释规范

• 类级注释：必须包含功能描述、@author、@version
• 方法注释：公有方法必须写 JavaDoc（一句话描述即可），私有方法可不写
• 非表字段：必须用 // 查询：xxx 注释说明用途
• 复杂逻辑：关键分支用 // 步骤1：xxx 注释
• 禁止：无意义的 // add by xxx 2024-01-01 注释
• TODO/FIXME：临时标记必须附带说明和日期

# 四、其它开发规范

# 1、主键规范

有意义的、有规则的数据必须采用手动编码方式，不允许使用 UUID 自动生成注解表示，方便运维，例如：组织机构编码，区域编码。

# 2、事务管理规范

• 写操作（insert / update / delete / save）必须标注 @Transactional
• 只读操作不标注事务注解，由 CrudService 基类默认管理
• 跨 Service 调用写入操作时，调用方必须标注事务，确保原子性
• 文件上传 + 数据库写操作必须在同一事务中处理，避免脏数据

# 3、异常处理规范

• Controller 层不抓取异常，统一由框架全局异常处理器拦截
• Service 层校验失败抛出 RuntimeException 或框架定义的业务异常
• 禁止在 DAO 层抛出业务异常（只抛数据访问异常）
• JSON 接口返回统一使用 renderResult(Global.TRUE/FALSE, text("xxx成功！"))

# 4、依赖注入规范

• 禁止在 Controller 中注入 DAO（违反分层原则）
• 使用构造器注入（非 @Autowired 字段注入），提高可测试性
• 不引入非必要的第三方依赖，优先使用框架已有工具类
• 新增 Maven 依赖必须在父 POM 中统一管理版本号

# 5、权限控制规范

• 每个 Controller 方法必须标注 @RequiresPermissions("模块名:功能名:操作名")
• 权限字符串格式：sys:user:view / sys:user:edit（三段式：模块:功能:操作）
• 数据权限过滤使用 addDataScopeFilter(entity, ctrlPermi) 方法，Service 里实现该方法，Controller 里调用该方法
• 字段权限过滤使用 addFieldScopeFilter(entity) 方法，Service 里实现该方法，Controller 里调用该方法

# 6、常量与枚举规范

• 模块级常量定义在实体类或专门的常量类中（如 User.USER_TYPE_EMPLOYEE）
• 字典值不得硬编码在视图层，必须通过数据字典组件读取
• 状态值、类型值禁止使用魔数，必须定义为常量或枚举

# 7、禁止硬编码与安全规范

• 禁止在代码中硬编码密码、密钥、Token、数据库连接串
• SQL 查询参数必须使用 #{} 占位符（预编译），严禁用 ${} 拼接用户输入（SQL 注入风险）
• ${} 仅用于 sqlMap.xxx.toSql() 动态 SQL 标签和 _prefix 表前缀

# 8、代码生成后的 AI 修订清单

AI 使用代码生成器模板生成代码后，必须逐项检查以下内容：

# 五、AI 开发助手行为边界

# 允许操作清单

# 禁止操作清单

# AI 决策树：选择正确的方法

Q1：新建模块？

→ 是：先创建模块包结构（entity/dao/service/web），再生成代码
→ 否：进入 Q2

Q2：功能是什么类型？

→ 单表 CRUD + Vue 前端：使用 crud_vue 模板，生成 5 个后端 + 5 个前端文件
→ 单表 CRUD + Beetl 前端：使用 crud 模板，生成 5 个后端 + 3 个 Beetl 文件
→ 树结构 CRUD：使用 treeGrid_vue / treeGrid 模板，Entity 继承 TreeEntity
→ 仅后端持久层：使用 service（含 Service）/ dao（仅 DAO）模板
→ 仅查询（不含增删改）：使用 query 模板

Q3：有子表（一对多）？

→ 主表按 Q2 选择模板
→ 子表 Entity 继承 DataEntity，外键用 attrName="父表Entity.id"
→ 主表 Service 用 executeBatch 处理子表批量操作

Q4：需要关联系统表（User/Office/Company/Area）？

→ Entity 中声明 private Office office; 属性
→ @JoinTable 中配置 LEFT_JOIN
→ @Column(name="office_code", attrName="office.officeCode")

Q5：需要导入导出？

→ Entity 加 @ExcelFields / @ExcelField 注解
→ Controller 加 exportData / importData 方法
→ Excel 导出用 new ExcelExport("标题", XxxEntity.class)

# 六、AI 代码生成模板约束

AI 在生成代码时，必须严格按照以下模板分类对应的文件清单输出，不允许生成模板之外的文件结构。每种模板分类对应固定的生成文件集合，File 数量不可多也不可少。

# 1、模板分类与生成文件对照表

说明：

• 主子表时，子表额外生成：Entity + Mapper XML + DAO（子表不生成 Service 和 Controller）
• Cloud 模式的模板（crud_cloud_vue 等）不在此列，适用于微服务架构

# 2、各文件生成约束（AI 必须精确遵循）

# Entity 文件约束

• 必须继承：DataEntity<T>（普通表）或 TreeEntity<T>（树表）
• 必须含：@Table 注解，columns 中使用对应通用字段时，必须 includeEntity BaseEntity/DataEntity/TreeEntity
• 必须含：无参构造器 this(null) + 带主键构造器 super(id)
• 字段声明：使用包装类型（String, Long, Integer, BigDecimal, Double），禁用基本类型
• 验证注解：全部写在 get 方法上（非字段上）
• 关联对象：private Office office; 方式声明，@Column(name="office_code", attrName="office.officeCode")

# DAO 文件约束

• 必须标注 @MyBatisDao，继承 CrudDao<T> / TreeDao<T>
• 禁止添加 @Mapper 注解（@MyBatisDao 已足够）
• 禁止写 get / insert / update / delete 基础方法（父接口已提供）
• 仅自定义查询方法需要声明（格式：List<T> findXxxList(T entity) / Page<T> findXxxPage(T entity)）

# Mapper XML 文件约束

• 生成时机：仅在 Entity 注解无法满足（如自定义复杂查询）时生成
• 存放位置：/src/main/resources/mappings/modules/{模块名}/{DaoName}.xml
• namespace：必须与 DAO 完整类名一致
• 基础 CRUD：不需要 XML（框架从 @Table 注解自动生成 SQL）
• 自定义查询：使用 #{} 预编译参数，条件判断用 <if test> 标签

# Service 文件约束

• 简单 CRUD：直接 extends CrudService<Dao, Entity>，不加接口
• API 契约：interface XxxService extends CrudServiceApi<T> + class XxxServiceSupport extends CrudService<D, T> implements XxxService
• 构造器注入：private final XxxDao xxxDao; + 构造函数参数（非 @Autowired 字段）
• 写操作：必须加 @Transactional
• 子表操作：在 save() 中用 executeBatch() 批量处理

# Controller 文件约束

• 必须继承 BaseController，使用 @Controller（非 @RestController）
• URL 前缀：@RequestMapping(value = "${adminPath}/模块/功能")
• 注入：仅注入 Service（禁止注入 DAO），构造器注入
• 方法顺序：get(ModelAttribute) → list → listData → form → save → disable → enable → delete → treeData(如需要) → exportData/importData(如需要)
• 权限注解：每个方法必须加 @RequiresPermissions
• JSON 返回：使用 renderResult(Global.TRUE/FALSE, text("提示信息"))

# 3、Controller 方法清单（标准 CRUD）

每个标准 CRUD Controller 方法按以下顺序排列（详细格式读取 crud/controller.xml 模板）：

★ = 树结构专属，☆ = 按需添加。JSON 返回统一用 renderResult(Global.TRUE/FALSE, text("xxx成功！"))。

# 4、Vue 分离端文件约束

Vue 分离端根据 config.xml 的 showType 和 gridRowCol 配置生成表单布局：

• 表单控件映射（基于 config.xml showType）：

• 栅格布局映射（基于 config.xml gridRowCol）：

# 5、文件头与版权声明

所有 AI 生成的 Java/Vue 文件必须包含以下版权声明（遵循项目约定）：

/**
 * Copyright (c) 2013-Now https://jeesite.com All rights reserved.
 */

# 6、禁止生成的破坏性代码

• 禁止生成改变现有 API 签名的代码（除非明确要求重构）
• 禁止生成删除/清空数据表的 SQL 语句（如 TRUNCATE, DROP, 无条件的 DELETE）
• 禁止生成绕过 Shiro 权限验证的代码
• 禁止生成 JS 中直接操作 DOM 绕过 Vue 数据绑定的代码
• 禁止在异步线程 / @Async 方法 / CompletableFuture 中通过 UserUtils.getUser() 或 SecurityUtils.getSubject() 获取当前登录用户信息（异步线程无登录上下文）