@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 驅動開發工作流程的特殊模板：

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 結構 |

進階可自行擴充：

// 在 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）加入：

// 示例
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 描述：適用情境 / 差異 / 附加指令

若要提供「多題流程」可在模板放：

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！