eCourt-note/docs/WORDADDIN-DEV.md

Word Add-in (wordaddin) — คู่มือ dev และการทดสอบ

Taskpane ของ Word add-in "e-Court Documents Versioning" พอร์ตมาเป็น route ของ Next.js ที่ /docedit/wordaddin (ต้นฉบับ webpack + Fluent UI: D:\word-addin-poc\addin) — spec พฤติกรรม UI ทั้งหมดอยู่ที่ docs/addin-ui-flow.md

ทางเข้า: เปิด /docedit เปล่า ๆ จะ redirect มาที่ taskpane ทันที (ไม่ผ่าน login — คำขอผู้ใช้ 2026-10-14) ยกเว้นลิงก์ e-Court /docedit/?fileUrl=&fileId=&typeId= ที่ยังส่งต่อให้ /note ตามสัญญา N8 · manifest ชี้ /docedit/wordaddin ตรง ๆ (ไม่ว่าผ่าน root เพื่อลด hop ใน webview)

สถานะช่วงนี้: auth และ API เป็น mock (login ทันที + version store เก็บ metadata ค้างข้าม session ใน localStorage ของ taskpane เพื่อทดสอบวงปิดเอกสาร→เปิดใหม่ — สลับกลับของจริงด้วยการลบ wordaddin-mock-versions หรือเคลียร์ storage ของ origin) รอ backend/auth จริง — ดูหัว "การสลับกลับของจริง" ด้านล่าง

ไฟล์หลัก

ที่	คือ
app/wordaddin/page.tsx + components/wordaddin/WordAddinGate.tsx	gate โหลด Office.js (self-host) → Office.onReady → mount TaskpaneApp
app/wordaddin/manifest.xml/route.ts	serve manifest พร้อม rewrite origin ตามโฮสต์ที่ขอ (อ่าน x-forwarded-proto/x-forwarded-host ก่อนแล้ว fallback host ตรง ผ่าน utils/request-origin.ts ที่แชร์กับ origin ของ deep link N10 — โฮสต์ที่ไม่ใช่ localhost บังคับ https เพราะ Office รับ https เท่านั้น)
components/wordaddin/TaskpaneApp.tsx	state machine checking/signed-out/untracked/tracking + ทุก handler
wordaddin/services/*	ชั้น Office.js พอร์ตดิบจากต้นฉบับ + authService/versioningService เป็น mock
public/wordaddin/manifest.template.xml	template ของ manifest (ค่า default dev https://localhost:3000) — serve ผ่าน route ด้านบนเท่านั้น ไม่ได้ใช้ตรง ๆ
public/wordaddin/office-js/	Office.js runtime — สร้างโดย postinstall scripts/fetch-office-js.mjs ดาวน์โหลดฉบับล่าสุดจาก CDN ของ Microsoft (gitignore — รัน npm install ทุกครั้งหลัง clone เครื่องต้องออกอินเทอร์เน็ตตอนติดตั้ง ส่วนตัวระบบ deploy ใช้ intranet ล้วน)
wordaddin/config.ts	env NEXT_PUBLIC_ADDIN_* (ตารางด้านล่าง)

Env

ตัวแปร	default	ใช้เมื่อไหร่
NEXT_PUBLIC_ADDIN_API_BASE_URL	"" (ว่าง)	ปลด mock ต่อ backend จริง (ต้องเป็น HTTPS)
NEXT_PUBLIC_ADDIN_MOCK_USERNAME	"tester01"	ชื่อผู้ใช้ของ mock — แสดง header + เป็น createdByUserId

รัน dev ด้วย HTTPS (จำเป็นสำหรับ sideload ใน Word)

manifest ต้องชี้ https — 2 ทางเลือก:

1. self-signed ของ Next (ง่ายสุด): npm run dev:https → https://localhost:3000 — Word อาจเตือน certificate ครั้งแรก (เปิด URL ใน browser กดผ่านก่อน 1 ครั้ง)
2. ใบรับรอง trusted (แนะนำ ไม่มี warning): รัน npx office-addin-dev-certs install ครั้งเดียว แล้ว copy %USERPROFILE%\.office-addin-dev-certs\localhost.crt + localhost.key มาที่ certs/ (gitignore แล้ว) แล้วใช้ npm run dev:https:cert

Sideload ใน Word Desktop (Windows)

เครื่อง dev ที่มี repo (แนะนำ — ไม่ต้องดาวน์โหลด/คัดลอกอะไรเลย):

1. Word: File > Options > Trust Center > Trust Center Settings > Trusted Add-in Catalogs เพิ่มโฟลเดอร์ public/wordaddin ของ repo (เช่น D:\dms\judes-note\public\wordaddin) > restart Word
2. Insert > My Add-ins > SHARED FOLDER > เปิด "e-Court Documents Versioning"
3. ชื่อไฟล์ไม่สำคัญ — Word สแกน *.xml ทุกไฟล์ในโฟลเดอร์ โดย manifest.template.xml คือ dev manifest อยู่แล้ว (URL localhost:3000) และเนื้อไฟล์อัปเดตตาม branch ที่ checkout อยู่เสมอ — ห้ามวาง xml manifest อื่นเพิ่มในโฟลเดอร์นี้ (GUID เดียวกันสองไฟล์ = Word สับสน)

เครื่องที่ไม่มี repo (production/เครื่องผู้ใช้):

1. ดาวน์โหลด manifest จาก environment นั้น: https://<โฮสต์>/docedit/wordaddin/manifest.xml
2. เอาไฟล์ไว้โฟลเดอร์ใดโฟลเดอร์หนึ่ง เช่น %USERPROFILE%\Documents\wordaddin-manifest\
3. ทำขั้น Trust Center ข้างบนด้วยโฟลเดอร์นั้น > restart Word > Insert > My Add-ins > SHARED FOLDER > เปิด "e-Court Documents Versioning"

Deploy จริง (intranet): ไม่ต้อง rewrite อะไรแล้ว — manifest serve ผ่าน app/wordaddin/manifest.xml/route.ts ซึ่งเขียนทับ origin ให้ตรงโฮสต์ที่ขอไฟล์อัตโนมัติ ดาวน์โหลด https://<โฮสต์>/docedit/wordaddin/manifest.xml แล้วใช้ sideload ได้ทันทีทุก environment (dev/UAT/production) · proxy ฝั่งหน้าควรส่ง X-Forwarded-Host/X-Forwarded-Proto ตามมาตรฐาน — ถ้าไม่ส่ง route ก็ยังใช้ Host ของ request และบังคับ https ให้โฮสต์ที่ไม่ใช่ localhost อยู่ดี

รุ่น Office ที่รองรับ: manifest กำหนด WordApi 1.3 เป็นค่าต่ำสุด (customXmlParts คือ API สูงสุดที่ใช้ประจำ) — Microsoft 365 / Office 2021+ ใช้ได้ครบทุกฟีเจอร์ · Office 2019 โหลดได้ แต่ปุ่ม "…และปิดเอกสาร" ถูกซ่อนอัตโนมัติ เพราะ document.close() ต้องการ WordApi 1.4/1.5 (Microsoft 365 เท่านั้น) — canCloseDocument() เช็ค isSetSupported ตอน runtime แล้วซ่อน พฤติกรรมเดียวกับ Word on the web · Office 2016 (WordApi 1.1) โหลดไม่ขึ้น (เดิมเคยตั้ง 1.5 ทำให้ Office 2019 โหลดไม่ขึ้นด้วย — แก้ 2026-10-16)

ทดสอบใน browser ธรรมดา (ไม่ต้องเปิด Word)

• /docedit/wordaddin — เส้นทางจริง: Office.js โหลดได้แม่นนอก host (host เป็น null) → เห็น signed-out → กด Sign in (mock ผ่านทันที) → detect พังที่ Word.run → bootError + ปุ่มลองใหม่ (ตรวจ state machine/handler ได้ครบ)
• /docedit/wordaddin?addindemo=untracked / ?addindemo=tracking — dev-only: ข้าม Office.js + sign in mock ทันที + ตั้ง phase ตามค่า (tracking มี history ตัวอย่าง 3 รายการ) — ทุกปุ่มกดได้ แต่ flow ที่แตะ Word จริง (Start Versioning / Save & Version / บันทึก) จะจบที่ error ตาม expected
• หมายเหตุ: ใน browser ปกติ (ไม่ใช่ demo) banner "บันทึกอัตโนมัติไม่สำเร็จ" จะโผล่หลัง ~30 วิ เพราะ auto-save (FR-17) พยายาม save ทุก 30 วิแต่ไม่มี Word — ถือว่าถูกต้อง

ทดสอบ e-Court pass-through (ข้าม login)

ไฟล์ที่ e-Court stamp custom properties token และ/หรือ owner ไว้ จะเข้าใช้ได้เลยโดยไม่ต้องกด Sign in — detect() อ่านค่าทั้งสองตอนเปิด task pane แล้วเรียก authService.signInFromDocument() (username ได้จาก owner → ถอด uid ใน JWT payload → NEXT_PUBLIC_ADDIN_MOCK_USERNAME, token จากไฟล์เก็บใน memory ให้ getAccessToken() ใช้ต่อ)

ทดสอบเองใน Word โดยไม่ต้องรอ e-Court: เปิดไฟล์ → File → Info → Properties → Advanced Properties → แท็บ Custom → เพิ่ม property ชื่อ token (ค่า JWT ตัวอย่าง eyJ... — payload มี uid ก็แสดงเป็นชื่อผู้ใช้ได้) และ/หรือ owner (เช่น u1001) → เปิด task pane ใหม่ → ต้องเข้าเฟส untracked/tracking ทันทีไม่ผ่านหน้า login

การสลับกลับของจริง (วันหน้า)

• Auth: wordaddin/services/authService.ts เป็น mock คง surface เดิมครบ (login/getAccessToken/refreshAccessToken/getUsername/signOut/startAutoRefresh/...) — เขียน implementation จริงทับ (ต้นฉบับ Keycloak PKCE + Office Dialog API อยู่ที่ D:\word-addin-poc\addin\src\services\authService.ts; ถ้าใช้ ต้องเพิม DialogAPI กลับเข้า manifest + หน้า auth-start/auth-callback) · signInFromDocument (pass-through จาก token/owner ในไฟล์) เป็น mock-only — วันหน้า token ในไฟล์ควรเป็นแค่ตัวจับคู่เอกสาร ส่วนสิทธิ์ผู้ใช้พิสูจน์ตอน runtime
• API: wordaddin/services/versioningService.ts เก็บชื่อ/ลายเซ็นเหมือนต้นฉบับเป๊ะ — ก้อบ body เดิม (multipart POST ผ่าน apiClient ซึ่งพอร์ตไว้แล้ว) กลับมา + ตั้ง NEXT_PUBLIC_ADDIN_API_BASE_URL
• ชุด unit test ของ services (jest → vitest) ยังไม่พอร์ต — ต้นฉบับอยู่ที่ D:\word-addin-poc\addin\src\services\*.test.ts + mock ที่ src/test/

Docker

ไม่ต้องทำอะไรเพิ่ม — docker/web.Dockerfile รัน scripts/fetch-office-js.mjs ใน build อยู่แล้ว (build stage ต้องออกอินเทอร์เน็ตถึง appsforoffice.microsoft.com ได้) และ runner stage คัดลอก public/ เข้า image เอง (COPY /app/public ./public — Next 14.2 standalone ไม่รวม public/ ให้อัตโนมัติ ต้อง copy เองตามเอกสาร deploy ของ Next; เคยเข้าใจผิดว่า Next รวมให้ เพราะบางไฟล์หลุดเข้า image ผ่าน output file tracing ของ Next ที่ตาม fs.readFile ใน server code — แต่ public/wordaddin/office-js ไม่มีใครอ่านผ่าน fs จึงไม่ถูกดึงมา แล้ว taskpane พังใน production 2026-10-16)

ทำไมต้องเป็นฉบับ CDN ล่าสุด: แพ็กเกจ npm @microsoft/office-js เลิกอัปเดตที่ 1.1.110 (~2018) ก่อน WordApi 1.4/1.5 — runtime ตัวนั้นไม่มี Document.close (ปุ่ม "บันทึกเวอร์ชันและปิดเอกสาร" พัง: context.document.close is not a function) และไม่มี enum Word.CloseBehavior/SaveBehavior ทับ ๆ กับ @types/office-js ฉบับใหม่ที่ใช้ compile