timelapse-2/memory.md

Construction Timelapse — Session Memory

Tổng quan dự án

Hệ thống timelapse construction monitoring.

• Repo: /Users/kingkong/Documents/code/timelaspe-2
• Stack: Next.js + NestJS + PostgreSQL (Drizzle) + Python (device-agent) + Redis
• Package manager: Bun (KHÔNG dùng npm vì workspace protocol không hoạt động với nexus registry của môi trường)
• Registry: Luôn thêm --registry https://registry.npmjs.org/ khi cài package từ public npm

---

Kiến trúc hiện tại

construction-timelapse/
├── apps/
│   ├── api-server/          # NestJS — API backend
│   ├── web-dashboard/       # Next.js 14 — Dashboard UI
│   ├── worker/              # (stub)
│   └── device-agent/        # Python — Pi agent (chưa implement)
├── packages/
│   ├── shared-types/        # Shared TypeScript types/enums
│   └── config/             # tsconfig.base
└── docs/
    ├── api/                 # (trống)
    └── firmware/            # (trống)

---

Workspace config (quan trọng!)

• KHÔNG dùng apps/* trong workspaces — device-agent là Python

• Workspace config đúng:

  "workspaces": ["apps/api-server", "apps/web-dashboard", "apps/worker", "packages/*"]
  

• @shared-types KHÔNG hợp lệ — đổi thành @shared/types ở mọi nơi (package.json + tsconfig.json)

• Luôn cd vào workspace trước khi bun add

---

Phase 1 — Trạng thái: ✅ HOÀN THÀNH

Backend (apps/api-server)

Chạy dev: cd apps/api-server && bun run dev Build: cd apps/api-server && bun run build ✅

Auth module (src/modules/auth/):

• auth.module.ts, auth.controller.ts, auth.service.ts — stub endpoints
• strategies/jwt.strategy.ts, strategies/google.strategy.ts — OAuth stubs

Devices module (src/modules/devices/):

• devices.controller.ts — 4 endpoints:
  • POST /v1/devices/:deviceId/heartbeat — X-API-Key auth
  • GET /v1/devices — list
  • GET /v1/devices/:id — detail
  • GET /v1/devices/:id/heartbeats — history
• devices.service.ts — heartbeat logic + API key verify
• devices.repository.ts — Drizzle queries
• dto/heartbeat.dto.ts — class-validator DTO

Common guards/decorators (src/common/):

• guards/api-key.guard.ts — X-API-Key header guard
• decorators/api-key.decorator.ts — @ApiKey() decorator

Các module stub (đều rỗng, chỉ để compile):

• modules/orgs/, modules/projects/, modules/captures/, modules/videos/, modules/alerts/, realtime/

Dashboard (apps/web-dashboard)

Chạy dev: cd apps/web-dashboard && bun run dev Build: cd apps/web-dashboard && bun run build ✅

• pages/index.tsx — Dashboard home (stats cards + recent devices)
• pages/devices/index.tsx — Device list
• pages/devices/[id].tsx — Device detail
• components/StatsCard.tsx, DeviceCard.tsx
• hooks/useDashboardStats.ts, useDevices.ts
• Tailwind CSS v3 + PostCSS đã setup

---

Database (Drizzle Schema)

File: apps/api-server/src/db/schema.ts

• Enum: org_status, project_status, device_status, capture_status, video_status, alert_severity, alert_type, alert_state, user_role, command_result_status
• Tables: organizations, projects, users, memberships, sessions, magic_links, devices, device_heartbeats, captures, videos, video_jobs, commands, alert_rules, alerts, audit_logs, activity_logs
• Lưu ý: table names trong Drizzle schema là lowercase (devices, deviceHeartbeats) nhưng khi truy vấn phải dùng devices, deviceHeartbeats đúng tên export

---

Các lỗi đã gặp và cách fix

1. @shared-types → đổi package name thành @shared/types
2. device-agent (Python) trong npm workspaces → loại khỏi workspaces
3. npm install không hoạt động → dùng bun install --registry https://registry.npmjs.org/
4. bun add với nexus registry → luôn thêm --registry https://registry.npmjs.org/
5. db không export được → import từ database.module.ts riêng
6. experimentalDecorators thiếu → thêm vào packages/config/tsconfig.node.json
7. rootDir conflict → bỏ rootDir khỏi tsconfig base

---

TODO — Phase tiếp theo

1. Phase 2: Auth thực sự (JWT login, refresh token, Google OAuth)
2. Phase 2: Database migration + seed data (drizzle-kit push)
3. Phase 2: Projects/Orgs CRUD endpoints
4. Phase 2: Device-agent (Python) heartbeat sender
5. Phase 2: Realtime WebSocket (Socket.io) cho device status
6. Phase 2: Dashboard auth flow (login/logout)

---

Lệnh dev nhanh

# Backend
cd apps/api-server && bun run dev  # http://localhost:3001

# Dashboard
cd apps/web-dashboard && bun run dev  # http://localhost:3000

# API test (heartbeat stub)
curl -X POST http://localhost:3001/v1/devices/test-device-1/heartbeat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dev-key-123" \
  -d '{"deviceId":"test-device-1","apiKey":"dev-key-123","status":"online","storageFreeGb":50,"capturesToday":12,"firmwareVersion":"1.0.0"}'