Phase 3

2026-08-19 12:15:20 +07:00 · 2026-08-19 12:15:20 +07:00 · 25c2ce53cd
commit 25c2ce53cd
parent 9321f5a370
23 changed files with 1746 additions and 68 deletions
--- a/README.md
+++ b/README.md
@ -33,12 +33,12 @@
 | 0 | Scaffold 3 โปรเจกต์ (addin / backend / web) | ✅ เสร็จ |
 | 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) | ⏳ รอ implement |
+| 3 | Template system + docx generation + field sync (FR-9–11) | ✅ เสร็จ |
 | 4–5 | Add-in services + task pane UI (FR-1–4) | ⏳ รอ implement |
 | 6 | Web Portal UI (FR-9–10) | ⏳ รอ implement |
 | 7–8 | Tests + เอกสารฉบับเต็ม | ⏳ รอ implement |

-**ใช้ได้แล้วตอนนี้:** infra ทั้งชุด + backend API สำหรับ upload / ดู history / ดาวน์โหลด version (พร้อม JWT auth จาก Keycloak) — ลองเล่นได้ผ่าน Swagger
+**ใช้ได้แล้วตอนนี้:** infra ทั้งชุด + backend API ครบทั้ง version API (upload / history / download) และ template system (upload template พร้อม auto-detect fields, generate เอกสารเป็น v1, field sync ตอนสร้าง version) — ลองเล่นได้ผ่าน Swagger หรือ curl (ตัวอย่างด้านล่าง)

 ## เอกสาร

@ -92,13 +92,27 @@ dotnet run                   # Swagger ที่ http://localhost:5075/swagger
 **API ที่มีตอนนี้** (ทุก endpoint ต้องแนบ `Authorization: Bearer <token>`):

 ```
-POST  /api/documents/{documentId}/versions                     # อัปโหลด version ใหม่ (FR-5)
-GET   /api/documents/{documentId}/versions                     # version history ใหม่ → เก่า (FR-6)
-GET   /api/documents/{documentId}/versions/{versionId}/download # ดาวน์โหลด version (FR-7)
+# Documents / versions (FR-5–7, 11)
+POST  /api/documents/{documentId}/versions                      # อัปโหลด version ใหม่ + field sync
+GET   /api/documents/{documentId}/versions                      # version history ใหม่ → เก่า (พร้อม snapshot fields)
+GET   /api/documents/{documentId}/versions/{versionId}/download # ดาวน์โหลด version (proxy stream จาก MinIO)
+
+# Generate จาก template (FR-10)
+POST  /api/documents/generate                                    # { templateId, values } → เอกสาร v1 พร้อม metadata
+
+# Templates (FR-9)
+GET    /api/templates                                            # รายการ (?includeInactive=true สำหรับ admin)
+GET    /api/templates/{id}                                       # รายละเอียด + field definitions
+POST   /api/templates                                            # upload .docx → detect fields อัตโนมัติ
+PUT    /api/templates/{id}                                       # แก้ metadata + field definitions (label/type/required/ลำดับ)
+PUT    /api/templates/{id}/file                                  # แทนที่ไฟล์ → re-detect (บอก tag ที่เพิ่ม/หาย)
+DELETE /api/templates/{id}                                       # deactivate (soft-delete)
 ```

 - Upload เป็น multipart/form-data: `file` (.docx เท่านั้น, จำกัด 100MB) + `clientVersionId` (GUID) + `fields` (optional, JSON map tag→text สำหรับ field sync)
 - `documentId` ยังไม่มีในระบบ = สร้างใหม่อัตโนมัติ · `versionNumber` เพิ่มอัตโนมัติต่อเอกสาร · เก็บ SHA256 ของทุก version
+- Field sync policy (FR-11): field ที่ส่งมาขาด (ผู้ใช้ลบ content control ใน Word) → เก็บค่าเดิม + mark missing ใน snapshot **ไม่ fail request** · ส่งเกินนิยาม → ignore
+- Generate (FR-10): backend เปิด template ด้วย OpenXML → แทนที่ค่าใน SDT ที่ **run level** (รักษา formatting) → stamp custom properties (`SavedByAddIn`, `DocumentTrackingId`) → upload เป็น v1 → response `{ documentId, versionId, versionNumber, downloadUrl }` — เปิดไฟล์ใน Word แล้ว add-in (Phase 4–5) จะรู้จักทันที

 ### ขอ token ทดสอบ (dev)

@ -121,6 +135,56 @@ curl -X POST http://localhost:5075/api/documents/$DOC_ID/versions \
 # → { "versionId": "...", "versionNumber": 1 }
 ```

+### ลองเล่น template → generate → field sync (Phase 3)
+
+**0) เตรียมไฟล์ template** — เขียน .docx ใน Word แล้วแทรก content controls ในจุดที่จะเป็น field (Developer tab → Rich Text Content Control → Properties ตั้ง **Tag** ให้ unique ต่อไฟล์ เช่น `employee_name`, `salary`)
+
+**1) Upload template → ระบบ detect fields อัตโนมัติ:**
+
+```bash
+curl -X POST http://localhost:5075/api/templates \
+  -H "Authorization: Bearer $TOKEN" \
+  -F "name=สัญญาจ้างงาน" \
+  -F "file=@template.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+# → { "id": "...", "fields": [ { "key": "employee_name", ... }, ... ] }
+```
+
+**2) ตั้งค่า field definitions** (label ที่แสดงในฟอร์ม / ชนิด `text|number|date` / required / ลำดับ):
+
+```bash
+curl -X PUT http://localhost:5075/api/templates/$TPL_ID \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"fields": [
+        { "key": "employee_name", "label": "ชื่อ-นามสกุล", "type": "text",   "isRequired": true,  "sortOrder": 0 },
+        { "key": "salary",        "label": "เงินเดือน",    "type": "number", "isRequired": true,  "sortOrder": 1 } ]}'
+```
+
+**3) Generate เอกสาร — ได้ .docx ที่เป็น version 1 พร้อม metadata:**
+
+```bash
+curl -X POST http://localhost:5075/api/documents/generate \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d "{\"templateId\":\"$TPL_ID\",\"values\":{\"employee_name\":\"สมชาย ใจดี\",\"salary\":\"50000\"}}"
+# → { "documentId": "...", "versionId": "...", "versionNumber": 1, "downloadUrl": "/api/documents/.../download" }
+
+curl -H "Authorization: Bearer $TOKEN" -o ไฟล์ที่สร้าง.docx \
+  "http://localhost:5075$DOWNLOAD_URL"
+```
+
+เปิดไฟล์ที่ได้ตรวจได้ว่า: ค่าถูกทุก field (formatting ของ template คงเดิม) และมี custom properties `SavedByAddIn` / `DocumentTrackingId` (unzip ดู `docProps/custom.xml` หรือ Word → File → Info → Properties → Advanced Properties)
+
+**4) Field sync ตอนสร้าง version ถัดไป** — upload v2 พร้อมแนบ `fields` (map tag→text ที่ extract จาก content controls — ในอนาคตฝั่ง add-in ทำให้อัตโนมัติ):
+
+```bash
+curl -X POST http://localhost:5075/api/documents/$DOC_ID/versions \
+  -H "Authorization: Bearer $TOKEN" \
+  -F "file=@ไฟล์แก้แล้ว.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
+  -F "clientVersionId=$(uuidgen)" \
+  -F 'fields={"employee_name":"สมชาย ใจดี มากกว่าเดิม","salary":"60000"}'
+```
+
+แล้วดู `GET /api/documents/$DOC_ID/versions` — แต่ละ version มี snapshot fields ของตัวเอง หากลบ content control ออกจาก Word ก่อน upload field นั้นจะเห็น `"missing": true` โดยค่าเดิมยังคงอยู่ (ไม่ error)
+
 ### 3) Add-in และ Web Portal (ยังเป็น scaffold)

 ```bash