---
title: 委外廠商網站開發協議書
description: 委外廠商網站開發協議書
tags: 交付文件
---
# 委外廠商網站開發協議書

本協議書（以下簡稱「本協議」）由以下兩方締結：

甲方：龍騰文化事業股份有限公司（以下簡稱「甲方」）

乙方：XXX科技有限公司（以下簡稱「乙方」）

<br>
就甲方委託乙方進行網站開發，達成以下協議：

1. 乙方負責網站功能開發與維護，甲方負責維運與部署，可參考 **[交付與部署流程圖](#交付與部署流程圖)** 與 **[開發規範](#開發規範)**。
2. 甲方提供程式碼交付伺服器(以下簡稱「龍騰 GitLab」)，乙方須完整交付開發過程所產出之資源，資源包含設計文件圖片、程式代碼、程式異動詳細紀錄說明、相關套件版本文件、相關環境參數文件等，並上傳至「龍騰 GitLab」，可參考 **[交付規範](#交付規範)**。
3. 甲方提供的 **[交付規範](#交付規範)**，乙方須照規範進行交付。
4. 乙方在完成每次交付後，若需甲方協同進行測試與驗收，則須通知並交付驗收項目之文件，甲方再照此文件進行測試與驗收。驗收項目文件格式先由乙方進行規範與提供，而待驗收過程進行到需甲方手動部署至正式機時，會由甲方通知甲、乙雙方相關人員進行測試驗收，驗收文件為乙方交付之驗收項目文件。
5. 交付規範內容，甲方有權再提起補充項目，並由甲方與乙方共同決議項目執行時間。
6. 甲方負責將乙方每次交付部屬至測試機，以供線上測試。

## 交付與部署流程圖

## 開發規範
- **前後端分離**
- 前後端各自一個龍騰 GitLab Repository。
- 將應用程式的前端和後端分開，讓它們各自獨立開發和部署。前端主要處理用戶介面和交互邏輯，後端主要處理資料處理和資料庫訪問。這樣做可以提高應用程式的可靠性、擴展性和安全性。

- **資料庫遷移**
- 對於已上線資料庫是無法透過還原覆蓋方法進行版本更新，否則會讓上線資料出現遺失狀況。因此在未來所有的資料庫更新都必須透過遷移機制進行更新。
- 乙方若已導入「資料遷移」機制，需優先說明「資料遷移」所使用的工具，如:用 Python 開發，所使用的遷移機制工具為「Flask-Migrate」，且需把工具使用方法記錄於文件並上傳至龍騰 GitLab，並在未來乙方有異動資料庫(例如：新增刪除修改資料表、資料表欄位)時，協助甲方使用該工具完成資料庫異動。
- 若專案因未使用 ORM Model 進行資料庫建模，因此無法導入 Migration(例如: Flask-Migrate 工具) 進行結構遷移。則必須以人工紀錄每次資料庫異動指令，未來乙方在異動資料庫(例如：新增刪除修改資料表、資料表欄位)時，須交付 **[資料庫異動範本](#2.-資料庫異動範本(configs/migrations.sql))**，以便甲方進行資料庫異動遷移。

- **部署容器化**
- 透過容器化技術，可快速進行各種環境部署，避免每次環境遷移時需要重新安裝相關套件與設定修改。
- 分成前端、後端、資料庫三個容器(視情況增加)，各容器使用適合的基礎映像檔來進行打包。

- **配置文件化**
- 透過將配置項目編寫成程式碼(JSON, YAML等)，可以使得配置更易於管理、測試和部署，例如: 過往用 flask 時會把 port 寫在 `app.run()` 的參數內，需改成將 host 和 port 等變數紀錄在`.env`檔，執行該程式時需要讀取`.env`檔內的 host 和 port，有需要讀某個檔案路徑也都可以改用這方式，盡量把變數、參數集中管理。

## 交付規範

### 交付清單

| 名稱 | 交付位置 |
| --- | ------- |
| 程式原始碼 | GitLab/source_code |
| `db.sql`/`migrations.sql` | GitLab/configs |
| `dev_info.md` | GitLab/ |
| `deploy_info.md` | GitLab/ |
| 資料遷移工具文件| GitLab/ |
| 環境參數 | GitLab/Wiki |
| 相關config檔(nginx.conf) | GitLab/configs |

由甲方提供前端、後端共兩組龍騰GitLab Repository，供乙方進行交付。如下：
- 前端Repository: `https://gitlab.ltedu.com.tw/xxx_frontend`
- 後端Repository: `https://gitlab.ltedu.com.tw/xxx_backend`
- 關於龍騰GitLab詳細使用方法，可參考[合作廠商GitLab操作手冊](https://hackmd.io/ZpqiSfyxQv2wQ5sWyn3afQ)

### 1. 交付之檔案結構
透過龍騰 GitLab進行文件與原始碼交付，此交付的檔案結構如下：
- **documents** : 資料夾，存放一些跟專案有關的設計文件。
- **source_code** : 資料夾，專案的程式碼，甲方會從這資料夾抓取程式碼進行CI/CD。
- **configs** : 資料夾，使用服務的一些設定檔案，例如`nginx.conf`、`db.sql`等。
- **dev_info.md** : Markdown文件，紀錄相關開發語言與套件資訊，可參考 **[開發紀錄範本](#1.-開發紀錄範本(dev_info.md))**。
- **deploy_info.md** : Markdown文件，紀錄開發環境部署資訊，可參考 **[部署紀錄範本](#5.-部署紀錄範本(deploy_info.md))**。

### 2. 原始碼交付
- **原始碼請放至 source_code 資料夾**
- **提供 release 和 master 兩分支再由龍騰進行CI/CD**
- `release`分支推送將自動部署至測試機，`master`分支推送則需由甲方手動部署至正式機，可參考 **[Git Flow 規範](#Git-Flow-規範)**。
- **開放乙方擁有 master 推送權限**
- 由乙方自主控管分支與合併，避免因甲方參與合併而產生錯誤。
- **Git Flow 和 Commit message 規範，盡可能貼近我方所建議的規範**
- 雙方使用相同規範，可以減少溝通和協調方面的時間浪費，並且確保程式碼與自動化流程相容，以提高項目的品質和可靠性。
- 規則範例請查看 **[Git Flow 規範](#Git-Flow-規範), [Commit message 規範](#Commit-message-規範)**

### 3. 資料庫交付

- **正式機第一次資料庫初始建置**
- 由乙方提供最後一次異動的 db.sql 備份檔，讓甲方於正式機進行第一次資料庫初始建立。甲方完成正式機資料庫建立後，未來乙方則需以資料庫異動範本進行交付。
- **資料庫備份檔名為db.sql**
- **上傳至 configs 資料夾**

<!-- - **正式機未來異動更新**
- 專案因未使用 ORM Model 進行資料庫建模，因此無法導入 Flask-Migrate 工具進行資料遷移。未來乙方異動資料庫(例如：新增刪除修改資料表、資料表欄位)時，須交付資料庫異動範本，以便甲方後續進行資料庫異動更新。
- **資料庫異動範本檔名為migrations.sql**
- **上傳至 configs 資料夾**
- 規則範例請查看 **[資料庫異動範本](#2.-資料庫異動範本(configs/migrations.sql))** -->

<!-- ### 4. 功能測試腳本交付
- **用來測試服務有正常啟動的腳本**
- 若有測試用的api或將應用程式轉換成系統服務，用該腳本測試api有正常或系統服務有正常啟用。
- **檔案或資料夾名稱以`test_`做開頭**
- **上傳至 configs 資料夾**
- 規則範例請查看 **[功能測試腳本](#4.-功能測試腳本範本)** -->
### 4. 開發紀錄交付
- **乙方開發紀錄**
- 乙方在開發程式過程，可詳細紀錄相關開發語言與套件資訊，甲方可參照此文件以詳細了解專案的技術範疇。
- **採用 Markdown 撰寫**
- **檔名為dev_info.md**
- **上傳至專案根目錄，與documents資料夾同ㄧ層**
- 相關範例請查看 **[開發紀錄範本](#1.-開發紀錄範本(dev_info.md)
)**

### 5. 部署紀錄交付
- **乙方部署紀錄**
- 乙方在內部部署開發環境過程，可詳細紀錄設定指令、參數設定、所遇問題與排除方法，甲方可參照此文件進行CI/CD建置與改善。
- **採用 Markdown 撰寫**
- **檔名為deploy_info.md**
- **上傳至專案根目錄，與documents資料夾同ㄧ層**
- 規則範例請查看 **[部署紀錄範本](#4.-部署紀錄範本(deploy_info.md))**

### 6. 環境參數檔交付

- **環境檔主要區分為:**
1. 前端
- `.env.local`: 本地端環境檔
- `.env.development`: 測試機環境檔
- `.env.production`: 正式機環境檔
2. 後端
- `.env.local`: 本地端環境檔
- `.env.development`: 測試機環境檔
- `.env.production`: 正式機環境檔
- **環境檔資訊並非以檔案形式交付，需在龍騰GitLab Wiki頁面進行填寫。**
- 前端與後端各有 .env.local、.env.development、.env.production等環境檔，需各別撰寫。
- ＷiKi撰寫，可用前端、後端可當作主標題，環境檔名當作次標題，如下：
<pre>
# Backend

## .env.local

  # 模式。共有local、development、production三種選項。
  - MODE=local

## .env.development

  # 模式。共有local、development、production三種選項。
  - MODE=development

</pre>

- 環境檔撰寫方式可參考 ***[參數環境檔範本](#3.-參數環境檔範本)***
:::danger
請把現有專案的`.env.*`環境檔加入`.gitignore`並移除git上的環境檔。

### 7. 相關 config 檔交付
- **服務所需 config 檔**
- 乙方在內部部署開發環境過程所需的設定檔，如: **nginx.conf**，甲方可參照此設定檔進行CI/CD建置與改善。
- **上傳至 configs 資料夾**

### 8. 資料遷移工具使用說明
- **需把工具使用方法記錄於文件並上傳至龍騰 GitLab，協助甲方使用該工具完成資料庫的異動**
- **若無導入資料遷移機制，則需按照「[資料庫異動範本](#2.-資料庫異動範本(configs/migrations.sql))」，人工紀錄每次資料庫異動 SQL 指令，並上傳至 configs 資料夾**

## Git Flow 規範

甲方針對 `release`、`master` 兩個分支提供CI/CD。乙方合併至 `release` 分支時會進行 CI/CD 自動部署至測試機；合併至 `master` 分支時則只會自動CI，再由甲方手動部署至正式機。

:::danger
`release` 及 `master` 分支均由乙方自行合併，再由甲方進行部署。
:::

- **測試機測試階段 :**
- 乙方可將本機分支推送合併至 `release` 分支，合併後 CI 會對 `release` 跑測試，若測試未過需修改重新推送合併，測試通過後會自動部署至測試機，乙方測試人員或甲方PM、測試人員均可在測試機上測試功能，若沒測過則修改後重新推送，都測試確認沒問題後由甲方 PM 通知乙方可合併至 `master`。
- **正式機上版階段 :**
- 乙方可合併至 `master` 後，CI 會對 `master` 跑測試，測試未過同樣需要修改後重新推送合併，測試通過後會由甲方手動部署至正式機。

- **正式機 BUG 修復階段 :**
- 若使用者或測試人員在正式機發現 BUG，由甲方回報給乙方進行修正並合併至 `release` 分支，於測試機進行測試與驗收後，再由甲方 PM 通知乙方合併至 `master`。
- 若為 **緊急 BUG** 需要立即修復，乙方可修正後可同時合併至 `release` 及 `master`，再由甲方手動部署至正式機。
- **緊急 BUG**均由甲方發起並通知乙方。

## Commit message 規範

:::info
建議使用 <a href="https://github.com/commitizen/cz-cli" target="_blank">commitizen</a> 或 <a href="https://github.com/streamich/git-cz" target="_blank">git-cz</a> 方便規範 commit message 格式。
:::

- 格式 : `<類型>(<更動範圍>): 描述`
- 範例 1 : `feat(card): change color background color`
- 範例 2 : `fix(login): fix OAuth login api`

**Commit 類型說明 :**

- `feat` &mdash; 新功能
- `fix` &mdash; 修復 bug
- `docs` &mdash; 修改文件
- `chore` &mdash; 修改打包過程或其他套件的設定
- `style` &mdash; 程式碼撰寫格式、風格、缺失修改，不影響程式運作
- `refactor` &mdash; 重構程式碼，不包含新功能
- `perf` &mdash; 改善效能
- `test` &mdash; 新增/修正測試
- `build` &mdash; 修改構建專案設定和第三方套件
- `ci` &mdash; 修改 CI 相關設定
- `revert` &mdash; 還原至某 commit

## 範本

### 1. 開發紀錄範本(dev_info.md)
可以依照前後端或使用服務當作標題，並於標題下說明使用的開發語言、相關套件與安裝指令。如下：

# Application Server
- Flask: 2.0.3
- Python: 3.6.8
- 相依套件安裝方法:
  pip install -r requirements.txt

# Web Server
- Nignx: 1.17
- 相依套件安裝方法:
  apt-get install -y libffi-dev py3-pip gcc openssl-dev

# Database Server
- mariadb: 10.4.19

### 2. 資料庫異動範本(configs/migrations.sql)

-- 異動ID: 00001
-- 異動資料表: Inform|首頁公告
-- 異動行為: 增加欄位
-- 異動人員: kevin
-- 異動日期: 2023/4/14
-- 異動用途: 首頁公告增加一個短說明欄位，實作於xxxAPI。
ALTER TABLE Inform ADD ShortInfo varchar(255);

-- 異動ID: 00002
-- 異動資料表: Inform|首頁公告
-- 異動行為: 更名欄位
-- 異動人員: kevin
-- 異動日期: 2023/4/15
-- 異動用途: 首頁公告短說明欄位進行更名為ShortDesciption，為了統一命名規範。
ALTER TABLE Inform RENAME COLUMN ShortInfo TO ShortDesciption;

> *每個異動行為都為獨立一個區塊。*

- **註解說明**
- 異動ID: 每個行為都為一個唯一ID，共五位數，範圍為: 00001~99999。
- 異動資料表: 異動資料表名稱與說明。
- 異動行為: 資源異動行為，暫定以下行為: 新增資料表、更名資料表、刪除資料表、新增欄位、更名欄位、異動欄位型態、刪除欄位。未來若有需要其他行為可再提出。
- 異動人員: 為乙方負責修改之工程師暱稱。
- 異動日期: 為乙方當前開發進行修改的日期。
- 異動用途: 說明這次異動的詳細目的。

### 3. 參數環境檔範本
前端與後端開發都會需要配置環境參數，每個參數需明確標記用途說明，格式可參照下方：

- .env.local <font color=#BEBEBE>*以下內容為「本地前端環境檔」內容範例*</font>

    # 模式。共有local、development、production三種選項。
    MODE=local

    # API呼叫網址
    API_URL=http://localhost/

- .env.development <font color=#BEBEBE>以下內容為「開發機後端環境檔」內容範例</font>

    #===FlaskAPI===
    # 模式。共有local、development、production三種選項。
    MODE=development

    #===Mysql===
    # 資料庫主機
    DB_HOST=XXX

    # 資料庫名稱
    DB_DATABASE=XXX

### 4. 部署紀錄範本(deploy_info.md)

# 建置流程和注意事項

## 前端建置和容器化
1.  用 Nginx 設置 proxy_pass 到 api 服務端口
2.  SSL 憑證檔案 VOLUME 的位置
3.  使用 npm 安裝相依套件，然後使用 webpack 構建，最後將產生的 dist 資料夾內容放置到 html 資料夾底下

## 後端建置和容器化
1. 使用 pip 安裝相依套件
2. 用啟動腳本啟動 api 服務

## 資料庫建置和容器化
1. 需執行腳本完成備份檔的匯入
2. ...

## 其他注意事項
...