# 傭獎系統

### 前端框架

- Vue3 (使用 Composition API)

### UI Libray :

- Element Plus (基於 Vue3)

### 樣式處理 :

- SCSS

### 狀態管理 :

- Pinia (基於 Vue3)

### 處理 Ajax 工具

- axios

### git 分支說明

- sit：測試環境(開發人員)
- uat：測試環境(user)
- master：正式環境

### 開發輔助工具

- eslint + prettier
> Visual Studio Code 建議安裝擴充工具：
> 1. ESLint
> 2. Prettier - Code formatter

### Package.json 自定義腳本指令說明
- dev-mockapi：啟動 vite dev server + 啟動 json-server的mock api server
> 1. 判斷是否要使用mock api的依據為.env.mock檔案的VITE_ISMOCK參數
> 2. 若api進行新增、修改等動作，會真的對專案的db.json檔做變動，因此originDB.json作為原始api資料的依據(若api的資料結構有變動，須適時的更新originDB.json檔)
> 3. json-server/db.json的資料被git ignore，因此各開發者就可任意根據自己的需求開發而不用擔心會影響版控

### 命名規則

- 專案資料夾命名
資料夾採小寫駝峰式(Lower-Camel-Case)
例如：assets、components、pageView
- 檔案名稱命名
除了.vue 檔案採大寫駝峰式(Upper-Camel-Case)
其他檔案一律小寫駝峰式(Lower-Camel-Case)
例如：HomePage.vue、benefits.js、dataInfo.json、mainLogo.svg
- **js 檔案內的程式碼** 命名採小寫駝峰式(Lower-Camel-Case)
例如：firstName、userPhone

- **vue 元件引入(template 內)** 命名採大寫駝峰式(Lower-Camel-Case)
例如：<Home></Home>
- **html、css 選擇器(class、id 等等)** 命名採小寫"-"式(Kebab-Case)
單字一律小寫，並以 "-" 符號做區隔
例如：first-name、user-phone

### 專案目錄結構
├── json-server
│ ├── db.json // api假資料(進行post等操作時，會自動更新此檔)
│ └── routes.json // api假資料的路由路徑轉換(key為要呼叫的路徑，value為對應db.json的key)
├── src
│ ├── assets // 其他雜項要引入的檔案(圖檔、json 檔...)
│ ├── commponents // 任何頁面都可以使用的共用元件
│ │ ├── units // 最小單位的元件
│ │ └── widgets // 由多個 Units 組成的元件
│ ├── composables // 自定義的組合函數(custom hook，命名請使用use開頭)
│ ├── layout // 大部分路由頁面都會出現的元件(header、footer...)
│ ├── router // 路由設定
│ ├── stores // 狀態管理
│ ├── styles // 全域的樣式
│ │ ├── custom // 自定義樣式(index.scss 只負責引入檔案，請勿撰寫 css)
│ │ ├── template // 第三方元件樣式調整(index.scss 只負責引入檔案，請勿撰寫 css)
│ │ ├── app.scss // 全站 scss 的總集合
│ │ ├── extend.scss // 全站 scss 的 extend 繼承
│ │ ├── mixin.scss // 全站 scss 的 mixin 方法
│ │ └── variable.scss // 全站 scss 定義的變數
│ ├── utilities // 任何頁面都可以使用的功能性 funtion
│ ├── views // 各路由頁面的主元件(根據路由設定的"/"路徑來決定巢狀結構)

### .vue 檔，內部 ref、reactive 資料拆分說明

若創建的 ref + reactive 內的靜態資料結構超出 50 行，請在同層資料夾路徑下創建 config.js 檔(與.vue檔檔名一樣)，來將靜態檔案填入後再匯出，並且將 .vue 檔案與此 config.js 檔放在同一資料夾。

> ref 與 reactive 的選擇，為了專案一致性，請盡量以使用ref為主

例如：
原始路徑檔案為
├── views
│ ├── login
│ │ └── Index.vue
變成
├── views
│ ├── login
│ │ ├── Index.vue
│ │ └── indexConfig.js

### .vue 檔，內部 method function 資料拆分說明

若創建的 method function 總和的資料結構超出 100 行，請在同層資料夾路徑下創建 helper.js 檔(與.vue檔檔名一樣)，來將function填入後再匯出，並且將 .vue 檔案與此 helper.js 檔放在同一資料夾。
例如：
原始路徑檔案為
├── views
│ ├── login
│ │ └── Index.vue
變成
├── views
│ ├── login
│ │ ├── Index.vue
│ │ └── indexHelper.js

### .vue 檔，元件內再拆分元件說明

路由下的第一層先創建資料夾，資料夾下再創建 Index.vue(主元件)，若主元件要再拆分子元件，則同層創建子元件(例如：Acomponent.vue、Bcomponent.vue)，而若子元件還要再拆分子元件，則再往下創建資料夾，(例如：Acomponent 要再拆分子元件)，資料夾名稱取為該元件名稱，並且創建 Index.js，以此類推的巢狀結構。
例如：
原始路徑檔案為
├── views
│ ├── login
│ │ ├── Index.vue (login 主元件)
│ │ └── Acomponent.vue (login 主元件拆分的子元件)
變成
├── views
│ ├── login
│ │ ├── Index.vue (login 主元件)
│ │ ├── acomponent
│ │ │ ├── Index.vue (login 主元件拆分的子元件,同Acomponent.vue(此時為子元件中的主元件))
│ │ │ └── AcomponentChild.vue (login 子元件下的子元件(孫元件))

### .vue 檔，script中各區塊的順序

區塊大致區分成：

1. 接收資料區塊：prop、emit、
2. 組合函數區塊：useRouter、useXXX...
3. 資料區塊：ref、reactive、computed、watch
4. 生命週期區塊：onMounted、onUpdated...
5. 方法區塊：event function ( 請使用函數宣告 (Function Statement) )
6. 輸出區塊：defineExpose (由於作為要從子元素輸出給父元素的項目，因此放置於最後比較合適)

> - 撰寫時，請依上述序號由上而下來撰寫各個區塊
> - 當同個頁面有多個邏輯需處理時，使用一個立即執行函數做為一個邏輯處理區塊，並在此立即執行函數中回傳所要回傳的資料、方法...,此邏輯處理區塊中的內容請持續依上述分類區塊撰寫
> 例如：
>
> ```xml
> <script setup>
> //表單邏輯
> const { formName } = (function handleFormLogic() {
> const state = ref({formName:"demo"});
>
> onMounted(() => {
> //...
> });
>
> function onSubmit(){
> //發送表單事件
> }
>
> return {
> ...toRefs(state.value),
> onSubmit
> };
> })();
>
> //表格邏輯
> const { tableName } = (function handleTableLogic() {
> const state = ref({tableName:"demo"});
>
> onMounted(() => {
> //...
> });
>
> function onBtnClick(){
> //表格中的按鈕事件
> }
>
> return {
> ...toRefs(state.value),
> onBtnClick
> };
> })();
>
> </script>
> ```

### 單元測試、元件測試

- 副檔名使用 .spec
- 檔案的位置建立在要測試的主元件(或要測試的function檔案)同層，先創建資料夾(資料夾名稱取名**tests**)，接著在此**tests**建立與主元件同名稱的.spec 檔，若有拆分多個子元件，則同 [.vue 檔，元件內再拆分元件說明](#vue-檔，元件內再拆分元件說明) 規則。
> ※ 在要創建**tests**資料夾時，只要它的上層資料夾以上出現過一次，之後的子、孫層就不需要再建立**tests**資料夾，只要單純建立一般資料夾即可

1. 例如：
├── views
│ ├── login
│ │ ├── Index.vue (login 主元件)
│ │ ├── Acomponent.vue (login 主元件拆分的子元件)
│ │ ├── **\_\_tests\_&zwnj;\_**
│ │ │ ├── **Index.spec**
│ │ │ └── **Acomponent.spec**
2. 例如：
├── views
│ ├── login
│ │ ├── Index.vue (login 主元件)
│ │ ├── acomponent
│ │ │ ├── Index.vue (login 子元件下的主元件)
│ │ │ └── AcomponentChild.vue (login 子元件下的子元件(孫元件))
│ │ ├── **\_\_tests\_&zwnj;\_**
│ │ │ ├── **Index.spec**
│ │ │ ├── **acomponent**
│ │ │ │ ├── **Index.spec**
│ │ │ │ └── **AcomponentChild.spec**
3. 例如：
├── utilities
│ ├── validation
│ │ ├── index.js (要測試的function檔案)
│ │ ├── **\_\_tests\_&zwnj;\_**
│ │ │ └── **Index.spec**

### 共用元件

[元件使用說明](https://hackmd.io/EkM9pGkeQK-f7hcedcu_BA)