eCourt-note/README.md

Judge's Note — PDF Annotation สำหรับ e-Court

ระบบ annotate ไฟล์ PDF คดีบนเว็บ แบบ Non-Destructive — ไฟล์ PDF ต้นฉบับไม่ถูกแก้ไขเด็ดขาด annotation ทั้งหมด (highlight / เส้นวาด / comment / bookmark) เก็บใน PostgreSQL เป็นพิกัด % ของขนาดหน้า แล้วซิงก์ระหว่างทุก browser แบบ realtime ผ่าน SSE (Server-Sent Events)

สร้างด้วย Next.js 14 (App Router) + TypeScript strict + pdfjs-dist v4 + Drizzle ORM + PostgreSQL (Docker container เดียว)

ฟีเจอร์

• Highlight — คลุมดำข้อความ เลือกสีจาก floating toolbar (5 สี) วาดซ้อนหลังข้อความด้วย mix-blend-mode: multiply
• Freehand draw — วาดเส้นอิสระบน SVG layer ความหนาสัมพัทธ์กับขนาดหน้า ไม่เบี้ยวเวลา zoom
• Sticky note comment — คลิกวาง pin บนหน้า พร้อม popover ข้อความ/ผู้เขียน/เวลา
• Bookmark — จดตำแหน่ง (หน้า + % ความสูง) กดแล้ว smooth-scroll กลับตำแหน่งเดิม
• Realtime sync — เปิด 2 แท็บ วาดในแท็บ A แท็บ B เห็นทันทีผ่าน SSE (EventSource ต่อใหม่อัตโนมัติเมื่อขาด)
• Page Virtualization — render เฉพาะหน้าใน viewport ± 1 หน้า ไฟล์หลายสิบหน้าเลื่อนลื่น
• หน้า login (mock e-Court — dropdown user1–user5 รหัสผ่านกลาง Demo1234) — identity จาก cookie oacCase บังคับทุกหน้า (ปุ่มลบ/แก้ไขแสดงเฉพาะรายการของตัวเอง)

สิ่งที่ต้องมี (Prerequisites)

เครื่องมือ	เวอร์ชันที่ใช้พัฒนา/ทดสอบ	หมายเหตุ
Node.js	v24.3.0	≥ 20 น่าจะใช้ได้
Docker	29.1.3	ใช้รัน PostgreSQL + MinIO ผ่าน docker-compose.yml

ขั้นตอน Setup จากศูนย์

1. ติดตั้ง dependencies

npm install

postinstall จะคัดลอก pdf.worker.min.mjs จาก node_modules/pdfjs-dist/build/ มาไว้ที่ public/ ให้อัตโนมัติ

2. รัน PostgreSQL + MinIO ด้วย docker compose

docker compose up -d

• db = PostgreSQL (judes-note-db พอร์ต 54322, database ecourt-note สร้างตอน first init) — ใช้ชื่อ container/วอลุ่มเดียวกับคำสั่ง docker run เดิม: ถ้ามี container เก่าจาก docker run อยู่ ให้ docker rm -f judes-note-db ก่อน (วอลุ่ม judes-note-db-data เดิม ข้อมูลไม่หาย — ถ้าวอลุ่มเดิม init ด้วย database postgres ให้สร้าง ecourt-note เอง: docker exec judes-note-db psql -U postgres -c 'CREATE DATABASE "ecourt-note"') · จะรันแค่ MinIO ก็ได้ด้วย docker compose up -d minio
• minio = object storage ของ API เอกสาร versioning (judes-note-minio — API ที่ พอร์ตโฮสต์ 19000, console ดูผ่าน browser ที่ http://localhost:19001; ข้างใน container ยังเป็น 9000/9001 — host เลี่ยงมา 19000/19001 เพราะ 9000/9001 มักชนกับ service อื่นในเครื่อง dev; image ดึงจาก quay.io/minio/minio ซึ่งเป็น registry ทางการของ MinIO) — bucket ไม่ต้องสร้างเอง app สร้างตอน first use

ครั้งต่อไปแค่ docker compose start — ข้อมูลอยู่ใน volume judes-note-db-data/judes-note-minio-data ไม่หาย

3. สร้างไฟล์ .env

DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/ecourt-note
# N10 (optional): API key ของ /api/note/external/* สำหรับ backend e-Court เรียกแบบ server-to-server
# ไม่ตั้งหรือเว้นว่าง = API ปฏิเสธทุก request (fail closed) — ตั้งค่ายาวและสุ่ม เช่น 32+ ตัวอักษร
# EXTERNAL_API_KEY=
# MinIO ของ API เอกสาร versioning (ค่าตรง docker-compose.yml — ไม่ต้องแก้ถ้ารันตามขั้นตอน 2)
MINIO_ENDPOINT=127.0.0.1
MINIO_PORT=19000
MINIO_USE_SSL=false
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin

(เทียบกับ .env.example)

4. สร้างตารางในฐานข้อมูล

npx drizzle-kit push

5. Seed ไฟล์ตัวอย่าง

ไฟล์ตัวอย่างอยู่ที่ public/note/samples/ แล้ว — sync ลงตาราง files (idempotent รันซ้ำได้) — รองรับทั้ง .pdf และรูปภาพ .jpg/.jpeg/.png/.tif/.tiff (N3):

npm run seed-samples

บน production ไม่ต้องรันมือ — script เดียวกัน (scripts/seed-samples.mjs) รันอัตโนมัติตอน container start ต่อจาก migration ไฟล์ที่หายจาก public/note/samples/ จะถูกลบ row พร้อม annotation ที่ผูกอยู่ (CASCADE)

6. รัน dev server

npm run dev

เปิด http://localhost:3000/docedit/note — หน้าแรก (landing) · ผู้ใช้จริงเข้าผ่านลิงก์เปิดเอกสารของ e-Court (dev mint ลิงก์ทดสอบเองด้วย node scripts/make-login-link.mjs — ดู docs/PLAN-SSO.md) ส่วนเครื่องมือทดสอบ (เปิดเอกสารตัวอย่าง + คู่มือทางเข้า SSO + ฟอร์ม mint ลิงก์) อยู่ที่ http://localhost:3000/docedit/note/dev

การใช้งานบนหน้า annotate

ปุ่ม	พฤติกรรม
ลูกศร (select)	คลุมดำข้อความ → เด้ง toolbar เลือกสี → ติด highlight บนหน้า
ดินสอ (draw)	ลากเมาส์วาดเส้นอิสระ (ปล่อย = บันทึก)
ลูกศร+กล่องแชท (comment)	คลิกจุดบนหน้า → พิมพ์ข้อความ → บันทึก pin
bookmark+	เพิ่ม bookmark ที่ตำแหน่งกึ่งกลางจอปัจจุบัน
zoom − / +	สเกล 50%–300% (annotation ทั้งหมด scale ตามเพราะเก็บเป็น %)

Sidebar ซ้าย: แท็บ Bookmarks / Annotations — คลิกรายการเพื่อเลื่อนกลับไปตำแหน่งนั้น และมีปุ่มลบเฉพาะรายการของตัวเอง (identity จากหน้า login)

ทดสอบ realtime: เปิดหน้า annotate ไฟล์เดียวกันใน 2 แท็บ แล้ววาด/comment จากแท็บหนึ่ง — อีกแท็บเห็นทันทีโดยไม่ต้อง refresh

API สำหรับระบบภายนอก (N10)

Read-only API ให้ backend ของ e-Court เรียกแบบ server-to-server (ไม่มีหน้า UI) — endpoint เดียว POST /api/note/external/documents (JSON body) ตรวจสิทธิ์ด้วย API Key เดียวใน env EXTERNAL_API_KEY ส่งผ่าน header x-api-key (env ไม่ตั้ง/ว่าง = ปฏิเสธทุก request — fail closed) — คู่มือการใช้สำหรับผู้เรียก: docs/API-DOCUMENTS.md · สเปก/เหตุผลการออกแบบ: docs/PLAN-API.md

// POST /docedit/api/note/external/documents   (URL เต็มฝั่งผู้เรียกอยู่ใต้ basePath)
// headers: x-api-key + content-type: application/json
{
  "fileId": "<fileId ของ e-Court>",     // ถามเอกสารเดียว — ส่งพร้อม typeId ได้ = กรองเฉพาะเอกสารที่ตรงทั้งสองเงื่อนไข (AND)
  "typeId": "<typeId>",                 // ถามทุกเอกสารในกลุ่ม N9 — กลุ่มว่าง = 200 documents: []
  "filter": {
    "type": "bookmarks",                // optional: "bookmarks" | "annotations" — ไม่ส่ง (หรือ type เป็น "") = ทั้งสอง
    "userId": "<userId>",               // optional: string หรือ array — กรองตามเจ้าของรายการ (ทั้ง annotations/bookmarks)
    "annotationTypes": ["COMMENT"],     // optional: ค่าจาก HIGHLIGHT|DRAW|COMMENT|SHAPE|REDACTION|TEXTBOX|STAMP — เฉพาะ annotations
  }
}

• Response 200 เป็นรูปเดียวเสมอ: { "documents": [ { "id", "externalFileId", "title", "typeId", "createdAt", "annotations": [… พร้อม url + replies], "bookmarks": [… พร้อม url] } ] } (field เอกสารอยู่ระดับเดียวกับ annotations/bookmarks) — ถามด้วย fileId ได้ array ยาว 1 ชิ้น (ไม่เคยเปิดในระบบ = 404)
• url ต่อรายการ = deep link กลับมาหน้า viewer เป็น URL เต็มพร้อมใช้ทันที (http://<host>/docedit/note/annotate/<fileId>?ann=<id> สำหรับ annotation · ?page=<หน้า 1-based> สำหรับ bookmark) — origin อ่านจาก request ที่เรียกเข้ามา (ผ่าน reverse proxy ต้องตั้งส่งต่อ x-forwarded-proto/x-forwarded-host)
• error ทุกสถานะ (400/401/404/500) เป็น JSON { "error": "<ข้อความไทย>" } รูปเดียวกันทั้ง endpoint — 500 เกิดเมื่อ query ฐานข้อมูลล้ม (log รายละเอียดฝั่ง server อย่างเดียว)
• ตัวอย่าง:

curl -X POST -H "x-api-key: $EXTERNAL_API_KEY" -H "content-type: application/json" \
  -d '{"fileId":"1234","filter":{"type":"bookmarks"}}' \
  "http://localhost:3000/docedit/api/note/external/documents"

curl -X POST -H "x-api-key: $EXTERNAL_API_KEY" -H "content-type: application/json" \
  -d '{"typeId":"CASE-2569-0001"}' \
  "http://localhost:3000/docedit/api/note/external/documents"

API จัด version เอกสาร (docver — stand-alone)

กลุ่ม API ให้ Word add-in / ระบบภายนอก เก็บเอกสารเป็น version: เอกสารเดียวต่อ docId (unique) แต่ละ version เก็บไฟล์ .docx + .pdf ใน MinIO พร้อม userId/userName/createdAt ของผู้อัปโหลด — ไม่มี auth ไม่มี session (stand-alone): ผู้เรียกบอก identity เองผ่าน field userId/userName ของ multipart · contract ตรง mock ของ wordaddin (versioningService) เป๊ะเพื่อวันสลับของจริง · สเปก/เหตุผล: docs/PLAN-DOCVER.md

# POST อัปโหลด version (เอกสารถูกสร้างแบบ implicit เมื่อเป็น version แรก)
curl -F "file=@คำสั่งเรียก.docx" -F "pdf=@คำสั่งเรียก.pdf" \
  -F "userId=u0001" -F "userName=ผู้พิพากษา ก." \
  "http://localhost:3000/docedit/api/documents/CASE-2569-0001/versions"
# → {"hasPdf":true,"versionId":"<uuid>","versionNumber":1}   (versionNumber เป็นค่าจาก server)

# GET history (ใหม่ → เก่า) — docId ที่ยังไม่เคยมี version = 404
curl "http://localhost:3000/docedit/api/documents/CASE-2569-0001/versions"

# GET presigned URL อายุสั้น (default docx, ?format=pdf — version ไม่มี pdf = 404)
curl "http://localhost:3000/docedit/api/documents/CASE-2569-0001/versions/<versionId>/download-link?format=pdf"

• ไฟล์แนบ file (.docx) บังคับ · pdf optional (add-in แนบ blob เปล่าได้ = ถือว่าไม่มี ดู hasPdf) · ทั้งคู่ ≤ 100MB + ตรวจ magic bytes · field นอก allowlist = 400 กัน typo เงียบ ๆ
• error ทุกสถานะเป็น JSON { "error": "<ข้อความไทย>" } — 400 (รูปผิด/ไม่ใช่ multipart/เนื้อไฟล์เพี้ยน) · 413 (เกิน 100MB) · 404 (ไม่มีเอกสาร/version/pdf) · 500 (MinIO env ไม่ตั้ง/ล้ม, DB ล้ม — log เต็มฝั่ง server)
• presigned URL อ้าง MINIO_ENDPOINT:MINIO_PORT ตรง ๆ — production ต้องเป็นโฮสต์ที่เบราว์เซอร์ของผู้ใช้เข้าถึงได้ ไม่ใช่แค่ที่ Next server เข้าถึงได้

Troubleshooting

อาการ	สาเหตุ/ทางแก้
Realtime ไม่ซิงก์	sync ใช้ pub/sub in-memory ของ process เดียว — ทุกแท็บต้องเข้าผ่าน dev server เดียวกัน (ถ้าวันหนึ่งรันหลาย instance ต้องเพิ่ม Redis pub/sub หรือ Postgres LISTEN/NOTIFY ก่อน)
หน้าเว็บ 500 หลังรัน next build ระหว่างที่ dev server กำลังรัน	build เขียนทับ cache ของ dev — ปิด dev server ก่อน build หรือ restart dev server หลัง build
tsc --noEmit error ชี้ route ที่ถูกลบไปแล้ว (เช่น app/api/external/document* หลังรวมเป็น query รอบสองของ N10)	type stub ค้างใน .next/types/ ของ dev/build รอบก่อน — ลบ .next หรือรัน next build/restart dev server หนึ่งครั้งให้ regenerate แล้วรันใหม่
ต่อ DB ไม่ได้	ตรวจว่า container รันอยู่ (docker compose start db — เดิม docker start judes-note-db) และพอร์ต 54322 ไม่ถูกใช้โดย container อื่น
API เอกสาร versioning ตอบ 500 ทุก call	ตรวจ env MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY และ container minio (docker compose start minio) — รายละเอียดอยู่ใน log ฝั่ง server
Highlight ใช้ไม่ได้กับไฟล์คดีตัวอย่าง	ไฟล์ 01012-*.pdf ทั้งสองเป็นภาพสแกนล้วน (ไม่มี text layer) — ใช้ dashboard-report-2026-09-03.pdf ซึ่งเป็น text-based PDF แทน จึงจะคลุมดำได้ (DRAW/COMMENT/BOOKMARK ใช้ได้ปกติกับทุกไฟล์)

หมายเหตุทางเทคนิค

• Realtime = SSE + pub/sub in-process: Server Actions (app/actions/annotations.ts) publish event หลังเขียน DB สำเร็จทุกครั้ง → lib/annotate-events.ts → SSE endpoint app/api/note/annotations/stream → hook เปิด EventSource รับ event (payload เป็น DTO จาก server ตรง ๆ)
• UI ใช้ useOptimistic ที่มาจาก React canary build ซึ่ง Next.js 14 vendored ไว้ให้ — หากหยิบ component ไปรันนอก Next bundling (เช่น unit test ด้วย react เปล่า) จะหา export นี้ไม่เจอ
• พิกัด annotation ทุกชนิดเก็บเป็น % ของขนาดหน้า → render ถูกต้องทุก zoom/ขนาดจอ และ mergeRectsByLine รวบ rect ให้เหลือ 1 อันต่อบรรทัดก่อนบันทึก highlight
• สถาปัตยกรรม/สเปกฉบับเต็ม: docs/PLAN.md · กติกาที่ต้องรักษาตอนแก้โค้ด: CLAUDE.md · ฟีเจอร์ต่อยอด: docs/PLAN-FEAT.md

โครงสร้างหลัก

db/schema.ts              ตาราง + JSONB strict union + DTO + toDTO
db/index.ts               postgres.js + drizzle (prepare: false)
lib/annotate-events.ts    pub/sub in-process (actions → SSE route)
lib/document-versioning.ts  validation ล้วนของกลุ่ม /api/documents (docver)
lib/docver-store.ts       MinIO client + tx จ่ายเลข version + query ของ docver
utils/coordinates.ts      px ⇄ % + clamp + mergeRectsByLine
utils/user.ts             parse/build cookie oacCase (mock login e-Court)
hooks/useAnnotationRealtime.ts   EventSource รับ SSE event + dedupe ด้วย id
app/actions/annotations.ts       Server Actions CRUD + publish event (ทางเขียนทางเดียว)
app/api/note/annotations/stream/route.ts  SSE endpoint (GET ?fileId=)
app/api/documents/            API จัด version เอกสาร (token + versions + download-link)
app/note/page.tsx              หน้าแรก landing (วิธีเข้าใช้ + ลิงก์ไปหน้าเครื่องมือทดสอบ)
app/note/dev/page.tsx          เครื่องมือทดสอบ: เปิดเอกสารตัวอย่าง + คู่มือ SSO + mint ลิงก์
app/note/annotate/[id]/page.tsx  โหลด file + initial data → PDFViewer
components/pdf/           PDFViewer (root + virtualization), InkLayer, HighlightToolbar
components/sidebar/       AnnotationSidebar
public/note/samples/      ไฟล์ตัวอย่าง (PDF + รูปภาพ) — seed ด้วย npm run seed-samples
public/note/uploads/      ไฟล์อัปโหลดสมัย N4 (ฟอร์มถอดแล้ว — เหลือแค่ route เสิร์ฟไฟล์เก่า)