@ooopenlab/create-module/README.md

CLI tool for creating OOOPEN Lab modules

# @ooopenlab/create-module

用來從既有且受維護的模板快速產生 OOOPEN Lab「測驗模組」(Quiz Module) 的互動式 CLI 工具。

> 目標：降低建立新模組時的重複樣板工作，統一檔案/指令結構，並確保 i18n 與建置流程一致。

---


## 🔧 安裝與使用 (Install / Usage)

最簡單方式（一次性使用）：

```
npx @ooopenlab/create-module my-module
```

若省略 `my-module`，CLI 會互動式詢問：

```
npx @ooopenlab/create-module
```

也可全域安裝（較不建議，易版本飄移）：

```
npm i -g @ooopenlab/create-module
create-module my-module
```

---


## 🧪 快速範例

```
npx @ooopenlab/create-module personality-test \
	--template factor-based \
	--language zh-TW
```

完成後目錄會長得像：

```
personality-test/
	package.json
	messages/
		zh-TW.json
	src/
		components/
			QuestionComponent.tsx
		module.ts
		index.ts
	scripts/
		validate.js
	README.md
	tsconfig.json
```

---


## 🏁 CLI 參數 (Options)

| 旗標 | 說明 |
|------|------|
| `-t, --template <name>` | 指定模板：`basic` / `single-question` / `multi-question` / `factor-based` |
| `-l, --language <lang>` | 預設主語系（目前主要用於初始化 i18n skeleton） |
| `--skip-install` | 產出後不要自動執行 `npm install` |

不加參數會進入互動式問答模式，可在清單中選擇模板。

---


## 🧱 產生的模組內容 (Generated Package)

每個新模組預設包含（已簡化，封面/結果畫面由主程式統一渲染，不再內建 Cover / Result 元件）：

- `messages/<lang>.json`：i18n 初始檔（`modules.<name>` namespace）
- `src/components/QuestionComponent.tsx`：唯一預設的互動畫面骨架（題目流程示意）
- `src/module.ts`：模組主 Class / 邏輯定義
- `src/index.ts`：匯出入口（提供給打包/主程式載入）
- `scripts/validate.js`：模組相容性自檢腳本（自動生成）
- 基本 `package.json`、`tsconfig.json`、`README.md`
- `.gitignore`：忽略 build 產物（模板層）

---


## 🧩 模板總覽 (Templates)

| 名稱 | 適用情境 | 說明重點 |
|------|----------|----------|
| `basic` | 極簡骨架 | 模組 class + 單一 `QuestionComponent` |
| `single-question` | 單題互動 | 題目+答案結構示例 |
| `multi-question` | 多題線性流程 | questions 陣列與簡易流程控制 |
| `factor-based` | 有計分 / 多結果分類 | factors 與題目 factor 權重示例 |
| `component-injection` | AI 生成互動元件 | 支援元件注入工作流程，整合 AI 生成的互動元件 |

### 🤖 元件注入模板 (Component Injection Template)

**新增！** 支援 AI 驅動開發工作流程的特殊模板：

```bash
npx @ooopenlab/create-module my-ai-quiz --template component-injection
```

**特色功能：**
- 🔌 **元件注入容器**：標準化的 AI 元件整合介面
- 🤖 **AI 提示範本**：內建多種 AI 生成提示範例
- 🛡️ **驗證工具**：自動檢查元件相容性與結果格式
- 📚 **完整文件**：詳細的整合指南與疑難排解
- 🎨 **範例元件**：Match4 遊戲、色彩選擇器等實作範例

**3 步驟工作流程：**
1. **生成元件** - 使用 AI 工具配合標準提示產生互動元件
2. **建立容器** - 執行 CLI 工具建立標準模組結構  
3. **執行注入** - 將 AI 元件整合到容器中

**適用情境：**
- 🎮 遊戲類測驗（配對、拼圖、反應測試）
- 🎨 創意互動（色彩選擇、圖像標註、拖拉排序）
- 📊 動態問卷（分支邏輯、即時驗證、視覺化回饋）
- 🧠 認知測試（記憶遊戲、注意力測驗、邏輯推理）

---


## 🛠 開發 (Contributing / Development)

在 monorepo 根目錄進行：

1. 新增模板目錄：`packages/create-module/templates/<template-name>`
2. 內部需含：`src/`、必要的 `components`、`module.ts`、`README.md`、`tsconfig.json`、`.gitignore`
3. 若要在 CLI 列表顯示，只要資料夾存在即會自動抓取（動態掃描）— 無需手動改程式碼清單。
4. 執行單元測試與型別檢查確保無破壞：

```
npm --prefix packages/create-module test
npm --prefix packages/create-module run typecheck
```

### 命名與驗證
CLI 內部會驗證模組資料夾名稱：
- 只能使用 `a-z0-9-`（kebab-case）
- 不能以 `-` 結尾或連續 `--`
若不符合會提示重新輸入。

### 自動驗證指令 (Validate)
產生的模組已內建：

```
npm run validate   # 執行 scripts/validate.js：檢查 package.json / dist / messages 等
npm run check      # 先 build 再 validate（CI 可直接用）
```

可加 `--json` 取得機器可讀結果：

```
node scripts/validate.js --json
```

---


## ✅ 相容性自檢詳解 (What validate.js Checks)

| 檢查 | 說明 | 未通過處理 |
|------|------|------------|
| package.json 存在 | 基礎檔案 | 重新建立或手動補上 |
| main/types 指向 dist | 可被主程式載入 | 修改為 `dist/index.js` / `dist/index.d.ts` |
| scripts.validate | 確保可執行自檢 | 加入 `"validate": "node scripts/validate.js"` |
| messages/ | 必備 i18n namespace | 建立 `messages/zh.json` 等 |
| dist/ build 產出 | 已執行 build | 跑 `npm run build` |
| index.js / index.d.ts | 出口正確 | 確認 `tsconfig` 與 `src/index.ts` 匯出 |
| require 成功 | Node 可載入 | 檢查語法 / 相依套件 |
| i18n namespace | `modules.<moduleName>` 存在 | 修正 JSON 結構 |

進階可自行擴充：
```js
// 在 scripts/validate.js 中新增
check('peerDependencies.react >=18', () => pkg.peerDependencies?.react?.startsWith('18'));
```

---


## 🔌 與主程式整合測試 (暫行手動流程)

在官方 `Module Loader` / SDK 尚未完成前，可用下列方式模擬整合：

1. 在模組專案：`npm run build && npm pack`
2. 在 superquiz 主專案：`npm install ../your-module-1.0.0.tgz`
3. 暫時於 `quiz-modules/index.js`（或未來 registry）加入：
```js
// 示例
const customX = { name: 'customX', title: '自訂模組', description: 'Demo', multiQuestions: false };
quizModules.push(customX);
```
4. 啟動主程式 dev，建立一個新的 quiz，檢查是否能選擇並渲染
5. 觀察 console 是否出現 require / render 相關錯誤

> 注意：這是過渡做法，上線後會改成動態載入 + 自動驗證。

---


## 🧬 模組檔案結構說明 (Generated Anatomy)

```
my-module/
	package.json          # main/types/scripts
	messages/
		zh.json             # i18n namespace: modules.my-module
	src/
		components/
			QuestionComponent.tsx
		module.ts           # 核心模組邏輯 (未綁定 Cover/Result)
		index.ts            # 匯出入口
	scripts/
		validate.js         # 自動生成自檢腳本
	tsconfig.json
	README.md
```

建議再自行補充：
- `CHANGELOG.md`
- `LICENSE`
- `.npmignore`（若需排除額外測試資源）

---


## 🛠 自訂 / 擴充模板 (Custom Template)

1. 在本 monorepo：`packages/create-module/templates/<your-template>`
2. 內含至少：`src/`, `src/module.ts`, `src/index.ts`, `README.md`, `tsconfig.json`
3. 可加入 `scripts/` 內專屬腳本（例如 `dev-server.js`）
4. 重新執行 CLI：新資料夾會自動列入可選 template（CLI 是動態掃描）
5. 建議於模板 README 描述：適用情境 / 差異 / 附加指令

若要提供「多題流程」可在模板放：
```ts
export interface Question { id: string; text: string; }
export class MyFlowModule { /* ... */ }
```

---


## 🩺 疑難排解 (Troubleshooting)

| 問題 | 症狀 | 解法 |
|------|------|------|
| validate: dist 缺失 | `dist/index.js` 未找到 | 先 `npm run build` |
| require 失敗 | `Cannot find module` | 確認 main 指向正確 / 有無 ESM CJS 混用 |
| i18n namespace 失敗 | 驗證顯示 ❌ | 檢查 messages/JSON 結構，需 `modules.<name>` |
| React Peer 衝突 | 主專案安裝後警告 | 在模組 `peerDependencies` 指定寬鬆版本，避免重覆安裝 |
| TS 路徑失效 | build 後 import 崩潰 | 避免使用未轉換的 TS path alias 或調整 `tsconfig` + 轉譯工具 |
| Windows 權限 | `validate.js` 無法執行 | 直接 `node scripts/validate.js` 呼叫即可 |

---


## ❓ 常見問題 (FAQ)

**Q: `npx` 執行很慢或卡住？**
A: 可能是第一次下載套件。可先 `npm cache verify` 或改用全域安裝暫時測試。

**Q: Windows PowerShell 有路徑或編碼問題？**
A: 儘量使用不含空白與全形字元的目錄；如需清除舊安裝可 `npm uninstall -g @ooopenlab/create-module`。

**Q: 可以用 Yarn / pnpm 嗎？**
A: 可以；產出的模組不綁定特定包管理器。若跳過安裝，自己進到新目錄後執行 `yarn` 或 `pnpm install` 即可。

**Q: 想擴充產生的檔案清單？**
A: 直接在模板目錄新增檔案。CLI 會完整複製該模板（忽略模板自己的 `node_modules` 與暫存）。

**Q: 語系檔 workflow？**
A: 初始僅放一個 `<lang>.json`。後續可透過腳本抽取字串、合併成多語或提交給翻譯平台（例如 Crowdin）。

---


## 📄 授權 (License)

MIT

---


若有改進建議（新增模板類型、增加欄位驗證、整合訊息抽取流程），歡迎提交 Issue / PR！