#โครงสร้างไดเรกทอรีของโปรเจกต์

ไม่ว่าคุณจะโคลนซอร์สโค้ดจาก Git หรือเริ่มต้นโปรเจกต์ด้วย create-nocobase-app โปรเจกต์ NocoBase ที่สร้างขึ้นมานั้น โดยพื้นฐานแล้วจะเป็น Monorepo ที่ใช้ Yarn Workspace ครับ/ค่ะ

#ภาพรวมไดเรกทอรีระดับบนสุด

ตัวอย่างด้านล่างนี้ใช้ my-nocobase-app/ เป็นไดเรกทอรีของโปรเจกต์นะครับ/คะ ซึ่งอาจมีความแตกต่างกันเล็กน้อยในแต่ละสภาพแวดล้อมครับ/ค่ะ

my-nocobase-app/
├── packages/              # ซอร์สโค้ดของโปรเจกต์
│   ├── plugins/           # ซอร์สโค้ดของปลั๊กอินที่กำลังพัฒนา (ยังไม่ได้คอมไพล์)
├── storage/               # ข้อมูลรันไทม์และเนื้อหาที่สร้างขึ้นแบบไดนามิก
│   ├── apps/
│   ├── db/
│   ├── logs/
│   ├── uploads/
│   ├── plugins/           # ปลั๊กอินที่คอมไพล์แล้ว (รวมถึงที่อัปโหลดผ่าน UI)
│   └── tar/               # ไฟล์แพ็กเกจปลั๊กอิน (.tar)
├── scripts/               # สคริปต์ยูทิลิตี้และคำสั่งเครื่องมือ
├── .env*                  # การกำหนดค่าตัวแปรสภาพแวดล้อมสำหรับสภาพแวดล้อมต่างๆ
├── lerna.json             # การกำหนดค่า Lerna Workspace
├── package.json           # การกำหนดค่าแพ็กเกจหลัก, ประกาศ workspace และสคริปต์
├── tsconfig*.json         # การกำหนดค่า TypeScript (ส่วนหน้า, ส่วนหลัง, การแมปพาธ)
├── vitest.config.mts      # การกำหนดค่าการทดสอบยูนิต Vitest
└── playwright.config.ts   # การกำหนดค่าการทดสอบ E2E ของ Playwright

#คำอธิบายไดเรกทอรีย่อย packages/

ไดเรกทอรี packages/ จะประกอบด้วยโมดูลหลักและแพ็กเกจที่สามารถขยายได้ของ NocoBase ครับ/ค่ะ โดยเนื้อหาจะขึ้นอยู่กับแหล่งที่มาของโปรเจกต์:

• โปรเจกต์ที่สร้างผ่าน create-nocobase-app: โดยค่าเริ่มต้น จะมีเพียง packages/plugins/ ซึ่งใช้สำหรับเก็บซอร์สโค้ดของปลั๊กอินที่กำหนดเองครับ/ค่ะ ไดเรกทอรีย่อยแต่ละอันเป็นแพ็กเกจ npm ที่เป็นอิสระต่อกัน
• เมื่อโคลนจาก Official Source Repository: คุณจะเห็นไดเรกทอรีย่อยอื่นๆ อีกมากมาย เช่น core/, plugins/, pro-plugins/, presets/ เป็นต้น ซึ่งแต่ละอันจะสอดคล้องกับแกนหลักของเฟรมเวิร์ก, ปลั๊กอินในตัว และโซลูชันที่ตั้งค่าไว้ล่วงหน้าอย่างเป็นทางการครับ/ค่ะ

ไม่ว่าจะเป็นกรณีใดก็ตาม packages/plugins คือตำแหน่งหลักสำหรับการพัฒนาและดีบักปลั๊กอินที่กำหนดเองครับ/ค่ะ

#ไดเรกทอรี storage/ สำหรับรันไทม์

storage/ ใช้เก็บข้อมูลที่สร้างขึ้นระหว่างรันไทม์และผลลัพธ์ของการบิลด์ครับ/ค่ะ โดยมีคำอธิบายไดเรกทอรีย่อยที่พบบ่อยดังนี้:

• apps/: การกำหนดค่าและแคชสำหรับสถานการณ์ที่มีหลายแอปพลิเคชัน
• logs/: บันทึกการทำงาน (Runtime logs) และผลลัพธ์การดีบัก
• uploads/: ไฟล์และทรัพยากรสื่อที่ผู้ใช้อัปโหลด
• plugins/: ปลั๊กอินแบบแพ็กเกจที่อัปโหลดผ่าน UI หรือนำเข้าผ่าน CLI
• tar/: แพ็กเกจปลั๊กอินแบบบีบอัดที่สร้างขึ้นหลังจากรันคำสั่ง yarn build <plugin> --tar

โดยทั่วไปแล้ว แนะนำให้เพิ่มไดเรกทอรี storage ลงใน .gitignore และจัดการแยกต่างหากเมื่อทำการ Deploy หรือสำรองข้อมูลครับ/ค่ะ

#การกำหนดค่าสภาพแวดล้อมและสคริปต์ของโปรเจกต์

• .env, .env.test, .env.e2e: ใช้สำหรับการรันในเครื่อง, การทดสอบยูนิต/การรวมระบบ และการทดสอบแบบ End-to-End ตามลำดับครับ/ค่ะ
• scripts/: เก็บสคริปต์การบำรุงรักษาที่ใช้บ่อย (เช่น การเริ่มต้นฐานข้อมูล, เครื่องมือช่วยในการ Deploy เป็นต้น)

#พาธการโหลดปลั๊กอินและลำดับความสำคัญ

ปลั๊กอินอาจมีอยู่ในหลายตำแหน่งครับ/ค่ะ เมื่อ NocoBase เริ่มทำงาน ระบบจะโหลดปลั๊กอินตามลำดับความสำคัญดังนี้:

1. ปลั๊กอินเวอร์ชันซอร์สโค้ดใน packages/plugins (ใช้สำหรับการพัฒนาและดีบักในเครื่อง)
2. ปลั๊กอินเวอร์ชันแพ็กเกจใน storage/plugins (อัปโหลดผ่าน UI หรือนำเข้าผ่าน CLI)
3. แพ็กเกจ Dependency ใน node_modules (ติดตั้งผ่าน npm/yarn หรือเป็นส่วนหนึ่งของเฟรมเวิร์ก)

หากมีปลั๊กอินชื่อเดียวกันอยู่ในทั้งไดเรกทอรีซอร์สโค้ดและไดเรกทอรีแพ็กเกจ ระบบจะให้ความสำคัญกับการโหลดเวอร์ชันซอร์สโค้ดก่อนครับ/ค่ะ เพื่อให้ง่ายต่อการแก้ไขและดีบักในเครื่อง

#โครงสร้างไดเรกทอรีของปลั๊กอิน

สร้างปลั๊กอินโดยใช้ CLI:

yarn pm create @my-project/plugin-hello

โครงสร้างไดเรกทอรีที่สร้างขึ้นมีดังนี้:

packages/plugins/@my-project/plugin-hello/
├── dist/                    # ผลลัพธ์การบิลด์ (สร้างเมื่อจำเป็น)
├── src/                     # ไดเรกทอรีซอร์สโค้ด
│   ├── client/              # โค้ดส่วนหน้า (บล็อก, หน้า, โมเดล เป็นต้น)
│   │   ├── plugin.ts        # คลาสหลักของปลั๊กอินฝั่งไคลเอนต์
│   │   └── index.ts         # จุดเริ่มต้นฝั่งไคลเอนต์
│   ├── locale/              # ทรัพยากรหลายภาษา (ใช้ร่วมกันทั้งส่วนหน้าและส่วนหลัง)
│   ├── swagger/             # เอกสาร OpenAPI/Swagger
│   └── server/              # โค้ดฝั่งเซิร์ฟเวอร์
│       ├── collections/     # การกำหนด คอลเลกชัน
│       ├── commands/        # คำสั่งที่กำหนดเอง
│       ├── migrations/      # สคริปต์การย้ายฐานข้อมูล (Database Migration)
│       ├── plugin.ts        # คลาสหลักของปลั๊กอินฝั่งเซิร์ฟเวอร์
│       └── index.ts         # จุดเริ่มต้นฝั่งเซิร์ฟเวอร์
├── index.ts                 # การส่งออกสำหรับเชื่อมต่อส่วนหน้าและส่วนหลัง
├── client.d.ts              # การประกาศประเภทสำหรับส่วนหน้า
├── client.js                # ผลลัพธ์การบิลด์ส่วนหน้า
├── server.d.ts              # การประกาศประเภทสำหรับส่วนหลัง
├── server.js                # ผลลัพธ์การบิลด์ส่วนหลัง
├── .npmignore               # การกำหนดค่าไฟล์ที่ละเว้นเมื่อ Publish
└── package.json

หลังจากบิลด์เสร็จสมบูรณ์ ไดเรกทอรี dist/ และไฟล์ client.js, server.js จะถูกโหลดเมื่อมีการเปิดใช้งานปลั๊กอินครับ/ค่ะ ในระหว่างการพัฒนา คุณเพียงแค่แก้ไขไดเรกทอรี src/ เท่านั้นครับ/ค่ะ ก่อนที่จะ Publish ให้รันคำสั่ง yarn build <plugin> หรือ yarn build <plugin> --tar