# 5C DB audit 程式 repo 結構檢查與實作前盤點

本文件承接 [5C DB audit 邊界分析](phase-five-c-db-audit-boundary-analysis.md) 與 [5C DB audit 實作前確認表](phase-five-c-db-audit-preimplementation-checklist.md)。

本文件以唯讀方式檢查程式 repo 目前的 audit / MySQL / schema / plugin 結構、候選檔案、測試基準與停止線。使用者尚未確認 5C 七項前，不修改程式 repo。

## 0. 文件狀態

| 項目 | 內容 |
|---|---|
| 文件狀態 | 已完成 |
| 建立日期 | 2026-06-07 |
| 對應節點 | 第五階段 5C DB audit 程式 repo 唯讀結構檢查 |
| 程式 repo | `hs-device-control-template` |
| 本機檢查路徑 | `C:\Users\Evan\OneDrive - 鴻森智能科技有限公司\重要資料\hs-device-control-template` |
| 本機 branch | `poc/nmodbus-tcp` |
| 程式基準 | `1f635d6`，5B config schema |
| 工作樹 | 程式 repo 與文件 repo 皆乾淨 |
| 是否修改程式 repo | 否，只做唯讀盤點、測試與文件整理 |

## 1. 檢查結論

| 項目 | 結論 |
|---|---|
| 5C 承接位置 | 第一批建議承接在 Application 層 audit contract / fake writer，不直接寫 MySQL。 |
| 既有 audit model | `PluginAuditRecord` 已存在，語意是安全摘要且明確不負責 DB 寫入。 |
| 既有 MySQL infrastructure | `HS.DeviceControl.Infrastructure.MySql` 已存在，含 schema、LogWriter、TaskTraceStore、TaskStore 與 manual-only 測試入口。 |
| 既有 schema 工具 | Core 已有 schema attribute、SQL generator、dry-run、manual apply preview，可供後續 audit table 草案使用。 |
| 既有測試 | Application / Infrastructure.MySql / solution tests 目前皆通過。 |
| 本批不建議修改 | 不直接改 MySQL writer、不新增 table、不改既有 DB public contract。 |

## 2. 目前可承接能力

| 現有檔案 | 目前能力 | 5C 意義 |
|---|---|---|
| `PluginAuditRecord.cs` | 保存 plugin metadata 審核決策安全摘要，會遮蔽敏感資訊。 | 可作為 5C audit record 安全語意參考。 |
| `PluginContractTextSafety.cs` | 檢查敏感 marker 與疑似路徑。 | 可重用於 audit reason、source、operator、correlation 等文字欄位。 |
| `ExternalDllManualVerifier.cs` | 明確宣告不寫 DB audit record。 | 5C 可補 audit request / fake writer，但不得讓 external DLL verifier 直接寫 DB。 |
| `ApplicationErrorCodes.cs` | 已有 APP-033x / APP-034x / APP-035x。 | 若新增 audit writer 錯誤碼，應使用相鄰 5C 區段並維持語意清楚。 |
| `HS.DeviceControl.Infrastructure.MySql` | 已有 MySQL provider 與 fake gateway 測試模式。 | 第二批可承接 MySQL writer，但需另行 DB table / DDL 確認。 |
| `MySqlTaskLogTraceSchema.cs` | 已有 log trace schema 定義。 | 可作為後續 audit table schema 草案參考，不在本批直接新增。 |
| `SchemaManualApplyPreviewBuilder.cs` | 支援 manual apply preview 與風險分級。 | 若後續設計 audit table DDL，需先走 dry-run / preview。 |

## 3. 候選新增 / 修改檔案

以下是確認後的候選範圍；本文件不授權直接實作。

| 類型 | 候選檔案 | 建議 |
|---|---|---|
| Audit model | `src/HS.DeviceControl.Application/Auditing/AuditEventRecord.cs` | 新增最小 audit event record，保存安全摘要欄位。 |
| Audit writer | `src/HS.DeviceControl.Application/Auditing/IAuditEventWriter.cs` | 建立 writer contract，不綁 MySQL。 |
| Fake writer | `src/HS.DeviceControl.Application/Auditing/InMemoryAuditEventWriter.cs` | 提供測試與本機驗證用 fake writer。 |
| Error codes | `src/HS.DeviceControl.Application/Common/ApplicationErrorCodes.cs` | 新增 audit request invalid / sensitive data rejected / writer failed 等錯誤碼。 |
| Tests | `tests/HS.DeviceControl.Application.Tests` | 新增 audit event record、writer、敏感資訊遮蔽測試。 |
| Docs | 程式 repo `docs/` | 新增 5C 實作與驗收紀錄，明確記錄停止線。 |

## 4. 不建議在第一批修改的檔案

| 檔案 / 範圍 | 原因 |
|---|---|
| `src/HS.DeviceControl.Infrastructure.MySql/Logging/*` | 會進入真實 DB 寫入邊界，需另行確認。 |
| `src/HS.DeviceControl.Infrastructure.MySql/Tasks/*` | 既有 TaskStore contract 不應被 5C audit 混入。 |
| `src/HS.DeviceControl.Core/Schema/*` | audit table schema / DDL 不在第一批直接新增。 |
| `src/HS.DeviceControl.WebApi/*` | auth / Swagger 留 5D。 |
| `src/HS.DeviceControl.ServiceHost/*` | Windows Service 留 5E。 |
| Adapter 專案 | Adapter public contract 不屬 5C。 |

## 5. 已執行唯讀檢查

| 檢查 | 指令 / 方式 | 結果 |
|---|---|---|
| 文件 repo 狀態 | `git status --short --branch` | `main...origin/main`，乾淨。 |
| 程式 repo 狀態 | `git status --short --branch` | `poc/nmodbus-tcp...origin/poc/nmodbus-tcp`，乾淨。 |
| 程式 repo 基準 | `git rev-parse --short HEAD` | `1f635d6`。 |
| audit / schema / MySQL 檔案盤點 | `rg --files` 搭配 Audit / Schema / TaskTrace / MySql 關鍵字 | 找到既有 Application plugin audit、Core schema、Infrastructure.MySql logging / task store。 |
| 既有 audit model | 讀取 `PluginAuditRecord.cs` | 只保存安全摘要，不負責 DB 寫入。 |
| external DLL 停止線 | 讀取 `ExternalDllManualVerifier.cs` | 明確包含不寫 DB audit record 的停止線。 |
| MySQL 專案 | 讀取 `HS.DeviceControl.Infrastructure.MySql.csproj` | 已引用 `MySqlConnector`，本批不新增套件。 |

## 6. 測試基準

| 測試 | 結果 |
|---|---|
| `dotnet test tests\HS.DeviceControl.Application.Tests\HS.DeviceControl.Application.Tests.csproj --no-restore` | 57 passed / 0 failed / 0 skipped |
| `dotnet test tests\HS.DeviceControl.Infrastructure.MySql.Tests\HS.DeviceControl.Infrastructure.MySql.Tests.csproj --no-restore` | 89 passed / 0 failed / 0 skipped |
| `dotnet test HS.DeviceControl.sln --no-restore` | 516 passed / 0 failed / 0 skipped |

補充：第一次在 sandbox 內執行測試時被 `obj` cache 寫入權限擋下；提升執行後通過。solution tests 仍出現既有 `.NET 5.0` EOL warning，非 5C 文件節點造成。

## 7. 實作前測試建議

使用者確認七項後，5C 最小實作建議至少新增或補強以下測試：

| 測試項目 | 建議驗證 |
|---|---|
| audit record 必填欄位 | EventType、SubjectType、SubjectId、Decision、CreatedAtUtc 不可缺少。 |
| 敏感資訊遮蔽 | secret、connection string、完整路徑、正式 IP、raw payload 需被拒絕或遮蔽。 |
| fake writer 成功 | 合法 audit record 可被寫入 in-memory writer。 |
| fake writer 拒絕 | 不合法 event 或敏感內容需回傳標準錯誤。 |
| 不碰真實 DB | 第一批測試不需要 DB 連線資訊，不執行 manual-only DB write。 |
| 停止線掃描 | 不新增 DDL、ALTER TABLE、formal Apply、external DLL loading、auth / Swagger 或 Windows Service。 |

## 8. 明確停止線

| 停止線 | 說明 |
|---|---|
| 不新增正式 audit table | table schema 與 DDL 需另行確認。 |
| 不執行 DDL / ALTER TABLE / formal Apply | 第一批只做 contract / fake writer。 |
| 不對真實 DB 寫入 | manual DB write / read / cleanup 需另行 gate。 |
| 不保存敏感資訊 | 不保存 secret、token、connection string、完整路徑、正式 IP、正式 port 或 raw payload。 |
| 不改既有 MySQL public contract | 不改 TaskStore、LogWriter、TaskTraceStore 既有簽章。 |
| 不做 auth / Swagger | WebApi 安全模型留 5D。 |
| 不做 Windows Service | Windows Service 留 5E。 |

## 9. 下一步

5C DB audit 程式 repo 唯讀結構檢查與基準測試已完成。下一步仍需等待使用者回覆 [5C DB audit 實作前確認表](phase-five-c-db-audit-preimplementation-checklist.md) 七項同意，才能進入程式 repo 的第一批 audit contract / fake writer 實作。