npm - @gumin61/transfer-data-sdk - Versions diffs - 1.2.0 → 1.2.1 - Mend

@gumin61/transfer-data-sdk 1.2.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +165 -263
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,317 +1,219 @@
-# คู่มือการใช้งาน Script Transfer Data PDPA
+# @gumin61/transfer-data-sdk
-สคริปต์นี้ใช้โอนย้ายข้อมูลจากฐานข้อมูลต้นทาง (source) ไปยังฐานข้อมูลปลายทาง (target) แบ่งเป็นส่วน (sections) ตามลำดับความสัมพันธ์ของตาราง (FK)
+SDK สำหรับโอนย้ายข้อมูลระหว่าง MySQL database (source → target) รองรับการ insert เฉพาะแถวใหม่ตาม PK, validation, restore user refs และจัดการ FK ที่ไม่มีในตารางอ้างอิง
-**หมายเหตุ:** ต้องมีไฟล์ `.env` กำหนดค่าเชื่อมต่อ DB ต้นทางและปลายทางก่อนรัน
+หมายเหตุ: structure schema ของฐานข้อมูลปลายทาง(target) จะต้องเหมือนกับฐานข้อมูลต้นทาง(source)
----
+## การติดตั้ง
+```bash
+npm install @gumin61/transfer-data-sdk mysql2
+```
+## ความต้องการของระบบ
-## การใช้งานแบบ SDK (สำหรับ npm package)
+- Node.js 18+
+- MySQL (ใช้ `mysql2` เป็น driver)
-แพ็กเกจนี้ export ฟังก์ชันหลัก `copyDataTables` ที่ path หลักของแพ็กเกจ
+## การใช้งานพื้นฐาน
 ```ts
 import mysql from "mysql2/promise";
 import { copyDataTables } from "@gumin61/transfer-data-sdk";
-const sourcePool = mysql.createPool({ /* source config */ });
-const targetPool = mysql.createPool({ /* target config */ });
+const sourcePool = mysql.createPool({
+  host: "localhost",
+  port: 3306,
+  user: "root",
+  password: "password",
+  database: "source_db",
+});
+const targetPool = mysql.createPool({
+  host: "localhost",
+  port: 3306,
+  user: "root",
+  password: "password",
+  database: "target_db",
+});
 const result = await copyDataTables(
   { sourcePool, targetPool },
   {
-    tableNames: ["permissions"],
-    restoreUserRefsOptions: [
-      { tableName: "organizations", batchSize: 100 },
-      { tableName: "systemlangaue", batchSize: 100 },
-    ],
-  },
+    tableNames: ["users", "permissions"],
+    options: { pageSize: 500, batchSize: 500 },
+  }
 );
-```
-- build SDK: `npm run build:sdk`
-- ทดสอบตัวอย่างการใช้งาน SDK: `npm run demo:test`
----
-## 1. คำสั่ง npm ที่มีในโปรเจกต์
-### 1.1 รันโอนข้อมูลทีละตาราง (ใช้กรณีที่ข้อมูลฐานนั้นไม่ครบหรือมีข้อมูลใหม่เข้ามา)
-```bash
-npm run table -- --name "<ชื่อตาราง>"
+console.table(result.tableResults);
+console.log(`Total: ${result.totalRowsTransferred} rows`);
 ```
-| คำสั่งตัวอย่าง | ความหมาย |
-|---------------|----------|
-| `npm run table -- --name "permissions"` | โอนเฉพาะตาราง permissions (sync จาก v3) |
-| `npm run table -- --name "users"` | โอนเฉพาะตาราง users |
-| `npm run table -- --name "pii_master"` | โอนเฉพาะตาราง pii_master |
-| `npm run table -- --name "organizations"` | โอนเฉพาะตาราง organizations |
-- ตารางต้องอยู่ใน config ของ section ใด section หนึ่ง (`sections.config.ts`) จึงจะรันได้
----
-### 1.2 รันโอนตาม Section
-| คำสั่ง | ความหมาย |
-|--------|----------|
-| `npm run transfer:sections` | รันทุก section ตามลำดับ (section-1 → master-data → section-2 → … → section-6 → section-1 อีกครั้ง → section-7-1 → section-7-2) |
-| `npm run transfer:section-1` | รันเฉพาะ Section 1 (Core Data) |
-| `npm run transfer:section-2` | รันเฉพาะ Section 2 |
-| `npm run transfer:section-3` | รันเฉพาะ Section 3 |
-| `npm run transfer:section-4` | รันเฉพาะ Section 4 |
-| `npm run transfer:section-5` | รันเฉพาะ Section 5 |
-| `npm run transfer:section-6` | รันเฉพาะ Section 6 |
-| `npm run transfer:master-data` | รันเฉพาะ Master Data |
-| `npm run transfer:section-7` | รัน Section 7 ทั้งหมด (section-7-1 + section-7-2) |
-| `npm run transfer:section-7-1` | รันเฉพาะ Section 7.1 |
-| `npm run transfer:section-7-2` | รันเฉพาะ Section 7.2 (จำเป็นต้องรัน 7.1 ก่อน หากรันแล้วสามารถรันส่วนนี้ทันทีได้เลย) |
----
-### 1.3 รันทดสอบและตรวจสอบข้อมูล (ส่วนนี้ต้องกำหนด Logic ที่จะตรวจสอบใน run-test.ts)
-| คำสั่ง | ความหมาย |
-|--------|----------|
-| `npm run test -- --function "<function_name>"` | รันฟังก์ชันทดสอบที่กำหนด (เช่น `validate_permissions`, `validate_data`, `copy_tables`) |
-| `npm run validate-data` | รันการตรวจสอบความถูกต้องของข้อมูล |
-| `npm run seed:permissions` | seed/อัปเดตตาราง permissions จาก `src/assets/data/permissions.ts` (รันแยกหลัง section-1 ตามต้องการ) |
----
-## 2. ลำดับการรันเมื่อใช้ `transfer:sections` (ไม่ควรข้าม section ใด section หนึ่ง)
-1. **section-1** (Core Data – company, org, users, roles, permissions ฯลฯ)
-2. **master-data** (Master tables – chanel_dsar, data_type_master ฯลฯ)
-3. **section-2** (Owner, Activity, ROP ฯลฯ)
-4. **section-3** (Consent)
-5. **section-4** (DSAR)
-6. **section-5** (Incident)
-7. **section-6** (PDPA message, file attach ฯลฯ)
-8. **section-1** อีกครั้ง (ถ้าต้องการ sync ข้อมูล core ซ้ำ)
-9. **`npm run seed:permissions`** (อัปเดต permissions จาก assets/data/permissions.ts — รันแยกเมื่อต้องการ)
-10. **section-7-1** (CK, Consent CK ฯลฯ)
-11. **section-7-2** (Access, DSAR เพิ่มเติม, Technical measures ฯลฯ)
----
-## 3. ตารางที่แต่ละ Section Insert และเงื่อนไขเพิ่มเติม
-### Master Data (`master-data`)
-**วิธีโอน:** ใช้ `copyTableMaster` — อ่านจาก source แล้ว insert ลง target โดยรันซ้ำจะ **insert เฉพาะแถวที่ PK ยังไม่มีใน target** (ไม่ insert ซ้ำ)
-**ตารางที่ insert (ตามลำดับ):**
-| ลำดับ | ชื่อตาราง |
-|-------|------------|
-| 1 | chanel_dsar_master |
-| 2 | data_backup_location_master |
-| 3 | disposal_data_type_master |
-| 4 | encryption_type_master |
-| 5 | subject_type_master |
-| 6 | subject_group_master |
-| 7 | rop_gap_type_master |
-| 8 | rop_gap_master |
-| 9 | data_type_master |
-| 10 | pii_master |
-| 11 | legal_bases_master |
-| 12 | tags |
-| 13 | taggables |
-| 14 | role_master |
-| 15 | rop_type_master |
-| 16 | question_master |
-| 17 | channel_group_master |
-| 18 | dsar_type_master |
-**เงื่อนไขเพิ่มเติม:**
-- ตาราง **data_type_master**: ถ้าไม่มีแถวจาก asset ใน target จะ insert ข้อมูลจาก asset ก่อน แล้วใช้ `data_type_id` ที่มีอยู่ทั้งหมดใน target ในการกรอง/อ้างอิง (เพราะมีข้อมูล FK ที่ไม่มีอยู่จริงในระบบ)
-- ตาราง **rop_type_master**: ทำแบบเดียวกัน insert จาก asset ถ้ายังไม่มี, ใช้ `rop_type_id` ใน target ในการกรอง (เพราะมีข้อมูล FK ที่ไม่มีอยู่จริงในระบบ)
-- หลังโอนครบทุกตารางจะมีการ **validate** จำนวนแถว source vs target
----
-### Section 1 (`section-1`) — Core Data
-**วิธีโอน:** ใช้ `copyDataTables` (โอนตาม PK, รันซ้ำ insert เฉพาะแถวใหม่) + จัดการ `created_by`/`updated_by`
-- **permissions**: โอนจาก source ตามตารางอื่น; การ **เติม/อัปเดต permissions ให้ครบ** ทำแยกด้วย `npm run seed:permissions` (ใช้ข้อมูลจาก `src/assets/data/permissions.ts`)
-**ตารางที่ insert (ตามลำดับ):**
-| ลำดับ | ชื่อตาราง |
-|-------|------------|
-| 1 | company_master |
-| 2 | organizations |
-| 3 | systemlangaue |
-| 4 | users |
-| 5 | theme |
-| 6 | roles |
-| 7 | model_has_roles |
-| 8 | permissions |
-| 9 | role_has_permissions |
-| 10 | oauth_clients |
-**เงื่อนไขเพิ่มเติม:**
-- **organizations**, **systemlangaue**: อยู่ก่อน `users` จึง insert ด้วย **created_by / updated_by = null** ก่อน แล้วหลัง copy `users` จะ **คืนค่า created_by / updated_by** จาก source ไปอัปเดตใน target (`restoreUserRefsInTable`)
-- **permissions**: รัน `npm run seed:permissions` แยกเพื่อ seed/อัปเดตจาก `src/assets/data/permissions.ts` (unique key `name`; มีใน target แล้วจะ skip)
-- หลังโอนครบจะ **validate** จำนวนแถวของตารางใน section นี้
----
-### Section 2 (`section-2`)
-**วิธีโอน:** ใช้ `copyDataTables` (รันซ้ำ insert เฉพาะแถวใหม่)
-**ตารางที่ insert (ตามลำดับ):**
-| ลำดับ | ชื่อตาราง |
-|-------|------------|
-| 1 | owner_master |
-| 2 | activity_master |
-| 3 | activity_owner_ref_master |
-| 4 | storage_asset_master |
-| 5 | report_preferences |
-| 6 | rop_header |
-| 7 | rop_answer |
-| 8 | rop_gap_results |
-| 9 | rop_activity_advisory_topics |
-| 10 | rop_activity_advisory_comments |
+## API หลัก
----
-### Section 3 (`section-3`) — Consent
-**วิธีโอน:** ใช้ `copyDataTables` พร้อม **columnMapping** บางตาราง
+### `copyDataTables(connectionPool, params)`
-**ตารางที่ insert (ตามลำดับ):**
+โอนข้อมูลจาก source ไป target ตาม PK (รันซ้ำจะ insert เฉพาะแถวใหม่)
-| ลำดับ | ชื่อตาราง |
-|-------|------------|
-| 1 | cs_consent_type |
-| 2 | cs_consent_send_template |
-| 3 | thank_consent_msg |
-| 4 | cs_consent_send_template_form |
-| 5 | cs_consent_form_client |
-| 6 | cs_consent_form_result |
-| 7 | cs_consent_form_personal |
+**พารามิเตอร์**
-**เงื่อนไขเพิ่มเติม:**
-- **cs_consent_form_client**: ใช้ **columnMapping** — คอลัมน์ `updated_at` ใน target ใช้ค่าจากคอลัมน์ `created_at` ของ source เนื่องจากตารางใหม่ updated_at ถูกระบุว่าห้ามเป็นค่าว่าง
-- หลังโอนครบจะ validate จำนวนแถว
----
+| พารามิเตอร์ | ประเภท | คำอธิบาย |
+|-------------|--------|----------|
+| `tableNames` | `string[] \| string` | ชื่อตารางที่จะโอน (รองรับ alias `tablesName`) |
+| `options.pageSize` | `number` | จำนวนแถวต่อหน้าการดึงข้อมูล (default: 500) |
+| `options.batchSize` | `number` | จำนวนแถวต่อ batch insert (default: 500) |
+| `setDataOptions` | `SetDataOptions[]` | กำหนดค่าแทนคอลัมน์ก่อน insert |
+| `restoreUserRefsOptions` | `RestoreUserRefsTableOption[]` | ตารางที่ต้องคืนค่า created_by/updated_by หลังโอน |
+| `insteadValueOptions` | `InsteadValueOptions[]` | จัดการ FK ที่ไม่มีในตารางอ้างอิง (ensure row หรือ fallback) |
+| `validateAndUpdate` | `boolean` | `false` = validate เฉพาะอย่างเดียว, `true` = validate แล้วอัปเดตข้อมูลที่ไม่ตรงกัน |
-### Section 4 (`section-4`) — DSAR
+**ผลลัพธ์**
-**วิธีโอน:** ใช้ `copyDataTables` (รันซ้ำ insert เฉพาะแถวใหม่)
-**ตารางที่ insert (ตามลำดับ):**
-| ลำดับ | ชื่อตาราง |
-|-------|------------|
-| 1 | dsar_setting |
-| 2 | dsar_setting_users_pivot |
-| 3 | dsar_form |
-| 4 | dsar_req |
-| 5 | dsar_req_log |
-| 6 | dsar_req_case_access_data |
-| 7 | dsar_req_case_access_data_dtl |
-| 8 | dsar_req_case_del |
-| 9 | dsar_req_case_del_dtl |
-| 10 | dsar_managements |
-| 11 | dsar_req_case_consent |
-| 12 | dsar_req_case_consent_dtl |
+```ts
+{
+  totalRowsTransferred: number;
+  tableResults: { tableName: string; rowsTransferred: number }[];
+  restoreUserRefsResults: { tableName: string; rowsUpdated: number }[];
+  validateResults: {
+    tableName: string;
+    totalChecked: number;
+    mismatchCount: number;
+    insertedCount: number;
+    updatedCount: number;
+  }[];
+}
+```
 ---
-### Section 5 (`section-5`) — Incident
+### `restoreUserRefsInTable(sourcePool, targetPool, tableName, options?)`
-**วิธีโอน:** ใช้ `copyDataTables` (รันซ้ำ insert เฉพาะแถวใหม่)
+คืนค่า `created_by`, `updated_by` ใน target ให้ตรงกับ source (ใช้หลังโอนตารางที่เคย insert ด้วยค่าสองตัวนี้เป็น `null`)
-**ตารางที่ insert (ตามลำดับ):**
+```ts
+import { restoreUserRefsInTable } from "@gumin61/transfer-data-sdk";
-| ลำดับ | ชื่อตาราง |
-|-------|------------|
-| 1 | incident_form |
-| 2 | incodent_req |
-| 3 | incodent_req_log |
-| 4 | incident_estimate |
-| 5 | incident_estimate_log |
-| 6 | incident_agency_personal |
-| 7 | agency_users_pivot |
-| 8 | incident_with_person |
-| 9 | incident_with_person_log |
+await restoreUserRefsInTable(sourcePool, targetPool, "organizations", {
+  batchSize: 100,
+});
+```
 ---
-### Section 6 (`section-6`)
+### `createRestoreUserRefsOptions(tableNames, batchSize?)`
-**วิธีโอน:** ใช้ `copyDataTables` (รันซ้ำ insert เฉพาะแถวใหม่)
+สร้าง `RestoreUserRefsTableOption[]` สำหรับใช้กับ `restoreUserRefsOptions`
-**ตารางที่ insert (ตามลำดับ):**
+```ts
+import { createRestoreUserRefsOptions } from "@gumin61/transfer-data-sdk";
-| ลำดับ | ชื่อตาราง |
-|-------|------------|
-| 1 | pdpa_message_history |
-| 2 | pdpa_file_attach |
-| 3 | cs_consent_form |
-| 4 | cs_consent_form_content |
+const options = createRestoreUserRefsOptions(
+  ["organizations"],
+  2500
+);
+```
 ---
-### Section 7.1 (`section-7-1`)
-**วิธีโอน:** ใช้ `copyTableMaster` (insert เฉพาะแถวที่ PK ยังไม่มีใน target)
+## ตัวอย่างการใช้งานขั้นสูง
-**ตารางที่ insert (ตามลำดับ):**
+### โอนตารางที่มี FK ต้องใส่ null ก่อน
-| ลำดับ | ชื่อตาราง |
-|-------|------------|
-| 1 | ck_type_master |
-| 2 | consent_ck_scan |
-| 3 | consent_ck_scan_dtl |
-| 4 | ck_consent_form |
-| 5 | cs_consent_form_dtl |
-| 6 | ck_ref_master |
+กรณีโอน `organizations` ก่อน `users` → ยังไม่มี user ใน target จึงต้องใส่ `created_by`/`updated_by` เป็น `null` ก่อน แล้วคืนค่าหลังโอน `users` เสร็จ
-**หมายเหตุ:** ตาราง `ck_ref_master` มีข้อมูล FK ที่ไม่มีอยู่จริงในระบบต้นทาง จึงเข้าเงื่อนไขเดียวกันกับของ data_type_master ใน section-master-data
+```ts
+const result = await copyDataTables(
+  { sourcePool, targetPool },
+  {
+    tableNames: ["organizations", "users"],
+    setDataOptions: [
+      { tableName: "organizations", columnName: "created_by", value: null },
+      { tableName: "organizations", columnName: "updated_by", value: null },
+    ],
+    restoreUserRefsOptions: createRestoreUserRefsOptions(
+      ["organizations"],
+      100
+    ),
+    options: { pageSize: 500, batchSize: 500 },
+  }
+);
+```
----
+### จัดการ FK ที่ไม่มีในตารางอ้างอิง
-### Section 7.2 (`section-7-2`)
+เมื่อ source มี FK ชี้ไปยังแถวที่ไม่มีใน target สามารถกำหนด `insteadValueOptions` ให้:
+- หาแถวในตารางอ้างอิงจาก `lookup` ก่อน
+- ถ้าไม่พบ จะ INSERT `createData` แล้วใช้ `insertId` เป็นค่าของ FK
-**วิธีโอน:** ใช้ `copyDataTables` (รันซ้ำ insert เฉพาะแถวใหม่)
+```ts
+const result = await copyDataTables(
+  { sourcePool, targetPool },
+  {
+    tableNames: ["pii_master"],
+    insteadValueOptions: [
+      {
+        tableName: "pii_master",  // ตารางที่มี FK ที่ไม่มีอยู่จริง(ทำให้เกิดข้อผิดพลาด)
+        columnName: "data_type_id",  // Column FK ของตาราง
+        referenceTableName: "data_type_master",  // ตารางที่จะต้องกำหนดข้อมูลใหม่แทนไปก่อน
+        referenceColumnName: "data_type_id",  // Column PK
+        ensureReferenceRow: {  // Mock FK Data ขึ้นมา โดย fields จะต้องตรงกับในตารางที่จะ insert
+          lookup: { company_id: 1, data_type_name_en: "Mock FK Data" },
+          createData: {
+            company_id: 1,
+            data_type_name_th: "ข้อมูลทดแทน FK",
+            data_type_name_en: "Mock FK Data",
+            is_deleted: 0,
+            created_by: null,
+            updated_by: null,
+          },
+        },
+      },
+    ],
+    options: { pageSize: 500, batchSize: 500 },
+  }
+);
+```
-**ตารางที่ insert (ตามลำดับ):**
-access_master, access_assign_group_user, dsar_type_master, dsar_req_case_del_dtl_log, technical_measures_master, storage_asset_technical_measures, telescope_entries, telescope_entries_tags, cs_consent_timeout, migrations, oauth_refresh_tokens, subscriptions, tbcookielog, failed_jobs, storage_asset_databackup_location, subscribables, user_assign_role, access_assign_user, incident_type_master, notifications, prog_group_master, versions, dsar_incident_doc_status_master, oauth_access_tokens, otp, storage_asset_location_master, user_preference, job_batches, organization_measures_master, dsar_req_case_consent_dtl_log, dsar_req_case_consent_log, incident_req_risk_management, prog_master, new_licenses, group_menu_authority, group_menu_master, chanel_master, risk_master, tbonchangecookielog, dsar_req_case_del_log, tbonfirstactioncookielog, agency_tr_master, source_asset_master, activity_log
+### Validate และอัปเดตข้อมูลที่ไม่ตรงกัน
----
+- `validateAndUpdate: false` — ตรวจสอบและแสดง log เฉพาะอย่างเดียว ไม่แก้ไขข้อมูล
+- `validateAndUpdate: true` — ตรวจสอบแล้ว INSERT/UPDATE ข้อมูลที่ขาดหรือไม่ตรงกันให้ target ตรงกับ source
-## 4. สรุปเงื่อนไขเฉพาะของแต่ละ Section
+```ts
+const result = await copyDataTables(
+  { sourcePool, targetPool },
+  {
+    tableNames: ["users", "permissions"],
+    validateAndUpdate: true, // true = validate + update
+    options: { pageSize: 500, batchSize: 500 },
+  }
+);
-| Section | เงื่อนไขเพิ่มเติม |
-|---------|-------------------|
-| **master-data** | ใช้ `copyTableMaster`; data_type_master / rop_type_master มีการ insert จาก asset ถ้ายังไม่มีใน target |
-| **section-1** | organizations, systemlangaue insert ด้วย created_by/updated_by = null แล้วคืนค่าหลัง copy users; permissions เติม/อัปเดตแยกด้วย `npm run seed:permissions` (จาก assets/data/permissions.ts) |
-| **section-3** | cs_consent_form_client: columnMapping updated_at ← created_at (จาก source) |
-| **section-6** | cs_consent_form และ cs_consent_form_content ย้ายมาจากรอบ section-3 |
-| **section-7-1** | ใช้ copyTableMaster; ck_ref_master อาจมี FK ที่ไม่มีอยู่จริง |
-| **section-7-2** | ใช้ copyDataTables |
+if (result.validateResults.length > 0) {
+  console.table(result.validateResults);
+}
+```
 ---
-## 5. การตั้งค่าโอนข้อมูล
-- **Batch size / Page size**: กำหนดใน `.env` หรือ `src/config/transfer.config.ts` (เช่น `TRANSFER_BATCH_SIZE`, `TRANSFER_PAGE_SIZE`)
-  - ตารางที่มีคอลัมน์ LONGTEXT หรือข้อมูลต่อแถวใหญ่ แนะนำให้ลดค่า (เช่น 50–100) เพื่อไม่ให้เกิน `max_allowed_packet` และลดโอกาสข้อมูลผิดพลาด
-- **Database**: กำหนด connection ต้นทางและปลายทางใน `.env` และใช้ใน `src/config/db.source.js` / `src/config/db.target.js`
-- **ลำดับ/รายการตารางต่อ section**: แก้ใน `src/config/sections.config.ts`
+## สรุป Types ที่ Export
----
+```ts
+// ฟังก์ชัน
+copyDataTables(connectionPool, params): Promise<CopyDataTablesResult>
+restoreUserRefsInTable(sourcePool, targetPool, tableName, options?): Promise<{ rowsUpdated: number }>
+createRestoreUserRefsOptions(tableNames, batchSize?): RestoreUserRefsTableOption[]
+// Types
+ConnectionPool
+CopyDataTablesResult
+TableTransferResult
+RestoreUserRefsResult
+RestoreUserRefsTableOption
+ValidateTableResult
+SetDataOptions
+InsteadValueOptions
+TransferOptions
+```
-*เอกสารนี้อ้างอิงจากโครงสร้างและ config ในโปรเจกต์ ณ เวลาที่เขียน*
+---

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@gumin61/transfer-data-sdk",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "publishConfig": {
     "access": "public"
   },