From acfd250bec1729d8381a904eae9b24a1153ef862 Mon Sep 17 00:00:00 2001 From: Tanakit Phetkumjad Date: Sun, 22 Nov 2026 03:57:30 +0700 Subject: [PATCH] Refresh setup and project status docs Document required service secrets, database migrations, event topology setup, and service startup order. Update implementation status and note when HR Jobs switches from mock data to the API. --- docs/developer-guide.md | 22 ++++++++++++---------- docs/getting-started.md | 24 ++++++++++++++++++++++-- 2 files changed, 34 insertions(+), 12 deletions(-) diff --git a/docs/developer-guide.md b/docs/developer-guide.md index 883d87e..64d069b 100644 --- a/docs/developer-guide.md +++ b/docs/developer-guide.md @@ -40,6 +40,8 @@ node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))" Lifecycle ตรวจ Service Token ที่ Identity เซ็น (เรียก `deletion-eligibility`) ด้วย `LIFECYCLE_SERVICE_SECRET_IDENTITY` — ตั้งค่าเดียวกันที่ `.env` ของ Lifecycle และ Identity (สร้างด้วยคำสั่งข้างบน) +ชื่อตัวแปรเป็นรูป `<ผู้รับ>_SERVICE_SECRET_<ผู้เรียก>` หนึ่งค่าต่อหนึ่งคู่ ตอนนี้มี 7 คู่: `IDENTITY_SERVICE_SECRET_GATEWAY`, `IDENTITY_SERVICE_SECRET_LIFECYCLE`, `IDENTITY_SERVICE_SECRET_NOTIFICATION`, `JOB_SERVICE_SECRET_LIFECYCLE`, `JOB_SERVICE_SECRET_IDENTITY` (Directory กรอง `category`), `LIFECYCLE_SERVICE_SECRET_JOB` (กระทบยอดโควตา), `LIFECYCLE_SERVICE_SECRET_IDENTITY` — ตารางว่าขาดตัวไหนแล้วกระทบอะไรอยู่ใน [getting-started.md](getting-started.md) §2 ถ้าเพิ่ม Internal API คู่ใหม่ ให้เพิ่มทั้งใน `.env.example` และตารางนั้น + ### 1.2 Gateway หลัง proxy เมื่อวาง Gateway หลัง proxy ให้ตั้ง `EDGE_SHARED_SECRET` เป็นค่าเดียวกันที่ proxy และ Gateway แล้วให้ proxy ส่ง `X-Edge-Secret` พร้อม `x-client-ip` ซึ่งเป็น IP ผู้ใช้จริง โดย proxy ต้องเขียนทับ header ทั้งสองจากคำขอภายนอก และปิดการเข้าถึง Gateway โดยตรงจากอินเทอร์เน็ต @@ -115,7 +117,7 @@ apps// 6. **ห้าม commit** `.env`, คีย์ JWT, รหัสผ่านจริง (มีแค่ `.env.example`) 7. ตรวจสิทธิ์ที่ **ทุก Service** ด้วย Guard (อย่าพึ่ง Gateway อย่างเดียว) และตรวจความเป็นเจ้าของข้อมูล เช่น `company_id` ใน Token ต้องตรงกับทรัพยากร 8. **Contract ล็อกแล้ว — ใช้ชนิดข้อมูลจาก `@internpath/contracts` เท่านั้น** (Event E01-E18 ทุกตัวและ Enum ใน `data-schema.md` §2.1 อยู่ใน `libs/contracts/src/`) ห้ามประกาศ payload/enum ซ้ำในแอป การเปลี่ยนชื่อ/ชนิด/ความหมายของฟิลด์หรือค่า Enum ต้องบอกใน PR (ติดป้าย "contract change"), แก้ `docs/` และ `libs/contracts` พร้อมกัน และให้ PM อนุมัติ — เพิ่มฟิลด์ที่ไม่บังคับ (`?`) ได้โดยไม่ต้องรออนุมัติ แต่ต้องบอกใน PR -9. **ทุก Service ที่ใช้ Prisma ต้องตั้ง `output = "../generated/client"` ใน `generator client` ของ `schema.prisma`** และ import `PrismaClient`/ชนิดจาก `../../generated/client` (ไม่ใช่ `@prisma/client`) — output ค่าตั้งต้นเป็นที่เดียวกันของทุก Service ทำให้ Client เขียนทับกันตอน generate ทั้ง repo ใน CI (`apps/*/generated/` ถูก gitignore) มีเทสต์ตรวจใน `libs/common/test/repo/prisma-outputs.spec.ts` (ยอมให้ใช้ค่าตั้งต้นได้ไม่เกิน 1 Service ระหว่างที่ Service นั้นยังไม่ได้ย้าย — ปัจจุบันคือ `job`) +9. **ทุก Service ที่ใช้ Prisma ต้องตั้ง `output = "../generated/client"` ใน `generator client` ของ `schema.prisma`** และ import `PrismaClient`/ชนิดจาก `../../generated/client` (ไม่ใช่ `@prisma/client`) — output ค่าตั้งต้นเป็นที่เดียวกันของทุก Service ทำให้ Client เขียนทับกันตอน generate ทั้ง repo ใน CI (`apps/*/generated/` ถูก gitignore) มีเทสต์ตรวจใน `libs/common/test/repo/prisma-outputs.spec.ts` (ทั้ง 5 Service ย้ายครบแล้ว — Service ใหม่ต้องตั้งเหมือนกัน) 10. **ส่ง E03 ทุกการเปลี่ยนสถานะประกาศ** พร้อม `company_id` และ `entity_version` ที่เพิ่มขึ้น (รวมทุกแถวที่เข้า `VERIFYING` ซึ่งส่งคู่กับ `JobSubmitted`) และตรวจ `submission_id === current_submission_id` ก่อนรับ `JobVerified` — รายละเอียดใน [data-schema.md](data-schema.md) §8.2 ## 5. Workflow การทำงาน @@ -222,17 +224,17 @@ npx prisma migrate dev --name <ชื่อการเปลี่ยนแป ## 7. ยังไม่มีอะไรบ้าง (รู้ไว้จะได้ไม่งง) -โครงตอนนี้รันได้และทดสอบผ่านบาง Service แล้ว ส่วนที่ยังต้องทำหรือเชื่อมต่อมีดังนี้: +สถานะ ณ 2026-11-22 (main หลัง #102) — ส่วนที่ยังต้องทำหรือเชื่อมต่อมีดังนี้: -- [ ] Prisma migration แรกของทุก Service และตารางเฉพาะ Service — **Verification และ Identity ทำแล้ว**; Job, Lifecycle และ Notification ยังมีแค่ `outbox_events` / `processed_events` +- [x] Prisma migration ของทุก Service (Identity, Job, Verification, Lifecycle, Notification) — รันตามคำสั่งใน [getting-started.md](getting-started.md) §3 - [x] Outbox relay และ Consumer — อยู่ใน `libs/common` (`OutboxWriter`, `OutboxRelay`, `EventConsumer`, `MessagingModule`); แต่ละ Service ต้องผูกกับงานของตนตาม §6.3 -- [ ] Service Token สำหรับ `/internal/**` และ allow-list ผู้เรียก — Identity ใช้ `ServiceTokenGuard` จาก `libs/common` แล้ว; Job/Lifecycle/Notification ยังต้องผูกเมื่อเพิ่ม endpoint ภายใน -- [x] Gateway: การ Route/Proxy, ตรวจ Token, Rate Limit, Denylist -- [ ] การลงทะเบียน `JwtAuthGuard` ใน Service ที่เพิ่ม endpoint ซึ่งต้องล็อกอิน (Identity ใช้แล้ว) -- [ ] **ลบบัญชี:** กติกาตัดสินแล้ว (api-contract §4.2/§9, data-schema §2.3 — PM 2026-11-17) ยังไม่มีโค้ด: Tester ทำ `POST /users/me/deletion-request` ใน `apps/identity` (เรียก `request()` แล้ว `complete()` ซิงโครนัส; PR ต้องให้ SA รีวิว), `GET /internal/v1/users/{user_id}/deletion-eligibility` ใน Lifecycle, client ฝั่ง Identity แทน provider ที่ fail-closed อยู่ตอนนี้ และ consumer E15 ของ Lifecycle — ยังไม่ควรแสดงฟังก์ชันลบบัญชีให้ผู้ใช้จนกว่าจะเสร็จ -- [ ] Scheduler (SLA, Reconciliation โควตา, Fail-safe 5 นาที) -- [ ] หน้าเว็บของแต่ละ Role (หน้า Auth/Account และหน้าแรกมีแล้ว; หน้า Admin เสียบเข้า Admin Shell กลางที่ PM ทำ — ตารางเจ้าของหน้าอยู่ใน [README](../README.md) หัวข้อ 11) -- [ ] โครงเว็บรวม (Header, Footer, เมนูตามบทบาท, Admin Shell, หน้านโยบายความเป็นส่วนตัว) — PM +- [x] Service Token สำหรับ `/internal/**` และ allow-list ผู้เรียก — Identity, Job และ Lifecycle ใช้ `ServiceTokenGuard` แล้ว; Service ที่เพิ่ม endpoint ภายในใหม่ทำตาม §6.1 และเพิ่ม secret คู่ใหม่ตาม §1.1 +- [x] Gateway: การ Route/Proxy, ตรวจ Token, Rate Limit (รวม `POST /advisor-links/students`), Denylist — ค้าง: ตอนเปิดก่อน Identity ต้องรอรอบดึง denylist 30 วินาทีกว่าจะหาย 503 (SA จะให้ลองใหม่ถี่ขึ้นจนกว่าจะดึงสำเร็จครั้งแรก) +- [x] `JwtAuthGuard` ใน Service ที่มี endpoint ซึ่งต้องล็อกอิน (ทุก Service แล้ว) +- [x] **ลบบัญชี:** `POST /users/me/deletion-request` (Identity), `GET /internal/v1/users/{user_id}/deletion-eligibility` (Lifecycle) และผู้รับ E15 ทำแล้ว +- [ ] Scheduler — ทำแล้ว: SLA (Lifecycle), กระทบยอดโควตา และล้างรอบรายงาน (Job); **ค้าง:** Fail-safe 5 นาทีของ `VERIFYING` (อยู่ใน #92 ที่ยังไม่ merge) และปิดประกาศอัตโนมัติเมื่อถึง `application_deadline` (งานถัดไปของ Junior) +- [ ] หน้าเว็บของแต่ละ Role — ทำแล้ว: Auth/Account, หน้าแรก, ค้นหางาน/รายละเอียดงาน (API จริง), Company Directory, หน้านักศึกษา, หน้าอาจารย์, หน้า Admin ของ Identity และ Verification; **ค้าง:** หน้า HR Jobs ยังใช้ข้อมูลจำลองจนกว่า #92 จะ merge — ตารางเจ้าของหน้าอยู่ใน [README](../README.md) หัวข้อ 11 +- [x] โครงเว็บรวม (Header, Footer, เมนูตามบทบาท, Admin Shell, หน้านโยบายความเป็นส่วนตัว) — PM - [ ] Dockerfile ของ Service ยังไม่เคยรัน; `docker compose --profile infra up -d postgres rabbitmq mailpit` รันผ่านแล้ว (2026-11-13) ส่วน **MinIO ดึง image ไม่ได้** (`minio/minio` บน Docker Hub ใช้ไม่ได้ และ `quay.io/minio/minio` ตอบ 401) จึงเปลี่ยนเป็น **RustFS** (`rustfs/rustfs:1.0.6`, PM ตัดสิน 2026-11-18): ทดสอบด้วย `S3StorageService` จริง — อัปโหลด 5 MB, Signed URL, หมดอายุ, ลบ (idempotent), public bucket — ผ่าน 13/13; ครั้งแรกหลัง `pnpm infra:up` ให้รัน `pnpm infra:init-buckets` (สร้าง bucket ด้วย region `us-east-1` เพราะ `auto` ถูกปฏิเสธตอน `CreateBucket` และตั้ง policy ให้ public bucket อ่านได้); ใช้เฉพาะ dev/สาธิตในเครื่อง ส่วนสาธิตจริงใช้ Cloudflare R2 - [ ] การสาธิตผ่าน Cloudflare ([architecture.md](architecture.md) §8.1): Worker proxy `/api/*` + `API_ORIGIN`, ตรวจ `X-Edge-Secret` / CORS / IP ผู้ใช้ที่ Gateway, ข้อความ "ระบบหลังบ้านออฟไลน์" ใน Front, ลิงก์อีเมลจาก `WEB_BASE_URL` - [x] `docker-compose.yml`: Postgres / RabbitMQ / RustFS / Mailpit และพอร์ตของ Service ทั้ง 6 ตัว (gateway, identity, job, verification, lifecycle, notification) bind เฉพาะ `127.0.0.1` และมี `restart: unless-stopped` (พอร์ตของเว็บ 3100 ยังไม่ปรับ เพราะอยู่ใน PR ที่แก้บริการ web) diff --git a/docs/getting-started.md b/docs/getting-started.md index 6375f3d..d17799f 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -19,7 +19,16 @@ pnpm install # ติดตั้ง + build libs/* อัต pnpm keys:generate # พิมพ์ JWT_PRIVATE_KEY / JWT_PUBLIC_KEY → วางลง .env ``` -ก่อนเปิด Gateway ให้สร้าง `IDENTITY_SERVICE_SECRET_GATEWAY` ด้วยตาม [developer-guide.md §1.1](developer-guide.md#11-ตั้งค่า-jwt-และ-service-secret-ก่อนเปิด-gateway) +จากนั้นสร้าง Service secret ทุกคู่ใน `.env` ตาม [developer-guide.md §1.1](developer-guide.md#11-ตั้งค่า-jwt-และ-service-secret-ก่อนเปิด-gateway) (แต่ละค่า ≥ 32 ตัวอักษร ใช้ค่าเดียวกันทั้งฝั่งผู้เรียกและผู้รับ เพราะอยู่ใน `.env` ไฟล์เดียว) — ถ้าเว้นว่าง Service จะไม่เริ่มหรือตอบ 503 ในฟีเจอร์ที่เกี่ยวข้อง: + +| ตัวแปร | ใช้ตอน | ขาดแล้วเป็นอย่างไร | +| :--- | :--- | :--- | +| `IDENTITY_SERVICE_SECRET_GATEWAY` | Gateway ดึง denylist จาก Identity | Gateway ไม่เริ่ม | +| `IDENTITY_SERVICE_SECRET_LIFECYCLE`, `JOB_SERVICE_SECRET_LIFECYCLE` | Lifecycle เรียก Identity (ชื่อ/ติดต่อ) และ Job (โควตา) | Lifecycle ไม่เริ่ม | +| `LIFECYCLE_SERVICE_SECRET_JOB` | Job ถาม Lifecycle ตอนกระทบยอดโควตา | กระทบยอดโควตาไม่ทำงาน | +| `LIFECYCLE_SERVICE_SECRET_IDENTITY` | Identity ถาม Lifecycle ก่อนลบบัญชี | ลบบัญชีตอบ 503 | +| `IDENTITY_SERVICE_SECRET_NOTIFICATION` | Notification หาผู้รับและอีเมลจาก Identity | Event ที่ต้องหาผู้รับล้มซ้ำจนเข้า DLQ ไม่มีแจ้งเตือน | +| `JOB_SERVICE_SECRET_IDENTITY` | Identity ถาม Job ว่าบริษัทไหนมีประกาศในสายงาน (Directory `?category=`) | ตัวกรองสายงานใน Company Directory ตอบ 503 | ## 3. รัน @@ -27,10 +36,20 @@ pnpm keys:generate # พิมพ์ JWT_PRIVATE_KEY / JWT_PUBLIC_KEY pnpm infra:up # Postgres, RabbitMQ, RustFS (S3), Mailpit pnpm infra:init-buckets # ครั้งแรกเท่านั้น: สร้าง bucket ใน RustFS (ไฟล์เรซูเม่/โลโก้) pnpm storage:check # (ไม่บังคับ) ตรวจ storage: อัปโหลด Signed URL หมดอายุ ลบ โลโก้สาธารณะ; กับ R2: pnpm storage:check -- --env .env.r2 +pnpm infra:topology # สร้างคิวผู้รับ Event ทุก Service ล่วงหน้า (รันซ้ำได้) pnpm --filter @internpath/identity start:dev # รัน Service เดียวแบบ watch (แทน identity ด้วย job, verification, ...) pnpm --filter @internpath/web dev # เว็บ http://localhost:3100 ``` +**สร้างตารางในฐานข้อมูล** (ครั้งแรก และทุกครั้งที่ `git pull` แล้วมีโฟลเดอร์ใหม่ใน `apps/*/prisma/migrations`) — Postgres สร้างฐานข้อมูลว่างให้ 5 ตัวตอน `pnpm infra:up` ครั้งแรก แต่ตารางต้องสร้างด้วย migration ของแต่ละ Service; Prisma CLI ไม่อ่าน `.env` ที่ราก repo จึงต้อง export URL ของฐานข้อมูลก่อน (Git Bash): + +```bash +export $(grep -E '^[A-Z]+_(DATABASE|DIRECT)_URL=' .env | xargs) +for s in identity job verification lifecycle notification; do pnpm --filter @internpath/$s exec prisma migrate deploy; done +``` + +**ลำดับการเปิด Service:** Identity ก่อน แล้ว Job, Verification, Lifecycle, Notification และ **Gateway เป็นตัวท้าย** — Gateway ปฏิเสธคำขอที่ล็อกอินด้วย `503 UPSTREAM_UNAVAILABLE` จนกว่าจะดึง denylist จาก Identity สำเร็จ (fail-closed) ถ้าเปิด Gateway ก่อน Identity จะได้ 503 ไปจนถึงรอบดึงถัดไป (ทุก 30 วินาที) • เปิดผู้รับ Event ให้ครบก่อนสร้างข้อมูล ไม่เช่นนั้น Event ที่ส่งก่อนผู้รับมีคิวจะหาย (ป้องกันได้ด้วย `pnpm infra:topology` ข้างบน) + | Service | Port | Health | API Docs (dev) | | :--- | :---: | :--- | :--- | | gateway | 3000 | `/health` | `/docs` | @@ -76,7 +95,8 @@ pnpm --filter @internpath/web dev # เว็บ http://localhost: - Prisma ล็อกที่ **6.x** (Prisma 7+ เปลี่ยนวิธีตั้งค่า ต้องย้ายก่อนอัปเกรด) และ TypeScript ล็อกที่ 5.6 ผ่าน `pnpm.overrides` - `libs/common` และ `libs/contracts` ต้อง build ก่อน (`dist/`) แอปถึง import ได้ — `pnpm install` ทำให้อัตโนมัติ ถ้าแก้โค้ดใน libs ให้รัน `pnpm --filter "./libs/*" build` -- Migration ของ Prisma: **Verification** (สไลซ์ 1-2) และ **Identity** (ฐานข้อมูลพื้นฐาน) มีแล้ว ส่วน Job, Lifecycle และ Notification ยังมีแค่ตารางร่วม (`outbox_events`/`processed_events`) — เขียนตาม [data-schema.md](data-schema.md) และขั้นตอนใน [developer-guide.md](developer-guide.md) §6.2 +- Migration ของ Prisma: ทุก Service มีแล้ว (Identity, Job, Verification, Lifecycle, Notification) — รันด้วยคำสั่งใน §3 "สร้างตารางในฐานข้อมูล"; เพิ่ม/แก้ตารางตาม [data-schema.md](data-schema.md) และขั้นตอนใน [developer-guide.md](developer-guide.md) §6.2 - Prisma Client ของแต่ละ Service generate ไป `apps//generated/client` (ไม่ commit) — รัน `pnpm --filter "./apps/*" --if-present prisma:generate` หลัง `pnpm install` และทุกครั้งที่ `schema.prisma` เปลี่ยน - เพิ่ง `git pull` แล้วเจอ error เรื่อง Prisma/คิว/โมดูลหาย → ดูขั้นตอนใน [developer-guide.md](developer-guide.md) §9 (สิ่งที่ต้องทำตามหลัง merge รายครั้ง) - หลัง `pnpm infra:up` ให้รัน `pnpm infra:topology` หนึ่งครั้ง เพื่อสร้างคิวผู้รับ Event ของทุก Service ล่วงหน้า (ไม่เช่นนั้น Event ที่ Service หนึ่งส่งก่อนที่ผู้รับจะเคยเปิดจะหาย) +- หน้า HR Jobs ของเว็บใช้ข้อมูลจำลองอยู่จนกว่า HR Jobs API ของ Job (#92) จะ merge — หลังจากนั้นค่าเริ่มต้นเรียก API จริง และตั้ง `NEXT_PUBLIC_HR_JOBS_MOCK=true` เมื่ออยากใช้ข้อมูลจำลอง