# MySQL Schema Attribute 實作前確認

## 1. 文件目的

本文件用於整理進入程式 repo 實作 `DbTableAttribute`、`DbColumnAttribute`、`DbIndexAttribute` 與 Schema Definition 轉換前的最後確認。

此確認表只代表「準備開始設計與實作前的條件整理」，不代表已經同意實際連線 MySQL、建立資料表、安裝套件、修改 public method 簽章或改變專案啟動方式。

## 2. 節點定位

建議節點名稱：

> Schema Attribute 實作前確認

建議放在：

1. MySQL Schema 自動建表設計
2. MySQL schema Class 初稿
3. MySQL 行前連線資訊確認
4. MySQL 行前資訊填寫範本
5. Schema Attribute 實作前確認
6. Schema Attribute / Schema Model 實作
7. Schema Generator / Initializer 實作
8. MySQL TaskStore PoC

## 3. 已確認的設計方向

| 項目 | 決策 | 備註 |
|---|---|---|
| MySQL 版本 | `5.6.2` | 第一版以 MySQL 5.6.2 相容為準 |
| Schema 維護方式 | C# Class + Attribute | 欄位型別、索引、描述直接由 C# 維護 |
| 自動建表範圍 | Table / Column / Index | 第一版不自動建立 database |
| 不做事項 | Drop column / Drop table / 改欄位型別 / 搬資料 | 避免破壞既有資料 |
| 原始資料欄位 | `TEXT` / `LONGTEXT` | MySQL 5.6.2 不使用 `JSON` |
| 時間欄位 | `datetime` | MySQL 5.6.2 第一版不依賴小數秒 |
| 關聯方式 | 邏輯關聯 + Index | 第一版不建立外鍵約束 |

## 4. 進入實作前必須確認

| 確認項目 | 建議值 | 目前狀態 | 是否卡住實作 | 說明 |
|---|---|---|---|---|
| MySQL 版本 | `5.6.2` | 已確認 | 否 | 使用者已提供版本 |
| Host / IP | 待填 | 待確認 | 是 | 尚未提供實際測試環境 |
| Port | `3306` | 待確認 | 是 | 若非 3306 需標註 |
| Database Name | `hs_device_control` | 待確認 | 是 | 第一版不自動建立 database |
| User | 待填 | 待確認 | 是 | 建議 PoC 專用帳號 |
| Password 提供方式 | 環境變數 / 臨時輸入 | 待確認 | 是 | 不得寫入 repo 或文件 |
| Charset | `utf8` | 建議採用 | 否 | MySQL 5.6.2 第一版建議 `utf8` |
| AutoCreateSchema | `true` | 待確認 | 是 | 是否允許建立 table / column / index |
| DryRunSchemaSql | `true` | 建議採用 | 是 | 首次先輸出 SQL，不實際改 DB |
| StopOnSchemaMismatch | `true` | 建議採用 | 是 | 欄位型別不一致時停止 |
| 權限 | `SELECT / INSERT / UPDATE / CREATE / ALTER / INDEX` | 待確認 | 是 | 權限不足會阻擋 PoC |

## 5. 本次實作允許範圍

若使用者確認進入程式 repo，第一批實作建議只允許：

| 類別 | 允許內容 |
|---|---|
| Attribute | `DbTableAttribute`、`DbColumnAttribute`、`DbIndexAttribute` |
| Schema Model | `SchemaDefinition`、`TableDefinition`、`ColumnDefinition`、`IndexDefinition` |
| 解析器 | 將 Attribute 解析為中立 Schema Model |
| 測試 | Attribute 解析測試、MySQL 5.6.2 型別字串測試 |
| 文件 | 同步實作範圍與限制 |

第一批不做：

- 不連線 MySQL。
- 不執行 DDL。
- 不安裝或更換 MySQL 套件。
- 不修改 Core public method 簽章。
- 不改變 ConsoleHost 啟動方式。
- 不建立 WebApi、ServiceHost 或 UI。

## 6. 建議 Attribute 契約

### 6.1 DbTableAttribute

| 屬性 | 用途 | 是否必要 |
|---|---|---|
| `Name` | MySQL table name | 是 |
| `Description` | 表格描述 | 否 |

### 6.2 DbColumnAttribute

| 屬性 | 用途 | 是否必要 |
|---|---|---|
| `Name` | MySQL column name | 是 |
| `Type` | MySQL column type，例如 `varchar(64)` | 是 |
| `IsPrimaryKey` | 是否主鍵 | 否 |
| `IsRequired` | 是否 `NOT NULL` | 否 |
| `Description` | 欄位描述 | 否 |

### 6.3 DbIndexAttribute

| 屬性 | 用途 | 是否必要 |
|---|---|---|
| `Name` | Index name | 是 |
| `Columns` | Index column list | 是 |
| `IsUnique` | 是否唯一索引 | 否 |

## 7. 實作前驗收標準

第一批 Schema Attribute 實作完成後，至少需能驗證：

| 驗收項目 | 預期結果 |
|---|---|
| 能讀取 class 上的 `DbTableAttribute` | 產出正確 table name 與描述 |
| 能讀取 property 上的 `DbColumnAttribute` | 產出正確欄位名稱、型別、必填與主鍵資訊 |
| 能讀取 class 上多個 `DbIndexAttribute` | 產出多組 index definition |
| 缺少 table name | 回傳標準錯誤或驗證失敗 |
| 缺少 column name / type | 回傳標準錯誤或驗證失敗 |
| 不支援的 MySQL type | 回傳標準錯誤或驗證失敗 |

## 8. 實作前仍需使用者確認

請使用者先確認以下非敏感資訊：

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

Password 請只填提供方式，不要填真實值。

## 9. 建議下一步

若使用者確認上述資訊與範圍，下一步建議進入「Schema Attribute 第一版實作前 commit/push 前確認」，再切換到程式 repo 實作 Attribute 與 Schema Model。