phase 0

README.md

@@ -0,0 +1,66 @@
+# Word Versioning Add-in
+
+ระบบจัดการ version history ของเอกสาร Word — สร้างเอกสารจาก template ผ่านเว็บ ติดตามทุกการแก้ไขผ่าน add-in ใน Word และ sync ข้อมูลสำคัญกลับฐานข้อมูลอัตโนมัติ
+
+## คุณสมบัติหลัก
+
+- 📝 **สร้างเอกสารจาก template** — กรอก form บนเว็บ → ระบบ generate .docx จาก template (แทนที่ค่าใน content controls) พร้อม stamp metadata และขึ้นเป็น **version 1 อัตโนมัติ**
+- 🗂️ **Template management** — upload ไฟล์ .docx ที่มี content controls แล้วระบบ **detect fields อัตโนมัติ** ตั้งชื่อ/ชนิด/required ต่อ field ผ่านหน้าเว็บ
+- 📌 **ตรวจจับ tracked document** — เปิดไฟล์ใน Word (Desktop Win/Mac หรือ Online) แล้ว add-in รู้ทันทีว่าไฟล์นี้อยู่ในระบบ พร้อมแสดง version history
+- 💾 **Save & Version** — ปุ่มใน task pane สร้าง version ใหม่ (stamp metadata + อัปโหลด snapshot ไป backend)
+- 🔄 **Field sync** — ทุกครั้งที่สร้าง version ระบบ extract ค่าจาก content controls ของเอกสารไป update fields ใน DB ให้ sync กับเนื้อหาจริงเสมอ
+- ⬇️ **ดาวน์โหลด version ย้อนหลัง** — ทุก version เก็บครบพร้อม SHA256 hash ตรวจสอบความถูกต้องได้
+
+## สถาปัตยกรรม
+
+| ส่วน | Stack | หน้าที่ |
+|---|---|---|
+| **Add-in** (`/addin`) | Office.js, TypeScript, React, Fluent UI | Task pane ใน Word — ตรวจจับ document, Save & Version, version history, field extraction |
+| **Backend** (`/backend`) | ASP.NET Core 8, EF Core, PostgreSQL, MinIO, OpenXML | Version API, template system, docx generation, JWT validation |
+| **Web Portal** (`/web`) | Nuxt.js, TailwindCSS | จัดการ template + สร้างเอกสารจาก form (light/dark theme) |
+| **Auth** | Keycloak (OIDC + PKCE) | Public clients ทั้ง add-in และเว็บ, backend validate ผ่าน JWKS |
+| **Storage** | MinIO (S3-compatible) | bucket `docx-versions` (snapshot ต่อ version) + `docx-templates` (ไฟล์ template) — private ทั้งคู่ |
+
+**Flow หลัก:**
+1. Admin upload template (.docx ที่มี content controls) → ระบบ detect fields อัตโนมัติ
+2. ผู้ใช้กรอก form บนเว็บ → ได้ไฟล์ .docx ที่เป็น version 1 แล้ว → เปิดใน Word
+3. Add-in รู้จักเอกสารทันที → แก้ไขเนื้อหา → กด **Save & Version** → เกิด version ใหม่ + fields ใน DB sync ตามเนื้อหาล่าสุด
+
+## สถานะโปรเจกต์
+
+> ⚠️ **อยู่ในขั้นตอนวางแผน — ยังไม่มีโค้ด** (spec และ implementation plan เสร็จแล้ว ยังไม่ได้เริ่ม implement)
+
+## เอกสาร
+
+- [specs/spec-officejs.md](specs/spec-officejs.md) — spec เต็มรูปแบบ: functional requirements (FR-1–11), data models, acceptance criteria (1–14)
+- [docs/plans/officejs-implementation-plan.md](docs/plans/officejs-implementation-plan.md) — implementation plan แบ่ง 9 phases พร้อม definition of done
+
+สำหรับผู้เริ่มพัฒนา: อ่าน spec ก่อน แล้วตามด้วย plan (เริ่มจาก Phase 0)
+
+## การพัฒนา (ใช้ได้หลัง implement Phase 0 ขึ้นไป)
+
+```bash
+# 1) รัน infrastructure (PostgreSQL + MinIO + Keycloak)
+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 ของแผน
+
+## เทคโนโลยี
+
+- **Add-in**: Office.js (WordApi 1.5+), TypeScript, React, Fluent UI, webpack — scaffold ด้วย `yo office`
+- **Backend**: .NET 8, EF Core + Npgsql (PostgreSQL), AWSSDK.S3 → MinIO (`ForcePathStyle = true`), DocumentFormat.OpenXml, JwtBearer
+- **Web**: Nuxt.js (Vue 3), TailwindCSS (`darkMode: 'class'`)
+- **Auth**: Keycloak — realm `word-versioning`, clients: `word-addin-officejs`, `word-versioning-web`, `word-addin-vsto` (public + PKCE S256 ทุกตัว)