AGENTS.md, rules và skills: viết ‘sổ tay nhân viên’ cho agent

# AGENTS.md — banhmoc-oms

Hệ thống quản lý đơn hàng (Mộc OMS) cho chuỗi tiệm bánh Bánh Mộc.
Next.js App Router + TypeScript, Supabase (Postgres, Auth), Drizzle ORM, Zod, Tailwind + shadcn/ui.

## Lệnh
- Cài đặt: `npm install` (Node theo `.nvmrc`)
- Chạy local: `npm run dev` (cần `.env.local`, mẫu ở `.env.example`)
- Kiểm tra trước khi báo xong: `npm run typecheck && npm run lint && npx vitest run --reporter=dot`
- Một file test: `npx vitest run tests/unit/<ten-file>.test.ts`
- E2E: `npm run db:seed` rồi `npm run test:e2e`
- Migration: sửa `src/db/schema.ts` → `npm run db:generate` → đọc file SQL sinh ra. KHÔNG tự chạy migration lên database ngoài local.

## Quy ước dữ liệu (bắt buộc)
- Tiền: số nguyên VNĐ (`bigint`), không dùng số thực. Định dạng hiển thị bằng `formatVND` trong `src/lib/format.ts`.
- Thời gian: lưu `timestamptz`, hiển thị theo Asia/Ho_Chi_Minh qua `src/lib/time.ts`.
- Trạng thái đơn: `moi → da_xac_nhan → dang_lam → dang_giao → hoan_tat`, hoặc `da_huy`. Mọi thay đổi trạng thái đi qua `src/features/orders/status.ts` và ghi `order_status_history`.
- Mã đơn: `BM-YYMMDD-XXX`, sinh ở server, không sinh ở client.
- Số điện thoại: chuẩn hóa bằng `normalizePhone` trước khi lưu hoặc tìm.

## Kiến trúc
- Mỗi tính năng trong `src/features/<ten>/` (actions.ts, queries.ts, schema.ts, components/).
- Ghi dữ liệu qua server action; validate đầu vào bằng Zod ở server, kể cả khi client đã validate.
- Phân quyền theo vai trò `owner | manager | staff`; kiểm tra ở server và bằng RLS. Xem `docs/adr/0003-phan-quyen.md`.

## Ranh giới
- Không cài thư viện mới khi chưa hỏi.
- Không dùng `SUPABASE_SERVICE_ROLE_KEY` trong code chạy ở trình duyệt.
- Không sửa `.env*` (trừ `.env.example`), không đọc `node_modules/`, `.next/`, file lock.
- Không sửa hoặc xóa test để cho qua; sửa nguyên nhân gốc.

## Git
- Nhánh: `feat/...`, `fix/...`, `chore/...`. Commit theo Conventional Commits, tiếng Việt được.
- Mỗi PR một thay đổi nhỏ; mô tả PR nêu cách đã kiểm chứng.

## Tài liệu
- Yêu cầu: `docs/PRD.md`; spec từng tính năng: `docs/specs/`; quyết định kiến trúc: `docs/adr/`.
- Khi thay đổi ảnh hưởng spec, cập nhật spec trong cùng PR.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/chan-sua-env.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write --ignore-unknown" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/chan-sua-env.sh
# Agent gửi thông tin lời gọi công cụ dạng JSON qua stdin; lấy đường dẫn file định sửa
file=$(jq -r '.tool_input.file_path // empty')

case "$file" in
  *.env|*.env.*)
    if [[ "$file" != *.env.example ]]; then
      echo "Không được sửa file bí mật: $file. Hãy cập nhật .env.example và báo người dùng." >&2
      exit 2   # mã thoát 2: chặn hành động và gửi lý do lại cho agent
    fi
    ;;
esac
exit 0