Linear Flow discipline + organization #224

src/services/ExecuteOfficerProfileService.ts

@@ -129,14 +129,23 @@ export interface ExecutionContext {
 /**
  * Service สำหรับสร้าง/อัปเดตทะเบียนประวัติข้าราชการ (Profile) หลังออกคำสั่งบรรจุ
  *
- * ถูกออกแบบมาเพื่อแก้ปัญหา "Circular Dependency" ระหว่าง API Org กับ API บรรจุ
- * โดยให้ฝั่งบรรจุส่ง resultData กลับมา แล้วฝั่ง Org ประมวลผลสร้าง profile เอง
- * ที่ต้นทาง (Linear Flow) แทนการเรียกซ้อนกันกลับไปมา
+ * ใช้กับ commandType: C-PM-01, 02, 14
  *
  * - endpoint /org/command/excexute/create-officer-profile เรียกผ่าน service นี้ (thin wrapper)
- * - consumer ใน rabbitmq handler เรียกผ่าน service นี้โดยตรง (no HTTP loopback)
+ * - consumer ใน rabbitmq handler เรียกผ่าน service นี้โดยตรง (Linear Flow)
  *
  * Behavior ทั้งหมด preserve จาก CommandController.CreateOfficeProfileExcecute ต้นฉบับ
+ *
+ * Batch semantics: all-or-nothing — ประมวลผลทุกคนภายใต้ transaction เดียว (sequential)
+ * ถ้าคนใด throw จะ rollback ทั้ง batch และ propagate error ออกไป (ล้มเหลวทั้งหมด)
+ * ถ้าทุกคนสำเร็จจะ return result รายงาน success count
+ *
+ * ⚠️ หมายเหตุ Keycloak: operations (createUser/addUserRoles/removeUserRoles/updateUserAttributes)
+ * ทำภายใน transaction เพื่อ preserve behavior เดิม — Keycloak ไม่สามารถ rollback ได้
+ * ถ้า DB rollback หลังจาก Keycloak operation สำเร็จ → Keycloak จะถูกเปลี่ยนไปแล้ว
+ *
+ * Design note: แก้ปัญหา "Circular Dependency" ระหว่าง API Org กับ API บรรจุ โดยให้ฝั่งบรรจุ
+ * ส่ง resultData กลับมา แล้วฝั่ง Org ประมวลผลสร้าง profile เองที่ต้นทาง แทนการเรียกซ้อนกัน
  */
 export class ExecuteOfficerProfileService {
   private commandRepository = AppDataSource.getRepository(Command);