desktop-team-doc 0.1.0

package/content/docs/knowledge/environment-setup/build-machine-setup.md

@@ -0,0 +1,224 @@
+# Desktop Product Build Machine 建置指南
+
+*Last Updated: 2025-10-16*
+
+本文件說明如何從頭建置一台新的 Desktop Product Build Machine，包含所有必要的軟體安裝、授權配置與環境設定。
+
+## 購置機器
+
+與 IT 部門討論機器需求，架設在公司內網。
+
+**注意事項**：
+- 確認硬體規格符合 BIAS 專案建置需求
+- 確保機器可以連接公司內網
+- 預留足夠的儲存空間供建置使用
+
+---
+
+## 安裝 Jenkins Agent
+
+請 IT 部門協助安裝 Jenkins agent。
+
+**相關資源**：
+- Jenkins 伺服器位址與設定資訊請洽 IT 部門
+- 需要設定適當的 user 權限以執行建置任務
+
+---
+
+## 安裝 iLok License Manager
+
+此項目主要是用來授權 AAX plugin。
+
+### 下載與安裝
+
+- 下載 [iLok License Manager](https://www.ilok.com/#!license-manager)
+- [Positive Grid 購買並支援 iLok 的軟體清單](https://www.ilok.com/#!myaccount)（帳號密碼請洽 IT）
+
+### iLok 裝置配置
+
+**macOS build machine 使用**: `iLok_209D6C-BuildMachine`
+**Windows build machine 使用**: `iLok_209D95`
+
+### 登入與授權
+
+1. 登入 iLok License Manager（帳號密碼請洽 IT）
+2. 確認對應的 iLok USB 已經接上
+
+**注意**：若沒插上 iLok USB，會出現以下畫面：
+
+![iLok USB 未連接](assets/buildmachine-1.png)
+
+**重要**：目前公司 macOS 和 Windows build machine 各有一隻 iLok USB，沒有添購更多。如果要使用，請把 iLok USB 接到對應的 build machine 上。
+
+### 驗證授權狀態
+
+若 iLok 有成功抓到授權，會顯示如下圖，對應的 iLok 會 activated，並且上面有一個戳記圖騰：
+
+![iLok 授權成功](assets/buildmachine-2.png)
+
+### 更新過期授權
+
+若授權過期，超過 expire date，可以與 IT 確認 renew 後，點擊右鍵選擇 `Refresh`：
+
+![更新 iLok 授權](assets/buildmachine-3.png)
+
+---
+
+## 安裝 PACE Anti-Piracy Eden Tool
+
+此項目主要是用來授權 AAX plugin。
+
+![PACE Eden Tool 示意圖](assets/buildmachine-4.png)
+
+### 下載安裝檔
+
+參考 [下載: EdenSDKLiteInstallerWin64.zip](https://drive.google.com/drive/folders/0B8ejQBhIj8C2YUpPOVRGZC1KQ2c?resourcekey=0-cjEeIPqu-zzyyy4ndGwsxA)
+
+### Eden SDK 安裝步驟
+
+1. **使用有連接 iLok dongle 的電腦**
+
+2. **打開 iLok License Manager**
+   - 點選首頁中的 "PACE CENTRAL"
+
+   ![iLok License Manager - PACE CENTRAL](assets/buildmachine-5.png)
+
+3. **下載 Eden SDK**
+   - 進去後點選 "DEVELOPER" 即可進入各版本下載頁
+
+   ![PACE Central - Developer Downloads](assets/buildmachine-6.png)
+
+4. **設定環境變數**
+   - 將 `PACE_FUSION_HOME` 加入到 user 環境變數
+
+   ![PACE 環境變數設定](assets/buildmachine-7.png)
+
+5. **更新 GlobalSign**（如需要）
+   - 參考 [AAX Sign Tool](https://git.positivegrid.com:8443/KnowledgeBase/BIASTeamWiki/wikis/%E5%A6%82%E4%BD%95%E6%9B%B4%E6%96%B0-aax-signid) 安裝 GlobalSign
+
+---
+
+## 安裝 SafeNet USB（Windows Only）
+
+此部分是用來授權 GlobalSign。
+
+**SafeNet USB Token** 是一支實體 USB，如圖：
+
+![SafeNet USB Token](assets/buildmachine-8.png)
+
+### 從頭安裝 GlobalSign
+
+按照此[說明](https://support.globalsign.com/code-signing/download-and-install-standard-code-signing-certificate)來安裝。
+
+**注意**：如果用 RDP 連線，開啟 SafeNet client 會看不到 SafeNet eToken 連線。
+參考：[Cannot see hardware security token on Windows PC](https://superuser.com/questions/1519063/cannot-see-hardware-security-token-on-my-windows-pc)
+
+### 從舊機器 Export 來新機器安裝
+
+1. 開啟 `certmgr.msc`（使用管理員權限執行）
+
+2. Export 憑證：
+
+   ![Export GlobalSign 憑證](assets/buildmachine-9.png)
+
+3. 在新機上安裝（會是 per user 安裝，沒有錯）
+
+**備份位置**：目前已經有一份備份在 BIAS_DEV 的 D 槽 BIAS misc 資料夾（updated: 20231220）
+
+---
+
+## 安裝 Apple Developer Certificate（macOS Only）
+
+### 錯誤情境
+
+如果沒有安裝憑證，會出現以下錯誤：
+
+![Apple 憑證錯誤](assets/buildmachine-10.png)
+
+### 正確安裝示例
+
+正確安裝憑證如下圖示（SKLFZ4533Y 那個）：
+
+![Apple 憑證已安裝](assets/buildmachine-11.png)
+
+### Option 1: 從舊機器上 Export
+
+1. 到 Keychain 裡面找到 Certificate category
+2. 找到含有 private key 的 certificate（參考下圖）
+3. 將其 export 成 `.p12`
+4. 傳到新機器去點擊，加入新機器的 keychain
+
+![Export Apple Certificate](assets/buildmachine-12.png)
+
+### Option 2: 安裝全新的 Certificate
+
+1. **登入 Apple Developer**
+   - 前往 https://developer.apple.com/account/resources/certificates/list
+   - 需要建立過帳號與權限，詳情洽 IT 開通
+
+2. **查看現有憑證**
+   - 若有權限，可看到自己的帳號與所有目前的 certificate
+
+   ![Apple Developer 憑證列表](assets/buildmachine-13.png)
+
+3. **下載 BIAS Product 所需憑證**
+
+   以 BIAS Product 為例，需要的授權為：
+
+   ```
+   Positive Grid Inc Developer ID Application   macOS   Calvin Abel  2024/10/25
+   Positive Grid Inc Developer ID Installer      macOS   Calvin Abel  2024/10/25
+   ```
+
+   需要用 Calvin Abel (`appstore@positivegrid.com`) 帳號登入點擊進去後下載，如下圖（只有 gary.hsieh 帳號的示意圖）：
+
+   ![下載 Apple Certificate](assets/buildmachine-14.png)
+
+---
+
+## 建構新的 Jenkins 專案
+
+### 基本步驟
+
+1. 首頁 → 新增作業
+2. 輸入專案名
+3. 選擇 "Copy from"（從現有專案複製設定）
+
+### SSH 憑證配置
+
+專案之前都是透過 GitLab 跟 Jenkins 預先建好的 credential 來 clone 專案，但是此用法在一些 script 內會直接下 git command 仍然會沒有權限。
+
+**現在的做法**：直接在 build machine 上使用 IT 帳號把 SSH 憑證匯入 GitLab。
+
+---
+
+## 安裝 BIAS 專案開發所需套件
+
+將套件安裝到執行 Jenkins agent 的 user 下。
+
+### Windows 環境
+
+參考 [BIAS Windows 環境建置](https://git.positivegrid.com:8443/desktop/native_docs/wikis/windows-development-environment-setup)
+
+### macOS 環境
+
+參考 [BIAS macOS 環境建置](https://git.positivegrid.com:8443/desktop/native_docs/wikis/macos-development-environment-setup)
+
+---
+
+## 相關資源
+
+**內部文件**：
+- [Tech Stack Overview](../development/tech-stack.md) - 技術堆疊概覽
+- [Development Glossary](../development/glossary.md) - 開發術語表
+
+**外部連結**：
+- [iLok License Manager](https://www.ilok.com/#!license-manager)
+- [PACE Central](https://www.ilok.com/)
+- [GlobalSign Code Signing](https://support.globalsign.com/code-signing/)
+- [Apple Developer Portal](https://developer.apple.com/account/)
+
+---
+
+**Maintained by**: Desktop Team
+**Contact**: IT 部門與 Build/Release 負責人

package/content/docs/knowledge/environment-setup/build-machine-troubleshooting.md

@@ -0,0 +1,193 @@
+# Build Machine Troubleshooting
+
+*Last Updated: 2025-10-16*
+
+本文件收錄 Desktop Team Build Machine 常見的建置問題與解決方案，幫助團隊快速排查並解決建置過程中遇到的問題。
+
+---
+
+## Fastlane Debug 資訊
+
+### Q: 如何讓 fastlane 在 build 的過程中有更多的 debug 資訊？
+
+**問題描述**：
+一般的 fastlane 指令幾乎看不到什麼 log 輸出，難以排查問題。
+
+**解決方案**：
+使用以下兩個參數可以看到更多 error 資訊：
+
+- `print_log:true` - 輸出詳細日誌
+- `verbose:true` - 啟用詳細模式
+
+**範例**：
+
+```bash
+fastlane run notarize \
+  print_log:true \
+  verbose:true \
+  package:BIAS_FX_2_Mac_Standalone_v2_6_0_11802.dmg \
+  bundle_id:com.positivegrid.BiasFx2Standalone \
+  username:it+buildmachine@positivegrid.com
+```
+
+**參考資源**：
+- [Fastlane notarize 文件](https://docs.fastlane.tools/actions/notarize/)
+
+---
+
+## Jenkins Console Log 優化
+
+### Q: 如何讓 build code 過程的 output 顯示在 Jenkins console？
+
+**問題描述**：
+以 BIAS FX2 為例，最重要的 build code 指令會使用 `/noconsolelogger` 參數，導致 console 沒有 log output，只會將 error 輸出到檔案。每次出問題都要連到 build machine 機器上查看。
+
+**原始指令**：
+
+```bash
+msbuild BiasFX2All.sln \
+  /t:rebuild \
+  /p:Configuration=Release \
+  /p:Platform=x64 \
+  %languageFlag% \
+  /nologo \
+  /noconsolelogger \
+  /m \
+  /flp:errorsonly;logfile=MSBuild_x64_error.log
+```
+
+**問題所在**：
+- `/noconsolelogger` - 關閉 console logger
+- 錯誤只會輸出到 `MSBuild_x64_error.log`
+
+**解決方案**：
+移除 `/noconsolelogger` 參數，讓 Jenkins console log 直接顯示更多錯誤訊息。
+
+**優化後指令**：
+
+```bash
+msbuild BiasFX2All.sln \
+  /t:rebuild \
+  /p:Configuration=Release \
+  /p:Platform=x64 \
+  %languageFlag% \
+  /nologo \
+  /m \
+  /flp:errorsonly;logfile=MSBuild_x64_error.log
+```
+
+**優點**：
+- Jenkins console 直接顯示建置輸出
+- 更快速地發現和診斷問題
+- 減少遠端登入 build machine 的需求
+
+**注意**：
+不確定以前的 RD 為什麼要把 console logger 關掉，目前看來開啟後對除錯更有幫助。
+
+---
+
+## Code Signing 問題
+
+### Q: Signing segmentation fault
+
+**問題描述**：
+在執行 codesign 或 productsign 時遇到 segmentation fault 錯誤。
+
+**錯誤範例 1 - codesign**：
+
+```bash
+../../../export/MacOSX/Release/bin/Standalone/BIAS FX 2.app: replacing existing signature
+./buildInstaller.sh: line 16: 59253 Segmentation fault: 11  codesign \
+  --entitlements "../BIAS FX 2.entitlements" \
+  -f --deep --timestamp -o runtime \
+  --sign "Developer ID Application: Positive Grid Inc (SKLFZ4533Y)" \
+  "../../../export/MacOSX/Release/bin/Standalone/BIAS FX 2.app"
+```
+
+**錯誤範例 2 - productsign**：
+
+```bash
+2023-08-24 02:33:37.689 productsign[16336:56487] CMS signature encoding failed: \
+  A timestamp was expected but was not found. (-67882)
+Error signing data.
+./buildInstaller.sh: line 38: 16336 Segmentation fault: 11  productsign \
+  --sign "Developer ID Installer: Positive Grid Inc (SKLFZ4533Y)" \
+  "$dstPkgPath" "$signedPkgPath"
+```
+
+**解決方案**：
+重新執行 build 通常可以解決問題。
+
+**排查步驟**：
+1. 重新執行 build job
+2. 如果問題持續，嘗試以下步驟：
+   - 重啟 build machine
+   - 重新同步 iLok license
+   - 重新登入 AVID 的 security client
+
+**注意**：
+目前沒有明確的根本解決方案（root cause），這似乎是 Apple 簽名服務的間歇性問題。
+
+---
+
+## AAX Plugin 建置問題
+
+### Q: AAX plugin is not built
+
+**問題描述**：
+AAX plugin 建置失敗，無法產生 AAX 格式的 plugin。
+
+**可能原因**：
+AVID dev license system 有時會不穩定（a little bit dodgy）。
+
+**解決方案**：
+
+**方案 1：重新建置**
+- 大多數情況下，重新執行整個 build task 即可解決
+
+**方案 2：重置授權環境**（如果重建無效）
+1. 重啟 build machine
+2. 重新同步 iLok license（參考 [Build Machine Setup](./build-machine-setup.md#安裝-ilok-license-manager)）
+3. 重新登入 AVID 的 security client
+
+**預防措施**：
+- 定期檢查 iLok license 狀態
+- 確保 PACE Eden Tool 正常運作
+- 保持 AVID tools 為最新版本
+
+---
+
+## 相關資源
+
+**內部文件**：
+- [Build Machine Setup](./build-machine-setup.md) - Build machine 建置指南
+- [Tech Stack Overview](../development/tech-stack.md) - 技術堆疊概覽
+- [Development Glossary](../development/glossary.md) - 開發術語表
+
+**外部連結**：
+- [Fastlane Documentation](https://docs.fastlane.tools/)
+- [MSBuild Command-Line Reference](https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild-command-line-reference)
+- [Apple Code Signing](https://developer.apple.com/support/code-signing/)
+
+**AVID/AAX 相關**：
+- [iLok License Manager](https://www.ilok.com/#!license-manager)
+- [PACE Anti-Piracy](https://www.ilok.com/)
+
+---
+
+## 回報新問題
+
+如果遇到本文件未涵蓋的建置問題：
+
+1. 記錄完整的錯誤訊息和 console log
+2. 記錄重現步驟
+3. 嘗試的解決方案
+4. 在 Slack #desktop-team 頻道討論
+5. 解決後更新此文件
+
+---
+
+**Maintained by**: Desktop Team
+**Contact**: Build/Release 負責人
+
+**Note**: 本文件持續更新中，歡迎團隊成員補充新的疑難排解經驗。

package/content/docs/knowledge/implementation-guides/adding-amp.md

@@ -0,0 +1,190 @@
+# How to add new Amp or update Amp resources into BIAS X
+
+*Last Updated: 2025-03-02*
+
+## Overview
+
+This guide explains how to add new amplifiers or update existing amp resources in BIAS X using the Figma parser plugin.
+
+## Steps
+
+1. Use the Figma plugin to download config/assets files:
+   - The plugin is located in the repository: `tools/gear-figma-parser`
+   - Follow the installation and usage instructions in the plugin's README
+
+2. Put the exported assets in the appropriate directories:
+   - Body assets → **public/images/amp-x-module/body**
+   - Signal path thumbnails → **public/images/amp-x-module/thumb**
+   - Config JSON files → **public/images/amp-x-module**
+
+3. If you need to add new control units, add their assets inside **public/images/amp-x-module/control-units**
+
+## Figma Plugin Setup
+
+### Installation
+
+1. Install the plugin dependencies:
+   ```
+   cd tools/gear-figma-parser
+   npm install
+   ```
+
+2. Run the plugin UI:
+   ```
+   npm run watch
+   ```
+
+### Usage
+
+1. Open Figma Desktop App
+2. Enable Figma Dev Mode
+3. Under Plugin tab > Click + > Select `Import plugin from manifest` > select the `manifest.json`
+4. Click the plugin and then select the Amp
+5. Click `Export All` or `Export JSON only` to export assets
+
+## Figma Naming Conventions
+
+### Amp Design
+
+- The main Figma node should be named `amp design`
+- Display name must match the PM documentation (used to find gear config files by ID)
+- Body image name: `body-amp name`, e.g., `body-ac chime`
+  - Amp name can include spaces, use all lowercase
+  - Should match the title/display name, don't add dashes
+- Thumbnail image name: `amp name`, e.g., `ac chime`
+  - Amp name can include spaces, use all lowercase
+- Knob name: `model-color`, e.g., `chicken-black`
+  - No spaces, all lowercase
+  - Must match the RD knob images folder name
+- Power Button and LED names: `model`, e.g., `hexagon`
+  - No spaces, all lowercase
+- Scale name: `Scale XX` where XX is a number like 00, 01, 02, etc.
+  - "Scale" with capital S
+
+## Config JSON Format
+
+The plugin generates a JSON configuration file for each amp. Here's the format:
+
+### Example
+
+```json
+{
+    "name": "boogiemkiic+",
+    "containerPos": "above",
+    "knob": {
+        "scale": "Scale 00",
+        "type": "mesa4",
+        "color": "#ffffff",
+        "opacity": 0.7
+    },
+    "power": {
+        "type": "hexagon",
+        "color": "#ffffff",
+        "opacity": 0.7
+    },
+    "led": "circle"
+}
+```
+
+### Attribute Description
+
+#### 1. `name`
+**Description:**
+- Represents the name of the equipment (e.g., amplifier name).
+
+**Data Type:**
+- String
+
+**Example:**
+```json
+"name": "boogiemkiic+"
+```
+
+#### 2. `containerPos`
+**Description:**
+- The position of the control panel, determined by the `y` value of `control` relative to the asset height.
+  - If `controlNode.y < assetNode.height / 2`, the value is `"above"`.
+  - Otherwise, it is `"below"`.
+
+**Data Type:**
+- String
+
+**Example:**
+```json
+"containerPos": "above"
+```
+
+#### 3. `knob`
+**Description:**
+- Defines the appearance attributes of the knob.
+
+**Sub-Attributes:**
+- `scale`: The scale of the knob (the dial markings)
+  - Data Type: String
+  - Example: `"Scale 00"`.
+
+- `type`: The type of knob.
+  - Data Type: String
+  - Example: `"mesa4"`.
+
+- `color`: The color of the knob label.
+  - Data Type: String
+  - Example: `"#ffffff"`.
+
+- `opacity`: The opacity of the knob label.
+  - Data Type: Number
+  - Example: `0.7`.
+
+**Example:**
+```json
+"knob": {
+    "scale": "Scale 00",
+    "type": "mesa4",
+    "color": "#ffffff",
+    "opacity": 0.7
+}
+```
+
+#### 4. `power`
+**Description:**
+- Defines the appearance attributes of the power indicator.
+
+**Sub-Attributes:**
+- `type`: The type of the power indicator.
+  - Data Type: String
+  - Example: `"hexagon"`.
+
+- `color`: The color of the power label.
+  - Data Type: String
+  - Example: `"#ffffff"`.
+
+- `opacity`: The opacity of the power label.
+  - Data Type: Number
+  - Example: `0.7`.
+
+**Example:**
+```json
+"power": {
+    "type": "hexagon",
+    "color": "#ffffff",
+    "opacity": 0.7
+}
+```
+
+#### 5. `led`
+**Description:**
+- Represents the type of LED indicator.
+
+**Data Type:**
+- String
+
+**Example:**
+```json
+"led": "circle"
+```
+
+## Additional Resources
+
+For more detailed information about the Figma parser plugin, refer to:
+- Plugin source code: `tools/gear-figma-parser`
+- Asset generation details: See `parseAmpDesign` in `code.ts` within the plugin

package/content/docs/knowledge/implementation-guides/adding-fx.md

@@ -0,0 +1,111 @@
+# How to add new FX into BIAS X
+
+*Last Updated: 2025-03-02*
+
+## Overview
+
+This guide explains how to add new effects (FX) or update existing FX resources in BIAS X using the Figma parser plugin.
+
+## Steps
+
+1. Use the Figma plugin to download config/assets files:
+   - The plugin is located in the repository: `tools/gear-figma-parser`
+   - Follow the installation and usage instructions in the plugin's README
+
+2. Put the exported assets in the appropriate directories:
+   - Body assets → **public/images/pedal-x-module/body**
+   - Signal path thumbnails → **public/images/pedal-x-module/thumb**
+   - Config JSON files → **public/images/pedal-x-module**
+
+3. Fill in **public/images/pedal-x-module/pedals.json**:
+   - Use `dspId` as key and `formatted displayName` (display name in lowercase with spaces removed) as value
+
+4. If you need to add new control units, add their assets inside **public/images/pedal-x-module/control-units**
+
+5. Add the `dspId` & `displayName` mapping into [bias-x-preset-thumbnail repo](https://git.positivegrid.com:8443/frontend/bias-x-preset-thumbnail)
+
+## Figma Plugin Setup
+
+### Installation
+
+1. Install the plugin dependencies:
+   ```
+   cd tools/gear-figma-parser
+   npm install
+   ```
+
+2. Run the plugin UI:
+   ```
+   npm run watch
+   ```
+
+### Usage
+
+1. Open Figma Desktop App
+2. Enable Figma Dev Mode
+3. Under Plugin tab > Click + > Select `Import plugin from manifest` > select the `manifest.json`
+4. Click the plugin and then select the Pedal
+5. Click `Export All` or `Export JSON only` to export assets
+
+## Figma Naming Conventions
+
+### Pedal Design
+
+- The main Figma node should be named `pedal design`
+- Display name must match the PM documentation
+- Template name format: `compact-nk`, `med-slim-nk`, `med-stout-nk` (where n is the number of knobs)
+- Knob name: no spaces, all lowercase
+  - Group in Figma named `knob`
+- Toggle name: no spaces, all lowercase
+  - Group in Figma named `toggle`
+- Footswitch name: no spaces, all lowercase
+  - Group in Figma named `footswitch`
+- LED name: no spaces, all lowercase
+  - Group in Figma named `led`
+- Slider name: no spaces, all lowercase
+  - Group in Figma named `slider`
+- Body image name: `body-pedal name`
+  - Pedal name can include spaces, use all lowercase
+  - Should match the title/display name, don't add dashes
+- Extra elements: use `extra-` prefix
+  - Example: `extra-lcd`
+
+## Config JSON Format
+
+The plugin generates a JSON configuration file for each FX. Here's the format:
+
+### Key Properties
+
+- **name**: Display name in lowercase with spaces removed
+  - Example: `"name": "bluedelay"`
+
+- **template**: Reference to the pedal template design
+  - Options: `compact`, `med-slim`, `med-stout`
+  - May include knob count suffix (e.g., `compact-3k` for compact with 3 knobs)
+
+- **toggle**: Toggle switch type
+  - Options: `round`, `rectangle`, `slider`
+
+- **footSwitch**: Footswitch type
+  - Options: `default`, `press`
+
+- **led**: LED indicator type
+  - Options: `on`, `off`
+
+### Example
+
+```json
+{
+  "name": "bluedelay",
+  "template": "med-slim-3k",
+  "toggle": "round",
+  "footSwitch": "default",
+  "led": "on"
+}
+```
+
+## Additional Resources
+
+For more detailed information about the Figma parser plugin, refer to:
+- Plugin source code: `tools/gear-figma-parser`
+- Asset generation details: See `parsePedalDesign` in `code.ts` within the plugin