Merge branch 'forgejo-dev' into working

Resolve CLAUDE.md: คำอธิบาย lib/document-versioning.ts เอาของ
forgejo-dev (field `fields` ถอดออก 2026-10-30) ส่วน lib/docver-token.ts
เอาของ working (purpose login / verifyDocverLoginToken — โค้ดฝั่ง
forgejo-dev มีครบแล้ว แค่คำอธิบายล้าหลัง)

Verify: npx tsc --noEmit ผ่าน · vitest 23 files / 338 tests ผ่าน

Co-Authored-By: Claude Code <noreply@anthropic.com>

docs/PLAN-DOCVER.md

@@ -80,13 +80,23 @@ multipart/form-data:
 | `file` | File (.docx) | บังคับ — ≤ 100MB, magic bytes `PK\x03\x04` |
 | `pdf` | File (.pdf) | optional — `size === 0` = ถือว่าไม่มี (add-in แนบ blob เปล่าได้) |
 | `clientVersionId` | string | optional ≤100 — GUID ที่ client generate เอง |
-| `fields` | string (JSON) | optional — map `{ [sdtTag]: text }` จาก content controls ทุกชนิด (add-in ใช้ `Document.getContentControls()` บน WordApi 1.5+; host ต่ำกว่าเห็นเฉพาะ rich text — ดู `docs/addin-ui-flow.md` §9 ข้อ 7) (≤1,000 keys · **ความยาวค่าไม่จำกัด** 2026-10-27 ตามคำขอผู้ใช้ — เอกสาร 100–200 หน้า; jsonb รับได้ถึง 255MB) |
 | `message` | string | optional — commit message ≤2048 (trim ว่าง = NULL) |
 | `fileName` | string | optional — ชื่อไฟล์ดั้งเดิม (ผ่าน `decodeUploadFilename` แล้ว) |
 
 - field ที่ไม่อยู่ในตาราง = **400 กัน typo เงียบ ๆ** (pattern `parseQueryBody` ของ N10) —
   **breaking change 2026-10-22:** `userId`/`userName`/`templateId` ถอดออกจาก form แล้ว
   (ส่งมา = 400) identity/template มาจาก Bearer token ของ request นั้นแทน
+  · **breaking change 2026-10-30:** `fields` ถอดออกจาก form เช่นกัน (ส่งมา = 400) —
+  `fields` ของ version ถูกแกะจากไฟล์ .docx ที่อัปโหลด**ฝั่ง server** เก็บ**ทั้งก้อน
+  เหมือน return ของ `/api/template/extract` เลย** (`{cc, bookmark, properties, verify}`
+  ผ่าน `extractDocumentSnapshot` ของ `lib/lib-tmpl.ts` ตัวเดียวกับ route นั้น — route
+  extract เรียก helper ตัวเดียวกัน จึงตรงกันเป๊ะโดยการก่อสร้าง) · `verify.HmacSha256`
+  ตรวจด้วย secret ของ add-in ticket ฝั่ง server (env chain `ADDIN_TICKET_SECRET` →
+  `SECRET` → `"super_secret"` ของ `lib/addin-ticket.ts` — ต่างจาก extract ที่ใช้ secret
+  ของผู้เรียกเพื่อทดสอบ) · เห็น content control ทุกชนิดเสมอ ไม่ขึ้นกับเวอร์ชัน WordApi
+  ของ host แบบตอน add-in อ่านเองผ่าน Office.js · ไฟล์ที่แกะไม่ได้ (ไม่มี
+  `word/document.xml`/ZIP เสีย/`ticket_data` ไม่ใช่ JSON) = 400 · snapshot เก็บทุกครั้ง
+  ที่แกะสำเร็จ (NULL เหลือเฉพาะ row เก่าก่อน 2026-10-30 ที่เก็บ map ดิบ)
 - เอกสาร (`documents` row) สร้าง **แบบ implicit** ตอน upload version แรก — ไม่มี endpoint
   "สร้างเอกสาร" แยก (เอกสารถูกระบุที่ fid ใน token ตั้งแต่ขอ token)
 - response 200: `{ "hasPdf": boolean, "versionId": string, "versionNumber": number }`
@@ -106,7 +116,16 @@ response: `DocumentVersionDTO[]` เรียง **ใหม่ → เก่า
   createdByUserId: string;    // = user_id
   createdByUserName: string;  // = user_name (ส่วนเสริมนอก contract เดิม)
   contentHash: string;        // SHA-256 hex ของ docx (คำนวณฝั่ง server)
-  fields: Record<string, string> | null;
+  fields: {                  // ก้อนเดียวกับ return ของ /api/template/extract (2026-10-30)
+    cc: Record<string, string>;        // ค่า Content Control { [tag]: text }
+    bookmark: Record<string, string>;  // ข้อความใน bookmark { [name]: text }
+    properties: {                      // core/extended/custom props (Date → ISO string)
+      standard?: Record<string, string | undefined>;
+      extended?: Record<string, number | string | undefined>;
+      custom?: Record<string, string | number | boolean | null>;
+    };
+    verify: Record<string, unknown>;   // exp (ฟอร์แมตไทย) + HmacSha256 (secret ฝั่ง server)
+  } | null;                  // null = row เก่าก่อน 2026-10-30 (map ดิบ) หรือไม่มีเลย
   message: string | null;
   hasPdf: boolean;            // derive จาก pdf_object_key !== null ตัวเดียว
 }
@@ -127,15 +146,53 @@ response: `DocumentVersionDTO[]` เรียง **ใหม่ → เก่า
 - URL อ้าง `MINIO_ENDPOINT:MINIO_PORT` โดยตรง — **โฮสต์นี้ต้องเข้าถึงได้จากเบราว์เซอร์
   ของผู้ใช้** ไม่ใช่แค่จาก Next server (หมายเหตุนี้อยู่ใน `.env.example`/README ด้วย)
 
+### `GET /api/documents/latest?type=docx|pdf&ticket_data=<json>` — ไฟล์ version ล่าสุด (2026-10-31)
+
+ให้ backend e-Court ดึงไฟล์ **version ล่าสุด** กลับไปเปิดให้ผู้ใช้ (server-to-server —
+ไม่ใช่ Bearer: auth ด้วย `x-api-key` อย่างเดียว) · `docId` = ฟิลด์ `fid` **ใน ticket_data**
+ไม่ใช่ claim จาก token
+
+- auth: header `x-api-key` เทียบ env **`DOCVER_API_KEY` หรือ `EXTERNAL_API_KEY` ตัวใด
+  ตัวหนึ่ง** (ต่างจาก /token ที่รับ `DOCVER_API_KEY` อย่างเดียว — ผู้เรียกถือ key สาย N10
+  หรือสาย docver ก็ได้) · ทั้งคู่ไม่ตั้ง/ว่าง = 401 fail closed · ไม่ใส่/ผิด = 401 ข้อความ
+  เดียวกันเป๊ะ (timing-safe เหมือน `requireDocverApiKey`)
+- query (บังคับทั้งคู่):
+  - `type` = `docx` | `pdf` — **ไม่มี default** (ต่างจาก `format` ของ download-link)
+  - `ticket_data` = JSON string ของ ticket — **บังคับ `fid` + `uid` + `uname`** (`tid`
+    optional, `exp` ถ้าส่งต้องเป็นจำนวนเต็มแต่จะถูกเติมใหม่เสมอ) เพราะ
+    `parseDocverTicket` (`utils/docver-ticket.ts`) บังคับทั้งสามตอน add-in เอาไฟล์ไป
+    redeem ที่ /token ทาง ticket — validate ตั้งแต่รับเข้า กันคืนไฟล์ที่ add-in เปิด
+    ไม่ได้เงียบ ๆ · ⚠️ **หมายเหตุถึงฝั่ง e-Court:** `uid` ต้องเป็น*รหัส*ผู้ใช้ (ไม่ใช่
+    ชื่อ) และต้องส่ง `uname` (ชื่อแสดงผล) เช่น `{"fid":"DOC-2569-0001","uid":"123",
+    "uname":"สมชาย ใจดี"}`
+- **type=pdf** → คืนไบต์ pdf ของ version ล่าสุดตรง ๆ (`Content-Type: application/pdf`) ·
+  version ล่าสุดไม่มี pdf = 404 (ข้อความเดียวกับ download-link)
+- **type=docx** → ดึงไบต์ docx จาก MinIO มา **stamp ticket ใหม่บนสำเนาในหน่วยความจำ**
+  ก่อนคืน (`buildStampedTicketData` + `stampTicketProps` ของ `lib/lib-tmpl.ts` — recipe
+  เดียวกับ `applyTemplate` ของกลุ่ม template: เติม `exp = now + TICKET_SEC` → เรียง key
+  → `HmacSha256` ด้วย secret จาก `addinTicketSecret()` (chain `ADDIN_TICKET_SECRET` →
+  `SECRET` → `"super_secret"` — ตรงฝั่ง verify ของ add-in//token ทาง ticket เป๊ะ) →
+  `Ed25519` เฉพาะเมื่อ `PRIVATE_KEY_HEX` ตั้ง (ไม่ตั้ง = ไม่ใส่ prop — chain ของ add-in
+  verify แค่ HMAC) → `setCustomDocProps` upsert เขียนทับ stamp เดิมได้) —
+  **ไม่เขียนกลับ MinIO ตาม invariant #1** (non-destructive) · stamp ล้ม = 500
+  (ห้ามกลืนเหมือน `applyTemplate` — ไฟล์ไม่มี stamp = add-in เปิดไม่ได้)
+- ticket_data หลังเติม exp ยาวเกิน **255 ตัวอักษร = 400** (Word ตัดทอนค่า custom
+  property ที่ 255 — คืนไฟล์ที่โดนตัด = HMAC เสียเงียบ ๆ)
+- response 200: ไบต์ไฟล์ + `Content-Type` ตามชนิด + `Content-Disposition` จาก
+  `fileName` ของ version (`contentDispositionValue`) + `Cache-Control: no-store`
+  · เช็ค magic bytes ของไบต์ที่อ่านได้ ไม่ตรง = 500 (ความผิดปกติของพื้นที่เก็บ
+  ไม่ใช่ความผิดของผู้เรียก)
+
 ### ตาราง error
 
 | เหตุ | สถานะ |
 |---|---|
-| รูป versionId/format ผิด · field ไม่รู้จัก (รวม userId/userName/templateId เก่า) · ไม่ใช่ multipart · magic bytes ผิด · body ขอ /token ผิดกติกา (รวมขาด fid) | 400 |
-| `x-api-key` ไม่ตั้ง/ไม่ใส่/ผิด (ที่ /token) · Bearer ขาด/เน่า/หมดอายุ/secret ไม่ตั้ง (ทุก endpoint อื่น) | 401 |
+| รูป versionId/format ผิด · field ไม่รู้จัก (รวม userId/userName/templateId/fields เก่า) · ไม่ใช่ multipart · magic bytes ผิด · แกะข้อมูลจากไฟล์ไม่ได้ · body ขอ /token ผิดกติกา (รวมขาด fid) | 400 |
+| `type` ไม่ส่ง/ค่าอื่น · `ticket_data` ไม่ส่ง/ไม่ใช่ JSON object/field นอก allowlist/ขาด fid·uid·uname/เกิน cap/ยาว >2048 · ticket_data หลังเติม exp ยาว >255 (ที่ /latest เฉพาะ type=docx) — ทั้งหมดของ GET /latest | 400 |
+| `x-api-key` ไม่ตั้ง/ไม่ใส่/ผิด (ที่ /token) · Bearer ขาด/เน่า/หมดอายุ/secret ไม่ตั้ง (ทุก endpoint อื่น) · `x-api-key` ไม่ตั้ง (ทั้งคู่)/ไม่ใส่/ไม่ตรงทั้ง `DOCVER_API_KEY`·`EXTERNAL_API_KEY` (ที่ /latest) | 401 |
 | ไฟล์เกิน 100MB (เช็ค `file.size` ก่อน buffer เสมอ — route ไม่มี `bodySizeLimit` คุม) | 413 |
-| เอกสาร/version ไม่มี · ขอ pdf ที่ version ไม่มี | 404 |
-| MinIO env ไม่ตั้ง/ล้ม · DB ล้ม (หลังเก็บกวาด object กำพร้า) · `DOCVER_TOKEN_SECRET` ไม่ตั้ง (ที่ /token) | 500 (log เต็มฝั่ง server + ข้อความกลาง ๆ ไทย) |
+| เอกสาร/version ไม่มี · ขอ pdf ที่ version ไม่มี (รวม type=pdf ที่ /latest แต่ version ล่าสุดไม่มี pdf) | 404 |
+| MinIO env ไม่ตั้ง/ล้ม · DB ล้ม (หลังเก็บกวาด object กำพร้า) · `DOCVER_TOKEN_SECRET` ไม่ตั้ง (ที่ /token) · stamp ticket ล้ม/magic bytes ของ object ไม่ตรง (ที่ /latest) | 500 (log เต็มฝั่ง server + ข้อความกลาง ๆ ไทย) |
 
 ## 2. ตาราง (db/schema.ts)
 
@@ -174,7 +231,9 @@ document_versions  — id uuid PK · document_id uuid FK→documents CASCADE
 
 ## 4. ลำดับงานต่อ request (POST) + เก็บกวาด object กำพร้า
 
-validate (text field ก่อนแตะไฟล์) → cap ขนาด → buffer → magic bytes → sha256 → `versionId`
+validate (text field ก่อนแตะไฟล์) → cap ขนาด → buffer → magic bytes → **แกะ fields snapshot
+จากไฟล์ทั้งก้อนด้วย `extractDocumentSnapshot` ของ lib/lib-tmpl.ts (ตัวเดียวกับ
+`/api/template/extract` — 2026-10-30)** → sha256 → `versionId`
 → **putObject MinIO** (docx ก่อน pdf; pdf ล้ม = ลบ docx ทิ้ง) → **insert DB (tx §3)** —
 ล้ม = `removeObject` ทั้งคู่แล้วโยนต่อ (pattern เดียวกับ `unlink` + rethrow ของ N4)
 
@@ -200,9 +259,12 @@ read-only ของ N10 แต่ตัวนี้เขียนได้)
 | `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` | — บังคับ | dev compose = `minioadmin` |
 | `MINIO_BUCKET` | `docver` | app สร้างเองตอน first use (`ensureBucket` — จับ race ข้าม process) |
 | `DOCVER_LINK_TTL_SECONDS` | `900` | อายุ presigned URL |
-| `DOCVER_API_KEY` | — บังคับ | API key ของ `POST /api/documents/token` (header `x-api-key`) — ไม่ตั้ง/ว่าง = 401 fail closed · เทียบ timing-safe · ห้าม log ค่าดิบ |
+| `DOCVER_API_KEY` | — บังคับ | API key ของ `POST /api/documents/token` (header `x-api-key`) — ไม่ตั้ง/ว่าง = 401 fail closed · เทียบ timing-safe · ห้าม log ค่าดิบ · GET /latest ใช้ตัวนี้**หรือ** `EXTERNAL_API_KEY` ตัวใดตัวหนึ่ง |
 | `DOCVER_TOKEN_SECRET` | — บังคับ | secret เซ็น/ตรวจ JWT HS256 — ไม่ตั้ง: /token = 500 · endpoint อื่น = 401 · ห้าม log ค่าดิบ |
 | `DOCVER_TOKEN_TTL_SECONDS` | `3600` | อายุ access_token (วินาที) |
+| `TICKET_SEC` | `300` | TTL (วินาที) ของ `exp` ที่ stamp ตอน GET /latest type=docx — env เดียวกับกลุ่ม template (`app/api/template/*`) |
+| `PRIVATE_KEY_HEX` | — optional | private key Ed25519 (hex seed) — ตั้งแล้ว GET /latest type=docx จะ stamp prop `Ed25519` เพิ่ม · ไม่ตั้ง = ไม่ใส่ (chain ของ add-in verify แค่ `HmacSha256`) · env เดียวกับกลุ่ม template |
+| `ADDIN_TICKET_SECRET` | chain → `SECRET` → `"super_secret"` | secret ของ HMAC ที่ stamp ที่ /latest — ใช้ `addinTicketSecret()` ให้ตรงฝั่ง verify ของ /token ทาง ticket (ดู `docs/PLAN-ADDIN-AUTH.md`) |
 
 `putObject` แนบ `Content-Type` + `Content-Disposition` (ชื่อไฟล์ไทยผ่าน `filename*=UTF-8''`
 best-effort + ASCII fallback `document.docx`/`document.pdf`) — presigned GET ได้ชื่อไฟล์สวย
@@ -214,15 +276,23 @@ best-effort + ASCII fallback `document.docx`/`document.pdf`) — presigned GET
 - `lib/document-versioning.ts` — pure validation (ห้าม import `@/db`/`minio` — unit test ได้
   โดยไม่ต้องตั้ง env อะไรเลย ตาม pattern `lib/external-api-auth.ts`)
 - `lib/docver-token.ts` — JWT HS256 issue/verify + `requireDocverApiKey`/`requireDocverBearer`
-  + `parseTokenRequestBody` (pure เหมือนกัน — ไม่ import `@/db`/`minio`)
+  + `parseTokenRequestBody` + `requireDocumentApiKey` (auth ของ GET /latest — สอง env)
+  (pure เหมือนกัน — ไม่ import `@/db`/`minio`)
 - `lib/docver-store.ts` — MinIO client (เก็บบน `globalThis` ใน dev แบบ `db/index.ts`) +
-  `ensureBucket` + put/remove/presign + `insertVersionRecord` (tx) + query helpers
+  `ensureBucket` + put/remove/presign + `getVersionObjectBytes` (อ่านไบต์ของ /latest) +
+  `insertVersionRecord` (tx) + query helpers (`findLatestVersionForDoc` ของ /latest)
 - `app/api/documents/token/route.ts` — POST ขอ access_token (x-api-key)
 - `app/api/documents/versions/route.ts` — POST + GET (docId = fid จาก token)
 - `app/api/documents/versions/[versionId]/download-link/route.ts` — GET
+- `app/api/documents/latest/route.ts` — GET ไฟล์ version ล่าสุด (2026-10-31 — docx
+  stamp ticket บนสำเนาในหน่วยความจำผ่าน `buildStampedTicketData`/`stampTicketProps`
+  ของ `lib/lib-tmpl.ts` + `parseTicketDataParam` ของ `utils/docver-ticket.ts` +
+  `parseLatestTypeParam` ของ `lib/document-versioning.ts`)
 - `docker-compose.yml` — db (ชื่อ/วอลุ่มเดิมกับ `docker run` ใน README) + minio
   (โฮสต์ 19000 API / 19001 console — ข้างใน container 9000/9001; image จาก quay.io)
 - `tests/lib/document-versioning.test.ts` + `tests/lib/docver-token.test.ts` — unit test ส่วน pure
+  (+ `parseTicketDataParam` ใน `tests/utils/docver-ticket.test.ts` + stamp helpers ใน
+  `tests/lib/lib-tmpl.test.ts` ของ /latest)
 
 ## 8. Out of scope รอบนี้