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 自動生成註解表示，方便運維，例如：組織機構編碼，區域編碼