├── README.md ├── frontend.md ├── design.md └── backend.md /README.md: -------------------------------------------------------------------------------- 1 | # 5xTraining 2 | 3 | ## 關於本教程 4 | 5 | 這份文件是五倍紅寶石的內部教育訓練教材，用以建立新進社員對於 Ruby on Rails 以及各種週邊技術的基礎知識。原始版本為[日本株式会社万葉](https://github.com/everyleaf/el-training)編撰。 6 | 7 | 所有新進工程師或技術實習生，不論其原本技術能力如何，皆需要完成本份教程中的必修課題。 8 | 9 | 我們對於研習期間沒有特別的規定，只要完成所有的步驟就算是研習結束。 10 | 11 | 在本教程中，預設會有下列兩種角色： 12 | 13 | - 新人（mentee）：本教程的使用者。 14 | - 導師（mentor）：對新人進行教育、指導、建議。也負責帶領新人討論並決定需求與規格等。 15 | 16 | 導師要指導新人到什麼程度，完全交由導師自己決定。研習期間的設定，也是由導師依據新人能力和公司專案狀態，做初步的評估。 17 | 18 | ## 目錄 19 | 20 | - [後端 & DevOps](backend.md) 21 | - [前端](frontend.md) 22 | - [設計](design.md) 23 | 24 | ## License 25 | 26 | 本教程以 [Creative Commons 姓名標示-非商業性-相同方式分享 4.0 國際](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh_TW) 授權。 27 | 28 | [![Creative Common License](https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png)](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh_TW) -------------------------------------------------------------------------------- /frontend.md: -------------------------------------------------------------------------------- 1 | # 5xTraining: 前端 2 | [使用說明](README.md) 3 | 4 | ## 概要 5 | 6 | ### 開發工具 7 | 8 | 請以下列程式語言、框架的最新版本進行開發。 9 | 10 | * JavaScript (ECMAScript 2015 / ES6) 11 | * React.js 12 | * [React Context API](https://reactjs.org/docs/context.html) 或 [Redux](https://github.com/reduxjs/redux) 13 | 14 | ※ 每一步驟如果沒有要求使用 library 就代表必須手刻實作該功能 15 | 16 | ※ 本教程中對效能、資安沒有特別的要求，但仍需要有一定的品質。網站效能太差的話，會被要求改善。 17 | 18 | ## 教程的最終目標 19 | 20 | 完成本教程後，我們會認為你已經習得以下能力： 21 | 22 | * 可以用 React 實做基本的網站 23 | * 可以將 React 專案上線至一般的環境 24 | * 對於已經上線的 React 專案，能夠進行功能的追加和資料維護 25 | * 知道如何在 GitHub 發 PR、merge 等協作流程，以及必須的 git 指令 26 | * 能將 commit 切成適度的大小 27 | * 能寫出適合的 PR 說明 28 | * 能針對 code review 進行修正 29 | * 遇到問題時，能夠適時以口頭或線上工具向相關人員（在本例中為導師）求救 30 | 31 | ## 參考教學資料 32 | 33 | - Git: [https://gitbook.tw/](https://gitbook.tw/) 34 | - [React 官方教學](https://reactjs.org/docs/hello-world.html) 35 | - [鐵人賽文章](https://ithelp.ithome.com.tw/users/20103131/ironman/1012?page=1) 36 | - [ECMAScript 6 简介](http://es6.ruanyifeng.com/?search=let&x=0&y=0#docs/intro#ECMAScript-%E7%9A%84%E5%8E%86%E5%8F%B2) 37 | - [React 入门实例教程](http://www.ruanyifeng.com/blog/2015/03/react.html) 38 | 39 | ## 必修課題 40 | 41 | ### 步驟1: 建立 JavaScript 的開發環境 42 | 43 | #### 1-1: 安裝 Node.js 44 | 45 | - 利用 [nvm](https://github.com/creationix/nvm) 或 [Homebrew](https://brew.sh/index_zh-tw) 安裝最新版本的 Node.js 46 | - 以 `node -v` 指令來確認 Node.js 的版本 47 | 48 | #### 1-2: 安裝 [yarn](https://yarnpkg.com/zh-Hans/) 49 | - `$ brew install yarn` 50 | - 以 `$ yarn -v` 指令來確認版本 51 | - 了解 `package.json` 基本內文格式與基本指令 52 | - 了解 `dependencies`、`devDependencies`、`peerDependencies` 的差異與指令 53 | 54 | ### 步驟2: 在 GitHub 建立 repo 55 | 56 | - 在你的環境中安裝 git 57 | - macOS 的話，請以 `brew` 等工具安裝 58 | - 以 `$ git config` 設定 user name 和 email 59 | - 請考慮專案名稱（也等於 repo 名稱） 60 | - 建立 repo 61 | - 如果沒有帳號的話，先申請帳號 62 | - 接著產生空白的 repo 63 | 64 | ### 步驟3: 建立 React 專案 65 | 66 | - 以 `$ npx create-react-app` 指令，建立 app 最低限度的樣板和檔案 67 | - 在 `create-react-app` 產生的專案目錄下，建立 `docs` 資料夾，並將本教程文件 commit 進去 68 | - 搬進來是為了方便之後開發時可以參考 69 | - 將成品 push 到 GitHub 的 repo 70 | - 將使用的 Node.js 版號寫進 `package.json`（也請確認 React 版號是否有標明） 71 | 72 | ### 步驟4: 復刻 [五倍官網首頁](https://5xruby.tw/) 73 | - 引入 `bootstrap`、`jquery` 請使用 yarn 安裝使用 74 | - 不使用 React、其它 library, 只能用 jquery + css 實作官網上的元件(bootstrap 只可用 grid system、排版用的 class) 75 | - 請分成三階段發 PR, header、footer、content 76 | - 只需考量 sm、md、lg 3種 RWD breakpoint 77 | - Carousel 元件的實作需要達成以下要求： 78 | - 不使用 BS 內建的 79 | - 點下圓點按鈕可以跳到指定的 Slide 80 | - 自動播放（5秒換頁一次） 81 | - 滑鼠在 Carousel 上時暫停自動播放 82 | - 目標著重於 jquery、javascript、css 熟悉度 83 | 84 | ### 步驟5: 使用 React 改寫 [五倍官網首頁](https://5xruby.tw/) 85 | - 使用 `bootstrap` 作為 css 框架，請使用 yarn 安裝引入 86 | - 除了 React App 進入點之外不要使用 jQuery 或是 Vanilla DOM API 87 | - 將靜態資料抽離存成 json 檔, 並以 react props 的方式帶入 88 | - 目標著重於 React 元件模組化與 props 傳遞 89 | - 只需考量 sm、md、lg 3種 RWD breakpoint 90 | - Carousel 元件的實作需要達成以下要求： 91 | - 不使用 BS 內建的，手刻 Carousel React 元件 92 | - 點下圓點按鈕可以跳到指定的 Slide 93 | - 自動播放（5秒換頁一次） 94 | - 滑鼠在 Carousel 上時暫停自動播放 95 | 96 | ### 步驟6: 使用 React 製作 [/contacts](https://5xruby.tw/contacts) 頁面 97 | - 必須符合 Controlled Components 特性 98 | - 各個欄位必須加上 html5 validate 99 | - 使用 [React Modal](https://github.com/reactjs/react-modal) 將送出的表單資料顯示在 Popup Modal 上面(樣式只要求有 popup modal 效果) 100 | 101 | ### 步驟7: 改用 [webpack](https://webpack.js.org/) 替代 `create-react-app` 102 | - 設定 loader, 讓專案能讀取 css、js、font、image 等...檔案 103 | - 設定 babel, 能編譯 react jsx + es6 語法 104 | - 分類好資料夾架構 105 | - 將先前的五倍首頁 react 版本導入至 webpack 並可運作 106 | 107 | ### 步驟8: 加入 eslint 修正語法錯誤與 coding style 108 | - 要求參照 [airbnb config](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb) 109 | - 能夠在終端機使用 `$ yarn lint` 來跑專案內的 js 檔案做檢查 110 | - 修正所有 eslint 錯誤 111 | 112 | ### 步驟9: 整合 Travis CI 113 | - 加入 eslint 當做測試項目 114 | 115 | ### 步驟10: 加入 [React-Router](https://github.com/ReactTraining/react-router) 116 | - 將首頁 nav 的導覽項目做成各個 router page, 並可以有 single page render(SPA) 的效果 117 | - 新加入的 router page 不需實作該頁內容, 只需標註是哪一頁即可 118 | - 需有當前網頁路徑的 nav list hightlight 的效果 119 | 120 | ### 步驟11: fetch api 資料串接 121 | - 使用 React 製作 [/posts](https://5xruby.tw/posts) 頁面, 資料來源請使用 [jsonplaceholder](https://jsonplaceholder.typicode.com/) 122 | - 使用 React 製作 pagination component 需達成以下要求： 123 | - 必須是一個獨立且可引入使用的 component 124 | - 一頁 post 資料比數最多顯示 4 筆 125 | - 至少需要有 `首頁`、`末頁`、`下一頁` 按鈕功能 126 | 127 | ### 步驟12: 錯誤處理 128 | - 使用 [HOC](https://reactjs.org/docs/higher-order-components.html) 與 [Error Boundaries](https://reactjs.org/docs/error-boundaries.html#introducing-error-boundaries) 替 `/post` 頁面製作 fetch api 拿不到資料的錯誤處理 129 | - 錯誤處理的效果顯示自行定義 130 | 131 | ### 步驟13: 使用 [React Context Api](https://reactjs.org/docs/context.html#api) refactor component 132 | - 了解 context api 使用時機, 並在現有程式碼尋找哪個 component 適合使用 context api 並以此做 refactor 133 | - 此步驟可以隨時安插在其他步驟實作 134 | 135 | ### （番外篇）選修課題 136 | - [react render props](https://reactjs.org/docs/render-props.html): 可替代 HOC 的另一種程式碼共用手法。 137 | - react: 用 create-react-app 建立一個新的專案，並研究用 [npm run eject](https://github.com/facebook/create-react-app/blob/master/packages/react-scripts/template/README.md#npm-run-eject) 產生出來的 webpack 設定檔與步驟七手刻的版本有哪些差異？ 138 | - react application test： https://jestjs.io/docs/en/tutorial-react 139 | - redux (container、action、reducer) 140 | - react: credit card form (信用卡表單) 141 | - react: infinite scroll 142 | - react: popup video 143 | -------------------------------------------------------------------------------- /design.md: -------------------------------------------------------------------------------- 1 | # 5xTraining: 設計 2 | [使用說明](README.md) 3 | 4 | ## 概要 5 | 6 | ### 開發需求 7 | 8 | 本教程的主要課題為指定網站的改版，過程中將訓練網頁設計的能力，並熟悉設計軟體與切版技巧。這個流程需要做到的事情有： 9 | 10 | #### 設計階段 11 | 12 | - 選定一指定網站並重新設計頁面 13 | - 與 Mentor 討論網站的問題與修改計畫，模擬與客戶溝通的過程 14 | - 使用 Sketch 進行設計 15 | - 含首頁至少三個頁面，其他頁面由 Mentor 指定 16 | - 需包含 Desktop HD, Desktop, Tablet, Mobile 四個版本的設計稿 17 | 18 | #### 開發階段 19 | 20 | - 使用 Rails 進行前台開發 21 | - 需套用 Bootstrap 22 | - 需具備 RWD 23 | - 使用 ERB, Haml 或 Slim 來撰寫 HTML 24 | - 使用 SCSS/SASS 來撰寫 CSS 25 | - 使用 YAML 檔案處理文字資料 26 | - 需包含指定網站所有動態效果 27 | 28 | 29 | ### 瀏覽器支援 30 | 31 | - 預設需要支援 macOS/Chrome 的最新版本 32 | 33 | ### 開發工具 34 | 35 | 請以下列程式語言的最新版本進行開發。 36 | 37 | #### 設計 38 | 39 | - [Sketch](https://www.sketchapp.com/) 40 | 41 | #### 開發 42 | 43 | - Ruby 44 | - Ruby on Rails 45 | 46 | ※ 本教程重點放在熟練 Sketch 操作與撰寫 Rails 前台，不需要部署。 47 | 48 | ## 教程的最終目標 49 | 50 | 完成本教程後，我們會認為你已經習得以下能力： 51 | 52 | - 能夠運用 Sketch 進行網頁設計 53 | - 能夠參照設計稿進行切版 54 | - 具備獨立開前台頁面的能力 55 | - 知道如何在 GitHub 發 PR、merge 等協作流程，以及必須的 git 指令 56 | - 能將 commit 切成適度的大小 57 | - 能寫出適合的 PR 說明 58 | - 能針對 code review 進行修正 59 | - 遇到問題時，能夠適時以口頭或線上工具向相關人員（在本例中為導師）求救 60 | 61 | ## 參考資料 62 | 63 | - Git: https://gitbook.tw/ 64 | - Sketch: https://www.sketchapp.com/ 65 | - Rails: https://railsbook.tw/ 66 | 67 | ## 必修課題 68 | 69 | ### 步驟1: 選定並分析指定網站 70 | 71 | - 可選擇的指定網站有： 72 | 1. [Mesido 和流行飾品](https://www.mesido.com.tw/) 73 | 2. [Elegant walk｜EW女鞋－踏上優雅的步伐！](http://www.ewshoes.tw/) 74 | 3. [ZARA Taiwan / 台灣](https://www.zara.com/tw/) 75 | 4. [ZALORA時尚服飾購物網站](https://www.zalora.com.tw/) 76 | 5. [Chiu3時尚服飾 官方網站](http://www.chiu3.com/v2/official) 77 | 78 | - 選定一指定網站並分析該網站現有的問題 79 | - 設計、架構、編排、用戶體驗等 80 | - 可沿用 Logo、文案、商品照片等 81 | - 也可以重新設計 Logo、照片等 82 | 83 | ### 步驟2: 與 Mentor 討論修改計畫 84 | 85 | - 與 Mentor 進行討論： 86 | - Mentor 會扮演客戶的角色 87 | - Mentee 需根據指定網站提出問題點與修正方案 88 | - 最終由 Mentor 指定其他頁面作為題目 89 | - 題目含首頁至少三個頁面 90 | 91 | ### 步驟3: Wireframe 設計 92 | 93 | - 根據指定題目進行 Wireframe 繪製 94 | - 至少完成每個頁面 Desktop 版本的 Wireframe 95 | - 繪製同時規劃 Sketch 的設計流程 96 | 97 | - 與 Mentor 討論 Wireframe 98 | 99 | ### 步驟4: 以 Sketch 進行設計 100 | 101 | - 根據 Wireframe 進行設計 102 | - 需包含 Desktop HD, Desktop, Tablet, Mobile 四個版本的設計稿 103 | - 根據不同版面的大小，可收合或隱藏部分元件，但不可刪減原本網站的內容 104 | 105 | - 設計時，需留意以下事項： 106 | - 圖層整理與命名 107 | - 文字／元件的樣式設定 108 | - Symbols 設計與套用 109 | - 不同版本間的風格必須統一 110 | 111 | ### 步驟5: 提交 Sketch 檔案，與 Mentor 進行討論與修正 112 | 113 | - 所有設計必須整合在同一個 Sketch 檔案中 114 | - 討論時，會根據版面設計、一致性、用戶體驗等不同面向進行綜合評估並給予 Feedback 115 | - 確定最終版本後即可進入開發階段 116 | 117 | ### 步驟6: 建立 Rails 的開發環境 118 | 119 | #### 1-1: 安裝 Ruby 120 | 121 | - 利用 [rbenv](https://github.com/rbenv/rbenv) 或 [RVM](https://rvm.io) 安裝最新版本的 Ruby 122 | - 以 `ruby -v` 指令來確認 Ruby 的版本 123 | 124 | #### 1-2: 安裝 Rails 125 | 126 | - 以 gem 指令安裝 Rails 127 | - 安裝最新版本的 Rails 128 | - 以 `rails -v` 指令來確認 Rails 的版本 129 | 130 | ### 步驟7: 學習使用 Git 131 | 132 | - 在你的環境中安裝 git 133 | - macOS 的話，請以 `brew` 等工具安裝 134 | - 以 `git config` 設定 user name 和 email 135 | 136 | - 我們會根據 Mentee 的設計，幫助 Mentee 建立基本的 Rails 專案 137 | - Mentee 可以選擇將專案 fork 到自己的帳號之下，或使用 `git remote set-url` 的方式建立新的 repo 138 | - 如果沒有 GitHub 帳號，請先申請帳號 139 | - 先建立新的 git topic branch 140 | - 之後都在 topic branch 上開發並 commit 141 | 142 | ### 步驟8: 前台設計 143 | 144 | - 前台開發需滿足以下條件： 145 | - 需套用 Bootstrap 146 | - 需具備 RWD 147 | - 使用 ERB, Haml 或 Slim 來撰寫 HTML 148 | - 使用 SCSS/SASS 來撰寫 CSS 149 | - 使用 YAML 檔案處理文字資料 150 | 151 | - 同時，熟悉 Rails 的架構。如不熟悉 MVC 的操作，或有資料庫的需求，請盡可能尋求幫助。 152 | - 記得在 GitHub 上建立 PR 並請人 review 153 | - 必要時，請在 PR 上標柱 WIP（work in progress） 154 | - 收到 comment 後就做必要的處置。收到兩個 LGTM（looks good to me） 後就可以 merge 回 master 155 | 156 | ## 後記 157 | 158 | 辛苦了，恭喜你已經完成本次教程！ 159 | 160 | 請盡可能持續練習 Sketch，熟悉快捷鍵與 Plugin 的操作，也可以嘗試搭配 [inVision](https://www.invisionapp.com/) 或 [Zeplin](https://zeplin.io/) 等協作工具。 161 | 162 | 你也可以嘗試建立 Rails 專案、學習開發 Rails，繼續選修課程做出真正的產品吧！ 163 | 164 | ## （番外篇）選修課題 165 | 166 | 選修課題延續必修課題。除了前台頁面，這次請嘗試自己建立全新的 Rails 專案，並根據你先前的設計稿，做出實際可以運作的產品。本產品除了前台頁面，需加入後台管理，讓使用者能順利新增、修改與刪除產品，並管理產品的狀態。 167 | 168 | ### 選修課題1: 完成網站所有頁面的設計 169 | 170 | - 延續先前的 Sketch 檔案，除 Mentor 指定的頁面之外，將其他頁面的設計完成 171 | 172 | ### 選修課題2: 建立 Rails 專案 173 | 174 | - 以 `rails new` 指令，建立 app 最低限度的樣板和檔案 175 | - 將使用的 Ruby 版號寫進 `Gemfile`（也請確認 Rails 版號是否有標明） 176 | - 在 GitHub 建立新的 Reop 並將成品 push 上去 177 | 178 | ### 選修課題3: 想像網站成品會是什麼樣子 179 | 180 | - 開始進行設計之前，請參照網站需求，和 Mentor 一起討論成品的架構 181 | - 需要哪些 model (table)？ 182 | - table 會需要哪些欄位？ 183 | - 有想法之後，將 model 關係圖手繪出來 184 | - 完成後將關係圖拍照存檔，放進 repo 裡 185 | - 把 table schema 寫進 `README.md`（model 名稱、欄位名稱、資料形態） 186 | 187 | ※ 在這個階段，model 關係圖不需要是完全正確的。以現在所能預想的範圍來規劃就好（做到後面的步驟，發現需要修改時再來調整的概念） 188 | 189 | ### 選修課題4: 資料庫連接等週邊設定 190 | 191 | - 安裝 bundler 192 | - 在 `Gemfile` 安裝 `pg`（PostgreSQL 的 adapter） 193 | - 設定 `database.yml` 194 | - 以 `rails db:create` 建立資料庫 195 | - 以 `rails db` 確認有正確連接資料庫 196 | 197 | ### 選修課題5: 建立任務 model 198 | 199 | 開始來做管理任務所需要的 CRUD。 200 | 201 | - 以 `rails generate` 指令建立 CRUD 所需的 model class 202 | - 撰寫 migration 並以此建立 table 203 | - 非常重要：migration 要確定能安全回到上一步的狀態！請養成以 `redo` 確認的習慣 204 | - 以 `rails c` 指令，透過 model 確認有正確連接資料庫 205 | - 順便試著以 ActiveRecord 建立資料 206 | 207 | ### 選修課題6: 讓任務能夠被新增、修改、刪除 208 | 209 | - 製作任務的列表、新增、檢視、修改頁面 210 | - 以 `rails generate` 指令產生 controller 211 | - 實做 controller 和 view 必要的部分 212 | - 新增、修改、刪除後，需要顯示對應的 flash 訊息 213 | - 修改 `routes.rb`，讓 `http://localhost:3000/` 會顯示任務的列表頁面 214 | - 在 GitHub 上發 PR 並請人 review 215 | - 之後的 PR，如果覺得過於龐大，就需要開始考慮分割成多個 PR 216 | 217 | 218 | ### 選修課題7: 加入設計 219 | 220 | 同必修步驟8: 前台設計，根據你的設計稿將頁面調整完畢。 221 | -------------------------------------------------------------------------------- /backend.md: -------------------------------------------------------------------------------- 1 | 2025/11/17 更新 2 | 3 | # 新進工程師訓練教材: 後端 4 | [使用說明](README.md) 5 | 6 | ## 概要 7 | 8 | ### 開發需求 9 | 10 | 本教材的主要目的，是要開發一套「任務管理系統」。這個系統需要做到的事情有： 11 | 12 | - 任務功能 13 | - 可新增自己的任務 14 | - 使用者登入後，只能看見自己建立的任務 15 | - 可設定任務的開始及結束時間 16 | - 可設定任務的優先順序（高、中、低） 17 | - 可設定任務目前的狀態（待處理、進行中、已完成） 18 | - 可依任務建立時間排序 19 | - 可依任務狀態篩選任務 20 | - 可以任務的標題、內容進行搜尋 21 | - 可為任務加上分類標籤，並以標籤進行搜尋 22 | - 任務列表，並可依優先順序、開始時間及結束時間等進行排序 23 | 24 | 滿足以上需求之後，還會需要如下的管理機制： 25 | 26 | - 使用者的管理功能 27 | - 定義使用者角色：管理者＆一般使用者 28 | - 管理者具有權限新增、修改、刪除使用者 29 | - 管理者具有權限查看所有使用者任務 30 | 31 | ※ 不使用 AASM & acts_as_tag 相關 Gem 32 | 33 | ### 瀏覽器支援 34 | 35 | - 預設需要支援 macOS/Chrome 的最新版本 36 | 37 | ### 開發工具 38 | 39 | 請以下列程式語言、網站開發框架及資料庫系統的最新穩定版本進行開發： 40 | 41 | - Ruby 3.3 或以上版本 42 | - Rails 7.1 或以上版本 43 | - PostgreSQL 15 或以上版本 44 | 45 | ### 前端相關工具 46 | 47 | #### CSS 48 | 49 | - TailwindCSS v4 50 | - 推薦使用 51 | - [TailwindCSS UI](https://tailwindcss.com/plus) 52 | - [Flowbite](https://flowbite.com/) 53 | 54 | #### JS 55 | 56 | - Hotwire 57 | - Stimulus JS：比較麻煩的任務 58 | - Alpine.JS：一般性任務，容易快速上手且大部份 case 可以在 JS 寫在 view 59 | 60 | #### View Component 61 | 62 | - [View Component](https://viewcomponent.org/) + [LookBook](https://lookbook.build/) 63 | 64 | ### server 端請使用： 65 | 66 | - render.com 67 | - fly.io 68 | - 其它任何類似的 PAAS 69 | - 申請新的 Vultr 或 DigitalOcean 帳號可以免費試用 70 | 71 | ※ 本教材中對效能、資安沒有特別的要求，但仍需要有一定的品質。網站效能太差的話，會被要求改善。 72 | 73 | ## 最終目標 74 | 75 | 完成本教材後，我們會認為你已經具備以下能力： 76 | 77 | - 可以實做基本的 Rails 網站以及做簡單的佈署 78 | - 對於已經上線的 Rails 專案，能夠進行功能的追加和資料維護 79 | - 知道如何在 GitHub 發 PR、merge 等協作流程，以及必須的 Git 指令： 80 | - 一個PR盡量將檔案變動控制在15個以內 81 | - 能將 commit 切成適度的大小 82 | - 能寫出適合的 PR 說明 83 | - 能針對 code review 進行修正 84 | - 遇到問題時，能夠適時以口頭或線上工具向相關人員（在本例中為導師）求救 85 | 86 | ## 參考資料 87 | 88 | - Git: [https://gitbook.tw/](https://gitbook.tw/) 89 | - Rails new with Typecraft: https://www.youtube.com/playlist?list=PLHFP2OPUpCeZcPutT9yn4-e0bMmrn5Gd1 90 | 91 | ## 必修課題 92 | 93 | ### 步驟1: 建立 Rails 的開發環境 94 | 95 | #### 1-1: 安裝 Ruby 96 | 97 | - 利用 [rbenv](https://github.com/rbenv/rbenv) 或 [RVM](https://rvm.io) 安裝最新版本的 Ruby 98 | - 以 `ruby -v` 指令來確認 Ruby 的版本 99 | 100 | #### 1-2: 安裝 Rails 101 | 102 | - 以 gem 指令安裝 Rails 103 | - 安裝最新版本的 Rails 104 | - 以 `rails -v` 指令來確認 Rails 的版本 105 | 106 | #### 1-3: 安裝資料庫（PostgreSQL） 107 | 108 | - 在你使用的 OS 下安裝 PostgreSQL 109 | - macOS 的話，請以 `brew` 等工具安裝 110 | 111 | ### 步驟2: 在 GitHub 建立 repository 112 | 113 | - 在你的環境中安裝 Git 114 | - macOS 的話，請以 `brew` 等工具安裝 115 | - 以 `git config` 設定 user name 和 email 116 | - 請考慮專案名稱（也等於 repo 名稱） 117 | - 建立 repo 118 | - 如果沒有帳號的話，先申請帳號 119 | - 接著建立空白的 repo 120 | 121 | ### 步驟3: 建立 Rails 專案 122 | 123 | - 以 `rails new` 指令，建立 Rails 應用程式最低限度的樣板和檔案 124 | - 在 `rails new` 產生的專案目錄下，建立 `docs` 資料夾，並將本教程文件 commit 進去 125 | - 目的是為了方便之後開發時可以參考 126 | - 將成品 push 到 GitHub 的 repo 127 | - 將使用的 Ruby 版號寫進 `Gemfile`（也請確認 Rails 版號是否有標明） 128 | 129 | ### 步驟4: 想像網站成品會是什麼樣子 130 | 131 | - 開始進行設計之前，先和導師一起討論對最終成品的預想。建議在紙上畫 prototype 132 | - 請參照網站需求，開始想需要怎樣的資料結構 133 | - 需要哪些 model (或資料表)？ 134 | - 資料表會需要哪些欄位？ 135 | - 有想法之後，將 model 的關係圖手繪出來（或其他繪圖軟體） 136 | - 完成後將關係圖拍照存檔，放進 repo 裡 137 | - 把 table schema 寫進 `README.md`（model 名稱、欄位名稱、資料形態） 138 | 139 | ※ 在這個階段，model 關係圖不需要是完全正確的。以現在所能預想的範圍來規劃就好（做到後面的步驟，發現需要修改時再來調整的概念） 140 | 141 | ### 步驟5: 資料庫連接等週邊設定 142 | 143 | - 建立新的 topic 分支 144 | - 之後都在 topic 分支上開發並進行 commit 145 | - 安裝 bundler 146 | - 在 `Gemfile` 安裝 `pg`（PostgreSQL 的 adapter） 147 | - 設定 `database.yml` 148 | - 以 `rails db:create` 建立資料庫 149 | - 以 `rails db` 確認有正確連接資料庫 150 | - 在 GitHub 上建立 PR 並請人 review 151 | - 必要時，請在 PR 上標柱 WIP（Work In Progress） 152 | - 收到 Comment 後就做必要的處置。收到兩個 LGTM（Looks Good To Me） 後就可以 merge 回 master 153 | 154 | ### 步驟6: 建立任務 model 155 | 156 | 開始來做管理任務所需要的 CRUD。一開始先簡單做，只要能記錄名字和任務內容即可。 157 | 158 | - 以 `rails generate` 指令建立 CRUD 所需的 model 類別 159 | - 撰寫 migration 並以此建立資料表 160 | - 非常重要：migration 要確定能安全回到上一步的狀態！請養成以 `redo` 確認的習慣 161 | - 以 `rails c` 指令，透過 model 確認有正確連接資料庫 162 | - 順便試著以 ActiveRecord 方式建立任務，確認能順利建立 163 | - 在 GitHub 上發 PR 並請人 review 164 | 165 | ### 步驟7: 新增、修改、檢視、刪除任務 166 | 167 | - 製作任務的列表、新增、檢視以及修改頁面 168 | - 以 `rails generate` 指令產生 controller 169 | - 請和導師討論要用哪一種 template engine（ERB / Slim / Haml..etc） 170 | - 實做 controller 和 view 必要的部分 171 | - 完成新增、修改、刪除動作之後，需要在畫面上顯示 Flash 訊息 172 | - 修改 `routes.rb`，讓 `http://localhost:3000/` 會顯示任務的列表頁面 173 | - 在 GitHub 上發 PR 並請人 review 174 | 175 | ※ 之後的 PR，如果覺得過於龐大（超過15個檔案變動），就需要開始考慮分割成多個 PR 176 | 177 | ### 步驟8: 寫 E2E 測試 178 | 179 | - 寫 spec 的事前準備 180 | - 安裝 gem 'rspec-rails' 181 | - 準備 `spec/spec_helper.rb` 、`spec/rails_helper.rb` 182 | - 針對任務的功能來寫 feature spec 183 | - 用Factory-Bot 與 faker 建立資料 184 | 185 | ※ 參照 [Better Specs](https://www.betterspecs.org/) ， 將測試寫得更簡潔 186 | - 導入 GitHub Action CI 之類的 CI 工具，每次 Push 後自動跑 Spec 187 | - 太難的話可以請導師幫忙設定 188 | - 安裝 rubocop 以統一程式風格 189 | 190 | ### 步驟9: 將網站中的中文部分共用化 191 | 192 | - 利用 Rails 的 i18n 功能，將 View / Controller / Model 中的語言部份共用化 193 | 194 | ※ i18n 化的好處是，之後的步驟中，各種訊息的處理會輕鬆很多 195 | 196 | ### 步驟10: 設定 Rails 的時區 197 | 198 | - 將 Rails 的時區設為台灣（台北） 199 | 200 | ### 步驟11: 任務列表以建立時間排序 201 | 202 | - 資料預設是以 id 進行排序，請試著讓它以建立時間排序 203 | - 完成後，撰寫此功能 feature spec 204 | 205 | ### 步驟12: 資料驗證 206 | 207 | - 開始設定資料驗證 208 | - 請思考需要在哪個欄位上加入哪種驗證比較好 209 | - 以 `rails generate` 指令產生 migration file 210 | - 與之配合的 DB 限制，請寫成 migration 211 | - 在頁面上加入驗證的錯誤訊息 212 | - 撰寫對應的 model 測試 213 | - 在 GitHub 上發 PR 並請人 review 214 | 215 | ### 步驟13: 網站佈署 216 | 217 | 目的：將 master 分支上的簡易任務管理系統推上線 218 | 219 | - 試著將網站 deploy 到 [Render](https://render.com/) 上 220 | - 沒有帳號的話，請建立帳號 221 | - 看一下被推上 Render 的網站 222 | - 接下來就會在這裡建立任務並繼續開發 223 | - ※ 不過，推上 Render 後，就是在網路上公開了，請注意不要放敏感資料 224 | - 現階段，或許可以考慮加入 basic 認證 225 | - 今後，每個步驟完成後，就繼續將成品推上 Render 226 | - 將佈署的方法和網站操作寫進 `README.md` 227 | - 也將使用的 framework 版號等資料記下來 228 | 229 | ### 步驟14: 加入結束時間，並以時間排序 230 | 231 | - 任務可設定結束時間 232 | - 列表頁可以結束時間排序 233 | - 擴充 spec 234 | - PR/review 後佈署 235 | 236 | ### 步驟15: 加入狀態，並且能夠查詢 237 | 238 | - 在任務上加入狀態（待處理、進行中、完成） 239 | - 【選項】不是初學者的話，可以使用管理 state 的 gem 240 | - 在列表頁面，要能夠以標題和狀態進行查詢 241 | - 【選項】不是初學者的話，可以使用 ransack 等 gem 242 | - 在設定條件查詢時，請觀察 log 並確認 SQL 的變化 243 | - 之後的步驟也需要這麼做，請養成習慣 244 | - 建立 search index 245 | - 使用 [Factory Bot](https://github.com/thoughtbot/factory_bot_rails) 和 [Faker](https://github.com/faker-ruby/faker) 準備多筆資料 246 | - 準備一定程度的測試資料後，觀察 log/development.log 以確認加入 index 後對速度的改善 247 | - 【選項】使用 PostgreSQL 的 explain 等功能，檢視資料庫端的 index 使用狀況 248 | - 針對查詢功能增加 model spec（feature spec 也要擴充） 249 | 250 | ### 步驟16: 設定優先順序，並以優先順序排序 251 | 252 | - 在任務上加入優先順序（高、中、低） 253 | - 列表頁可依優先順序做排序 254 | - 擴充 feature spec 255 | - PR/review 後佈署 256 | 257 | ### 步驟17: 增加分頁功能 258 | 259 | - 使用 [Pagy gem](https://rubygems.org/gems/pagy) 在列表頁面加入分頁功能 260 | 261 | ### 步驟18: 加入設計 262 | 263 | - 使用 TailwindCSS，為目前的作品套入設計 264 | - 【選項】自己寫 CSS 來設計 265 | 266 | ### 步驟19: 支援多人使用 267 | 268 | - 建立使用者 model 269 | - 以 seed 建立第一個使用者 270 | - 建立使用者和任務的關聯 271 | - 建立關聯所需的 index 272 | - 要避免 N+1 問題 273 | - ※ 需要考慮到此步驟前的任務尚未存在使用者，此時會發生什麼情況？要如何解決？ 274 | - ※ 推上 Render 時，已經建立過的任務，要和使用者建立關係（資料維護） 275 | - 試著以 `rails console` 方式建立使用者，並確認使用者與任務關聯，順利建立任務 276 | 277 | ### 步驟20: 註冊/登入/登出功能 278 | 279 | - 這裡不使用任何 Gem，請自己實做 280 | - 不使用 devise 等便利的 Gem，是為了讓新人能更深入了解 Rails 中 HTTP cookie 和 session 的原理 281 | - 以及加強對一般認證機制的理解（例如密碼的處理） 282 | - 實做註冊的功能與頁面 283 | - 實做登入的功能與頁面 284 | - 未登入時，不能進入任務管理頁面 285 | - 請改成只能看到自己建立的任務 286 | - 實做登出功能 287 | 288 | ### 步驟21: 使用者管理頁面 289 | 290 | - 在頁面上新增管理選單 291 | - 管理頁面的網址 `/admin` 292 | - 在修改 `routes.rb` 之前，請想一下 URL 以及 routing name（會變成 `*_path` 的部分）要怎麼設計 293 | - 實做使用者的列表、新增、修改、刪除等功能 294 | - 刪除使用者後，也一併刪除該使用者的任務 295 | - 在使用者列表頁面，顯示使用者的任務數量 296 | - 能夠看到每位使用者所建立的任務列表 297 | 298 | ### 步驟22: 為使用者加入角色 299 | 300 | - 將使用者分為管理員和一般使用者 301 | - 請改成只有管理員可以存取使用者管理頁面 302 | - 若一般使用者存取管理頁面時，需提示權限不足訊息無法存取，並轉向適當頁面 303 | - 能在使用者管理頁面新增角色 304 | - 管理者只剩下一個人時，不能再被刪除 305 | - 利用 model 的 callback 實做 306 | - ※ 可以自己決定是否要使用 Gem 307 | 308 | ### 步驟23: 為任務加入標籤 309 | 310 | - 一個任務可以設定多個的標籤 311 | - 能夠以標籤進行搜尋 312 | 313 | ### 步驟24: 設定錯誤頁面 314 | 315 | - 客制化 Rails 的預設錯誤頁面 316 | - 根據不同狀況，設定適合的錯誤頁面 317 | - 至少需要做 404 和 500 這兩頁 318 | 319 | ## 後記 320 | 321 | 辛苦了，恭喜你已經完成本次教材！ 322 | 323 | 另外，雖然沒有包括在教程中，以下這些主題也是必要的技能，希望各位能漸漸掌握（大部分會在專案開發的過程中學習到）。 324 | 325 | - 加深對網站應用程式的基本理解 326 | - HTTP 與 HTTPS 327 | - Rails 稍微進階一點的用法 328 | - STI 329 | - logging 330 | - explicit transactions 331 | - 非同步處理 332 | - asset pipeline（佈署方面） 333 | - JavaScript、CSS 等 frontend 技術 334 | - 資料庫 335 | - SQL 336 | - query 的效能 337 | - index 338 | - Server 環境 339 | - Linux OS (CentOS) 340 | - web server（nginx）的設定 341 | - application server（Passenger）的設定 342 | - PostgreSQL 的設定 343 | - 佈署工具 344 | - Capistrano 345 | 346 | ## （番外篇）選修課題 347 | 348 | 有別於前述的必修課題，任務管理系統還有以下選修課題。要做到什麼程度，請和導師一起討論決定。 349 | 350 | ### 選修課題1: 任務接近或超過結束時間時，顯示提示訊息 351 | 352 | - 在登入時提醒有接近或超過結束時間的任務 353 | - 如果能做出已讀、未讀狀態更好 354 | 355 | ### 選修課題2: 讓使用者之間可以共享任務 356 | 357 | - 任務可讓多個的使用者檢視或進行修改 358 | - 例：在新人和導師之間共享 359 | - 顯示任務作者 360 | 361 | ### 選修課題3: 群組 362 | 363 | - 選修課題2的延續 364 | - 新增群組設定的功能，並增加群組內分享的功能 365 | 366 | ### 選修課題4: 附加檔案 367 | 368 | - 讓任務可以上傳附加檔案 369 | - 使用 Render 的話，要能夠管理上傳到 S3 bucket 的檔案 370 | - 請使用適合的 Gem 371 | 372 | ### 選修課題5: 使用者大頭照 373 | 374 | - 讓使用者可以設定大頭照 375 | - 由於上傳的檔案會被當成 icon 使用，請做成 thumbnail 376 | - 請使用適合的 Gem 377 | 378 | ### 選修課題6: 任務日曆 379 | 380 | - 為了將結束時間視覺化，在日曆上以結束時間來顯示任務 381 | - 可以自己決定是否要使用其它套件 382 | 383 | ### 選修課題7: 以拖曳方式排序 384 | 385 | - 在任務列表中，加入以拖曳方式排序的功能 386 | 387 | ### 選修課題8: 標籤使用率的圖表 388 | 389 | - 來把統計資料視覺化吧 390 | - 圖表的形式，要簡單易懂 391 | - 可以自己決定是否要使用其它套件 392 | 393 | ### 選修課題9: 任務到期通知信 394 | 395 | - 任務接近結束時間時，在背景以 email 進行通知 396 | - 使用雲端服務來發信 397 | - Render 的話就是 SendGrid 398 | - VPS 的話就是 MailGun 或是公司的 Postal 399 | - 以一天一次的頻率，批次發信 400 | - Render 的話用 Render Scheduler（add-on） 401 | - VPS 的話就設定 cron job 402 | 403 | ### 選修課題10: 用 Let's Encrypt 在 VPS 上加上 SSL 憑證 404 | 405 | - 用 Certbot 申請 letsencrypt 憑證並設定在 Nginx 上 406 | --------------------------------------------------------------------------------