eCourt-note/docs/PLAN.md

📋 Implementation Plan — Judge's Note (PDF Annotation System for e-Court)

แผนงานก่อนเริ่ม implement โปรเจกต์ Next.js แยกต่างหากจากโปรเจกต์ Nuxt (dms-main)

---

0. สมมติฐาน & ข้อตกลงเบื้องต้น (Assumptions)

#	หัวข้อ	ข้อตกลง
A1	ตำแหน่งโปรเจกต์	D:\dms\judes-note\ — directory แยกต่างหาก (ไม่ใช่ subdirectory ของ dms-main) เพื่อไม่ชนกับโปรเจกต์ Nuxt ที่มีโฟลเดอร์ app/ อยู่แล้ว
A2	Framework	Next.js 14 (App Router) + TypeScript strict
A3	PDF Renderer	pdfjs-dist เวอร์ชัน v4 (^4.10.38) — ใช้ built-in TextLayer class; worker ตั้ง path ตรง ๆ: คัดลอก pdf.worker.min.mjs (จาก node_modules/pdfjs-dist/build/) มาไว้ที่ public/ ด้วย postinstall script แล้วตั้ง pdfjs.GlobalWorkerOptions.workerSrc = "/pdf.worker.min.mjs" — ไม่ใช้ new URL(..., import.meta.url) เพราะ v4 เป็นไฟล์ .mjs และมักชนกับ Turbopack/webpack ใน Next 14
A4	Identity	สเปกไม่ระบุระบบ auth → ใช้ anonymous user สร้างครั้งเดียวเก็บใน localStorage (userId = UUID, userName = "ผู้ใช้ XXXX") เพื่อเติม field userId/userName ในตาราง
A5	ไม่มีไฟล์ปุ่ม Upload	หน้า / อ่านรายการจาก DB เท่านั้น (ตามสเปก) — sample PDF เก็บใน public/samples/ แล้ว seed ด้วย SQL ใน README (รายละเอียดด้านล่าง)
A6	ทุก annotation ลบได้	แสดงปุ่มลบเฉพาะรายการของตัวเอง (userId ตรงกัน) — ไม่มี role/permission ในเฟสนี้
A7	Database & Realtime (ปรับปรุง 2026-09-08)	PostgreSQL แบบ plain container เดียว (judes-note-db, Docker, image postgres:17-alpine, พอร์ต 54322) — เลิกใช้ Supabase stack ทั้งหมด (ไม่มี CLI/Kong/realtime container) เพราะโปรเจกต์ใช้จริงแค่ DB + sync; realtime sync ใช้ SSE (Server-Sent Events) + pub/sub in-process แทน Supabase Realtime
A8	Event ของ SSE เป็น DTO ตรง ๆ (2026-09-08)	Server Actions publish event ผ่าน lib/annotate-events.ts หลังเขียน DB สำเร็จ — payload เป็น DTO (camelCase + ISO string) โดยตรง ไม่มีการแปลง snake_case เหมือนสมัยใช้ Supabase Realtime

ไฟล์ตัวอย่าง (อยู่ที่ public/samples/ แล้ว)

ไฟล์	ที่มา	หน้า	ขนาด	ลักษณะ
01012-672427-4f-690609-0000840227.pdf	judgement-api.admincourt.go.th	15	~1.8 MB	สแกนภาพล้วน — ไม่มี text layer
01012-672427-1f-690609-0000840223.pdf	judgement-api.admincourt.go.th	44	~38 MB	สแกนภาพล้วน — ไม่มี text layer
dashboard-report-2026-09-03.pdf	เพิ่มโดยผู้ใช้ (2026-09-08)	2	~150 KB	text-based ภาษาไทย (ตรวจด้วย pdfjs: 285 text items หน้า 1) — ใช้ทดสอบ HIGHLIGHT ได้

⚠️ ไฟล์คดีทั้งสองเป็นภาพสแกนทุกหน้า (ตรวจแล้ว: 0 หน้ามี /Font) → ใช้ทดสอบ DRAW / COMMENT / BOOKMARK / Page Virtualization (ไฟล์ 44 หน้า 38 MB เหมาะกับทดสอบ virtualization มาก) แต่ทดสอบ HIGHLIGHT ไม่ได้ เพราะ pdfjs สร้าง TextLayer ไม่ได้เมื่อไม่มี text

สถานะ (2026-09-08): มี text-based PDF แล้ว — dashboard-report-2026-09-03.pdf (เพิ่มโดยผู้ใช้) ใช้ทดสอบ HIGHLIGHT ได้ ปัญหาเดิมเกี่ยวกับการหาไฟล์ text-based ยุติแล้ว

---

1. System Architecture — Multi-Layer Non-Destructive Overlay

หนึ่งหน้า PDF = หนึ่ง <div data-page="N"> ที่ซ้อน layer ทั้งหมดไว้ใน viewport เดียวกัน ไฟล์ PDF ต้นฉบับไม่ถูกแก้ไข (Non-Destructive) — annotation เก็บใน PostgreSQL เป็นพิกัด % เท่านั้น

┌─ div.relative[data-page=N] (ขนาด = viewport.width × viewport.height)
│
├── z-1  <canvas>                     ← pdfjs page.render()        | pointer-events: none เสมอ
├── z-2  div.highlight-layer          ← วาด rects จาก HIGHLIGHT %  | pointer-events: none เสมอ
│       (mix-blend-mode: multiply)
├── z-2  div.textLayer                ← pdfjs TextLayer (span โปร่งใส) | pointer-events: สลับตาม tool
├── z-3  <svg> InkLayer               ← freehand DRAW + live stroke | pointer-events: สลับตาม tool
└── z-4  div.comment-pins             ← Sticky note pin COMMENT     | pointer-events: auto (ยกเว้นตอน draw)

ตารางสลับ pointer-events ตาม Tool

Tool	Base (canvas)	TextLayer (z-2)	InkLayer (z-3)	Pins (z-4)	พฤติกรรม
select (ค่าเริ่มต้น)	none	auto	none	auto	คลุมดำข้อความได้ → เด้ง Floating Toolbar → Highlight
draw	none	none	auto	none	เมาส์วาดเส้นอิสระ (pointer capture)
comment	none	auto*	none	auto	คลิกจุดบนหน้า → เปิด composer → บันทึก COMMENT
shape (PLAN-FEAT.md F5)	none	none	auto	none	ลากคลุมวาดรูปทรง rect/ellipse/line/arrow บน InkLayer (เหมือน draw)
erase (PLAN-FEAT.md F6)	none	none	auto	none	ลากผ่านเส้น/รูปทรงของตัวเองบน InkLayer → hit-test โดน = ลบทันที (comment/highlight ไม่เกี่ยว)

* โหมด comment ให้ TextLayer ยัง select ได้ ส่วนการคลิกวาง pin จับ event ที่ page wrapper (bubble ขึ้นจาก layer ล่าง)

จุดสำคัญ: กฎ z-index 2 ตัว (highlight-layer กับ textLayer) ไม่ทับกันเพราะ DOM order กำหนด — textLayer อยู่ทีหลัง = อยู่บนสุดของ z-2 → ข้อความ select ได้และ highlight ซ้อนหลัง text เสมอ (text เป็นสีโปร่งใสอยู่แล้ว)

---

2. Coordinate System — Relative Percent (%)

• ทุกพิกัดใน JSONB (rects, paths, position) เป็น % ของขนาดหน้า PDF ณ scale ปัจจุบัน ณ ตอนวาด → นำไป render ที่ zoom/จอเล็กจอใหญ่ได้ไม่เบี้ยว
• strokeWidth ของ DRAW เก็บเป็น % ของความกว้างหน้า (เช่น 0.4 = 0.4% ของ width) → แปลงกลับเป็น px ตอน render
• yOffset ของ bookmark เก็บเป็น % ของความสูงหน้า (0–100)

กลไกแปลง (utils/coordinates.ts)

Pixel (event/getBoundingClientRect)  ──÷size×100──▶  Percent (เก็บลง DB)
Percent (จาก DB)  ──×size÷100──▶  Pixel (render ลง SVG/div)

เหตุผลที่ InkLayer ใช้ SVG แบบไม่มี viewBox

กลเล่น viewBox="0 0 100 100" preserveAspectRatio="none" จะทำให้ ความหนาเส้นบิดเบี้ยว (scale แกน x,y ไม่เท่ากัน) → จึง render ในระบบ px จริง: แปลง % → px ด้วยขนาดที่วัดจาก ResizeObserver แล้ววาด <path> ตรง ๆ (ไม่ต้องใช้ vector-effect)

---

3. Database Schema (Drizzle ORM + PostgreSQL)

ไฟล์ db/schema.ts

ตาราง files

column	type	หมายเหตุ
id	uuid PK defaultRandom()
title	text NOT NULL
description	text	nullable
pdf_url	text NOT NULL
created_at	timestamptz defaultNow()

Enum annotation_type = 'HIGHLIGHT' | 'DRAW' | 'COMMENT'

ตาราง annotations

column	type	หมายเหตุ
id	uuid PK
file_id	uuid FK → files ON DELETE CASCADE
page_index	integer NOT NULL	0-based
user_id	text NOT NULL	anonymous id จาก localStorage
user_name	text NOT NULL
type	annotation_type NOT NULL
data	jsonb NOT NULL $type<AnnotationData>()	strict typed union (ด้านล่าง)
created_at / updated_at	timestamptz

Index: (file_id, page_index) สำหรับ query หลักตอนเปิด viewer

ตาราง bookmarks

column	type	หมายเหตุ
id	uuid PK
file_id	uuid FK → files CASCADE
page_index	integer NOT NULL
user_id	text NOT NULL
title	text NOT NULL
y_offset	double precision NOT NULL	% ของความสูงหน้า (0–100)
created_at	timestamptz

Strict JSONB Union (export เป็น TypeScript types)

type Rect = { x: number; y: number; width: number; height: number };   // ทุกค่าเป็น %
type HighlightData = { text: string; color: string; rects: Rect[] };
type DrawData     = { strokeColor: string; strokeWidth: number; paths: { x: number; y: number }[] }; // % + strokeWidth เป็น % ของ width
type CommentData  = { position: { x: number; y: number }; message: string };  // %
type AnnotationData = HighlightData | DrawData | CommentData;   // เลือกตาม column `type` (discriminated โดย enum)

→ พร้อม DTO types (AnnotationDTO, BookmarkDTO) ที่ timestamp เป็น ISO string เพื่อให้ server → client → realtime payload ใช้ type เดียวกัน

---

4. Data Flow & Realtime Sync

Client A วาด ──▶ Server Action createAnnotation() ──▶ INSERT PostgreSQL
                        │ (เขียนสำเร็จ)
                        ▼
              publish ใน process (lib/annotate-events.ts)
                        │
                        ▼
        SSE /api/annotations/stream?fileId=<uuid> ──▶ Client B ได้ event ทันที

• เขียน: ผ่าน Server Actions เท่านั้น (ต่อ DATABASE_URL ตรง ๆ) — และหลังเขียนสำเร็จทุกครั้ง ต้อง publish event ให้ lib/annotate-events.ts
• อ่าน/ sync: useAnnotationRealtime hook เปิด EventSource ไปที่ SSE route /api/annotations/stream?fileId=<id> — payload เป็น DTO (camelCase + ISO string) จาก server ตรง ๆ ไม่ต้องแปลง; EventSource ต่อใหม่อัตโนมัติเมื่อ connection ขาด (ห้ามทำ retry เอง)
• pub/sub เป็น in-memory ของ Next.js process เดียว (dev / next start ธรรมดา) — หากอนาคตรันหลาย instance ต้องเพิ่มตัวกลาง (Redis pub/sub หรือ Postgres LISTEN/NOTIFY) ก่อน
• Optimistic update ด้วย useOptimistic (React 18): ตอนผู้ใช้ปล่อยเมาส์ → startTransition(() => { addOptimistic(row ชั่วคราว); return createAnnotation(...) }) → React ถอด optimistic row ออกอัตโนมัติเมื่อ action เสร็จ และ rollback ให้เองหาก action ล้มเหลว (ไม่ต้องจัดการ id temp-* เอง) → หาก SSE event มาถึงก่อน action เสร็จ จะเห็น duplicate ชั่วขณะแล้วหายเองเมื่อ optimistic row ถูกถอด (self-healing) — hook ยัง dedupe ด้วย id กับ state ปัจจุบันอยู่

---

5. โครงสร้างไฟล์ทั้งหมด

judes-note/
├── PLAN.md                          ← ไฟล์นี้
├── README.md                        ← วิธี setup (docker run postgres, env, drizzle push, seed, run)
├── package.json / tsconfig.json / next.config.mjs
├── tailwind.config.ts / postcss.config.js / drizzle.config.ts
├── .env.example
├── db/
│   ├── schema.ts                    ← ตาราง + Strict JSONB types + DTO types + mapper toDTO
│   └── index.ts                     ← postgres.js client + drizzle (DATABASE_URL → container judes-note-db, prepare:false)
├── lib/
│   └── annotate-events.ts           ← pub/sub in-process (Server Actions publish → SSE route subscribe)
├── utils/
│   ├── coordinates.ts               ← pixel⇄% (point/rect/path) + getPointerPercent + clamp + mergeRectsByLine (รวบ rects บรรทัดเดียวกันเหลือ 1 rect/บรรทัดก่อนบันทึก)
│   └── user.ts                      ← anonymous user identity (localStorage)
├── hooks/
│   └── useAnnotationRealtime.ts     ← EventSource ต่อ SSE stream + dedupe + expose setters
├── app/
│   ├── layout.tsx / globals.css     ← globals.css มี CSS ของ .textLayer ที่ pdfjs ต้องการ
│   ├── page.tsx                     ← รายการไฟล์ (server component, drizzle query)
│   ├── actions/annotations.ts       ← Server Actions: CRUD annotations + bookmarks (+ validation guards
│   │                                  + publish event หลังเขียนสำเร็จทุกครั้ง)
│   ├── api/annotations/stream/route.ts  ← SSE endpoint (GET ?fileId=) ยิง event จาก lib/annotate-events
│   └── annotate/[id]/page.tsx       ← โหลด file + initial data → ส่งเข้า <PDFViewer/>
├── components/
│   ├── pdf/
│   │   ├── PDFViewer.tsx            ← client root: โหลดเอกสาร, tool state, zoom, selection→highlight,
│   │   │                               bookmark, comment composer, sidebar layout, Page Virtualization
│   │   │                               (IntersectionObserver render เฉพาะหน้าใน viewport ± 1 หน้า)
│   │   ├── InkLayer.tsx             ← SVG freehand (pointer capture, live stroke, ResizeObserver re-render)
│   │   └── HighlightToolbar.tsx     ← Floating popup เลือกสี (fixed ตำแหน่งจาก selection rect)
│   └── sidebar/
│       └── AnnotationSidebar.tsx    ← แท็บ Bookmarks / Annotations + ปุ่ม scroll-to + ลบรายการตัวเอง

---

6. พฤติกรรมหลักของแต่ละ Feature

6.1 Text Selection → Highlight

1. Tool select → คลุมดำบน TextLayer (span โปร่งใส + ::selection)
2. mouseup → window.getSelection() → range.getClientRects() → กรอง rect กว้าง 0 → mergeRectsByLine: รวบ rects ที่ y/height ใกล้กัน (บรรทัดเดียวกัน) เหลือ 1 rect ต่อบรรทัด กัน JSONB บวม → แปลงเป็น % เทียบ pageEl.getBoundingClientRect()
3. เด้ง HighlightToolbar (position: fixed ที่มุม rect แรก) เลือกสี 5 สี
4. กดสี → createAnnotation('HIGHLIGHT', { text, color, rects }) + optimistic
5. Render: div สีทึบนิดหน่อย + mix-blend-mode: multiply ที่ z-2 (อยู่หลัง text เสมอ)

6.2 Freehand Drawing (InkLayer)

1. Tool draw → svg รับ pointerdown → setPointerCapture (เส้นไม่ขาดเวลาเลื่อนออกนอก page)
2. เก็บจุดทั้ง px (render) และ % (save) — สร้าง path M x y L ...
3. pointerup → ถ้าจุด ≥ 2 → createAnnotation('DRAW', { strokeColor, strokeWidth, paths })
4. Path เดิมจาก DB แปลง % → px ด้วยขนาดที่ ResizeObserver วัด → re-render เมื่อ resize/zoom

6.3 Comment (Sticky Note)

1. Tool comment → คลิกตำแหน่งบนหน้า → เปิด composer เล็ก ๆ (fixed) ใส่ข้อความ
2. บันทึก → วาด pin (icon MessageSquare) ที่ตำแหน่ง % → คลิก pin เพื่อดู popover (ข้อความ + ผู้เขียน + เวลา)

6.4 Bookmark

1. ปุ่ม BookmarkPlus บน toolbar → หา "หน้าปัจจุบัน" (page ที่ midpoint ใกล้ viewport center สุด จาก scroll listener)
2. yOffset = ตำแหน่งกึ่งกลาง viewport เทียบหน้านั้น (% ของความสูงหน้า)
3. Sidebar คลิก bookmark → window.scrollTo (smooth) ไปที่ pageTop + pageHeight × yOffset% (คำนวณ absolute ก่อนแล้ว smooth-scroll ครั้งเดียว ไม่ scroll ซ้อนสองจังหวะ)

---

7. ลำดับการ Implement (ตาม Task Output Order) + เกณฑ์ตรวจ

#	งาน	ไฟล์	Verify
1	Scaffolding + Schema	package.json, config ทั้งหมด, db/schema.ts, db/index.ts	tsc ผ่าน, drizzle-kit push สร้างตารางได้
2	Coordinate helpers	utils/coordinates.ts, utils/user.ts	Unit เช็คตาโค้ด: 1000px → 50% ที่ width 2000 (round-trip ต้องได้ค่าเดิม ± ε); mergeRectsByLine รวม rects หลายอันบรรทัดเดียวกัน → เหลือ 1 rect ครอบข้อความเดิม
3	Server Actions	app/actions/annotations.ts	เรียก action สร้าง/ลบ annotation แล้ว row ใน DB เปลี่ยนตาม; input ผิด type โดน reject
4	Realtime hook	hooks/useAnnotationRealtime.ts	เปิด 2 browser แท็บ — แท็บ A highlight แล้วแท็บ B เห็นภายใน ~1s โดยไม่ refresh
5	UI หลัก	globals.css, layout.tsx, page.tsx, annotate/[id]/page.tsx, PDFViewer.tsx, InkLayer.tsx, HighlightToolbar.tsx, AnnotationSidebar.tsx	คลุมดำ→toolbar→สีติดหน้า / วาดเส้นลื่น ไม่เบี้ยวตอน zoom / bookmark กดแล้ว scroll ลื่น / pin comment แสดงถูกตำแหน่ง / PDF ยาว 100 หน้า เลื่อนลื่น (canvas ของหน้าที่พ้นจอถูก unmount)
6	README	README.md	ทำตามขั้นตอนจากศูนย์แล้วรัน npm run dev ได้

---

8. Edge Cases ที่ออกแบบไว้ล่วงหน้า

• TextLayer ต้อง re-render ทุกครั้งที่ zoom (scale เปลี่ยน = viewport เปลี่ยน) → effect dep [doc, pageNumber, scale] + cancel render task ตอน unmount กัน memory leak
• Canvas คมชัดบนจอ Retina → canvas.width × devicePixelRatio + transform: [dpr,0,0,dpr,0,0] แต่ style.width คง viewport px
• Selection ข้ามหน้า → ยอมรับเฉพาะ rects ใน page เดียว (หา page จาก commonAncestorContainer.closest('[data-page]')) — สเปกเก็บ pageIndex ค่าเดียวต่อ annotation
• SSE event ชน optimistic row → duplicate ชั่วขณะหายเองเมื่อ useOptimistic ถอด row + dedupe ด้วย id ใน hook (ดู §4)
• Server component ส่ง Date ไม่ได้ตรง ๆ กับ realtime string → normalize เป็น ISO string DTO ทั้งระบบ
• pdfjs บน SSR → dynamic import("pdfjs-dist") ภายใน useEffect เท่านั้น (ไม่ import top-level ใน module scope ที่ server evaluate ด้วย)
• PDF ยาว (20–100+ หน้า): Page Virtualization → IntersectionObserver ใน PDFViewer render เฉพาะหน้าใน viewport ± 1 หน้า (canvas + TextLayer + InkLayer); หน้าที่พ้นจอเก็บเป็น placeholder div ขนาดจริง (วัดจาก pdfPage.getViewport() ทุกหน้าตอนโหลดครั้งเดียว — cost ถูก) เพื่อไม่ให้ scroll jump และให้ bookmark ยังคำนวณ absolute scroll ได้ แล้ว unmount layer ทั้งหมดของหน้านั้นคืน memory — annotation ของหน้าที่ยังไม่ render อยู่ใน state ตามปกติ จะแสดงเมื่อหน้าเข้าจอ
• pdf.worker v4 เป็นไฟล์ .mjs → คัดลอก pdf.worker.min.mjs จาก node_modules/pdfjs-dist/build/ ไป public/ ด้วย postinstall script (version ตรงกับ lockfile เสมอ) และตั้ง pdfjs.GlobalWorkerOptions.workerSrc = "/pdf.worker.min.mjs" — อย่าใช้ new URL(..., import.meta.url) ซึ่งมักชน Turbopack/webpack ใน Next 14

---

9. ขอบเขตที่ ไม่ ทำในเฟสนี้ (Out of Scope)

• ระบบ login/roles (ใช้ anonymous identity)
• แก้ไข/ย้าย annotation ที่วาดแล้ว (มีเฉพาะสร้าง + ลบ) — ข้อนี้ถูกขยายโดย docs/PLAN-FEAT.md F1: อนุญาตแก้ไข data (ย้าย/ปรับขนาด/เปลี่ยนสี–ความหนา) ของตัวเอง ในหน้าเดียวกัน ผ่าน updateAnnotation
• Undo/redo, export PDF ที่ฝัง annotation
• แสดงรายชื่อ "ใครออนไลน์อยู่" (presence)

หากต้องการเพิ่มข้อใด กรุณาบอกก่อนเริ่ม implement