feat(docver): derive docId from fid claim and drop [docId] URL segment
All checks were successful
Deploy eCourt Note Web to Server / Validate Database Schema (Drizzle) (push) Successful in 3s
Deploy eCourt Note Web to Server / Build Web Docker Image (push) Successful in 1m9s
Deploy eCourt Note Web to Server / Deploy eCourt Note Web to Server (push) Successful in 4s
Deploy eCourt Note Web to Server / Notify Deployment Status (push) Successful in 1s

- docId of every docver operation now comes from the Bearer token: the fid
  claim (e-Court fileId) is used directly as docId; segment [docId] removed
  from URLs — POST/GET /api/documents/versions and
  GET /api/documents/versions/{versionId}/download-link
- fid is required and must be a string (trim 1-200): token issuance rejects
  missing/blank/non-string fid with 400, verify rejects fid-less tokens with 401
- parseDocId removed from lib/document-versioning.ts (dead code, no callers)
- openapi spec: paths renamed, docId path params removed, fid required + string
- PLAN-DOCVER.md / CLAUDE.md / wordaddin versioningService comment updated
- tests: fid required/string cases added, parseDocId describe removed (256 pass)

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
Suphonchai Phoonsawat 2026-10-26 10:05:01 +07:00
parent aad6f155fe
commit 0b2c9e6343
10 changed files with 122 additions and 158 deletions

View file

@ -8,13 +8,15 @@
ทำ backend จริงของฟีเจอร์ **"e-Court Documents Versioning"** (ตอนนี้ wordaddin ใช้ mock ใน
`wordaddin/services/versioningService.ts`):
- รับ `docId` จากผู้เรียก → ตารางเอกสารที่ `docId` **ห้ามซ้ำ** (unique index)
- ตารางเอกสารคีย์ด้วย `docId` **ห้ามซ้ำ** (unique index) — **`docId` = claim `fid`
(string) จาก Bearer token ตรง ๆ** (2026-10-26 ถอด path param `{docId}` ออกจาก URL ทุก
endpoint — fileId ของ e-Court ใน token เป็นที่มาเดียวของรหัสเอกสาร)
- แต่ละ version อ้าง **object ใน MinIO** — เก็บทั้ง `.docx` และ `.pdf` (pdf เป็น
optional/best-effort ตาม contract ของ add-in — `pdf.size === 0` = ไม่มี, มี `hasPdf` บอกใน
response)
- เก็บ `userId`, `userName`, `createdAt` ต่อ version เพื่อรู้ว่าใครอัปโหลด
- **identity (`userId`/`userName`/`templateId`) แกะจาก Bearer token** (2026-10-22 — เดิมส่ง
plain field ใน multipart): ขอ token ที่ `POST /api/documents/token` ด้วย header
- **identity (`userId`/`userName`/`templateId`) และ `docId` แกะจาก Bearer token** (2026-10-22
— เดิมส่ง plain field ใน multipart): ขอ token ที่ `POST /api/documents/token` ด้วย header
`x-api-key` แล้วแนบ `Authorization: Bearer <token>` กับทุก request — ระบบ stand-alone
ไม่มี session ร่วมกับใคร (ผู้เรียกคือ add-in ใน Word หรือระบบภายนอก) token จึงเป็น
พาหะ identity เดียว
@ -45,7 +47,7 @@ JSON body (allowlist — key อื่น = 400 กัน typo):
|---|---|---|
| `userid` | string | บังคับ — trim 1–100 (claim `userid` → column `user_id`) |
| `username` | string | บังคับ — trim 1–200 (claim `username` → column `user_name`) |
| `fid` | integer | optional — **fileId ของ e-Court** เก็บเป็น claim อย่างเดียว ยังไม่มี operation ใดอ่าน/บังคับ (ตารางของกลุ่มนี้คีย์ด้วย `docId` ไม่มี column fileId) |
| `fid` | string | **บังคับ** — trim 1–200 · **fileId ของ e-Court** เป็น `docId` ของทุก operation ตรง ๆ · verify ไม่รับ token ที่ไม่มี fid |
| `template` | string | optional ≤100 (claim `template` → column `template_id` ตอน upload) |
- env `DOCVER_TOKEN_SECRET` ไม่ตั้ง/ว่าง = **500** "DOCVER_TOKEN_SECRET ยังไม่ได้ตั้งค่า"
@ -57,10 +59,10 @@ JSON body (allowlist — key อื่น = 400 กัน typo):
ไม่มี header / รูปผิด / signature ผิด / หมดอายุ / secret ไม่ตั้ง = 401 ข้อความไทย
เดียวกันทุกกรณี (ไม่เปิดให้ใช้ endpoint เป็น oracle รู้สาเหตุ)
### `POST /api/documents/{docId}/versions` — อัปโหลด version ใหม่
### `POST /api/documents/versions` — อัปโหลด version ใหม่
auth: `Authorization: Bearer` (ดู /token ด้านบน) — identity/templateId ของ row ใหม่
มาจาก claims ของ token ไม่รับจาก form อีกต่อไป
auth: `Authorization: Bearer` (ดู /token ด้านบน) — identity/templateId ของ row ใหม่และ
`docId` (= `fid` — string) มาจาก claims ของ token ทั้งหมด ไม่รับจาก URL/form อีกต่อไป
multipart/form-data:
@ -77,12 +79,12 @@ multipart/form-data:
**breaking change 2026-10-22:** `userId`/`userName`/`templateId` ถอดออกจาก form แล้ว
(ส่งมา = 400) identity/template มาจาก Bearer token ของ request นั้นแทน
- เอกสาร (`documents` row) สร้าง **แบบ implicit** ตอน upload version แรก — ไม่มี endpoint
"สร้างเอกสาร" แยก (ตาม flow ของ add-in ที่ generate documentId เองแล้วอัปโหลดทันที)
"สร้างเอกสาร" แยก (เอกสารถูกระบุที่ fid ใน token ตั้งแต่ขอ token)
- response 200: `{ "hasPdf": boolean, "versionId": string, "versionNumber": number }`
(= `UploadVersionResult` เป๊ะ) — `versionNumber` เป็นค่า **authoritative จาก server**
(client เดา `latest+1` แล้วแก้ XML part ตัวเองเมื่อไม่ตรง — กรณีอัปโหลดชนกัน)
### `GET /api/documents/{docId}/versions` — history
### `GET /api/documents/versions` — history (ของเอกสาร fid ใน token)
response: `DocumentVersionDTO[]` เรียง **ใหม่ → เก่า** (ตาม `VersionRecord[]` ของ add-in +
ส่วนเสริม `createdByUserName`):
@ -101,13 +103,14 @@ response: `DocumentVersionDTO[]` เรียง **ใหม่ → เก่า
}
```
- `docId` ไม่รู้จัก (ยังไม่เคยมี version) = **404** (สัญญาณ REST ตรง ๆ แบบ N10 — UI ของ
add-in แสดง error + ปุ่มลองใหม่ ไม่พัง)
- `docId` (จาก fid ใน token) ไม่รู้จัก (ยังไม่เคยมี version) = **404** (สัญญาณ REST ตรง ๆ แบบ
N10 — UI ของ add-in แสดง error + ปุ่มลองใหม่ ไม่พัง)
### `GET /api/documents/{docId}/versions/{versionId}/download-link?format=docx|pdf`
### `GET /api/documents/versions/{versionId}/download-link?format=docx|pdf`
- format ไม่ส่ง/"" = `docx` · ค่าอื่น = 400
- query version row **เช็คทั้ง docId และ versionId พร้อมกัน** (กันโยน id ข้ามเอกสาร) — ไม่เจอ = 404
- query version row **เช็ค docId (จาก fid ใน token) กับ versionId พร้อมกัน** (กันโยน id
ข้ามเอกสาร) — ไม่เจอ = 404
- `format=pdf` แต่ version นั้นไม่มี pdf = 404 "version นี้ไม่มีสำเนา PDF"
- response 200: `{ "url": string, "expiresAt": string }` — url เป็น **MinIO presigned GET**
(อายุตาม env `DOCVER_LINK_TTL_SECONDS` default 900 วิ) ให้ UI เปิดในเบราว์เซอร์จริงของ
@ -119,7 +122,7 @@ response: `DocumentVersionDTO[]` เรียง **ใหม่ → เก่า
| เหตุ | สถานะ |
|---|---|
| รูป docId/versionId/format ผิด · field ไม่รู้จัก (รวม userId/userName/templateId เก่า) · ไม่ใช่ multipart · magic bytes ผิด · body ขอ /token ผิดกติกา | 400 |
| รูป versionId/format ผิด · field ไม่รู้จัก (รวม userId/userName/templateId เก่า) · ไม่ใช่ multipart · magic bytes ผิด · body ขอ /token ผิดกติกา (รวมขาด fid) | 400 |
| `x-api-key` ไม่ตั้ง/ไม่ใส่/ผิด (ที่ /token) · Bearer ขาด/เน่า/หมดอายุ/secret ไม่ตั้ง (ทุก endpoint อื่น) | 401 |
| ไฟล์เกิน 100MB (เช็ค `file.size` ก่อน buffer เสมอ — route ไม่มี `bodySizeLimit` คุม) | 413 |
| เอกสาร/version ไม่มี · ขอ pdf ที่ version ไม่มี | 404 |
@ -206,8 +209,8 @@ best-effort + ASCII fallback `document.docx`/`document.pdf`) — presigned GET
- `lib/docver-store.ts` — MinIO client (เก็บบน `globalThis` ใน dev แบบ `db/index.ts`) +
`ensureBucket` + put/remove/presign + `insertVersionRecord` (tx) + query helpers
- `app/api/documents/token/route.ts` — POST ขอ access_token (x-api-key)
- `app/api/documents/[docId]/versions/route.ts` — POST + GET
- `app/api/documents/[docId]/versions/[versionId]/download-link/route.ts` — GET
- `app/api/documents/versions/route.ts` — POST + GET (docId = fid จาก token)
- `app/api/documents/versions/[versionId]/download-link/route.ts` — GET
- `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