CalisCoaching MVP — Nền tảng Hồ sơ Sức khỏe & Vận động Cá nhân
Dự án MVP web ưu tiên giao diện điện thoại (mobile-first), sử dụng Next.js (TypeScript), Supabase Auth & Postgres (RLS), và Tailwind CSS.
1. Mục tiêu & Ranh giới MVP
🎯 Trọng tâm MVP:
- Hồ sơ & Mục tiêu cá nhân (Agent B): Lưu thông tin kinh nghiệm, lịch rảnh, dụng cụ có sẵn, chỉ số tự khai (chiều cao, cân nặng theo ngày & nguồn). Không yêu cầu bệnh án y tế.
- Nhật ký đa hoạt động (Agent C): Ghi chép calisthenics, chạy bộ, cầu lông, đi bộ hoặc khác; thời lượng, mức mệt tự đánh giá (1-10) và ghi chú; phân biệt rõ lịch dự kiến và hoạt động thực tế.
- Bài tập calisthenics minh họa (Agent D): Buổi tập mẫu để trải nghiệm ghi kết quả vào hồ sơ; cơ chế chống ghi trùng (idempotency key); quy tắc xem lại lịch hoạt động gần nhau.
- Tương tác AI theo hồ sơ (Agent E): Tóm tắt hồ sơ có trích dẫn nguồn và khoảng thời gian; hỏi đáp theo hồ sơ; xin đồng ý trước khi chia sẻ dữ liệu và hỗ trợ rút lại đồng ý; tự động fallback sang bản mẫu có nhãn "Không dùng AI" khi thiếu cấu hình hoặc lỗi.
🚫 Ranh giới nghiêm ngặt (KHÔNG xây dựng trong MVP):
- KHÔNG xây chức năng Huấn luyện viên (HLV), kết nối hay phản hồi HLV.
- KHÔNG chia sẻ mã QR, không chia sẻ công khai dữ liệu cá nhân giữa người dùng.
- KHÔNG tích hợp Strava hay thiết bị đeo (wearable).
- KHÔNG tính toán dinh dưỡng, calo chi tiết.
- KHÔNG tích hợp thanh toán hay phân tích video bằng AI.
- KHÔNG tự động chẩn đoán y khoa, không kết luận trạng thái hồi phục, không tự động thay đổi tải tập hay sửa hồ sơ người dùng.
- KHÔNG sử dụng dữ liệu thật trong fixture, mã nguồn, log hoặc debug.
2. Yêu cầu hệ thống & Cài đặt cục bộ (Local Setup)
Yêu cầu tiên quyết:
- Node.js: >= 18.18 (khuyến nghị Node 20 LTS hoặc 22/24)
- npm: >= 9.x
- Supabase CLI (tùy chọn nếu chạy Supabase cục bộ) hoặc tài khoản Supabase Cloud.
Các bước khởi chạy dự án:
Bước 1: Sao chép tệp biến môi trường
cp .env.example .env.local
Mở .env.local và điền thông tin Supabase:
NEXT_PUBLIC_SUPABASE_URL: URL máy chủ Supabase (VD: http://127.0.0.1:54321 hoặc URL Supabase Cloud).NEXT_PUBLIC_SUPABASE_ANON_KEY: Khóa ẩn danh (Anon public key).SUPABASE_SERVICE_ROLE_KEY: Khóa quản trị Server (chỉ dùng ở server, không lộ ra client).
[!NOTE]
Khi chưa cấu hình .env.local, hệ thống vẫn khởi chạy an toàn ở chế độ kiểm tra độc lập (Standalone Mode). Giao diện sẽ hiển thị biểu ngữ cảnh báo rõ ràng và vô hiệu hóa các nút ghi dữ liệu trực tiếp, tuyệt đối không giả lập đăng nhập hoặc bỏ qua bảo mật.
Bước 2: Chạy kiểm thử tự động
npm run test
Kiểm tra hợp đồng dữ liệu TypeScript, bộ kiểm soát quyền ở Server, và chạy migration + RLS trên Postgres thật bằng PGlite (src/tests/rls-pglite.test.ts, không cần Docker hay Supabase).
npm run lint chưa dùng được: dự án chưa cài/cấu hình ESLint.
Bước 3: Khởi chạy máy chủ phát triển
npm run dev
Mở trình duyệt tại http://localhost:3000.
Bước 4: Build bản production
npm run build
3. Cơ sở dữ liệu, Migration & Kiểm tra quyền Row Level Security (RLS)
Tất cả bảng trong cơ sở dữ liệu đều được thiết kế theo nguyên tắc: Mỗi người dùng chỉ có quyền đọc/ghi dữ liệu của chính mình (auth.uid() = user_id). Tuyệt đối không có bảng quan hệ chia sẻ cho HLV hay bên thứ ba.
Danh sách 12 bảng trong MVP:
public.profiles: Hồ sơ người dùng (kinh nghiệm, lịch rảnh, dụng cụ).public.goals: Mục tiêu rèn luyện cá nhân.public.observations: Chỉ số tự quan sát / tự khai (cân nặng, chiều cao; không tạo điểm sức khỏe tổng hợp).public.activities: Nhật ký các hoạt động (calisthenics, chạy, cầu lông, đi bộ; phân biệt thực tế vs kế hoạch).public.programs: Giáo trình bài tập (gắn nhãn is_demo = true).public.sessions: Chi tiết các buổi tập trong giáo trình.public.session_results: Kết quả tự khai sau buổi tập (có ràng buộc idempotency_key chống ghi trùng).public.review_suggestions: Gợi ý xem lại lịch (quy tắc demo tĩnh, không tự đổi tải tập).public.ai_consents: Quản lý sự đồng ý chia sẻ dữ liệu với AI (phiên bản, phạm vi, trạng thái rút lại).public.ai_summaries: Ảnh chụp bản tóm tắt hồ sơ do AI hoặc template mẫu tạo.public.ai_conversations: Phiên hội thoại hỏi đáp theo hồ sơ.public.ai_messages: Tin nhắn hỏi đáp có lưu nguồn tham chiếu cụ thể.
Áp dụng migration vào Supabase:
supabase/migrations/20261027000001_mvp_schema_and_rls.sql: schema và RLS ban đầu.supabase/migrations/20261027000002_a_fixes_ownership_idempotency.sql: tự tạo hồ sơ khi đăng ký, chống ghi trùng, bảng AI chỉ ghi từ server, kiểm chủ sở hữu bản ghi cha, đánh dấu gợi ý cũ, sửa mặc định thời gian.supabase/migrations/20261027000003_goal_dates_check.sql: ngày kết thúc mục tiêu không sớm hơn ngày bắt đầu (khớp validateGoalDates trong contract).supabase/migrations/20261027000004_activity_duration_review_dedupe.sql: hoạt động tối đa 1440 phút; chặn trùng gợi ý xem lại lịch còn hiệu lực (cùng user, phiên bản quy tắc, bộ hoạt động đã sắp xếp).- Dữ liệu bài tập minh họa:
supabase/seed_demo.sql
Supabase CLI đã có trong devDependencies và supabase/config.toml đã cấu hình seed seed_demo.sql. Cần Docker Desktop đang chạy:
npx supabase start
npx supabase db reset
Lấy URL và khóa local cho .env.local (khóa local là khóa demo mặc định của Supabase CLI, không phải bí mật thật):
npx supabase status -o env
Kiểm tra RLS trên Supabase local:
docker exec -i supabase_db_CalisCoaching psql -U postgres -v ON_ERROR_STOP=1 < supabase/tests/rls_ownership_test.sql
Dừng: npx supabase stop.
Với Supabase Cloud: chạy lần lượt các tệp migration theo thứ tự tên rồi seed_demo.sql trong SQL Editor.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
