# UOFX CLI

> 🚀 在 Windows WSL 環境中快速部署和管理 UOFX 開發環境的命令列工具

---

## ✨ 主要功能

- ✅ **環境檢查與自動安裝** - 驗證系統需求，可自動安裝 WSL 環境
- 🐳 **容器化隔離** - 使用 WSL + Kubernetes 建立完全隔離的開發環境
- 🎯 **多實例管理** - 建立多個獨立環境，輕鬆切換專案
- 📊 **即時狀態監控** - 查看實例運行狀態與資源使用
- 🔐 **憑證管理** - 安全儲存並快速取得登入資訊
- 📝 **詳細日誌** - 完整的操作記錄，協助除錯

---

## 📋 系統需求

| 項目 | 需求 |
|------|------|
| 作業系統 | Windows 10/11 |
| Node.js | 18.20.0 或更高版本 |
| 記憶體 | 最低 16 GB |
| 網路 | 需要連線至容器倉庫 |

> **注意**：WSL 可透過 CLI 自動安裝（需系統管理員權限）

---

## 🚀 安裝

```bash
npm install -g @uofx/cli
```

驗證安裝：

```bash
uofx --version
```

---

## 快速開始

### 1️⃣ 環境檢查

```bash
uofx env setup
```

> 如果 WSL 未安裝，請以**系統管理員身份**執行此指令進行自動安裝

### 2️⃣ 安裝開發環境

```bash
uofx env install --name dev
```

> ⏱️ **注意**：安裝過程需要下載容器映像檔，通常需要 **15 分鐘以上**，實際時間依網路速度而定。


### 3️⃣ 取得連線資訊

```bash
uofx env list credentials --name dev --reveal
```

完成！現在你可以使用顯示的帳號密碼登入開發環境了。

---

## 💡 使用範例

### 查看所有實例

```bash
uofx env list
```

輸出示例：
```
NAME  STATUS   VERSION  CHART VERSION  ADMIN URL                    SQL SERVER
───────────────────────────────────────────────────────────────────────────────────
dev   Running        2  2.100.002      http://[ip]:16888            [ip],30022
test  Stopped        2  2.100.001      
```

### 多專案環境管理

```bash
# 建立專案 A 的環境
uofx env install --name project-a

# 建立專案 B 的環境
uofx env install --name project-b

# 切換到專案 A（會自動停止其他運行中的實例）
uofx env start --name project-a

# 停止實例
uofx env stop --name project-a

# 不再需要時刪除
uofx env delete --name project-a
```

### 指定版本安裝

```bash
# 查看可用版本
uofx env list charts

# 安裝特定版本
uofx env install --name dev --chart-version 1.2.0
```

### 除錯模式

```bash
# 啟用詳細日誌
uofx config set --log-level debug

# 查看日誌
uofx logs --level DEBUG --since 10m

# 過濾特定指令的日誌
uofx logs --command env.install
```

---

## 📖 指令參考

### 環境管理 (env)

#### `env setup`
檢查並驗證系統環境，若 WSL 未安裝可自動進行安裝。

```bash
uofx env setup
```

> **注意**：若需要安裝 WSL，必須以系統管理員身份執行。

#### `env install`（別名 `i`）
安裝並部署 UOFX 開發環境。

```bash
uofx env install [選項]
uofx env i [選項]
```

> ⏱️ **安裝時間**：需要下載容器映像檔，通常需要 15 分鐘以上，實際時間依網路速度而定。

**選項：**
- `--name <name>` - 實例名稱（預設：`dev`）
- `--chart-version <version>` - 指定 Helm chart（UOFX） 版本（預設：最新版本）
- `--no-northwind` - 跳過 Northwind 範例資料庫安裝

**範例：**
```bash
# 使用預設名稱
uofx env install

# 指定名稱和版本
uofx env install --name my-project --chart-version 1.2.0

# 不安裝 Northwind 範例資料庫
uofx env install --no-northwind
```

#### `env list`
顯示實例、憑證或相容版本資訊。

```bash
uofx env list [type] [選項]
```

**類型（type）：**
- `instances` - 列出所有實例（預設）
- `charts` - 列出相容的 chart（UOFX） 版本
- `credentials` - 顯示實例憑證（需要 `--name`）

**選項：**
- `--name <name>` - 實例名稱（credentials 類型必填）
- `--reveal` - 顯示完整憑證（搭配 credentials 使用）

**範例：**
```bash
uofx env list                                  # 列出所有實例
uofx env list charts                           # 列出相容的 UOFX 版本
uofx env list credentials --name dev --reveal  # 查看完整憑證
```

#### `env start`
啟動指定的 UOFX 實例。

```bash
uofx env start --name <name>
```

> **提示**：若有其他實例正在運行，CLI 會詢問是否停止該實例。

#### `env stop`
停止指定的 UOFX 實例。

```bash
uofx env stop --name <name>
```

#### `env delete`
刪除指定的 UOFX 實例。

```bash
uofx env delete --name <name> [選項]
```

**選項：**
- `-f, --force` - 跳過確認提示

> ⚠️ **警告**：請務必使用此指令來刪除實例，**請勿**直接使用 `wsl --unregister` 指令。

---

### 設定管理 (config)

#### `config list`
列出所有設定值。

```bash
uofx config list
```

#### `config set`
設定配置值。

```bash
uofx config set [選項]
```

**選項：**
- `--log-level <level>` - 日誌等級（`debug`、`info`、`error`）
- `--acr.name <name>` - ACR 名稱
- `--acr.account <account>` - ACR 帳號
- `--acr.password <password>` - ACR 密碼

**範例：**
```bash
# 設定日誌等級
uofx config set --log-level debug

# 設定 ACR 連線資訊
uofx config set --acr.name myregistry --acr.account user --acr.password secret
```

---

### 日誌查看 (logs)

查看和過濾 CLI 操作日誌。

```bash
uofx logs [選項]
```

**選項：**
- `--lines <number>` - 顯示行數（預設：`50`）
- `--level <level>` - 過濾日誌等級（`DEBUG`、`INFO`、`ERROR`）
- `--since <range>` - 時間範圍（例如：`1h`、`2d`、`30m`）
- `--correlation <id>` - 依關聯 ID 過濾
- `--command <command>` - 依指令過濾（例如：`env.install`）
- `--command-group <group>` - 依指令群組過濾（例如：`env`）

**範例：**
```bash
uofx logs                           # 查看最近日誌
uofx logs --level ERROR             # 只看錯誤
uofx logs --since 1h                # 過去一小時的日誌
uofx logs --command env.install     # 特定指令的日誌
```

---

### 開發工具 (dev)

#### `dev template install`（別名 `i`）
從 GitHub Release 或自訂 URL 安裝 Plugin 專案範本。`template` 可縮寫為 `t`。

```bash
uofx dev template install [選項]
uofx dev template i [選項]
uofx dev t i [選項]
```

**選項：**
- `--url <url>` - 自訂範本 URL（ZIP 檔案）
- `--name <name>` - 自訂範本名稱
- `--no-sample` - 安裝不含範例程式碼的基礎範本（使用 UOFX-Plugin-Base）

**範例：**
```bash
uofx dev template install
uofx dev template install --no-sample
uofx dev template install --url https://example.com/template.zip --name my-template
```

#### `dev template list`
列出已安裝的範本。

```bash
uofx dev template list
uofx dev t list
```

#### `dev template delete`
刪除指定的範本。

```bash
uofx dev template delete --name <name>
uofx dev t delete --name <name>
```

**選項：**
- `--name <name>` - 要刪除的範本名稱（必填）

#### `dev project generate`（別名 `g`）
從已安裝的範本建立新的 Plugin 專案。`project` 可縮寫為 `p`。

```bash
uofx dev project generate [選項]
uofx dev project g [選項]
uofx dev p g [選項]
```

**選項：**
- `--template <template>` - 指定使用的已安裝範本名稱（必填）
- `--output <path>` - 目標目錄（預設：當前目錄）
- `--skip-install` - 跳過 `npm install`（適用於離線環境或需要手動安裝依賴的情境）
- `-f, --force` - 跳過非空目錄檢查

**範例：**
```bash
uofx dev project generate --template v2025R4.123.2
uofx dev project g --template v2025R4.123.2 --output ./dest
uofx dev project g --template v2025R4.123.2 --skip-install
uofx dev project g --template v2025R4.123.2 --force
```

#### `dev component generate`（別名 `g`）
使用 `@uofx/plugin-schematics` 產生 Plugin 元件。`component` 可縮寫為 `c`。

```bash
uofx dev component generate [選項]
uofx dev component g [選項]
uofx dev c g [選項]
```

> **注意**：此指令需搭配 v2026R1.128.1 或更新版本的樣板使用。請先透過 `uofx dev template install` 安裝符合版本需求的樣板，並使用 `uofx dev project generate` 建立專案。

**元件類型：**

| 類型 | 說明 |
|------|------|
| `field` | 自訂表單欄位 |
| `mobile-field` | 行動端表單欄位 |
| `admin-panel` | 管理端面板元件 |
| `user-panel` | 使用者端面板元件 |
| `mobile-panel` | 行動端面板元件 |
| `admin-page` | 管理端頁面 |
| `user-page` | 使用者端頁面 |
| `mobile-page` | 行動端頁面 |

**必填選項：**
- `--type <type>` - 元件類型（見上表）
- `--name <name>` - 元件名稱

**通用選項：**
- `--display-name <name>` - UI 顯示名稱（預設：`<name>` 的 PascalCase）
- `-f, --force` - 跳過 dry-run 預覽與確認提示

**Field / Panel 專用選項：**（`field`、`mobile-field`、`admin-panel`、`user-panel`、`mobile-panel`）
- `--code <code>` - 元件代碼，camelCase 格式（預設：`<name>` 的 camelCase）

**Field 專用選項：**
- `--group <group>` - 欄位群組代碼（預設：`group1`）
- `--no-design` - 跳過 design 子元件
- `--no-print` - 跳過 print 子元件
- `--no-view` - 跳過 view 子元件

**Page 專用選項：**
- `--layout <layout>` - 頁面佈局類型（預設：`basic`）
  - `admin-page`：`basic`、`container`、`sider`、`tab`
  - `user-page`：`basic`、`full`、`tab`
  - `mobile-page`：`basic`、`tab`
- `--func-id <id>` - 授權功能 ID

**範例：**
```bash
uofx dev component g --type field --name hello-world
uofx dev component g --type mobile-field --name customer-info
uofx dev component g --type field --name hello-world --no-print
uofx dev component g --type admin-panel --name dashboard --display-name="Dashboard Panel"
uofx dev component g --type admin-page --name settings --layout container
uofx dev component g --type user-page --name profile --layout full
uofx dev component g --type mobile-page --name home --layout tab
```

#### `dev project publish`
發佈 Plugin 專案（版本更新 + dotnet publish + 整理輸出）。`project` 可縮寫為 `p`，`publish` 可縮寫為 `p`。

```bash
uofx dev project publish [選項]
uofx dev p publish [選項]
uofx dev p p [選項]
```

**必填選項：**
- `--service-version <version>` - Plugin 版本號（例如 `1.0`）
- `--min-uofx-version <version>` - 最低 UOFX 版本（例如 `2.89.0`）
- `--service-name <name>` - 服務名稱（例如 `Ede.Sample`）

**選填選項：**
- `--output <path>` - 輸出目錄（預設：../wwwroot）
- `-f, --force` - 跳過確認提示，並覆蓋已存在的輸出目錄與版本項目

**範例：**
```bash
uofx dev project publish --service-version=1.0 --min-uofx-version=2.89.0 --service-name=Ede.Sample
uofx dev project publish --service-version=1.1 --min-uofx-version=2.89.0 --service-name=Ede.Sample --output=./publish
uofx dev project publish --service-version=1.0 --min-uofx-version=2.89.0 --service-name=Ede.Sample --force
```

---

## ⚠️ 重要限制

### 實例互斥

**由於 WSL 架構限制，所有 WSL 實例共用同一個 IP 位址**，因此：

- ⚠️ 同一時間只能有**一個**實例處於「執行中」狀態
- ⚠️ 以下連接埠會被佔用，請確保沒有其他服務使用

| 服務 | 連接埠 |
|------|--------|
| 前台網站 (HTTP) | 80 |
| 前台網站 (HTTPS) | 443 |
| 後台管理 (HTTP) | 16888 |
| 後台管理 (HTTPS) | 16890 |
| 手機入口 | 9000 |
| SQL Server | 30022 |

> 💡 **提示**：當啟動實例時，CLI 會自動檢測衝突並詢問是否停止其他實例

### 與本機服務的連接埠衝突

如果您的 Windows 主機上有其他服務正在使用相同連接埠（如 IIS、Apache、Nginx 等），將會發生衝突。

**解決方式：停用 localhost 轉發**

如果您需要同時運行本機服務和 UOFX，可以停用 WSL 的 localhost 轉發功能。

**步驟：**

1. 在 Windows 使用者目錄建立 `.wslconfig` 檔案：
   ```powershell
   notepad $env:USERPROFILE\.wslconfig
   ```

2. 加入以下內容：
   ```ini
   [wsl2]
   localhostForwarding=false
   ```

3. 重啟 WSL：
   ```powershell
   wsl --shutdown
   ```

4. 重新啟動 UOFX 實例：
   ```bash
   uofx env start --name dev
   ```

**使用 WSL IP 存取：**

停用 localhost 轉發後，您需要使用 WSL 的實際 IP 位址來存取服務：

```bash
# 查看實例資訊（包含 IP）
uofx env list

# 輸出範例：
# NAME  STATUS   VERSION  ADMIN URL              SQL SERVER
# dev   Running        2  http://[IP]:16888      [IP],30022
```

**注意事項：**
- ⚠️ 無法再使用 `localhost` 或 `127.0.0.1` 存取

---

## 🔧 常見問題

### WSL 未安裝

**問題**：執行 `uofx env setup` 顯示 Runtime 未安裝

**解決方案**：
1. 以**系統管理員身份**開啟 PowerShell
2. 執行 `uofx env setup`
3. 依照提示完成 WSL 安裝
4. 重新啟動電腦

### 記憶體不足

**問題**：環境檢查顯示記憶體不足

**解決方案**：
- 關閉不必要的應用程式
- 確保至少有 16 GB 可用記憶體

### 實例無法啟動

**問題**：`uofx env start` 執行失敗

**解決方案**：
```bash
# 1. 檢查是否有其他實例運行
uofx env list

# 2. 停止衝突的實例
uofx env stop --name <其他實例>

# 3. 查看錯誤日誌
uofx logs --level ERROR --since 5m
```

### 安裝過程中斷

**問題**：安裝意外中斷

**解決方案**：
```bash
# 刪除失敗的實例
uofx env delete --name <實例名稱> --force

# 重新安裝
uofx env install --name <實例名稱>
```

### 取得詳細協助

```bash
# 啟用除錯模式
uofx config set --log-level debug

# 查看詳細日誌
uofx logs --since 1h
```

---

## 📚 運作原理

本工具採用「容器化」概念來隔離開發環境：

```mermaid
flowchart LR
    A[UOFX CLI] --> B[建立 WSL 實例]
    B --> C[安裝 MicroK8s]
    C --> D[部署 UOFX 服務]
    D --> E[開發環境就緒]
    
    style A fill:#4CAF50
    style E fill:#2196F3
```

**兩個主要步驟：**

1. **建立 WSL 實例** - 在 Windows 上建立獨立的 Ubuntu 環境（類似輕量級虛擬機）
2. **部署 UOFX 服務** - 在 WSL 內安裝 Kubernetes 並部署所有微服務

**優點**：
- ✅ 完全隔離，不影響本機環境
- ✅ 可建立多個獨立實例
- ✅ 刪除實例即可完全清除

---

## 📄 授權

請參閱 [LICENSE](./LICENSE) 檔案

---

_UOFX CLI v1.0.2_