# MySQL 行前連線資訊確認

## 1. 文件目的

本文件用於補齊 MySQL TaskStore PoC 進入程式實作前的行前確認節點。

在 Schema Attribute、Schema Initializer 或 TaskStore 實作前，需先確認使用者已建立可供測試的 MySQL database，並提供必要連線資訊，讓後續可進行最小連線測試、權限測試與 Dry Run 建表測試。

本文件只定義行前確認項目，不代表已經同意連線資料庫、建立資料表、修改程式 repo、安裝套件或改變啟動方式。

## 2. 節點定位

建議節點名稱：

> MySQL 行前連線資訊確認

建議放在：

1. MySQL 套件選型分析
2. MySQL Schema 自動建表設計
3. MySQL schema Class 初稿
4. MySQL 行前連線資訊確認
5. Schema Attribute 實作前確認
6. Schema Generator / Initializer 實作
7. MySQL TaskStore PoC

此節點的目的是先確認測試環境存在，避免進入程式 repo 後才發現沒有 DB、權限不足或連線條件不明。

## 3. 使用者需提供資訊

| 項目 | 範例 | 是否必填 | 說明 |
|---|---|---|---|
| MySQL 版本 | `5.6.2` | 是 | 需確認是否為 PoC 目標版本 |
| Host / IP | `127.0.0.1` 或內部 IP | 是 | MySQL Server 位置 |
| Port | `3306` | 是 | MySQL 連線埠 |
| Database Name | `hs_device_control` | 是 | 建議先由使用者或 DBA 建立 |
| User | `hs_app` | 是 | PoC 使用者帳號 |
| Password | 不寫入文件 | 是 | 不得提交到 repo |
| Charset | `utf8` | 建議 | MySQL 5.6.2 第一版建議 `utf8` |
| 是否允許自動建表 | `true / false` | 是 | 對應 `AutoCreateSchema` |
| 是否允許補欄位 | `true / false` | 是 | 對應 Schema Initializer 行為 |
| 是否只做 Dry Run | `true / false` | 是 | 首次建議先 Dry Run |

## 4. 密碼與敏感資訊規則

- 實際 password 不得寫入 Markdown、HTML、README、commit 訊息或 GitHub issue。
- 若需要提供給 Codex 測試，建議使用本機環境變數、`.env.local` 或臨時輸入方式。
- `.env.local`、連線字串檔、匯出的 DB 密碼檔不得提交到 repo。
- 文件可保存欄位名稱與範例格式，但不得保存真實密碼。

建議環境變數名稱：

```text
HS_DB_HOST
HS_DB_PORT
HS_DB_NAME
HS_DB_USER
HS_DB_PASSWORD
```

## 5. 建議連線字串格式

```text
Server={HOST};Port={PORT};Database={DB_NAME};Uid={USER};Pwd={PASSWORD};CharSet=utf8;
```

範例，僅供格式參考：

```text
Server=127.0.0.1;Port=3306;Database=hs_device_control;Uid=hs_app;Pwd=***;CharSet=utf8;
```

## 6. Database 建立責任

第一版建議：

- Database 由使用者、DBA 或部署流程先建立。
- 程式不自動建立 database。
- 程式只在既有 database 內自動建立缺少的 table、column、index。

建議建立語法：

```sql
CREATE DATABASE hs_device_control DEFAULT CHARACTER SET utf8;
```

若未來要讓程式自動建立 database，需另開決策，因為這會提高帳號權限與部署風險。

## 7. 權限需求

PoC 帳號至少需要：

| 權限 | 用途 |
|---|---|
| `SELECT` | 查詢任務紀錄、讀取 `information_schema` |
| `INSERT` | 寫入任務、節點、命令與錯誤紀錄 |
| `UPDATE` | 更新任務狀態與結束時間 |
| `CREATE` | 建立缺少的 table |
| `ALTER` | 補缺少的 column |
| `INDEX` | 建立缺少的 index |

第一版不需要：

- `DROP`
- `DELETE`
- `CREATE USER`
- `GRANT`
- 全域管理權限

## 8. 行前測試順序

| 順序 | 測試 | 目的 | 預期結果 |
|---:|---|---|---|
| 1 | TCP 連線測試 | 確認 Host / Port 可達 | 可連到 MySQL port |
| 2 | 登入測試 | 確認 user / password 正確 | 可成功登入 |
| 3 | 版本查詢 | 確認 MySQL 版本 | 回傳 `5.6.2` 或相容版本 |
| 4 | Database 存在測試 | 確認 DB name 正確 | 可切換到指定 database |
| 5 | 權限測試 | 確認可建表與補索引 | 權限符合 PoC 需求 |
| 6 | Dry Run SQL | 先產 SQL 不執行 | 可檢視即將建立的 DDL |
| 7 | AutoCreateSchema 測試 | 建立缺少 table / column / index | 建表成功且可重複啟動 |

## 9. 最小 SQL 檢查建議

版本查詢：

```sql
SELECT VERSION();
```

確認 database：

```sql
SELECT SCHEMA_NAME
FROM INFORMATION_SCHEMA.SCHEMATA
WHERE SCHEMA_NAME = 'hs_device_control';
```

確認目前使用者：

```sql
SELECT CURRENT_USER();
```

確認資料表是否存在：

```sql
SELECT TABLE_NAME
FROM INFORMATION_SCHEMA.TABLES
WHERE TABLE_SCHEMA = 'hs_device_control';
```

## 10. 行前確認表

| 項目 | 狀態 | 完成條件 | 是否卡住下一步 |
|---|---|---|---|
| MySQL Server 可連線 | 待確認 | Host / Port 已提供，且後續可測試連線 | 是 |
| MySQL 版本符合 5.6.2 | 待確認 | 查詢結果為 `5.6.2` 或已確認相容差異 | 是 |
| Database 已建立 | 待確認 | 指定 database 已存在 | 是 |
| User 已建立 | 待確認 | PoC 專用帳號已建立 | 是 |
| Password 已安全提供 | 待確認 | 以環境變數、臨時輸入或其他安全通道提供 | 是 |
| 權限符合需求 | 待確認 | 具備 `SELECT / INSERT / UPDATE / CREATE / ALTER / INDEX` | 是 |
| Dry Run 策略已確認 | 待確認 | 首次建議先只輸出 SQL | 是 |
| AutoCreateSchema 策略已確認 | 待確認 | 確認是否允許程式建立 table / column / index | 是 |
| 敏感資訊未進 repo | 待確認 | 未寫入真實密碼或完整 ConnectionString | 是 |

## 11. 需要使用者確認

1. 是否接受 database 先由使用者或 DBA 建立。
2. PoC database name 是否使用 `hs_device_control`。
3. 是否提供 MySQL Host / IP。
4. 是否提供 MySQL Port。
5. 是否提供 PoC 專用 User。
6. 是否以安全方式提供 Password，不寫入 repo。
7. PoC 帳號是否具備 `CREATE / ALTER / INDEX` 權限。
8. 第一次測試是否先執行 Dry Run，不直接建表。

## 12. 可回覆給 Codex 的確認摘要

請只填非敏感資訊。Password 請填提供方式，不要填真實值。

```text
MySQL 版本：
Host / IP：
Port：
Database Name：
User：
Password 提供方式：
Charset：
AutoCreateSchema：
DryRunSchemaSql：
StopOnSchemaMismatch：
權限確認：
```

## 13. 建議下一步

MySQL 行前資訊填寫範本請參考：[MySQL 行前資訊填寫範本](./mysql-preflight-info-template.md)。

建議下一步先由使用者依範本確認並提供 MySQL 行前連線資訊。

資訊齊全後，再進入「Schema Attribute 實作前確認」與程式 repo 實作。