From 6f01f51934177cc8e9329d1e409868522fdd0457 Mon Sep 17 00:00:00 2001
From: warrenchen <warrenchen@innovedus.com>
Date: Tue, 3 Feb 2026 12:16:11 +0900
Subject: [PATCH] Update installation documentation to clarify installation
 process and CLI commands

---
 docs/INSTALL.md | 104 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 92 insertions(+), 12 deletions(-)

diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 0be72ff..f000208 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -1,16 +1,96 @@
-# 安裝與初始化（Schema + Seed）
+# 安裝流程（Installer + 管理者帳號）
 
-提供一個簡單安裝流程，將 DB schema 與種子資料一起初始化。
+此文件定義「首次安裝」與「既有環境管理」兩種情境，並以 EF Core Code First 為主。
 
-## 內容
-- Schema：`docs/SCHEMA.sql`
-- Seed：`docs/SEED.sql`
+## 目標
+- 透過 EF Core migrations 建立/更新 DB schema
+- 建立或更新 superuser 帳號
+- 已設定 DB 連線時，可重複執行（不重建 schema）
 
-## 建議流程（範例）
-1) 建立資料庫
-2) 執行 `SCHEMA.sql`
-3) 執行 `SEED.sql`（包含預設 admin 角色與初始帳號）
+## 安裝模式
 
-## 注意事項
-- `docs/SEED.sql` 內 `admin@example.com` 與 `<PASSWORD_HASH>` 為預設值，請部署前替換
-- 若使用 ASP.NET Core Identity，請使用對應的密碼雜湊格式
+### A. 首次安裝（Init）
+1) 輸入 DB 連線資訊
+2) 連線檢查與版本檢查
+3) 建立/更新 schema（EF Core migrations）
+4) 建立 superuser（預設帳號 admin，可自訂）
+5) 建立必要 seed（roles 等）
+
+### B. 既有環境（管理）
+- 建立額外 superuser
+- 強制重設 superuser 密碼
+- 只執行 migration（差異安裝），不重建 schema
+
+## 建議實作方式（.NET）
+- 提供一個 CLI 或安裝頁面（類 nopCommerce / Wagtail）
+- CLI 支援互動式輸入（DB 連線、admin 帳號、密碼）
+- 內部流程一致：
+  1) 讀取/寫入連線資訊
+  2) 執行 migration（`dbContext.Database.Migrate()`）
+  3) 建立角色與 superuser（若不存在）
+
+## CLI 指令規格（草案）
+
+### 通用參數
+- `--connection-string <string>`: DB 連線字串
+- `--db-provider <string>`: 預設 `postgres`
+- `--appsettings <path>`: 設定檔路徑（預設 `appsettings.json`）
+- `--no-prompt`: 不使用互動輸入（CI/CD）
+- `--dry-run`: 只檢查，不寫入
+- `--verbose`: 詳細輸出
+
+### 1) `installer init`
+用途：首次安裝（含 migrations + seed + superuser）
+
+參數：
+- `--admin-email <email>`: 預設 `admin@example.com`
+- `--admin-password <string>`: 預設需互動輸入
+- `--admin-display-name <string>`: 可選
+- `--force`: 若偵測已初始化，仍強制執行
+
+流程：
+1) 讀取/寫入 DB 連線資訊
+2) 執行 migrations（不 Drop）
+3) 建立 roles（admin, support）
+4) 建立 admin（不存在才建立）
+5) 寫入安裝鎖定（install.lock 或 DB flag）
+
+### 2) `installer add-admin`
+用途：新增 superuser
+
+參數：
+- `--admin-email <email>`
+- `--admin-password <string>`
+- `--admin-display-name <string>`
+
+流程：
+1) 檢查 DB 連線
+2) 建立使用者並指派 admin 角色
+
+### 3) `installer reset-admin-password`
+用途：重設指定 admin 密碼
+
+參數：
+- `--admin-email <email>`
+- `--admin-password <string>`
+
+流程：
+1) 檢查帳號存在
+2) 更新密碼（強制）
+3) 寫入 audit log
+
+### 4) `installer migrate`
+用途：只執行 migrations
+
+參數：
+- `--target <migration>`: 指定遷移（可選）
+
+流程：
+1) 連線檢查
+2) 執行 migrations
+3) 輸出版本
+
+## 安全注意
+- 密碼必須符合強度規則
+- 初次安裝完成後，禁用安裝入口或限內網
+- 安裝過程需紀錄 audit log