ปรับปรุง readme file

2026-08-19 10:58:37 +07:00 · 2026-08-19 10:58:37 +07:00 · 9321f5a370
commit 9321f5a370
parent b976cf3124
1 changed files with 90 additions and 16 deletions
--- a/README.md
+++ b/README.md
@ -28,7 +28,17 @@

 ## สถานะโปรเจกต์

-> ⚠️ **อยู่ในขั้นตอนวางแผน — ยังไม่มีโค้ด** (spec และ implementation plan เสร็จแล้ว ยังไม่ได้เริ่ม implement)
+| Phase | เนื้อหา | สถานะ |
+|---|---|---|
+| 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 |
+| 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

 ## เอกสาร

@ -37,26 +47,90 @@

 สำหรับผู้เริ่มพัฒนา: อ่าน spec ก่อน แล้วตามด้วย plan (เริ่มจาก Phase 0)

-## การพัฒนา (ใช้ได้หลัง implement Phase 0 ขึ้นไป)
+## การพัฒนา (local)
+
+### Prerequisites
+
+- Docker Desktop
+- .NET 8 SDK + `dotnet-ef` tool (สำหรับ migration):
+  ```bash
+  dotnet tool install --global dotnet-ef --version 8.0.11
+  ```
+- Node.js LTS (add-in และ web — ยังเป็น scaffold)
+
+### 1) รัน infrastructure (PostgreSQL + MinIO + Keycloak)

 ```bash
-# 1) รัน infrastructure (PostgreSQL + MinIO + Keycloak)
+cp .env.example .env      # ครั้งแรกครั้งเดียว — แก้ password ได้ตามต้องการ
 docker compose up -d
-
-# 2) Backend
-cd backend/WordVersioning.Api
-dotnet run
-
-# 3) Add-in dev server (https://localhost:3000 — sideload ใน Word ผ่าน manifest)
-cd addin
-npm start
-
-# 4) Web Portal (http://localhost:5173)
-cd web
-npm run dev
 ```

-รายละเอียด local dev แบบเต็ม (sideload บน Word Desktop/Online, ตั้งค่า Keycloak/MinIO, สร้าง test user, สร้าง template แรก) จะเขียนใน README นี้อีกครั้งเมื่อ implement ถึง Phase 8 ของแผน
+เมื่อขึ้นครบแล้ว:
+
+| บริการ | URL | เข้าด้วย |
+|---|---|---|
+| Keycloak admin console | http://localhost:8080/admin/ | `KC_BOOTSTRAP_ADMIN_USERNAME` / `KC_BOOTSTRAP_ADMIN_PASSWORD` จาก `.env` |
+| MinIO console | http://localhost:9001 | `MINIO_ROOT_USER` / `MINIO_ROOT_PASSWORD` จาก `.env` |
+| PostgreSQL | `localhost:5432` | `POSTGRES_USER` / `POSTGRES_PASSWORD` จาก `.env`, ฐานข้อมูล `wordversioning` |
+
+Keycloak จะ import realm `word-versioning` อัตโนมัติ (clients 3 ตัว + test user) จาก [keycloak/realm-export.json](keycloak/realm-export.json) — ไฟล์นี้คือ source of truth ของ realm ฝั่ง dev: แก้ realm ให้แก้ที่ไฟล์นี้แล้วรัน `docker compose rm -sf keycloak && docker compose up -d` เพื่อ import ใหม่ (การแก้ผ่าน admin console จะหายเมื่อ recreate container)
+
+**Test user สำหรับล็อกอิน:** `testuser` / `Test1234!` (เปลี่ยนได้ใน realm-export.json)
+
+MinIO จะมี bucket `docx-versions` และ `docx-templates` (private ทั้งคู่) สร้างให้อัตโนมัติ
+
+### 2) Backend API
+
+```bash
+cd backend/WordVersioning.Api
+dotnet ef database update    # ครั้งแรก / เมื่อมี migration ใหม่
+dotnet run                   # Swagger ที่ http://localhost:5075/swagger
+```
+
+ค่าเชื่อมต่อ (DB/MinIO/Keycloak) อยู่ใน `appsettings.json` + `appsettings.Development.json` — override ผ่าน env ได้ทั้งหมด เช่น `ConnectionStrings__Default`, `MinIO__Endpoint`, `Authentication__Authority`
+
+**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)
+```
+
+- Upload เป็น multipart/form-data: `file` (.docx เท่านั้น, จำกัด 100MB) + `clientVersionId` (GUID) + `fields` (optional, JSON map tag→text สำหรับ field sync)
+- `documentId` ยังไม่มีในระบบ = สร้างใหม่อัตโนมัติ · `versionNumber` เพิ่มอัตโนมัติต่อเอกสาร · เก็บ SHA256 ของทุก version
+
+### ขอ token ทดสอบ (dev)
+
+ทุก client บังคับ PKCE (ปิด direct grants ตาม spec) — วิธีเร็วสุดตอนทดสอบคือขอผ่าน client `admin-cli` ของ realm:
+
+```bash
+curl -s -X POST http://localhost:8080/realms/word-versioning/protocol/openid-connect/token \
+  -d "client_id=admin-cli&grant_type=password&username=testuser&password=Test1234!" \
+| jq -r .access_token
+```
+
+แล้วลอง upload:
+
+```bash
+DOC_ID=$(uuidgen | tr 'A-Z' 'a-z')
+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)"
+# → { "versionId": "...", "versionNumber": 1 }
+```
+
+### 3) Add-in และ Web Portal (ยังเป็น scaffold)
+
+```bash
+cd addin && npm start       # https://localhost:3000 — ครั้งแรก: npx office-addin-dev-certs install
+cd web && npm run dev       # http://localhost:5173
+```
+
+สองส่วนนี้ยังเป็นโครงจาก Phase 0 — logic จริง (login, Save & Version, template UI) มาตาม Phase 4–6
+
+> คำแนะนำฉบับเต็ม (sideload บน Word Desktop/Online, สร้าง template แรก, สร้างเอกสารจากเว็บ) จะเติมเมื่อ implement ครบตาม Phase 8 ของแผน

 ## เทคโนโลยี