# SKILL: Investigate — Điều tra luồng nghiệp vụ từ codebase

## Dự án: car-security-web (SMART BLOCKER)

| Thuộc tính | Giá trị |
|------------|---------|
| Codebase | `~/GMSTB/car-security-web` |
| Frontend | `app/` — Vue 3 + Vite + Pinia |
| Backend API | `api/` — NestJS + Prisma |
| Notification | `notification/` — NestJS cron + MSPF sync |
| Manifest | `manifest/flows.yaml` (74 luồng) |
| Branch git | `manifest/car-security-web` |

**Domain chính:** Auth, Home/Dashboard, Security ON/OFF, Geofence, Security Schedule, Device Installation, Notification, Payment, Mypage.

---

## Mục đích

Dùng skill này khi một luồng nghiệp vụ **chưa có tài liệu** hoặc cần xác minh
xem codebase hiện tại có những màn hình, API, use case, business rule nào.

Output của skill này là đầu vào cho skill **SRS**.

---

## Khi nào dùng

- Lần đầu bắt đầu sinh tài liệu cho một luồng
- Cần verify lại manifest hiện tại đã đúng chưa
- Có thay đổi lớn ở codebase cần sync lại với tài liệu

---

## Đầu vào cần cung cấp

```
flow_id:        <ví dụ: F001, F016, F029>
flow_name:      <ví dụ: Đăng nhập email/password>
codebase_path:  ~/GMSTB/car-security-web
manifest_path:  ~/gmstb-docs/manifest/flows.yaml
```

**Ví dụ luồng tham chiếu:**
- F001 — Đăng nhập email/password (`LoginView.vue`, FirebaseUI)
- F016 — Bật/tắt Security thủ công (`PUT /devices/activation`)
- F029 — Luồng lắp đặt thiết bị 3 bước (`MaintenanceInstallation.vue`)

---

## Hướng dẫn thực hiện cho AI Agent

### Bước 1 — Đọc manifest hiện tại

1. Đọc `manifest/flows.yaml` và tìm entry có `id` khớp với `flow_id`.
2. Đọc `manifest/screens.yaml` và lọc screen liên quan (nếu có `flow` ref).
3. Đọc `manifest/use-cases.yaml` và lọc use case liên quan.
4. Đọc `docs/flows/{flow_folder}/meta.yaml` nếu đã tồn tại.

> `flow_folder` = `{flow_id}-{flow-name-kebab}` (vd: `F001-dang-nhap-email-password`)

### Bước 2 — Điều tra codebase

Duyệt codebase theo thứ tự sau:

**2a. Tìm route / page (frontend `app/`):**
- File routing: `app/src/router/index.ts`
- Views: `app/src/views/`
- Keyword theo luồng (vd F001: `login`, `password-reset`; F016: `activation`, `security`; F029: `installation`, `maintenance`)

**2b. Tìm API endpoint (backend `api/`):**
- Controllers: `api/src/**/*.controller.ts`
- HTTP method + path + DTO
- Ví dụ F016: `PUT /devices/activation` trong device store/controller

**2c. Tìm business rule:**
- Pinia stores: `app/src/stores/`
- Service layer: `api/src/**/*.service.ts`
- Notification cron: `notification/src/app.service.ts` (Security schedule, geofence)

**2d. Tìm actor / permission:**
- Firebase auth guard trong `router/index.ts` → `authenticate()`
- Role Owner vs Member trong device/member stores

**2e. Tìm exception flow:**
- `apiErrorWithSignOutHandler` — sign out khi 401
- Payment block: `statusId=2` → `PaymentExpired`, `statusId=3` → chưa lắp đặt

### Bước 3 — So sánh với manifest

- Báo cáo screen trong code nhưng không có trong manifest (**missing**)
- Báo cáo screen trong manifest nhưng không tìm thấy trong code (**stale**)
- Tương tự với use cases và API endpoints

### Bước 4 — Tạo / Cập nhật file

**4a. Cập nhật `manifest/flows.yaml`** nếu phát hiện thông tin mới.

**4b. Thêm screen vào `manifest/screens.yaml`** (nếu missing).

**4c. Thêm use case vào `manifest/use-cases.yaml`** (nếu missing).

**4d. Tạo `docs/flows/{flow_folder}/meta.yaml`:**

```yaml
flow_id: F016
flow_name: "Bật/tắt Security thủ công"
module: Security
priority: P1
assignee: ""
started_at: "2026-06-23"
completed_at: ""

docs:
  srs:
    status: not_started
    reviewer: ""
    pr_url: ""
    reviewed_at: ""
    notes: ""
  bd:
    status: not_started
    reviewer: ""
    pr_url: ""
    reviewed_at: ""
    notes: ""
  dd:
    status: not_started
    reviewer: ""
    pr_url: ""
    reviewed_at: ""
    notes: ""

screens: []
use_cases: []
technical_notes: ""
```

### Bước 5 — Báo cáo kết quả

Output báo cáo gồm:
1. Tóm tắt luồng (1 đoạn)
2. Danh sách screens tìm được (path + component)
3. Danh sách API endpoints (method + path + mô tả)
4. Business rules quan trọng
5. Actors / roles
6. Exception flows
7. So sánh manifest (missing / stale)
8. File đã tạo/cập nhật

---

## Output checklist

- [ ] `manifest/flows.yaml` entry đã verify/cập nhật
- [ ] `manifest/screens.yaml` đã bổ sung screen mới (nếu có)
- [ ] `manifest/use-cases.yaml` đã bổ sung UC mới (nếu có)
- [ ] `docs/flows/{flow_folder}/meta.yaml` đã tạo/cập nhật
- [ ] Báo cáo investigate đầy đủ 8 mục ở Bước 5
