DEAL — P2P TCG Trading Platform（手数料ゼロ）

Nền tảng web P2P cho người chơi TCG ở Nhật (Pokémon / One Piece) trao đổi thẻ trực tiếp, không thu phí. Mục tiêu cốt lõi: thu thập giá đóng (closing price) đáng tin cậy qua cơ chế give-to-get — muốn xem dữ liệu giá thị trường thì phải đóng góp ít nhất 1 giao dịch đã xác nhận.

Core loop MVP: List thẻ → Chat → Xác nhận giao dịch → Lưu giá (nhãn confirmed / self-reported).

Tech stack

• Next.js 15 (App Router) + TypeScript — full-stack 1 repo
• Prisma + SQLite (dev) — đổi sang Postgres khi deploy chỉ cần đổi DATABASE_URL
• Tailwind CSS 4, UI tiếng Nhật
• Vitest — unit test tầng service
• Auth: session cookie + email/password (bcrypt). LINE Login / SMS OTP → phase 2.

Cài đặt & chạy

Yêu cầu: Node.js 20+.

cd deal
npm install
npx prisma migrate dev   # tạo db + generate client + seed tự động
npm run dev              # → http://localhost:3000

Tài khoản demo (seed sẵn): [email protected] / password123 (4 tài khoản khác: taro|hanako|kenji|[email protected], cùng mật khẩu.)

Lệnh khác:

npm test        # unit tests (vitest)
npm run build   # production build + typecheck
npm run db:seed # chạy lại seed (idempotent)

Cấu trúc thư mục

deal/
├── CLAUDE.md              ← bản đồ dự án: làm gì đọc file nào
├── docs/                  ← tài liệu theo chủ đề; docs/api/ = API contract (nguồn chân lý)
├── prisma/
│   ├── schema.prisma      ← 8 bảng (users, cards, listings, conversations,
│   │                         messages, trades, price_records, sessions)
│   └── seed.ts            ← 5 users, 38 thẻ, 10 listing, 66 price records
├── src/
│   ├── app/               ← pages (App Router) + API route handlers
│   │   └── api/           ← routes: CHỈ validate + gọi service
│   ├── server/
│   │   ├── services/      ← business logic (unit test ở tests/)
│   │   ├── repositories/  ← mọi truy cập Prisma
│   │   ├── session.ts     ← session cookie (bảng sessions)
│   │   ├── validation.ts  ← zod schemas + "enum" values
│   │   └── errors.ts      ← ApiError + error response thống nhất
│   ├── components/        ← React components (client)
│   └── lib/
│       ├── api-client.ts  ← tầng gọi API duy nhất của frontend
│       └── types.ts       ← DTO dùng chung FE/BE
└── tests/                 ← vitest (28 tests)

Biến môi trường

Biến	Mặc định	Ghi chú
DATABASE_URL	file:./dev.db	SQLite dev; Postgres khi deploy
APP_URL	http://localhost:3000	URL gốc dùng trong link email
SMTP_HOST/PORT/USER/PASS/FROM	(trống)	Trống → email vào hộp thư dev /dev/mailbox. Muốn gửi Gmail thật: bật 2FA → tạo App Password tại myaccount.google.com/apppasswords → điền SMTP_HOST=smtp.gmail.com, SMTP_PORT=465, SMTP_USER=địa chỉ Gmail, SMTP_PASS=app password

Xem .env.example.

Xác thực (Phase 4)

• Đăng ký → nhận mail xác nhận (link hạn 24h). Chưa xác nhận: xem thoải mái nhưng không đăng tin/mua/comment/chat/trade được.
• Quên mật khẩu: link "パスワードをお忘れですか？" ở trang login → mail reset (hạn 1h) → đổi xong tự đăng xuất mọi thiết bị.
• Dev chưa có SMTP: mở /dev/mailbox để xem mail và bấm link.

Thiết kế quan trọng (đầy đủ: docs/business-rules.md + docs/overview.md)

• Tách 3 luồng: xác nhận giao dịch / rating / lưu giá. Giá được lưu NGAY khi trade chốt, không gate bằng rating (chống selection bias). Rating chưa có trong MVP.
• Chống khai láo giá: bên xác nhận sau phải nhập đúng số tiền bên khởi tạo đã khai (PRICE_MISMATCH nếu lệch).
• Tự chốt sau 7 ngày: trade pending không được phản hồi → self_reported (lazy-check khi có request, không cần cron).
• Ẩn danh từ schema: bảng price_records không có cột user nào.
• Give-to-get: GET /api/prices/:cardId trả 403 NEED_CONTRIBUTION (kèm teaser số record) nếu user chưa đóng góp giao dịch nào.
• Catalog chuẩn hóa: user chỉ chọn thẻ qua autocomplete từ bảng cards, condition là field bắt buộc.
• Rating blind-mutual (Phase 2): mỗi bên rate 1 lần sau khi trade chốt, ẩn đến khi cả 2 đã rate — chống trả đũa; ★ trung bình chỉ tính từ rating đã reveal.
• Flag giá bất thường (Phase 2): record lệch >50% median thị trường bị gắn ⚠ và loại khỏi stats/chart — chống thông đồng bơm giá phá model AI.
• Report user (Phase 2): nút 通報 trên listing.
• BOX thẻ sealed (Phase 3): loại sản phẩm riêng với condition シュリンク付き/なし, tab lọc riêng, dữ liệu giá riêng.
• Bình luận công khai (Phase 3): dưới mỗi listing, ai cũng đọc, đăng nhập mới viết.
• Luồng mua 購入希望 → 連携 (Phase 3): thay thế chat trực tiếp — seller thấy danh sách người muốn mua (kèm ★ uy tín) và toàn quyền chọn ai để mở chat riêng.
• 利用規約 & プライバシーポリシー (Phase 5): /terms + /privacy (bản mẫu, nên nhờ luật sư rà trước khi vận hành thật); đồng ý bắt buộc khi đăng ký + modal re-accept khi đổi TERMS_VERSION (src/lib/terms.ts — nhớ sync bản hardcode trong prisma/seed.ts); server chặn 403 TERMS_NOT_ACCEPTED.

Troubleshooting

Lỗi 500 ngẫu nhiên khi npm run dev (log: SyntaxError: Unexpected end of JSON input): dự án nằm trong thư mục OneDrive — OneDrive khóa file trong .next khi sync. Cách xử lý: tạm dừng OneDrive sync khi dev (icon OneDrive → 一時停止), hoặc bỏ sync thư mục deal (OneDrive 設定 → アカウント → フォルダーの選択), hoặc chuyển dự án ra ngoài OneDrive (vd C:\dev\deal) sau khi đã đưa code lên GitHub. Không chạy npm run build khi dev server đang chạy (cả hai cùng ghi .next).

Roadmap V3 (cần tài khoản/dịch vụ ngoài)

LINE Login · SMS OTP chống Sybil · push/email notification nhắc xác nhận · tích hợp Pokémon TCG API · cloud storage cho ảnh · deploy Vercel + Supabase · AI dự đoán giá.