🚀 Jin's Notes

專案流程

22 min read

SA 需求規格書

  • 以 睿進 為練習專案。

睿進在做什麼的？

工業材料製造與批發、電子機械安裝與製造

基本資料管理模組

客戶管理模組

  • 匯入功能是匯入什麼樣的檔案格式？看 SDS 文件是寫 CSV、XML 檔，但是跟後端發 API 要資料
    • 沒有畫面的部分，要先把流程畫面想清楚，方便立案會議討論。
    • 比較多邏輯處理的部分，可以跟後端討論，是否後端包辦，前端專注畫面的呈現。
  • 條件搜尋：
    • 按查詢才會執行查詢嗎？還是輸入即查詢？基本上是
  • 檢視功能是列表檢視就好了嗎？還是可以點進去客戶單筆檢視？通常如果規格寫到需要檢視畫面，就會需要檢視按鈕，會依資料量多寡，看是要以 dialog 或是 show 頁面呈現

品項管理模組

  • 3.3.3.3 如果厚度、寬度、長度只輸入寬跟長，那顯示的規格字串是要：
    • 厚度（顯示 0）x 長度 x 寬度
    • 長度 x 寬度
    • 看一下 SDS 規格，如果送 request 時 key 是分開來，那就請後端幫忙組字串就好，這個邏輯就會是他們決定。

類別管理模組

  • 「類別」跟 「ERP 類別」的差異跟關係？
    • 類別是客戶提供的固定選單
    • ERP 類別是讓客戶可以自訂義填入的文字

權限管理模組

  • 3.3.5.4 權限說明 - 查詢可看到列表畫面，這邊是不需要查詢功能嗎？
    • 這邊的查詢是檢視列表的意思，不代表 filter 功能
    • 補充：權限的細項勾選，會互相影響，如果勾了編輯，查詢當然也要自動勾選。

工單管理模組

  • 3.4.1.2：
    • 欄位輸入的方式採用自動輸入的方式，是指 Autocomplete（帶搜尋功能的下拉選單）嗎？Yes
    • 這幾個欄位指：紙筒、紙箱、產品的 ERP 編號、原料的 ERP 編號嗎？Yes
    • 目前認知「紙筒」、「紙箱」是數於品相管理中的變動項目，因此延伸了兩個問題：
      • 工單資料 - 「紙筒」、「紙箱」欄位是變動的嗎？不是，原料、產品、紙筒、紙箱都是固定的類別選項
      • 這個選項也會包含在「產品的 ERP 編號」、「原料的 ERP 編號」內嗎？不包含，這兩個是另外獨立的類別
  • 工單的狀態列表（3.4.1.2）上方圖示，是要從哪邊點擊進入查看？主列表畫面應該要有一個檢視按鈕，可以透過這個按鈕進到工單的報工列表畫面

現場報工模組

  • 「報工功能」跟「工單管理功能 - 編輯 - 狀態欄位」，這兩個功能的情境差異？
    • 工單管理的編輯，後來畫面有修掉，是無法改變狀態欄位，只能檢視。
    • 報工是給趕單人員，完成訂單後報工用，所以不會有暫停或重新開始的選項。
    • 暫停或重新開始的狀態變更，是在工單管理列表那可以更動，目前的設計稿雖然沒有，但後來有改。
  • 3.5.1.2 「報工時只能填寫原料批號…」，目前在畫面上並沒有看到原料批號的欄位。
    • 這邊是畫面缺少的，可以在立案會議提出來，請 PM 確認需求，以及規格書是否需要更新。
  • 工單管理模組那邊有提到：「製作中」可異動到「暫停中」或「已完成」，目前報工的 dialog 欄位只有 「已完成」的 checkbox，不需要提供「暫停中」的 checkbox 嗎？
    • 「暫停中」跟「製作中」是在報工管理列表，狀態欄位可以下拉去設定的，所以報工動作則是給線上去報「已完成」的工單。
  • 3.5.1.3 欄位列表跟畫面上對不太起來：
    • 數量以前應該是指工單列表？
      • 標頭、紙筒在工單列表畫面上並沒有顯示（應該可以直接參考電子看板模組的列表畫面）。
    • 生產數量以後應該是指手動報工？
      • 「設備參數」是「生產參數」嗎？對
      • 「備註」欄位在畫面上沒有顯示。可以自己加
  • 補充：表單寬度與 scroll 的取捨
    • QA 測試時，很可能會用極端長字串來測試，需調適每個 td 在長字串下該怎麼排列
    • 盡量讓全部欄位適應在畫面寬度，不要讓使用者必須 scroll 才可以看到全部欄位

電子看板模組

  • 電子看板 2 要從哪邊進去查看？因為電子看板只是給人看，不會有修改的行為，所以就固定時間輪播兩個畫面。setInterval 定期撈資料，慣例是 60 second 撈一次資料，15 秒畫面切換。

資料介接模組

  • 資料介接模組頁面要從哪邊進來？目前主畫面並沒有這個選項
  • 3.7.1.1、3.7.1.2 的示意畫面是空的

其他問題

如果對規格書，是要直接在規格書的 Google Doc 標注嗎？

可以跟 PM 溝通

如果規格書有待補充或修改的部分，前端工程師可以直接編輯嗎？

修改內容只有 PM 有權限，需要跟 PM 提出修改建議。 公司內的默契是文件是誰寫的，權限只有他能改，除非經過對方同意。 有些商業邏輯不方便在官方規格書寫進去，就會寫進 Redmine 的 Issue 下方

SDS 規格書

全域

  • API 常見的 response 欄位 flash[:notice] 是後端的 controller action 會自動偵測要不要顯示 _notice.html.rb 嗎？後端在的 Controller Action（轉譯 JSON 階段）會存放在 rails 全域變數 flash 的狀態，是為了可以在畫面跳轉的時候，繼續存取這個資料並顯示 _notice.html.rb 作為使用者反饋 toast。再 survey 一下 rails flash 提供哪些 params
  • API 的 request param 如果前端沒有帶的話，是可以的嗎？如何從文件上看出可帶 null 或只能是 empty string 或可以整個 key 都 undefine？如果不是必填欄位就可選，然後 id 通常是必填
  • 各個列表的 request.sort 跟 request.dir 有默認預設值嗎？（前端預設要帶的，或是如果前端沒帶，後端預設什麼欄位，然後是 desc 或 asc 呢？）預設排序會寫在 SA 規格書
  • 各個編輯的 API，過往慣例是全部的 key 都要帶給後端，還是只帶有變更過的欄位就好了呢？可以跟後端溝通，正常狀況是會整個給

權限 Permission

  • 權限內容描述 content: String，往後看有提到這是一個 JSON 格式的欄位，但關於 JSON 內容 key / value 在文件上找不到定義。
    • 在 config/initilaize/permission_policy.rb 裡面可以找到。這個檔案夾在放不太需要修改的 API 定義。
  • 6.3.1.6 送出編輯：request 不需要帶 id 嗎？有，帶在 url query 內

客戶 Customer

  • request.only_blank_ubn 是只要使用者沒填統一編號，這個欄位就自動帶 true 嗎？不是，這是後來新功能的查詢變數，只為了查詢使用
  • @customer[:類別] blueprint 缺少「狀態 key」的定義。應該不需要這個 key 了（因為 customer form 畫面上也沒有這個欄位可以輸入），所以如果要在立案會議後，回頭跟 PM 確認該需求，是在 slack 專案 channel 上 tag PM 嗎？對，這個後來畫面上不需要，要確認的話就在 slack 專案 channel 跟 PM 確認，確認之後再去 Redmine 記下這個結論的筆記

匯入 Import

  • API 的 response 並沒有給前端解析 xml 檔之後的 json，只有顯示成功或失敗，所以這邊的匯入是，前端給後端 file 之後，後端直接解析並將每一筆（客戶之類的）存進 DB 嗎？
    • 然後前端收到成功後，再自行 reload 頁面？對

工單

  • GET /work_order/infos 沒有提供搜尋需要帶的 request params。請後端補上
  • produced_pcs 生產數量、quantity_pcs 需求數量(顆)、quantity_boxes 需求數量(箱) 是後端有給的 keys，但畫面上只有提到「數量(顆)」、「數量(箱)」，是對應後端的哪兩個 keys？工單的表單畫面應該要有完成數量的欄位，規格書沒有更新而已。所以列表上的「數量(顆)」、「數量(箱)」都是需求數量。
  • 新增、編輯的 customer、meterial，需要帶哪些 keys？
    • customer 可以帶 id 跟 name 就好了嗎？id 即可
    • material 原料跟 product 產品，選擇 ERP 編號，會自動帶入厚寬長跟顏色，後者欄位是可以在這個表單客製化填入的嗎？會自動填入，且不可在工單的 form 裡面更改，要更改要去品項編輯更改。
  • 「暫停」跟「恢復」工單目前的功能是在工單列表上，還是工單編輯頁上？在工單編輯頁右上會有按鈕可以按，這是後來的需求修改，畫面上沒有。
  • 「完成」工單在報工頁面可以使用，「結案」工單是在哪個畫面可以觸發？
  • 「匯出」工單在哪個畫面可以觸發？目前是已完成的工單點進去才有按鈕可以按

報工

  • reply_work_order 是要幹嘛的？是可報工的工單，因為第一頁拿到的列表中，可能不會包含可報工的工單，所以後端將可報工工單存在這個參數。
  • 為什麼報工工單 List 特別有 @pagy ，其他列表沒有？應該都有，再檢查一下，如果沒有就是後端沒有給

電子看板

  • 目前看起來 dashboard/reload 的 work_orders 是 工單 Panel，error_state 是異常代碼，machine_params 是設備參數，只有一組，但 設備 Panel 卻需要呈現多個，跟 API 的定義對不太上（不過看起來測試站的另外 5 個設備參數是空資料）。原本電子看板只有 1 個 Panel，但客戶想要 2 個，但切換到第設備 Panel 只有 1 個設備，在畫面上不符合政府所要求的規格，所以另做了 5 個空設備資料只是畫面需求，實際上只有 1 個。

前端測試書

疑問

  • 參考 哪一份範例 比較符合目前的專案開發流程？K3PMS
  • 需要寫模組編號嗎？不用，因為看這份測試書的時候，不太需要對照規格書查看
    • 以 睿進 為範例的話，模組編號應該怎麼填？
    • 睿進的模組編號為什麼從 3 開始而不是 1？
  • 大的模組分類（比方基本資料、類別管理、工單管理…）是要切成 subsheet 來管理嗎？可以大方向那樣規劃，並依模組實際項目多寡來調整，重點是要讓人可以讀懂就好

Redmine Issue 與時數預估

  • 開案後 Redmine 會有 PM 開的 Issue，可以在每個 Issue 的筆記欄位預估每個功能需要的時數，也可以用 check list 列出需要完成的細項
  • 評估需求所需的時數後，把時數加總填在：開發時數
  • P.S. 要確定自己的能力，過程是不是需要用到較不熟悉的技術，不要為了趕快或為了證明自己就少開時數
  • 如果上線後有 Bug 跟客訴，由 RD 自己開 Redmine Issue。

影響範圍評估

  • 主要是要寫給 QC 測試用的，目的是讓對方知道要測的範圍、該怎麼測
    • 影響範圍：定義該功能會影響哪些頁面
    • 原因：該功能目的
    • 修改方式：該功能的行為

內部 Demo

  • PM 會訂時程，時程前完成，在本端用 demo 分支串起開發好的功能分支
  • 用 demo 分支開 server，demo 給 PM 看
  • 紀錄要修改的部分，修好後，反覆 demo 確認

發 PR

  • 功能 demo 完成後，要拆掉 demo分支，以功能分支為單位 push 到遠端
  • 選擇要 pull request 的功能分支，選擇目標分支 master or main
  • 寫標題 example：feat: <功能說明> #issue_number
  • 寫描述：放 Redmine issue 連結即可
  • 指定 Reviewer
  • 送出 PR
  • 將 PR 連結貼到 slack 進度追蹤的留言區，並 tag reviewer

接著 Reviewer 會看過，並提出有問題的地方。

  • 要回應 reviewer 的 comments。
  • 修改好 PR 再 push 一次
  • 在 slack tag reviewer 幫忙看新的修改。

QC 測試

  • 使用 QC VM 環境產靜態檔
  • 跑 staging server 給 QC 測試
  • 提供影響範圍、前端測試文件給 QC 看
  • 反覆修改 bugs，直到全部通過

Staging

在網站上產品前，可以跑 staging 來讓 QC 可以測試。staging 是最接近 production 的環境，所以應該得用編譯好的靜態檔，來跑網站的測試。

DB key

公司的 DB yaml key 是雜湊出來的，本地需要有 key 可以解雜湊的碼。目前我們的 DB 在 QC 要測試時，會有 stagin DB，但目前練習可以先借用 dev DB 就好。

可以看到公司的 config/credentials 內已經有 development.yml.enc，裡面就是雜湊出來的亂碼。這是在 github 上拉得下來的，畢竟雜湊過了嘛。

我們需要在本地建立 development.key 並放入 key 來解開 development.yml.enc 的雜湊碼：

config/
	└─ credentials/
		├─ development.key
		└─ development.yml.enc

因為是跑 staging mode，所以我們也要建一個 staging 的雜湊碼與相對應的 key：

EDITOR="vim" bin/rails credentials:edit -e staging

這個指令是在啟動「解密 → 編輯 → 重新加密」的自動化流程。

  • 解密： 它會去讀取你的 staging.key，把原本亂碼般的 staging.yml.enc 解密成人類看得懂的文字。但如果這兩個檔案不存在：
    • 自動生成一把新鑰匙：在 config/credentials/ 底下建立 staging.key。
    • 它會自動生成一個加密檔：在 config/credentials/ 底下建立 staging.yml.enc。
  • 開啟 Vim 編輯：：讓你編輯這個 tmp/ 資料夾下，全新的、內容幾乎是空白的暫存檔。
  • 重新加密： 當你在 Vim 輸入 :wq 存檔退出後，Rails 會立刻把新內容加密，並儲存覆蓋原本的加密檔。

所以上面指令，會產生：

config/
	└─ credentials/
		├─ staging.key
		└─ staging.yml.enc

編譯靜態檔

💡 使用 Vite 編譯

RAILS_ENV=staging bundle exec vite build

或是使用 Rails 環境編譯（推薦，比較全面）

💡 將 app/assets 或編譯靜態檔到 public/assets 時使用。

RAILS_ENV=staging bundle exec rails assets:precompile
  • Rails 會讀取 config/initializers/assets.rb 裡的設定。
  • 將檔案壓縮（Minify）並加上編譯後的 Hash 檔名（例如 application-87af...js）。
  • 產生的檔案會存放在 public/assets/。
  • 同時會產生一個 manifest.json，記錄原始檔名與編譯後檔名的對照表。

💡 保留最近編譯的檔案，刪除過期、不再使用的舊版本。

RAILS_ENV=staging bundle exec rails assets:clean

💡直接刪除整個 public/assets 資料夾以及快取。當發現「改了程式碼但畫面沒變」或是「編譯爛掉」時，執行這個最全面。

RAILS_ENV=staging bundle exec rails assets:clobber

Staging Server

RAILS_ENV=staging bundle exec rails s -p ${PORT} -b 0.0.0.0

後續流程

公司的 QC 測試 Server 屆時需要用 Apache HTTP Server 跟 Nginx 來跑 Server，用的 IP 也跟 VM 的不一樣。但這到時候再繼續往前學習，目前先搞懂 Staging 的設定跟機制即可。

延伸問題

staging 的靜態檔放哪去了？

解答

建在 public/vite 底下

0.0.0.0 是幹嘛的？

0.0.0.0 是開放所有網域連上你開的伺服器

如果設定了，其他人不管 IP 是多少，你開伺服器的 IP（比方 124.xxx.xxx:6001）也可以拜訪；沒有設定，就只有同網域可以拜訪。

時數統計

  • 以 303 表單來統計時數
  • PR 完成前的的時數都記在「開發」
  • QC 階段的修改與測試都記在「額外」
  • 在 Redmine 的 issue 記詳細時數，也作為每日工時的紀錄。
  • 若時數的落差達到一定標準，要簡要說明原因跟改善方式。

產品部署

前面的測試都沒問題了，就會由後端跑 Rails CLI 編譯靜態檔，並部署到公司架的 server 給客戶使用。

溝通筆記

  • 如果專案在 demo 後遇到新的 issue，但無法解決，會怎麼處理？
    • 功能需求，要能分辨可行還是不可行
      • 一開始判斷不可行，要一開始就跟 PM 說，是否換個方式。
      • 開始做之後，不可行。
        • 先詢問前端工程師們，有無相關經驗或以往經驗可以參考。
        • 若無以往經驗，再跟 PM 提出來，無法做到的原因，並提出 solution，加以討論。（站在 UI 是合理好用的角度，提出解法，並判斷優缺點）
  • 開案會議開始後，至後端把 Routes 開出來前，前端通常是做：
    • 看 SDS 文件
      • 後端 SDS 文件也是分段寫完，不會等整個產出才給前端
    • 列出跟後端要討論的問題
    • 調整 Tailwind 設定或全域 style 之類的準備
    • 調整首頁 meta data、page title
    • icon、圖片、字體素材收集
    • 可以先切版，雖然不符合路徑
    • 前端測試文件撰寫

Graph View

Backlinks