Thai Honda - Smart Factory

# Spec: Notification Stock Alert — แจ้งเตือนอัตโนมัติเมื่อ Stock ต่ำกว่า Minimum

> สำหรับ Dev — พร้อม implement

---

## ภาพรวม

เปลี่ยนระบบ notification จาก "แจ้งเฉพาะตอน user กด search ที่หน้า Stock Retrieval" → เป็น "แจ้งอัตโนมัติทันทีที่ stock ต่ำกว่า minimum" โดยเก็บ notification ใน DB แทน localStorage

---

## กฎหลัก

1. **แจ้ง 1 ครั้งต่อ 1 part** จนกว่า stock กลับ >= minimum

2. **ไม่แจ้งซ้ำ** ตราบใดที่ stock ยังต่ำอยู่

3. **แจ้งใหม่ได้** ถ้า stock กลับปกติแล้วต่ำอีกรอบ

4. **Global notification** — ทุกคนเห็นเหมือนกัน ไม่ต้อง config role

5. **ไม่มี seen/unseen mode** — กระดิ่งแสดง noti ที่ยัง unresolved ทั้งหมดเสมอ (หายจากกระดิ่งเมื่อ stock กลับปกติเท่านั้น)

---

## 1. Database — สร้างตาราง `notify_log`

```sql

CREATE TABLE notify_log (

  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),

  notify_category VARCHAR(50) NOT NULL,  -- เช่น 'stock_alert'

  ref_id          VARCHAR(100) NOT NULL, -- part code (ma_part_code)

  description     TEXT,                  -- รายละเอียด เช่น "P-BRG-6205 : Bearing 6205 — Stock: 3 < Min: 10"

  is_resolved     BOOLEAN DEFAULT false, -- stock กลับปกติแล้วหรือยัง

  created_date    TIMESTAMPTZ DEFAULT NOW()

);

CREATE INDEX idx_notify_log_unresolved ON notify_log (ref_id, notify_category) WHERE is_resolved = false;

```

**Prisma model:**

```prisma

model notify_log {

  id              String   @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid

  notify_category String   @db.VarChar(50)

  ref_id          String   @db.VarChar(100)

  description     String?

  is_resolved     Boolean  @default(false)

  created_date    DateTime @default(now()) @db.Timestamptz()

}

```

---

## 2. Backend — เช็ค Stock หลัง Part Ship

**ไฟล์:** `src/modules/call-monitor/part-ship/part-ship.service.ts`

**Logic เพิ่มหลัง ship สำเร็จ:**

```typescript

// หลังจาก UPDATE part_stock_item.status = 'SHIPPED' สำเร็จแล้ว

async function checkAndNotifyLowStock(maPartId: string) {

  // 1. นับ stock ปัจจุบัน

  const currentStock = await prisma.part_stock_item.count({

    where: {

      part_stock_detail: { ma_part_id: maPartId },

      status: 'STOCK',

    },

  });

  // 2. ดึง minimum_qty

  const part = await prisma.ms_ma_part.findUnique({

    where: { id: maPartId },

    select: { ma_part_code: true, ma_part_name: true, minimum_qty: true },

  });

  if (!part || part.minimum_qty <= 0) return;

  // 3. เช็คว่าต่ำกว่า min มั้ย

  if (currentStock >= part.minimum_qty) return;

  // 4. เช็คว่ามี unresolved alert อยู่แล้วมั้ย

  const existing = await prisma.notify_log.findFirst({

    where: {

      notify_category: 'stock_alert',

      ref_id: part.ma_part_code,

      is_resolved: false,

    },

  });

  if (existing) return; // เคยแจ้งแล้ว ยังไม่ resolved

  // 5. INSERT notify_log

  await prisma.notify_log.create({

    data: {

      notify_category: 'stock_alert',

      ref_id: part.ma_part_code,

      description: `${part.ma_part_code} : ${part.ma_part_name} — Stock: ${currentStock} < Min: ${part.minimum_qty}`,

      is_resolved: false,

    },

  });

}

```

---

## 3. Backend — Resolve ตอน Stock-In

**ไฟล์:** service ที่ทำ stock-in (Inspection Good / รับของเข้าคลัง)

**Logic เพิ่มหลัง stock-in สำเร็จ:**

```typescript

// หลังจาก INSERT part_stock_item (status = 'STOCK') สำเร็จแล้ว

async function resolveAlertIfStockRecovered(maPartId: string) {

  const currentStock = await prisma.part_stock_item.count({

    where: {

      part_stock_detail: { ma_part_id: maPartId },

      status: 'STOCK',

    },

  });

  const part = await prisma.ms_ma_part.findUnique({

    where: { id: maPartId },

    select: { ma_part_code: true, minimum_qty: true },

  });

  if (!part) return;

  // ถ้า stock กลับ >= minimum → resolve alert

  if (currentStock >= part.minimum_qty) {

    await prisma.notify_log.updateMany({

      where: {

        notify_category: 'stock_alert',

        ref_id: part.ma_part_code,

        is_resolved: false,

      },

      data: { is_resolved: true },

    });

  }

}

```

---

## 4. Backend — API Endpoints

**สร้าง module ใหม่:** `src/modules/notify-log/`

### GET /api/v1/notify-log/active

ดึง notification ที่ยัง unresolved (สำหรับ Frontend poll แสดงในกระดิ่ง)

```typescript

// Response

{

  data: [

    {

      id: "uuid",

      notify_category: "stock_alert",

      ref_id: "P-BRG-6205",

      description: "P-BRG-6205 : Bearing 6205 — Stock: 3 < Min: 10",

      created_date: "2026-05-20T10:30:00Z"

    }

  ],

  total: 5

}

```

**Logic:** ดึง notify_log ที่ `is_resolved = false` เรียงตาม `created_date DESC` จำกัด 15 รายการ

### POST /api/v1/notify-log/mark-seen

> ไม่ต้องทำ — ไม่มี seen mode

---

## 5. Frontend — เปลี่ยน useNotifications

**ไฟล์:** `packages/shared/feature/notification/hooks/use-notifications.ts`

**เปลี่ยนจาก:**

- เก็บ noti ใน localStorage

- เพิ่ม noti เฉพาะตอน user กด search

**เป็น:**

- Poll API `GET /api/v1/notify-log/active` ทุก 60 วินาที

- แสดง noti ที่ยัง unresolved ทั้งหมดในกระดิ่ง (ไม่มี seen/unseen)

- Badge = จำนวน noti ที่ยัง unresolved

- noti หายจากกระดิ่งเมื่อ stock กลับปกติ (is_resolved = true) เท่านั้น

- เสียง 🔔 ดังเมื่อมี noti ใหม่ (เทียบ count กับรอบก่อน)

```typescript

// Pseudo-code

const { data } = useQuery({

  queryKey: ['notify-log-active'],

  queryFn: () => fetch('/api/v1/notify-log/active'),

  refetchInterval: 60_000, // poll ทุก 1 นาที

});

const badgeCount = data?.total ?? 0; // แสดงจำนวน unresolved ทั้งหมด

```

---

## 6. Frontend — กระดิ่ง (NotificationBell)

**ไม่เปลี่ยน UI** — ยังใช้ popover + badge เหมือนเดิม

**เปลี่ยนแค่ data source + behavior:**

- Badge = จำนวน noti ที่ `is_resolved = false` (unresolved)

- Popover แสดง noti จาก API (ไม่เกิน 15 ตัว)

- **ไม่มี seen mode** — เปิดกระดิ่ง badge ไม่หาย (ยังแสดงจำนวน unresolved อยู่)

- noti หายจาก popover เมื่อ stock กลับปกติเท่านั้น (backend resolve)

---

## 7. สิ่งที่ไม่ต้องแก้

- ❌ แถบแดงในตาราง Stock Retrieval — ยังใช้ logic เดิม

- ❌ เสียง notification — ยังใช้ Web Audio API เดิม

- ❌ ไม่ต้องเพิ่ม role/permission

- ❌ ไม่ต้องทำ Cron Job (stock เปลี่ยนผ่าน Part Ship เท่านั้น)

- ❌ ลบ `notifyLowStockParts()` ใน `useStockRetrievalLocation.ts` ออกได้ (เพราะ backend จัดการแทนแล้ว)

---

## 8. ไฟล์ที่ต้องแก้/สร้าง

| ไฟล์ | Action | รายละเอียด |

|---|---|---|

| `prisma/schema.prisma` | แก้ | เพิ่ม model `notify_log` |

| `src/modules/notify-log/` | สร้างใหม่ | controller, service, repository |

| `src/modules/call-monitor/part-ship/part-ship.service.ts` | แก้ | เพิ่ม `checkAndNotifyLowStock()` หลัง ship |

| service ที่ทำ stock-in | แก้ | เพิ่ม `resolveAlertIfStockRecovered()` หลัง stock-in |

| `packages/shared/feature/notification/hooks/use-notifications.ts` | แก้ | เปลี่ยนจาก localStorage → poll API |

| `packages/shared/feature/stock-retrieval/hooks/useStockRetrievalLocation.ts` | แก้ | ลบ `notifyLowStockParts()` |

---

## 9. Seed Query — รันครั้งแรกตอน Deploy

> รันครั้งเดียวหลัง deploy เพื่อ INSERT notify_log สำหรับ part ที่ stock ต่ำกว่า min อยู่แล้ว ณ ปัจจุบัน

> (เพราะ part เหล่านี้ไม่เคยผ่าน Part Ship flow ใหม่ จึงยังไม่มี record ใน notify_log)

```sql

INSERT INTO notify_log (notify_category, ref_id, description, is_resolved, created_date)

SELECT

  'stock_alert',

  p.ma_part_code,

  p.ma_part_code || ' : ' || p.ma_part_name || ' — Stock: ' || COALESCE(stock.current_stock, 0) || ' < Min: ' || p.minimum_qty,

  false,

  NOW()

FROM ms_ma_part p

LEFT JOIN (

  SELECT

    psd.ma_part_id,

    COUNT(psi.id) AS current_stock

  FROM part_stock_detail psd

  JOIN part_stock_item psi ON psi.part_stock_detail_id = psd.id

  WHERE psi.status = 'STOCK'

  GROUP BY psd.ma_part_id

) stock ON stock.ma_part_id = p.id

WHERE p.is_active = true

  AND p.is_deleted = false

  AND p.minimum_qty > 0

  AND COALESCE(stock.current_stock, 0) < p.minimum_qty

  -- ไม่ INSERT ซ้ำถ้ามี record อยู่แล้ว (กรณีรัน query ซ้ำ)

  AND NOT EXISTS (

    SELECT 1 FROM notify_log nl

    WHERE nl.ref_id = p.ma_part_code

      AND nl.notify_category = 'stock_alert'

      AND nl.is_resolved = false

  );

```

**หมายเหตุ:** รัน query นี้ 1 ครั้งหลัง deploy ฟีเจอร์ใหม่ หลังจากนั้น Part Ship flow จะจัดการ INSERT ให้อัตโนมัติ

---

## 10. Flow Diagram

```

Part Ship (เบิกอะไหล่)

  │

  ├─ UPDATE part_stock_item.status = 'SHIPPED'

  │

  ├─ นับ stock ที่เหลือ (status = 'STOCK')

  │

  ├─ stock < minimum_qty?

  │   ├─ NO → จบ

  │   └─ YES → มี unresolved alert อยู่แล้ว?

  │       ├─ YES → จบ (ไม่แจ้งซ้ำ)

  │       └─ NO → INSERT notify_log → กระดิ่ง 🔔

  │

Stock-In (รับอะไหล่เข้าคลัง)

  │

  ├─ INSERT part_stock_item (status = 'STOCK')

  │

  ├─ นับ stock ใหม่

  │

  ├─ stock >= minimum_qty?

  │   ├─ NO → จบ

  │   └─ YES → UPDATE notify_log SET is_resolved = true

  │

Frontend (ทุก 1 นาที)

  │

  ├─ GET /api/v1/notify-log/unseen

  │

  ├─ มี noti ใหม่ (created_date > lastSeenDate)?

  │   ├─ NO → จบ

  │   └─ YES → badge +N + เสียง 🔔

```