implement phase 4

README.md

@@ -34,11 +34,12 @@
 | 1 | Local dev infra — docker-compose + Keycloak (realm, 3 clients + PKCE) + MinIO (buckets) | ✅ เสร็จ |
 | 2 | Backend core — version API (FR-5–7) + JWT auth (FR-8) | ✅ เสร็จ |
 | 3 | Template system + docx generation + field sync (FR-9–11) | ✅ เสร็จ |
-| 4–5 | Add-in services + task pane UI (FR-1–4) | ⏳ รอ implement |
+| 4 | Add-in services layer — auth (PKCE + Dialog API), metadata, file/API, field extraction (FR-8, FR-11) | ✅ เสร็จ |
+| 5 | Task pane UI — sign-in, Start Versioning, Save & Version, history (FR-1–4) | ⏳ รอ implement |
 | 6 | Web Portal UI (FR-9–10) | ⏳ รอ implement |
-| 7–8 | Tests + เอกสารฉบับเต็ม | ⏳ รอ implement |
+| 7–8 | Tests ครบชุด + เอกสารฉบับเต็ม | ⏳ รอ implement |
 
-**ใช้ได้แล้วตอนนี้:** infra ทั้งชุด + backend API ครบทั้ง version API (upload / history / download) และ template system (upload template พร้อม auto-detect fields, generate เอกสารเป็น v1, field sync ตอนสร้าง version) — ลองเล่นได้ผ่าน Swagger หรือ curl (ตัวอย่างด้านล่าง)
+**ใช้ได้แล้วตอนนี้:** infra ทั้งชุด + backend API ครบทั้ง version API (upload / history / download) และ template system (upload template พร้อม auto-detect fields, generate เอกสารเป็น v1, field sync ตอนสร้าง version) — ลองเล่นได้ผ่าน Swagger หรือ curl (ตัวอย่างด้านล่าง) · ฝั่ง add-in มี services layer พร้อมใช้ครบพร้อม unit tests 40 ตัว (รอ Phase 5 เอาไปต่อ UI)
 
 ## เอกสาร
 
@@ -56,7 +57,7 @@
   ```bash
   dotnet tool install --global dotnet-ef --version 8.0.11
   ```
-- Node.js LTS (add-in และ web — ยังเป็น scaffold)
+- Node.js LTS (add-in และ web)
 
 ### 1) รัน infrastructure (PostgreSQL + MinIO + Keycloak)
 
@@ -185,14 +186,49 @@ curl -X POST http://localhost:5075/api/documents/$DOC_ID/versions \
 
 แล้วดู `GET /api/documents/$DOC_ID/versions` — แต่ละ version มี snapshot fields ของตัวเอง หากลบ content control ออกจาก Word ก่อน upload field นั้นจะเห็น `"missing": true` โดยค่าเดิมยังคงอยู่ (ไม่ error)
 
-### 3) Add-in และ Web Portal (ยังเป็น scaffold)
+### 3) Add-in (services layer พร้อม — UI ตามมาใน Phase 5)
 
 ```bash
-cd addin && npm start       # https://localhost:3000 — ครั้งแรก: npx office-addin-dev-certs install
-cd web && npm run dev       # http://localhost:5173
+cd addin
+npx office-addin-dev-certs install   # ครั้งแรกครั้งเดียว (https localhost)
+npm run build                        # webpack build + type-check ทั้ง program
+npm test                             # Jest — unit tests ของ services layer (40 ตัว)
+npm run lint                         # eslint (ใช้ eslint.config.mjs ของโปรเจกต์)
+npm run validate                     # ตรวจ manifest.xml
+npm start                            # dev server https://localhost:3000 — sideload ผ่าน manifest.xml
 ```
 
-สองส่วนนี้ยังเป็นโครงจาก Phase 0 — logic จริง (login, Save & Version, template UI) มาตาม Phase 4–6
+**Services layer ที่มีแล้ว** ([addin/src/services/](addin/src/services/)) — ทุกตัวมี unit tests ครอบ (mock `Word.run`, `Office.context.ui`, `fetch`):
+
+| ไฟล์ | หน้าที่ |
+|---|---|
+| `authService.ts` | OIDC Authorization Code + PKCE (S256) ผ่าน Office Dialog API, token ใน memory เท่านั้น, silent refresh, state กัน CSRF |
+| `metadataService.ts` | อ่าน/stamp custom properties (`SavedByAddIn` ฯลฯ), Custom XML Part แบบ delete-then-add (fail เงียบๆ ตาม known bug บน Mac), `readContentControlFields()` (FR-11) |
+| `fileService.ts` | ดึงไฟล์ปัจจุบันผ่าน File/Slice API ประกอบเป็น Blob — เรียก `closeAsync` เสมอ |
+| `apiClient.ts` | fetch wrapper แนบ Bearer, โดน 401 → refresh + retry ครั้งเดียว, ยัง fail → `AuthRequiredError` ให้ UI กลับหน้า sign-in |
+| `versioningService.ts` | uploadVersion (แนบ `fields`), getVersions, downloadVersion |
+
+หน้า login ของ add-in คือ [addin/src/taskpane/auth-callback.html](addin/src/taskpane/auth-callback.html) — redirect target ของ Keycloak (ตรง `https://localhost:3000/auth-callback.html` ใน realm-export.json)
+
+**Config ฝั่ง add-in** ฉีดตอน build ผ่าน webpack DefinePlugin (อ่านจาก env — default ชี้ dev ในพื้นที่):
+
+```bash
+KEYCLOAK_AUTHORITY=http://localhost:8080/realms/word-versioning \
+API_BASE_URL=http://localhost:5075 \
+npm run build
+```
+
+(ตัวแปรที่เหลือ: `KEYCLOAK_CLIENT_ID` — default `word-addin-officejs`)
+
+**ข้อจำกัดชั่วคราว:** task pane ยังเป็นหน้า demo ของ scaffold — Phase 5 จะเอา services ชุดนี้ไป wire เป็น UI จริง (sign-in → detect → Save & Version → history)
+
+### 4) Web Portal (ยังเป็น scaffold)
+
+```bash
+cd web && npm run dev       # http://localhost:5173 (ห้ามใช้ 3000 — ชน add-in)
+```
+
+logic จริง (login, template UI, dynamic form) มาตาม Phase 6
 
 > คำแนะนำฉบับเต็ม (sideload บน Word Desktop/Online, สร้าง template แรก, สร้างเอกสารจากเว็บ) จะเติมเมื่อ implement ครบตาม Phase 8 ของแผน