From 9321f5a370a6731839ae14e3114105a7935326d4 Mon Sep 17 00:00:00 2001 From: Suphonchai Phoonsawat Date: Wed, 19 Aug 2026 10:58:37 +0700 Subject: [PATCH] =?UTF-8?q?=E0=B8=9B=E0=B8=A3=E0=B8=B1=E0=B8=9A=E0=B8=9B?= =?UTF-8?q?=E0=B8=A3=E0=B8=B8=E0=B8=87=20readme=20file?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 106 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 90 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index de04386..02978f4 100644 --- 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 `): + +``` +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 ของแผน ## เทคโนโลยี