# 📌 簽呈系統 API

🚀 **簽呈系統 API**是一個基於 Laravel 架構開發的 RESTful API，大致上可以分成四個部分:

-   公司列表
-   用戶功能
-   簽呈資料
-   管理員功能

## ✨ 功能介紹

### 1️⃣ 公司列表

### 2️⃣ 用戶功能

-   ✅ 登入
-   ✅ 登出
-   ✅ 獲取個人資料
-   ✅ 更改個人資料
-   ✅ 更改密碼

### 3️⃣ 簽呈資料

-   ✅ 簽呈製作
-   ✅ 刪除簽呈
-   ✅ 密碼簽核
-   ✅ 簽呈清單
-   ✅ 個人簽呈清單
-   ✅ 待簽核簽呈清單
-   ✅ 單一簽呈詳細資料

### 4️⃣ 管理員功能

-   ✅ 註冊用戶
-   ✅ 重置密碼
-   ✅ 用戶列表
-   ✅ 停用/啟用帳號

## 📂 專案結構

```
/s_api
├── app/
│   ├── Console/
│   │   ├── Commands
│   │   │   ├── SignatureScheduledTask.php                # 任務排程
│   ├── Models/
│   │   ├── Company.php                                   # 公司資料模型
│   │   ├── Payment.php                                   # 出款記錄模型
│   │   ├── Record.php                                    # 簽核記錄模型
│   │   ├── Signature.php                                 # 簽呈資料模型
│   │   ├── User.php                                      # 用戶資料模型
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── AuthController.php                        # 用戶功能控制器
│   │   │   ├── DataController.php                        # 簽呈功能控制器
│   │   │   ├── AdminController.php                       # 管理員功能控制器
├── database/
│   ├── migrations/
│   │   ├── signature_migrations/
│   │   │   ├── 2025_02_26_161720_companies_table.php     # 公司列表遷移表
│   │   │   ├── 2025_02_26_161909_signatures_table.php    # 簽呈資料遷移表
│   │   │   ├── 2025_02_26_162034_sign_payment_table.php  # 出款資料遷移表
│   │   │   ├── 2025_02_26_162149_sign_record_table.php   # 簽核記錄遷移表
│   │   ├── 2014_10_12_000000_create_users_table.php      # 用戶資料遷移表
│   ├── seeders/
│   │   ├── CompanySeeder.php                             # 公司資料填充
├── routes/
│   ├── api.php                                           # 路由
├── .env.example                                          # 環境變數範例
├── composer.json                                         # Laravel依賴管理
├── README.md                                             # 這個文件
```

## 🔰 API 使用方式

### 公司列表

-   **Endpoint:** GET /companies
-   **Response Example:**
    ```json
    [
        {
            "id": 1,
            "company": "玉霖建設"
        },
        {
            "id": 2,
            "company": "邑舍設紀"
        },
        {
            "id": 3,
            "company": "展璽國際"
        },
        {
            "id": 4,
            "company": "盈米科技"
        },
        {
            "id": 5,
            "company": "晶霖物業"
        },
        {
            "id": 6,
            "company": "晶霖保全"
        },
        {
            "id": 7,
            "company": "晶霖公寓大廈"
        }
    ]
    ```

### 登入

-   **Endpoint:** POST /register
-   **Request Example:**
    ```json
    {
        "email": "test@gmail.com",
        "password": "test123"
    }
    ```
-   **Response Example:**
    ```json
    {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC8zNC44MS4xNzEuMTkwXC9hcGlcL3B1YmxpY1wvYXBpXC9sb2dpbiIsImlhdCI6MTcyNTUyNzA3MSwiZXhwIjoxNzI1NTMwNjcxLCJuYmYiOjE3MjU1MjcwNzEsImp0aSI6ImM2eHlpU2xkd1BtZUNwajkiLCJzdWIiOjMsInBydiI6IjIzYmQ1Yzg5NDlmNjAwYWRiMzllNzAxYzQwMDg3MmRiN2E1OTc2ZjcifQ.UH1eriH_DM6BXztKK1bXtz1U04Azu1zTVJcuUB7ukzA"
    }
    ```
-   **補充**
    -   會檢查 alive 欄位，若為 0，則被停用，不可登入；反之，預設為 1(啟用中)

### 登出

-   **Endpoint:** POST /logout
-   **Request Headers:**
    ```json
    {
        "Authorization": "Bearer {token}"
    }
    ```
-   **Response Example:**
    ```json
    {
        "message": "Successfully logged out"
    }
    ```

### 獲取個人資料

-   **Endpoint:** GET /me
-   **Request Headers:**
    ```json
    {
        "Authorization": "Bearer {token}"
    }
    ```
-   **Response Example:**
    -   一般帳號
        ```json
        {
            "id": 1,
            "name": "普通員工",
            "email": "test@gmail.com",
            "position": "一般職員",
            "access": 3,
            "companies": [
                {
                    "id": 4,
                    "company": "盈米科技",
                    "grade": 1
                }
            ]
        }
        ```
    -   董事長、財務長、儀華
        ```json
        {
            "id": 1,
            "name": "工程師測試",
            "email": "test@gmail.com",
            "position": "工程師",
            "access": 0,
            "companies": [
                {
                    "id": 1,
                    "company": "玉霖建設",
                    "grade": 0
                },
                {
                    "id": 2,
                    "company": "邑舍設紀",
                    "grade": 1
                },
                {
                    "id": 3,
                    "company": "展璽國際",
                    "grade": 1
                },
                {
                    "id": 4,
                    "company": "盈米科技",
                    "grade": 1
                },
                {
                    "id": 5,
                    "company": "晶霖物業",
                    "grade": 4
                },
                {
                    "id": 6,
                    "company": "晶霖保全",
                    "grade": 4
                },
                {
                    "id": 7,
                    "company": "晶霖公寓大廈",
                    "grade": 4
                }
            ]
        }
        ```
    -   晶霖職員帳號
        ```json
        {
            "id": 1,
            "name": "普通員工",
            "email": "test@gmail.com",
            "position": "一般職員",
            "access": 3,
            "companies": [
                {
                    "id": 5,
                    "company": "晶霖物業",
                    "grade": 4
                },
                {
                    "id": 6,
                    "company": "晶霖保全",
                    "grade": 4
                },
                {
                    "id": 7,
                    "company": "晶霖公寓大廈",
                    "grade": 4
                }
            ]
        }
        ```

### 更改個人資料

-   **Endpoint:** POST /change-profile
-   **Request Headers:**
    ```json
    {
        "Authorization": "Bearer {token}"
    }
    ```
-   **Request Example:**
    ```json
    {
        "name": "用戶姓名"
    }
    ```
-   **Response Example:**
    ```json
    {
        "message": "Profile successfully changed"
    }
    ```

### 更改密碼

-   **Endpoint:** POST /change-password
-   **Request Headers:**
    ```json
    {
        "Authorization": "Bearer {token}"
    }
    ```
-   **Request Example:**
    ```json
    {
        "current_password": "test123",
        "new_password": "test@gmail.com",
        "new_password_confirmation": "test@gmail.com"
    }
    ```
-   **Response Example:**
    ```json
    {
        "message": "Password successfully changed"
    }
    ```

### 簽呈製作

-   **Endpoint:** POST /store
-   **Request Headers:**
    ```json
    {
        "Authorization": "Bearer {token}"
    }
    ```
-   **Request Example:**
    ```json
    {
        "company_id": 4,
        "type": "簽呈類型",
        "number": 1140401,
        "title": "簽呈主旨",
        "description": "簽呈說明，此為選填項目",
        "note": "簽呈備註，此為選填項目",
        "imgs[]": "前端要用formData將檔案作為陣列傳送，json不支援檔案傳送，會重新命名檔名並儲存，此為選填項目"
    }
    ```
-   **Response Example:**
    ```json
    {
        "message": "Successfully applied"
    }
    ```
-   **補充說明**
    -   上傳的圖片檔案存取路徑: /storage/signatures/`簽呈編號`/`檔案名稱`

### 刪除簽呈

-   **Endpoint:** DELETE /signature/{id}
-   **Request Headers:**
    ```json
    {
        "Authorization": "Bearer {token}"
    }
    ```
-   **Response Example:**
    ```json
    {
        "message": "Successfully deleted"
    }
    ```
-   **補充說明**
    -   會同步刪除整個圖片資料夾

### 密碼簽核

-   **Endpoint:** POST /review
-   **Request Headers:**
    ```json
    {
        "Authorization": "Bearer {token}"
    }
    ```
-   **Request Example:**
    ```json
    {
        "signature_id": 1,
        "password": "test@gmail.com",
        "status": 1,
        "reason": "否決理由，選填",
        "date": "2025-04-01", // 此為財務長必填
        "type": 1 // 此為財務長必填，出款方式
    }
    ```
-   **Response Example:**
    ```json
    {
        "message": "Successfully signed off"
    }
    ```
-   **補充說明**
    -   這邊的 status 是 boolean，1 為通過，0 為否決
    -   type 是出款方式，1 為現金，2 為支票，3 為銀行
    -   任何一階段否決，該簽呈更新為否決
    -   reason 是否決理由，為選填
    -   簽呈類型為**用印簽呈**或**一般簽呈**時，簽核終點為董事長;**採購簽呈**時，簽核終點為財務;**請款簽呈**時，則為財務長

### 簽呈清單

-   **Endpoint:** POST /all-application
-   **Request Headers:**
    ```json
    {
        "Authorization": "Bearer {token}"
    }
    ```
-   **Request Example:**
    ```json
    {
        "status": 0, // 選填
        "company_id": 1 // 選填
    }
    ```
-   **Response Example:**
    ```json
    [
        {
            "id": 1,
            "type": "測試類別",
            "company": "玉霖建設",
            "title": "測試主旨",
            "number": 1131225001,
            "user": "工程師測試",
            "status": "申請中",
            "created_at": "2025-03-04 07:50:41",
            "updated_at": "2025-03-11 02:50:11"
        }
    ]
    ```
-   **補充說明**
    -   status 為選填，0→ 申請中，1→ 已通過，2→ 已否決，沒填(null)則全部查詢
    -   company_id 為選填，公司代號參見公司列表，此參數只有公司為複數者需使用，沒填(null)則查詢所屬所有公司資料

### 個人簽呈清單

-   **Endpoint:** POST /my-application
-   **Request Headers:**
    ```json
    {
        "Authorization": "Bearer {token}"
    }
    ```
-   **Request Example:**
    ```json
    {
        "status": 0, // 選填
        "company_id": 1 // 選填
    }
    ```
-   **Response Example:**
    ```json
    [
        {
            "id": 1,
            "type": "測試類別",
            "company": "玉霖建設",
            "title": "測試主旨",
            "number": 1131225001,
            "user": "工程師測試",
            "status": "申請中",
            "created_at": "2025-03-04 07:50:41",
            "updated_at": "2025-03-11 02:50:11"
        }
    ]
    ```
-   **補充說明**
    -   規則同上，只差在這個搜尋條件會多加一個，申請者為該使用者
    -   status 為選填，0→ 申請中，1→ 已通過，2→ 已否決，沒填(null)則全部查詢
    -   company_id 為選填，公司代號參見公司列表，此參數只有公司為複數者需使用，沒填(null)則查詢所屬所有公司資料

### 待簽核簽呈清單

-   **Endpoint:** POST /waiting-review
-   **Request Headers:**
    ```json
    {
        "Authorization": "Bearer {token}"
    }
    ```
-   **Request Example:**
    ```json
    {
        "company_id": 1 // 選填
    }
    ```
-   **Response Example:**
    ```json
    [
        {
            "id": 1,
            "type": "測試類別",
            "company": "玉霖建設",
            "title": "測試主旨",
            "number": 1131225001,
            "user": "工程師測試",
            "status": "申請中",
            "created_at": "2025-03-04 07:50:41",
            "updated_at": "2025-03-11 02:50:11"
        }
    ]
    ```
-   **補充說明**
    -   company_id 為選填，公司代號參見公司列表，此參數只有公司為複數者需使用，沒填(null)則查詢所屬所有公司資料
    -   只有下一個簽核者可看到待簽核的簽呈

### 單一簽呈詳細資料

-   **Endpoint:** GET /application/{id}
-   **Request Headers:**
    ```json
    {
        "Authorization": "Bearer {token}"
    }
    ```
-   **Response Example:**
    -   申請中，尚無人簽核
        ```json
        {
            "name": "工程師測試",
            "company": "玉霖建設",
            "number": 1131225001,
            "title": "測試主旨",
            "type": "測試類別",
            "description": "測試說明",
            "note": "測試備註",
            "imgs": "1741074641_0.jpg",
            "status": "申請中",
            "reason": null,
            "created_at": "2025-03-04 07:50:41",
            "review": [
                {
                    "position": "董事長",
                    "record": null
                },
                {
                    "position": "財務長",
                    "record": null
                }
            ],
            "money": null
        }
        ```
    -   申請中，已有人簽核
        ```json
        {
            "name": "工程師測試",
            "company": "玉霖建設",
            "number": 1131225001,
            "title": "測試主旨",
            "type": "測試類別",
            "description": "測試說明",
            "note": "測試備註",
            "imgs": "1741074641_0.jpg",
            "status": "申請中",
            "reason": null,
            "created_at": "2025-03-04 07:50:41",
            "review": [
                {
                    "position": "董事長",
                    "record": [
                        {
                            "name": "測試",
                            "position": "董事長",
                            "status": "已通過",
                            "created_at": "2025-03-14 15:36:17"
                        }
                    ]
                },
                {
                    "position": "財務長",
                    "record": null
                }
            ],
            "money": null
        }
        ```
    -   已通過
        ```json
        {
            "name": "工程師測試",
            "company": "玉霖建設",
            "number": 1131225001,
            "title": "測試主旨",
            "type": "測試類別",
            "description": "測試說明",
            "note": "測試備註",
            "imgs": "1741074641_0.jpg",
            "status": "已通過",
            "reason": null,
            "created_at": "2025-03-04 07:50:41",
            "review_grade": 0,
            "review": [
                {
                    "position": "董事長",
                    "record": [
                        {
                            "name": "測試",
                            "position": "董事長",
                            "status": "已通過",
                            "created_at": "2025-03-14 15:36:17"
                        }
                    ]
                },
                {
                    "position": "財務長",
                    "record": [
                        {
                            "name": "測試",
                            "position": "財務長",
                            "status": "已通過",
                            "created_at": "2025-03-14 15:40:01"
                        }
                    ]
                }
            ],
            "money": {
                "date": "2025-03-14",
                "type": "現金"
            }
        }
        ```
    -   已否決
        ```json
        {
            "name": "工程師測試",
            "company": "玉霖建設",
            "number": 1131225001,
            "title": "測試主旨",
            "type": "測試類別",
            "description": "測試說明",
            "note": "測試備註",
            "imgs": "1741074641_0.jpg",
            "status": "已否決",
            "reason": "否決原因，選填",
            "created_at": "2025-03-04 07:50:41",
            "review": [
                {
                    "position": "董事長",
                    "record": [
                        {
                            "name": "測試",
                            "position": "董事長",
                            "status": "已否決",
                            "created_at": "2025-03-14 15:43:11"
                        }
                    ]
                },
                {
                    "position": "財務長",
                    "record": null
                }
            ],
            "money": null
        }
        ```

### 註冊用戶

-   **Endpoint:** POST /register
-   **Resquest Example:**
    ```json
    {
        "name": "用戶名稱",
        "position": "用戶職稱",
        "email": "用戶信箱",
        "password": "用戶密碼",
        "company_id": 1, // 用戶公司代號
        "access": 3 // 用戶權限
    }
    ```
-   **Response Example:**
    ```json
    {
        "message": "Successful registration"
    }
    ```
-   **補充說明**
    -   公司代號參見公司列表
    -   權限代號: 0→ 老闆，1→ 財務長，2→ 財務，3→ 一般職員，4→ 不簽核主管，5→ 一級主管(總監、總經理)，6→ 協理，7→ 經理，8→ 行政秘書，9→ 董事長特助
    -   簽呈權限: 0、1、2→ 看得到所有簽呈&有簽核權限，9→ 看得到所有簽呈&無簽核權限，5、6、7、8→ 看得到自己公司簽呈&有簽核權限，4→ 看得到自己公司簽呈&無簽核權限，3→ 只看得到自己申請的簽呈&無簽核權限

### 重置密碼

-   **Endpoint:** POST /reset-password
-   **Request Example:**
    ```json
    {
        "email": "test@gmail.com"
    }
    ```
-   **Response Example:**
    ```json
    {
        "message": "Password successfully reset"
    }
    ```
-   **補充說明**
    -   重置後密碼就是帳號信箱

### 用戶列表

-   **Endpoint:** GET /user-list
-   **Response Example:**
    ```json
    {
        "current_page": 1,
        "data": [
            {
                "id": 1,
                "name": "陳彥良",
                "email": "test@gmail.com",
                "position": "副理",
                "access": 0,
                "alive": 0,
                "company": "盈米科技"
            }
        ],
        "first_page_url": "http://127.0.0.1:8000/api/user-list?page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "http://127.0.0.1:8000/api/user-list?page=1",
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/user-list?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "active": false
            }
        ],
        "next_page_url": null,
        "path": "http://127.0.0.1:8000/api/user-list",
        "per_page": 13,
        "prev_page_url": null,
        "to": 1,
        "total": 1
    }
    ```
-   **補充**
    -   用戶列表有使用 Laravel 分頁功能

### 停用/啟用帳號

-   **Endpoint:** POST /alive-account
-   **Resquest Example:**
    ```json
    {
        "id": 1,
        "alive": 0
    }
    ```
-   **Response Example:**
    ```json
    {
        "message": "Account successfully update"
    }
    ```
-   **補充**
    -   id 為用戶編號；alive 為 boolean，0→ 已停用，1→ 已啟用，預設值為 1

## 🗓️ 任務排程

-   **每天 18 點執行**
-   從建立日開始算起，**超過 7 天**未達董事長簽核階段，自動更新為否決
-   系統否決的話，會在否決原因欄位寫入: "系統否決-超過 7 天未達董事長簽核階段"
-   記錄會寫進 log 檔案，如下

    有資料被更新時

    ```
    [2025-03-21 18:00:01] local.INFO: 超過7天的簽呈已更新為否決，影響筆數: 1，ID: 1
    ```

    沒有資料被更新時

    ```
    [2025-03-22 18:00:01] local.INFO: 沒有符合條件的簽呈需要更新
    ```