JeeSite 4.x 开发规范、设计原则、数据库规范

1、用户界面

一、设计原则

1）对齐

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

2）多元化

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

3）布局色彩

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

4）导航设计

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

二、数据列表

1）列对齐方式

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

2）列显示格式

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

3）其余要求

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

4）查询条件

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

三、编辑表单

1）表单控件

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

2）其它要求

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

2、数据库设计规范

一、命名规范

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

二、设计规范

• 一般状况下每张表必须有主键，对于非主键，具备惟一性质的，必须加，惟一索引
• 每张表，每一个字段都必须有正确的中文描述说明，以便快速生成数据字典
• 业务数据表必要时冗余基础信息表的核心字段，如：部门编码、部门名称，须要成对出如今业务数据表中
• 对于字符类型（VERCHAR）字段，肯定数据值仅是数字、字母并没有其它特殊字符的状况下使用VERCHAR字段，其它必须使用NVARCHAR类型，避免使用VARCHAR类型
• 表字段的长度要统一，尤为基础数据在业务数据中的引用，如：部门编码、部门名称，在任何业务数据表中的长度务必保持一致
• 存储过程、自定义函数、视图，以及调度，必需要有详细的注释说明
• 统一入口，统一出口原则：相赞成义的数据存储、提取，使用同一过程和方法
• 不要盲目的加入其余索引，根据须要统一加索引

三、使用规范

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

3、平台开发规范

一、JeeSite 包的命名规范

设有公司统一报名如：com.jeesite 包，不容许直接在此包下直接创建模块，要先建立一个 modules 包。

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

二、JeeSite 分层命名规范

Controller

操做	命名	备注
类名	以Controller结尾，继承BaseController	UserController
类上的映射路径	${adminPath} /模块/子模块/功能	${adminPath}/sys/user
自动注入属性	与注入名相同，不容许注入Dao	@Autowired
方法上的映射路径	与方法名相同	@RequestMapping
方法上的权限字符串	模块名:子模块名:控制器名:功能名	@RequiresPermissions
每次请求都会执行的方法	get	@ModelAttribute
列表页面	list
列表数据	listData
新增或编辑表单	form
新增或编辑提交地址	save
删除	delete
停用	disable
启用	enable
主键校验	check开头
导入	import开头
导出	export开头
树结构数据	treeData

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

操做	命名	备注
类名	SysUserController.java	系统模块可不加 sys
映射路径	/sys/user/list	/模块[/子模块]/功能/操做
映射方法	public list() {}	功能名，如列表：list，列表数据：listData，表单：form
视图文件名	userList.html	不要直接命名为 list.html
视图文件路径	/WEB-INF/views/modules/sys/user/

Service

操做	命名	备注
类名	以Service结尾	继承 CrudService，TreeService，QueryService
查询一条数据	get	以 get 开头
插入数据	insert	以 insert 开头
更新数据	update	以 update 开头
新增或编辑	save
删除	delete	以 delete 开头
查询多条数据	findList	以 find 开头
查询多条分页	findPage	以 find 开头

Dao

操做	命名	备注
类名	以Dao结尾	继承 CrudDao，TreeDao，QueryDao
查询一条数据	get	以 get 开头
插入数据	insert	以 insert 开头
更新数据	update	以 update 开头
删除	delete	以 delete 开头
物理删除	phyDelete
查询多条数据 findList	以 find 开头

Entity

操做	命名	备注
类名	根据表名以驼峰命名法转换	继承 DataEntity，TreeEntity，BaseEntity
主键	@Column(isPk=true)	指定主键的列会自动与 getId() setId() 绑定
验证方法	Hibernate Validator	例如：@Length，@NotNull，查看文档
注解位置	依据能写 get 方法上毫不写字段上原则
父类中已有的属性	父类中已有的属性无需定义，特殊状况除外
非表属性的字段	如查询字段，必须写清楚注释说明用途。

三、JeeSite 视图文件规范

全部视图文件均放在：模块项目/src/main/resources/views 目录下，尽可能不放在web项目下，约束以下：

命名	备注
include	公共视图代码块
layouts	公共视图布局文件
modules	功能模块视图文件，格式：/modules/模块名[/子模块]/功能页面
themes	个性化主题视图文件存放路径，格式：/themes/modules/模块名[/子模块]/功能页面

四、JeeSite 静态文件规范

全部静态文件均放在：模块项目/src/main/resources/static 目录下，尽可能不放在web项目下，约束以下：

命名	备注
common	存放公共脚本，不建议项目使用过程当中修改。
modules	项目相关的模块 js 和 css 文件存放位置，格式：/modules/模块名[/子模块]/静态文件
themes	个性化主题视图文件存放路径，格式：/themes/modules/模块名[/子模块]/静态文件
组件文件	格式：组件名/组件版本/组件文件，例如：/static/echarts/4.2/组件文件包

4、其它开发规范

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