From 83a949cfa0ebd941d0ceaf177b5a408eeb0516a9 Mon Sep 17 00:00:00 2001 From: Suphonchai Phoonsawat Date: Thu, 10 Sep 2026 13:59:45 +0700 Subject: [PATCH] v9.2 follow-up: skip ms-word on Mac by default + sideload notes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Web: ยิง ms-word:ofe คู่กับการดาวน์โหลดเฉพาะ non-Mac โดย default — บน Mac ไม่ยิงเพราะ Word 16.101+ เมิน URL แล้วเด้งหน้าเลือกไฟล์ ทุกครั้งจนรำคาญ (override ด้วย NUXT_PUBLIC_OPEN_IN_WORD=on|off) - CLAUDE.md: จดสูตร sideload บน Mac — ปิด Word ก่อน npm start (Word อ่าน manifest ตอน startup เท่านั้น), ปล่อย dev server รันทิ้ง, แก้โค้ดใช้ hot reload - Spec/plan sync + web 60/60 + build; QA reviewer PASS (1 round, minors 3 — แก้ 2 ปฏิเสธ 1 พร้อมเหตุผล) Co-Authored-By: Claude Code --- CLAUDE.md | 5 ++++- docs/acceptance-review.md | 4 +++- docs/plans/officejs-implementation-plan.md | 2 +- specs/spec-officejs.md | 2 +- web/app/composables/useVersionOpen.ts | 20 ++++++++++++----- web/nuxt.config.ts | 3 +++ web/test/useVersionOpen.spec.ts | 26 ++++++++++++++++++++++ 7 files changed, 52 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ff88f5c..9b32984 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,7 +14,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co Infra ทั้งหมดรันผ่าน `docker-compose.yml`: PostgreSQL + MinIO + Keycloak (OIDC, 3 public clients พร้อม PKCE: `word-addin-officejs`, `word-versioning-web`, `word-addin-vsto`) -**สถานะปัจจุบัน: Phase 0–12 — FR-16 ไฟล์ร่าง: automated QA PASS (backend 86 / add-in 66 / web 58 + build ครบ · v9.2: download-first + open-link ของ backend), ค้าง manual บน Word จริง · Phase 0–11 เสร็จครบ (FR-15 ผ่าน QA + manual บน Word for Mac 2026-09-08)** — ค้างยืนยันบน Word for Windows / Word on the web ตามรายการใน `docs/acceptance-review.md` +**สถานะปัจจุบัน: Phase 0–12 — FR-16 ไฟล์ร่าง: automated QA PASS (backend 86 / add-in 66 / web 60 + build ครบ · v9.2: download-first + open-link ของ backend), ค้าง manual บน Word จริง · Phase 0–11 เสร็จครบ (FR-15 ผ่าน QA + manual บน Word for Mac 2026-09-08)** — ค้างยืนยันบน Word for Windows / Word on the web ตามรายการใน `docs/acceptance-review.md` ## เอกสารหลัก (อ่านก่อนเริ่มงานใดๆ) @@ -83,6 +83,9 @@ npx office-addin-dev-certs install # ครั้งแรก npm run build # webpack build npm start # dev server — sideload ผ่าน manifest (symlink) npm test +# ⚠️ sideload บน Mac: ปิด Word ทุกหน้าต่าง (Cmd+Q) ก่อน `npm start` — Word อ่าน manifest ตอน +# startup เท่านั้น ถ้าเปิดค้างไว้ manifest ใหม่จะไม่ถูกโหลด (ต้อง stop/start) · ปล่อย dev server +# รันทิ้งไว้ตลอด session (ถ้าตาย task pane โหลดไม่ได้) · แก้โค้ด add-in ใช้ hot reload ได้เลยไม่ต้อง restart npx jest src/services/metadataService.test.ts # รัน test เดี่ยว # web portal (http://localhost:5173 — ห้ามใช้ 3000) diff --git a/docs/acceptance-review.md b/docs/acceptance-review.md index 27bdcdf..b11979f 100644 --- a/docs/acceptance-review.md +++ b/docs/acceptance-review.md @@ -157,7 +157,7 @@ QA reviewer: **PASS**, 2 rounds, 3 findings fixed (build compatibility, pending | add-in: อ่าน TemplateId / ส่งเฉพาะ startVersioning / append form field | `metadataService.test.ts` (ไฟล์ร่างอ่าน TemplateId), `versionFlow.test.ts` (แนบ/ไม่แนบ templateId), `versioningService.test.ts` (form field) | | เว็บ: เปิด docx URL ที่ถืออยู่เอง (ไฟล์ร่าง) ผ่าน ms-word + fallback + notice | `useVersionOpen.spec.ts` `openDocxUrl` test | -ชุดเต็ม (v9.2): backend **86 ผ่าน**, add-in **66 ผ่าน**, web **58 ผ่าน** + production build ผ่าน +ชุดเต็ม (v9.2): backend **86 ผ่าน**, add-in **66 ผ่าน**, web **60 ผ่าน** + production build ผ่าน ### ค้างยืนยันด้วยมือ (ต้องมี Word จริง) @@ -189,3 +189,5 @@ QA reviewer รอบ hotfix อักขระควบคุม 0x0B จาก QA reviewer รอบ hotfix "เปิดใน Word ตอน cold-start" (v9.1): **PASS**, 1 round (2026-09-10) — reviewer stash-verify ว่า test ใหม่ fail จริงบนโค้ดก่อนแก้ · minors 3: แก้ 1 (เพิ่ม test re-click ยกเลิก auto-download ค้าง — save ครั้งเดียว URL ล่าสุด) · ยอมรับ 2 พร้อมเหตุผล: (1) ถ้า Word cold-start มาถึงหน้าต่างภายใน 3 วิ heuristic เห็น "สลับแอป" จึงไม่ auto-download ทั้งที่เอกสารไม่เปิด — เป็นข้อจำกัดเชิงหลักการของ heuristic (แยก "Word เปิด" กับ "เปิดเอกสาร" ไม่ได้จาก web) spec ระบุชัดว่าไม่ใช่หลักฐานความสำเร็จ + มี manual check item ครอบ (2) ถ้า Word เปิดเอกสารสำเร็จแต่ช้ากว่า 3 วิ ผู้ใช้ได้ไฟล์ซ้ำใน Downloads — ต้นทุนต่ำยอมรับได้ · ตรวจแล้ว: PDF path ไม่โดน auto-download, ทุก docx entry point (version rows/v0/ไฟล์ร่าง) ผ่าน openDocxUrl ครบ QA reviewer รอบ v9.2 (download-first + open-link): **PASS**, 1 round (2026-09-10) — reviewer ตรวจ security ของ `/api/open` เชิงลึก (HMAC binding/fixed-time compare/path scoping ของ draft catch-all route — ผ่านทั้งหมด) + รัน suites เองได้ 86/58/66 ตรงตาม docs · minors 4 แก้ครบ: (1) คำ spec header ที่ขัดแย้งตารางทดสอบเอง (2) OpenLinks config ตรวจตั้งแต่สตาร์ทด้วย ValidateOnStart (Secret ว่าง/BaseUrl ไม่ใช่ https = fail ดัง) (3) เอา dead code presigned ออก (GetPresignedGetUrl/PresignedExpirySeconds) + comment/copy เก่าทั้ง web/add-in/CLAUDE.md (4) draft success copy นำด้วยการดาวน์โหลดแทน "กำลังเปิดใน Word" + +QA reviewer รอบ follow-up v9.2 (เลิกยิง ms-word บน Mac default + จดสูตร sideload): **PASS**, 1 round (2026-09-10) — minors 3: แก้ 2 (sync implementation plan กับ spec + ตัวเลข 60, comment เก่าใน create page) · ปฏิเสธ 1 พร้อมเหตุผล: ปุ่มยังชื่อ "เปิดใน Word" บน Mac ทั้งที่ตอนนี้=ดาวน์โหลด — notice หลังกดอธิบายชัดและชื่อปุ่มเดิมมาก่อนการเปลี่ยนนี้ เปลี่ยนชื่อกระทบ UX ที่ทีมคุ้นเคย เก็บเป็นข้อสังเกตไว้ก่อน (จะเปลี่ยนเมื่อมี feedback ผู้ใช้จริง) diff --git a/docs/plans/officejs-implementation-plan.md b/docs/plans/officejs-implementation-plan.md index fa3aaa2..af12e6e 100644 --- a/docs/plans/officejs-implementation-plan.md +++ b/docs/plans/officejs-implementation-plan.md @@ -646,5 +646,5 @@ npm test # vitest (46 ตัว) - [x] Tests/build (backend 82 / add-in 66 / web 59 + build ทั้ง add-in/web) - [x] QA reviewer PASS (2 rounds, 2026-09-10) - [x] **v9 (feedback จากการใช้จริง): เปิดใน Word ทันที** — เก็บ object ใต้ `drafts/` + lifecycle รายวัน + คืน presigned URL + `useVersionOpen.openDocxUrl` · **แก้ตัดคำไทย** — ค่าเขียนที่ run ข้อความ placeholder จริง (complex script) + SDT เปล่าสืบทอด sdtPr rPr (backend 85 / web 59) + QA reviewer PASS (2 rounds, 2026-09-10) -- [x] **v9.2: Word 16.101+ เมิน `ms-word:ofe` ทุกรูปแบบ (ทดสอบ 6 รอบบนเครื่องจริง)** → download-first (ดาวน์โหลดทันที + ยิง scheme ควบคู่, เอา heuristic ออก) + `download-link`/draft ออก open-link ของ backend แทน presigned MinIO (`/api/open/{t}/{e}/...` HMAC ใน path ไม่มี query) — backend 86 / web 58 +- [x] **v9.2: Word 16.101+ เมิน `ms-word:ofe` ทุกรูปแบบ (ทดสอบ 6 รอบบนเครื่องจริง)** → download-first (ดาวน์โหลดทันที + ยิง scheme ควบคู่เฉพาะ non-Mac โดย default — `NUXT_PUBLIC_OPEN_IN_WORD` override, เอา heuristic ออก) + `download-link`/draft ออก open-link ของ backend แทน presigned MinIO (`/api/open/{t}/{e}/...` HMAC ใน path ไม่มี query) — backend 86 / web 60 - [ ] ตรวจ Word จริง (manual): เว็บสร้างไฟล์ร่าง → **ไฟล์ตก Downloads ทันที + ตัดคำไทยถูก** → เปิดไฟล์เอง → untracked + hint → Start Versioning → v1 ผูก template + fields sync · รวมในรายการค้างเดิมของ Word for Windows / Word on the web diff --git a/specs/spec-officejs.md b/specs/spec-officejs.md index 2d9e29c..ed5aaaf 100644 --- a/specs/spec-officejs.md +++ b/specs/spec-officejs.md @@ -292,7 +292,7 @@ POST /api/documents/generate { templateId, values: { : } } - เก็บ PDF ใน bucket docx-versions, sibling key `{documentId}/v{N:D4}_{clientVersionId}.pdf`; `PdfObjectKey` nullable - docx upload ล้มใช้ error เดิม; PDF upload ล้มเป็น best-effort → version สำเร็จ `hasPdf:false`; task pane เตือน “บันทึกแล้ว แต่สร้าง PDF ไม่สำเร็จ” และแนะนำ Save & Version ใหม่ - upload/history response มี `hasPdf`; ปุ่ม PDF แสดงเฉพาะเมื่อมี PDF; add-in เปิด presigned URL ผ่าน `openBrowserWindow` -- เว็บ history ทั้ง desktop/mobile เปิด docx แบบ **download-first** (v9.2): กดปุ่ม → **ดาวน์โหลดไฟล์ทันทีทุกครั้ง** (ลิงก์เปิดของ backend, disposition attachment) + ยิง `ms-word:ofe|u|` ควบคู่แบบ best-effort เผื่อเครื่องที่ scheme ยังทำงาน (Windows / Word รุ่นก่อน) + ข้อความบอกว่าไฟล์อยู่ Downloads; PDF เปิดแท็บใหม่ · เลิกใช้ heuristic การสลับแอป (v9.1) เพราะ Word for Mac 16.101+ เมิน URL ทุกรูปแบบแต่เด้งหน้าเลือกไฟล์เหมือนสลับแอปจริง ทำให้ heuristic โดนหลอกจนไม่ดาวน์โหลด (ยืนยันด้วยการทดสอบบนเครื่องจริง 2026-09-10) +- เว็บ history ทั้ง desktop/mobile เปิด docx แบบ **download-first** (v9.2): กดปุ่ม → **ดาวน์โหลดไฟล์ทันทีทุกครั้ง** (ลิงก์เปิดของ backend, disposition attachment) + ยิง `ms-word:ofe|u|` ควบคู่แบบ best-effort **เฉพาะ non-Mac โดย default** — บน Mac ไม่ยิงเพราะ Word 16.101+ ไม่เพียงเมิน URL แต่เด้งหน้าเลือกไฟล์ทุกครั้งจนรำคาญ (override ได้ด้วย env `NUXT_PUBLIC_OPEN_IN_WORD=on|off`) + ข้อความบอกว่าไฟล์อยู่ Downloads; PDF เปิดแท็บใหม่ · เลิกใช้ heuristic การสลับแอป (v9.1) เพราะโดนหลอกจนไม่ดาวน์โหลด (ยืนยันด้วยการทดสอบบนเครื่องจริง 2026-09-10) - หน้า generate success เปิด v0 ใน Word พร้อมลิงก์ดาวน์โหลดสำรอง; PDF fidelity และ tracked changes ต้องยืนยันบน Word จริง ### FR-16: ไฟล์ร่าง (draft) — สร้าง .docx จาก template โดยไม่สร้าง Document (เพิ่มเติม v8 · ปรับ v9) diff --git a/web/app/composables/useVersionOpen.ts b/web/app/composables/useVersionOpen.ts index 2321d6f..126cfb0 100644 --- a/web/app/composables/useVersionOpen.ts +++ b/web/app/composables/useVersionOpen.ts @@ -4,6 +4,14 @@ import { versionDownloadPath, wordOpenUrl, type VersionFormat } from '../utils/v /** Shared by history and generate success — ลิงก์เปิดอายุสั้นของ backend (open-link) ใช้ทั้งดาวน์โหลดและเปิดแบบ best-effort */ export function useVersionOpen() { const { apiJson } = useApi() + // อ่านตอน setup (มี nuxt context) — จะยิง ms-word:ofe ควบคู่กับการดาวน์โหลดหรือไม่ + // (v9.2): Word for Mac 16.101+ เมิน URL ทุกรูปแบบและเด้งหน้าเลือกไฟล์ทุกครั้ง — default + // จึงไม่ยิงบน Mac; override ด้วย env NUXT_PUBLIC_OPEN_IN_WORD=on|off เพื่อบังคับทุกแพลตฟอร์ม + const openInWord = String(useRuntimeConfig().public.openInWord ?? '').toLowerCase() + const isMac = typeof navigator !== 'undefined' + && /Mac/i.test(navigator.platform || navigator.userAgent) + const fireWordScheme = openInWord === 'on' ? true : openInWord === 'off' ? false : !isMac + const openingVersionId = ref(null) const downloadError = ref(null) const fallbackUrl = ref(null) @@ -32,17 +40,17 @@ export function useVersionOpen() { } /** เปิดไฟล์ docx แบบ download-first (v9.2): ดาวน์โหลดไฟล์ให้ทันทีทุกครั้ง แล้วยิง ms-word:ofe - * ควบคู่แบบ best-effort เผื่อเครื่องที่ scheme ยังทำงาน (Windows / Word รุ่นก่อน) — - * เลิกพึ่ง heuristic การสลับแอป เพราะ Word for Mac 16.101+ (ก.ย. 2026) เมิน URL ทุกรูปแบบ - * โดยเด้งหน้าเลือกไฟล์ (เหมือนสลับแอปจริง — heuristic โดนหลอกจนไม่ดาวน์โหลดให้) + * ควบคู่แบบ best-effort เฉพาะเมื่อ fireWordScheme (default: ไม่ยิงบน Mac — ดูคอมเมนต์ด้านบน) * ใช้กับลิงก์ที่ถืออยู่เองได้เลย (ไฟล์ร่าง FR-16: response ของ generate-draft คือ URL แล้ว) */ function openDocxUrl(url: string) { resetOpen() fallbackUrl.value = url saveToDownloads(url) - openNotice.value = - 'ดาวน์โหลดไฟล์แล้วที่โฟลเดอร์ Downloads — เปิดจากที่นั่นได้เลย (บางเครื่อง Word จะเปิดให้อัตโนมัติ)' - window.location.assign(wordOpenUrl(url)) + openNotice.value = fireWordScheme + ? 'ดาวน์โหลดไฟล์แล้วที่โฟลเดอร์ Downloads — เปิดจากที่นั่นได้เลย (บางเครื่อง Word จะเปิดให้อัตโนมัติ)' + : 'ดาวน์โหลดไฟล์แล้วที่โฟลเดอร์ Downloads — เปิดจากที่นั่นได้เลย' + if (fireWordScheme) + window.location.assign(wordOpenUrl(url)) } async function openVersion(documentId: string, versionId: string, format: VersionFormat = 'docx') { diff --git a/web/nuxt.config.ts b/web/nuxt.config.ts index d9fecac..4f66d45 100644 --- a/web/nuxt.config.ts +++ b/web/nuxt.config.ts @@ -27,6 +27,9 @@ export default defineNuxtConfig({ // Keycloak dev ใช้ https:8443 (cert ของ office-addin-dev-certs — เชื่อถือได้ในเครื่อง) keycloakAuthority: 'https://localhost:8443/realms/word-versioning', keycloakClientId: 'word-versioning-web', + // ยิง ms-word:ofe ควบคู่กับการดาวน์โหลดหรือไม่ — '' = auto (ไม่ยิงบน Mac เพราะ Word 16.101+ + // เมิน URL ทุกรูปแบบและเด้งหน้าเลือกไฟล์รำคาญ, ยิงบน Windows/อื่นๆ), 'on'/'off' = บังคับทุกที่ (v9.2) + openInWord: '', }, }, diff --git a/web/test/useVersionOpen.spec.ts b/web/test/useVersionOpen.spec.ts index 4e03fc6..e684425 100644 --- a/web/test/useVersionOpen.spec.ts +++ b/web/test/useVersionOpen.spec.ts @@ -20,6 +20,8 @@ function mount() { beforeEach(() => { vi.stubGlobal('useApi', () => ({ apiJson })) + // default: auto — happy-dom ไม่ใช่ Mac UA จึงยิง ms-word ควบคู่ (แต่ละ test ที่ต้องการก็ stub ทับได้) + vi.stubGlobal('useRuntimeConfig', () => ({ public: { openInWord: '' } })) tab = { opener: {}, closed: false, location: { replace }, close } vi.spyOn(window, 'open').mockReturnValue(tab as unknown as Window) }) @@ -130,4 +132,28 @@ describe('version open lifecycle', () => { expect(saved[1].href).toBe('https://files.example/second.docx') expect(state.fallbackUrl.value).toBe('https://files.example/second.docx') }) + it('OPEN_IN_WORD=off: ไม่ยิง ms-word เลย — ดาวน์โหลดอย่างเดียว (Word 16.101+ บน Mac เด้งหน้าเลือกไฟล์ทุกครั้ง)', () => { + vi.stubGlobal('useRuntimeConfig', () => ({ public: { openInWord: 'off' } })) + const assign = vi.spyOn(window.location, 'assign').mockImplementation(() => {}) + vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {}) + const state = mount() + state.openDocxUrl('https://files.example/draft.docx') + expect(assign).not.toHaveBeenCalled() + expect(state.openNotice.value).not.toContain('อัตโนมัติ') // ข้อความไม่เกี้ยวเรื่องเปิดอัตโนมัติ + }) + it('auto บน Mac: ไม่ยิง ms-word (default), override on แล้วยิงแม้บน Mac', () => { + vi.spyOn(window.navigator, 'platform', 'get').mockReturnValue('MacIntel') + let state = mount() // default '' → auto → Mac = ไม่ยิง + const assign = vi.spyOn(window.location, 'assign').mockImplementation(() => {}) + vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {}) + state.openDocxUrl('https://files.example/draft.docx') + expect(assign).not.toHaveBeenCalled() + + app.unmount() + host.remove() + vi.stubGlobal('useRuntimeConfig', () => ({ public: { openInWord: 'on' } })) + state = mount() + state.openDocxUrl('https://files.example/draft.docx') + expect(assign).toHaveBeenCalledWith('ms-word:ofe|u|https://files.example/draft.docx') + }) })