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` เมื่ออยากใช้ข้อมูลจำลอง