Add generate API, Prototype for developer, Clean data
Some checks failed
Deploy eCourt Note Web to Server / Validate Database Schema (Drizzle) (push) Successful in 5s
Deploy eCourt Note Web to Server / Build Web Docker Image (push) Failing after 1m11s
Deploy eCourt Note Web to Server / Deploy eCourt Note Web to Server (push) Has been skipped
Deploy eCourt Note Web to Server / Notify Deployment Status (push) Failing after 0s

This commit is contained in:
oom 2026-10-27 01:47:08 +07:00
parent 6ce071ee14
commit a3d14fd58d
26 changed files with 911 additions and 1267 deletions

View file

@ -32,13 +32,12 @@ export const openApiSpec = {
{
name: "template",
description:
"Template เอกสาร DOCX ด้วย Content Control — ส่ง template (.docx) + data (JSON) " +
"แล้วได้เอกสารที่กรอกค่าแล้วกลับมา",
"Next Generation of Template : เป็นเทมเพลต MS Word(docx) รองรับรูปแบบข้อมูลที่ซับซ้อนได้ ",
},
{
name: "documents",
description:
"จัด version เอกสาร (docver — docs/PLAN-DOCVER.md): เอกสารเดียวต่อ docId แต่ละ " +
"จัด version เอกสาร (docver): เอกสารเดียวต่อ docId แต่ละ " +
"version เก็บ .docx + .pdf ใน MinIO พร้อมผู้อัปโหลด — auth ด้วย access_token " +
"ของกลุ่มนี้: ขอที่ POST /api/documents/token (ยืนยัน x-api-key กับ env " +
"DOCVER_API_KEY) แล้วแนบ Authorization: Bearer ทุก request — identity/template " +
@ -75,67 +74,15 @@ export const openApiSpec = {
},
},
},
"/api/template/extract": {
post: {
tags: ["template"],
summary: "ดึงค่า Content Control ทั้งหมดออกมาจากไฟล์ .docx",
description:
"อ่าน w:sdt (Content Control) ทุกตัวใน word/document.xml — คืน map " +
"ชื่อแท็ก (w:tag) → ข้อความปัจจุบันในนั้น (ใช้สำรวจว่า template มีแท็กอะไรบ้างก่อนเรียก render)",
requestBody: {
required: true,
content: {
"multipart/form-data": {
schema: {
type: "object",
required: ["file"],
properties: {
file: {
type: "string",
format: "binary",
description: "ไฟล์ .docx ที่มี Content Control",
},
secret: {
type: "string",
description:
"ค่า secret สำหรับ validate HMAC-SHA256 กับข้อมูลใน custom property" ,
example:
"super_secret",
},
public_key: {
type: "string",
description:
"Public key ในรูปแบบ HEX <br/> openssl genpkey -algorithm ED25519 -out private.pem <br/> openssl pkey -in private.pem -outform DER | tail -c 32 | xxd -p -c 32 > private.hex <br/>openssl pkey -in private.pem -pubout -outform DER | tail -c 32 | xxd -p -c 32 > public.hex",
example:
"66b09b4a1b66271d5728c592c2409657e1c070a7bf371bf9f6ed457855270546",
},
},
},
},
},
},
responses: {
200: {
description: "รายการแท็กพร้อมข้อความ",
content: {
"application/json": {
schema: { $ref: "#/components/schemas/ExtractResponse" },
},
},
},
400: { $ref: "#/components/responses/BadRequest" },
500: { $ref: "#/components/responses/ServerError" },
},
},
},
"/api/template/render": {
post: {
tags: ["template"],
summary: "สร้างเอกสารจาก template (.docx) + data (JSON)",
summary: "สร้างเอกสารจาก template (.docx) + data (JSON) ใช้สำหรับนักพัฒนาเท่านั้น",
description:
"แทนค่า JSON ลงใน Content Control ของ template แล้วคืนไฟล์ .docx ใหม่ " +
'(filename ตอน download = generated-document.docx) — ส่ง data ได้ 2 ทาง: ' +
'field "data" เป็นไฟล์ JSON หรือ field "dataJson" เป็น string ตรง ๆ (เลือกอย่างใดอย่างหนึ่ง)',
'field "data" เป็นไฟล์ JSON หรือ field "dataJson" เป็น string ตรง ๆ (เลือกอย่างใดอย่างหนึ่ง)<br/>'+
'<i>สำหรับนักพัฒนา Template เท่านั้น ไม่ต้อง ใช้ API Key ต้องตั้งค่า secret และ private key เองไม่ใช้ของระบบของระบบ</i>',
requestBody: {
required: true,
content: {
@ -194,6 +141,410 @@ export const openApiSpec = {
},
},
},
"/api/template/extract": {
post: {
tags: ["template"],
summary: "ดึงค่า Content Control ทั้งหมดออกมาจากไฟล์ .docx ใช้สำหรับนักพัฒนาเท่านั้น",
description:
"อ่าน Content Control, bookmark , property ของ MS Word(docx) ออกมาแสดง" +
"ค่าของ Content Control จะเป็น Plain Text ไม่มี markup ซึ่งเหมาะกับการเอาไปใส่ในฐานข้อมูล"+
'<i>สำหรับนักพัฒนา Template เท่านั้น ไม่ต้อง ใช้ API Key ต้องตั้งค่า secret และ Public key เองไม่ใช้ของระบบของระบบ</i>',
requestBody: {
required: true,
content: {
"multipart/form-data": {
schema: {
type: "object",
required: ["file"],
properties: {
file: {
type: "string",
format: "binary",
description: "ไฟล์ .docx ที่มี Content Control",
},
secret: {
type: "string",
description:
"ค่า secret สำหรับ validate HMAC-SHA256 กับข้อมูลใน custom property",
example:
"super_secret",
},
public_key: {
type: "string",
description:
"Public key ในรูปแบบ HEX <br/> openssl genpkey -algorithm ED25519 -out private.pem <br/> openssl pkey -in private.pem -outform DER | tail -c 32 | xxd -p -c 32 > private.hex <br/>openssl pkey -in private.pem -pubout -outform DER | tail -c 32 | xxd -p -c 32 > public.hex",
example:
"66b09b4a1b66271d5728c592c2409657e1c070a7bf371bf9f6ed457855270546",
},
},
},
},
},
},
responses: {
200: {
description: "รายการแท็กพร้อมข้อความ",
content: {
"application/json": {
schema: { $ref: "#/components/schemas/ExtractResponse" },
},
},
},
400: { $ref: "#/components/responses/BadRequest" },
500: { $ref: "#/components/responses/ServerError" },
},
},
},
"/api/template/generate": {
post: {
tags: ["template"],
summary: "สร้างเอกสาร DOCX จากข้อมูล JSON และ template ที่กำหนด",
description:
"เทมเพลตมีแท็กแบบพิเศษ(รองรับตัวแปร ลูป เงื่อนไข), Content Control เมื่อรวมกับข้อมูล(JSON) "+
"จะได้เอกสาร รูปแบบฟอร์มที่กรอกค่าแล้วดึงค่ากลับมาใช้งานต่อได้เช่นอัปเดตฐานข้อมูล<br><ul>"+
"<li>JSON payload ต้องมี info.ticket_data เป็น JSON string รูปแบบถูกต้อวมีค่าครบ(tid, fid และ uid)</li>" +
"<li>ไฟล์เทมเพลต(tid)ในระบบ + ข้อมูล(payload) เพื่อสร้างเอกสาร </li>" +
"<li>ticket_data จะทำการ hash/sign แบบอายุสั้นแล้วนำไปฝังไว้ใน custom property เพื่อนำไปใช้ร่วมกับระบบ Versioning</li>"+
"</ul>",
security: [{ ApiKeyAuth: [] }],
requestBody: {
required: true,
content: {
"application/json": {
schema: {
type: "object",
required: ["info"],
properties: {
info: {
type: "object",
required: ["ticket_data"],
properties: {
ticket_data: {
type: "string",
description:
"JSON string ที่ต้อง parse ได้ และต้องมี tid, fid และ uid",
example:
'{"tid":"T12","fid":"DOC-2569-0001","uid":"123"}',
},
},
additionalProperties: true,
},
},
additionalProperties: true,
},
example: {
"info": {
"ticket_data": "{\"fid\":\"T12_b2_IN\",\"tid\":\"T12_X\",\"uid\":\"oom\",\"uname\":\"สรวิชญ์\"}"
},
"dc": {
"Interpleader": true,
"docname": "",
"docabbr": "(ต. ๑๒)",
"blackno": "คดีหมายเลขดำที่",
"redno": "คดีหมายเลขแดงที่",
"court": "ศาลปกครองนครราชสีมา",
"panels": [
{
"pname": "นายวิรุฬห์ จินตนะกุล",
"pmname": "ตุลาการศาลปกครองกลาง",
"pm": "ตุลาการเจ้าของสำนวน"
},
{
"pname": "นายสัมฤทธิ์ อ่อนคำ",
"pmname": "ตุลาการศาลปกครองสูงสุด"
}
],
"pnameT": "",
"pmnameT": "",
"pmT": "",
"acc_name": ""
},
"cc": {
"blackyear": "๙๐/๒๕๖๙",
"redyear": "",
"curdate": "วันที่ เดือน สิงหาคม พุทธศักราช ๒๕๖๙",
"accuser": "นายธีรพล ร่มเริง",
"acc1": "ผู้ฟ้องคดี",
"accused": "รร",
"acc2": "ผู้ถูกฟ้องคดี",
"interpleader": "สมชาย ใจดี",
"acc3": "ผู้ร้องสอด",
"detail1": "ตุลาการเจ้าของสำนวนได้พิจารณาคำฟ้องและเอกสารประกอบคำฟ้องแล้วเห็นว่าคดีนี้เป็นคดีพิพาทซึ่งไม่อยู่ในอำนาจศาลปกครองสูงสุด ผู้ฟ้องเป็นผู้มีสิทธิฟ้องคดี คดีนี้มีกฎหมายกำหนดให้ต้องดำเนินการแก้ไขความเดือดร้อนหรือเสียหายก่อนฟ้องคดี และผู้ฟ้องคดีได้ดำเนินการครบถ้วน โดยเป็นการยื่นฟ้องคดีภายในระยะเวลาการฟ้องคดีตาม พรบ. จัดตั้งศาลปกครองและวิธีพิจารณาคดีปกครองฯ คดีนี้มีค่าธรรมเนียมที่ต้องชำระ\nโดยผู้ฟ้องคดีได้ชำระค่าธรรมเนียมครบถ้วนแล้ว รวมทั้งคดีนี้ไม่เป็นการฟ้องซ้อน การดำเนินกระบวนพิจารณาซ้ำ และการฟ้องซ้ำ\n\nจึงมีคำสั่งรับคำฟ้องไว้พิจารณาและสั่งให้ส่งสำเนาคำฟ้องพร้อมทั้งสำเนาพยานหลักฐานไปยังผู้ถูกฟ้องคดีเพื่อให้ผู้ถูกฟ้องคดีทำคำให้การยื่นต่อศาลภายใน ๓๐ วัน นับแต่วันที่ได้รับคำสั่ง"
}
},
},
},
},
responses: {
200: {
description: "ไฟล์ DOCX ที่สร้างสำเร็จ",
headers: {
"Content-Disposition": {
description: "ชื่อไฟล์สำหรับดาวน์โหลด",
schema: { type: "string" },
},
"Cache-Control": {
description: "ป้องกันการ cache response",
schema: { type: "string", example: "no-store, max-age=0" },
},
},
content: {
"application/vnd.openxmlformats-officedocument.wordprocessingml.document": {
schema: { type: "string", format: "binary" },
},
},
},
400: {
description:
"JSON ไม่มี info.ticket_data, ticket_data ไม่ใช่ string, JSON string ไม่ถูกต้อง หรือไม่มี tid/fid/uid",
content: {
"application/json": {
schema: { $ref: "#/components/schemas/Error" },
examples: {
missingTicketData: {
value: {
error:
"template/generate json.info.ticket_data not avaliable",
},
},
missingIdentifiers: {
value: {
error:
"template/generate require json.info.ticket_data.(fid|tid|uid)",
},
},
},
},
},
},
401: {
description: "ไม่ได้ส่ง x-api-key หรือ API key ไม่ถูกต้อง",
content: {
"application/json": {
schema: { $ref: "#/components/schemas/Error" },
example: { error: "Unauthorized: Invalid API Key" },
},
},
},
404: {
description: "ไม่สามารถดึงข้อมูลขึ้นมาได้",
content: {
"application/json": {
schema: { $ref: "#/components/schemas/Error" },
example: { error: "NotFound: Invalid template ID or incorrect storage path" },
},
},
},
500: {
description:
"เกิดข้อผิดพลาดระหว่างอ่าน template หรือสร้างเอกสาร",
content: {
"application/json": {
schema: { $ref: "#/components/schemas/Error" },
example: { error: "Failed to generate document payload" },
},
},
},
},
},
},
"/api/template/download-docx": {
get: {
tags: ["template"],
summary: "ดาวน์โหลดเอกสาร DOCX ผ่าน Query Parameters (GET) ใช้เพื่อเป็นตัวอย่างจะถูกเอาออกในภายหลัง",
description:
"รับค่า fid, tid, uid, uname จาก Query Parameter อ่านข้อมูล JSON ประจำไฟล์ fid จาก TMPL_PATH แล้วส่งไปประมวลผลต่อที่ /api/template/generate เพื่อสร้างและคืนค่าเป็นไฟล์ DOCX stream ใช้เพื่อเป็นตัวอย่างสำหรับนักพัฒนา ต้องนำออกก่อน production",
parameters: [
{
name: "fid",
in: "query",
required: true,
schema: { type: "string" },
description: "ID เอกสาร (File ID)",
example: "T_no_warning",
},
{
name: "tid",
in: "query",
required: true,
schema: { type: "string" },
description: "ID เทมเพลต (Template ID)",
example: "T_X",
},
{
name: "uid",
in: "query",
required: true,
schema: { type: "string" },
description: "รหัสผู้ใช้งาน (User ID)",
example: "123",
},
{
name: "uname",
in: "query",
required: true,
schema: { type: "string" },
description: "ชื่อผู้ใช้งาน (User Name)",
example: "สมชาย ใจดี",
},
],
responses: {
200: {
description: "ไฟล์ DOCX stream ที่สร้างสำเร็จ",
headers: {
"Content-Disposition": {
description: "ชื่อไฟล์สำหรับการดาวน์โหลด (attachment)",
schema: { type: "string", example: 'attachment; filename="T_no_warning_123_xxx.docx"' },
},
"Cache-Control": {
description: "การควบคุม Cache (no-store)",
schema: { type: "string", example: "no-store, max-age=0" },
},
},
content: {
"application/vnd.openxmlformats-officedocument.wordprocessingml.document": {
schema: { type: "string", format: "binary" },
},
},
},
400: {
description: "พารามิเตอร์ไม่ครบถ้วน หรือรูปแบบไฟล์ JSON ไม่ถูกต้อง",
content: {
"text/plain": {
schema: { type: "string" },
examples: {
missingParams: { value: "Missing fid,tid,uid or uname" },
invalidData: { value: "Invalid data format" },
},
},
},
},
404: {
description: "ไม่พบไฟล์ข้อมูล JSON ใน TMPL_PATH",
content: {
"application/json": {
schema: { $ref: "#/components/schemas/Error" },
example: { error: "Data not found: /path/to/TMPL_PATH/T_no_warning.json" },
},
},
},
502: {
description: "เกิดข้อผิดพลาดในการเรียกไปยังบริการ Docedit /api/template/generate",
content: {
"text/plain": {
schema: { type: "string" },
example: "Error from docedit generate: Expected docx stream but received text/html (Status 500)",
},
},
},
500: {
description: "เกิดข้อผิดพลาดภายในเซิร์ฟเวอร์",
content: {
"text/plain": {
schema: { type: "string" },
example: "Internal Server Error",
},
},
},
},
},
post: {
tags: ["template"],
summary: "ดาวน์โหลดเอกสาร DOCX ผ่าน HTML Form / Multipart Form Data (POST) เป็นตัวอย่างเท่านั้น จะถูกเอาออกในภายหลัง",
description:
"รับค่า fid, tid, uid, uname จาก Multipart Form Data หรือ Form-urlencoded อ่านข้อมูล JSON และประมวลผลสร้างไฟล์ DOCX stream คืนกลับไป "+
"จะเรียก generate ในเบื้องหลัง ใช้เพื่อเป็นตัวอย่างสำหรับนักพัฒนา ต้องนำออกก่อน production",
requestBody: {
required: true,
content: {
"multipart/form-data": {
schema: {
type: "object",
required: ["fid", "tid", "uid", "uname"],
properties: {
fid: { type: "string", description: "ID เอกสาร (File ID)",example:"T12_b2_IN" },
tid: { type: "string", description: "ID เทมเพลต (Template ID)",example:"T12_X" },
uid: { type: "string", description: "รหัสผู้ใช้งาน (User ID)", example:"john" },
uname: { type: "string", description: "ชื่อผู้ใช้งาน (User Name)", example:"John Doe"},
},
},
},
"application/x-www-form-urlencoded": {
schema: {
type: "object",
required: ["fid", "tid", "uid", "uname"],
properties: {
fid: { type: "string", description: "ID เอกสาร (File ID)" },
tid: { type: "string", description: "ID เทมเพลต (Template ID)" },
uid: { type: "string", description: "รหัสผู้ใช้งาน (User ID)" },
uname: { type: "string", description: "ชื่อผู้ใช้งาน (User Name)" },
},
},
},
},
},
responses: {
200: {
description: "ไฟล์ DOCX stream ที่สร้างสำเร็จ",
headers: {
"Content-Disposition": {
description: "ชื่อไฟล์สำหรับการดาวน์โหลด (attachment)",
schema: { type: "string", example: 'attachment; filename="T12_b2_IN_john_xxx.docx"' },
},
"Cache-Control": {
description: "การควบคุม Cache (no-store)",
schema: { type: "string", example: "no-store, max-age=0" },
},
},
content: {
"application/vnd.openxmlformats-officedocument.wordprocessingml.document": {
schema: { type: "string", format: "binary" },
},
},
},
400: {
description: "พารามิเตอร์ไม่ครบถ้วน หรือรูปแบบไฟล์ JSON ไม่ถูกต้อง",
content: {
"text/plain": {
schema: { type: "string" },
examples: {
missingParams: { value: "Missing fid,tid,uid or uname" },
invalidData: { value: "Invalid data format" },
},
},
},
},
404: {
description: "ไม่พบไฟล์ข้อมูล JSON ใน TMPL_PATH",
content: {
"application/json": {
schema: { $ref: "#/components/schemas/Error" },
example: { error: "Data not found: /path/to/TMPL_PATH/T12_b2_IN.json" },
},
},
},
502: {
description: "เกิดข้อผิดพลาดในการเรียกไปยังบริการ Docedit /api/template/generate",
content: {
"text/plain": {
schema: { type: "string" },
example: "Error from docedit generate: Expected docx stream but received text/html (Status 500)",
},
},
},
500: {
description: "เกิดข้อผิดพลาดภายในเซิร์ฟเวอร์",
content: {
"text/plain": {
schema: { type: "string" },
example: "Internal Server Error",
},
},
},
},
},
},
"/api/note/external/documents": {
post: {
tags: ["external"],
@ -524,7 +875,6 @@ export const openApiSpec = {
Error: {
type: "object",
properties: {
success: { type: "boolean", example: false },
error: { type: "string" },
},
},
@ -563,14 +913,44 @@ export const openApiSpec = {
ExtractResponse: {
type: "object",
properties: {
success: { type: "boolean", example: true },
data: {
type: "object",
description: "ชื่อแท็ก Content Control → ข้อความในนั้น (หลายบรรทัดคั่นด้วย \\n)",
additionalProperties: { type: "string" },
example: {
blackno: "คดีหมายเลขดำที่",
court: "ศาลปกครองสุพรรณบุรี",
"cc": {
"blackyear": "๙๐/๒๕๖๙",
"redyear": "xxx",
"curdate": "วันที่ เดือน สิงหาคม พุทธศักราช ๒๕๖๙ ",
"accuser": "นายธีรพล ร่มเริง",
"detail1": "ตุลาการเจ้าของสำนวนได้พิจารณาคำฟ้อง...",
},
"bookmark": {
"signature": ""
},
"properties": {
"standard": {
"creator": "mam",
"created": "2026-10-22T02:58:00.000Z",
"modified": "2026-10-22T07:08:00.000Z"
},
"extended": {
"template": "TS_P2_IN.dotx",
"totalTime": 172,
"pages": 2,
"words": 124,
},
"custom": {
"ticket_data": "{\"exp\":1793013726,\"fid\":\"T_no_warning\",\"tid\":\"T_X\",\"uid\":\"john\",\"uname\":\"John Doe\"}",
"HmacSha256": "1dc53fbd48410845c895ddb841a8fe4ad93da413126fae9c688202e57f2baaa9",
"Ed25519": "95ea0ca6d81df885c22a2334ed89b2fc3c75a1a309fb5843e0deb0a16c9d05a45b345fb28fd606f3b152285e70560ad43a6389534794aa0d6f06d13f1307b005"
}
},
"verify": {
"exp": "26/10/2569 18:22:06",
"HmacSha256": true,
"Ed25519": true
}
},
},
},