# CMS (Next.js + Refine) — checklist deploy production

CMS quản trị bài viết / danh mục / media — **gọi cùng backend Nest** với public web, **không** có Google OAuth trên UI CMS.

**Thứ tự:** backend trước — [`backend/docs/deploy-backend-checklist.md`](../../backend/docs/deploy-backend-checklist.md).

---

## File mẫu env

Xem [`../.env.example`](../.env.example) và [`../DEPLOYMENT.md`](../DEPLOYMENT.md). Production build **fails** nếu `NEXT_PUBLIC_API_BASE_URL` thiếu, trỏ localhost, hoặc không dùng `https://`.

---

## Biến môi trường (CMS)

Chỉ các biến **đã xuất hiện** trong codebase CMS:

| Biến | Bắt buộc | Ghi chú |
|------|-----------|---------|
| `NEXT_PUBLIC_API_BASE_URL` | **Có** | Gốc API Nest (production: **HTTPS**, không dấu `/` cuối). Dùng cho `fetch` tới `/auth/*`, posts, categories, media, upload rewrite trong `next.config.ts`. |

**Không** đặt secret backend (`DATABASE_URL`, `JWT_*`, `GOOGLE_*`, v.v.) vào CMS — chỉ URL API **public** là `NEXT_PUBLIC_*`.

Các file tham chiếu: `src/providers/auth-provider.ts`, `src/providers/data-provider.ts`, `src/app/login/page.tsx`, `next.config.ts`.

---

## Phụ thuộc backend

1. API đã deploy; **`GET <API>/health`** → `ok: true`.
2. **`CORS_ALLOWED_ORIGINS`** trên backend phải **gồm origin CMS production** (ví dụ `https://cms.example.com`) — cùng cơ chế `credentials: true` như web public.
3. Admin đã tồn tại (bootstrap/seed) và đăng nhập được bằng **email + mật khẩu** — không dùng Google trên CMS.

---

## Auth — giả định hiện tại (không đổi hành vi)

| Mục | Chi tiết |
|-----|----------|
| Đăng nhập | Chỉ **`POST /auth/login`** với email/password (`auth-provider.ts`). |
| Google | **Không** dùng trên CMS. |
| Access token | Lưu **`localStorage`** key **`accessToken`** (Bearer gửi kèm request Refine). |
| Hồ sơ | Sau login, gọi **`GET /auth/me`**, lưu snapshot **`authUser`** (JSON) cho `getIdentity`. |
| Refresh | **`POST /auth/logout`** + `credentials: "include"` — cookie refresh do backend set khi login (cùng pattern public web / CMS). |
| **`/auth/me`** | Backend vẫn trả **`permissions`** (các quyền gắn role) — cần cho guard/refine. |
| **PhoneVerifiedGuard** | Trong backend chỉ gắn endpoint **beta** `GET /auth/account-gate-test`; **không** chặn các API CMS (posts, categories, media, …). Nếu sau này thêm guard lên route admin, cần hồi quy lại checklist này. |

**Rủi ro hồi quy:** User chỉ tạo bằng **Google** (`passwordHash: null`) **không** đăng nhập CMS bằng mật khẩu — đúng thiết kế; admin vẫn là tài khoản có mật khẩu + role CMS.

---

## Bootstrap SUPER_ADMIN (backend)

Trên máy có `.env` trỏ DB production (hoặc job CI một lần):

- `BOOTSTRAP_SUPER_ADMIN_EMAIL`
- `BOOTSTRAP_SUPER_ADMIN_PASSWORD` (≥ 8 ký tự)

Hoặc chạy sau khi DB đã có roles:

```bash
cd backend
npm run bootstrap:super-admin
```

Xem [`backend/README.md`](../../backend/README.md). **Gỡ mật khẩu bootstrap** khỏi env sau khi đã đăng nhập và đổi mật khẩu thực tế.

---

## Thứ tự deploy (khuyến nghị)

1. **Deploy backend** — env, migrate, build, start.
2. **`npm run prisma:migrate:deploy`** (hoặc tương đương trên host).
3. **Bootstrap super admin** (hoặc `prisma:seed` nếu workflow của bạn tạo admin lần đầu).
4. **Đặt env CMS** — ít nhất `NEXT_PUBLIC_API_BASE_URL` trỏ tới API production.
5. **`npm ci` / `npm install`** trong `cms/`.
6. **`npm run build`**
7. **`npm run start`** (mặc định script dùng cổng **3001** — chỉnh trên platform nếu cần `PORT` động).
8. **Kiểm tra:** đăng nhập CMS → **`/auth/me`** (DevTools / Network) có **`permissions`** → mở dashboard posts/categories/media.

---

## Khi login CMS lỗi — checklist nhanh

- `NEXT_PUBLIC_API_BASE_URL` sai, thiếu, hoặc không HTTPS khi page là HTTPS.
- Backend **`POST /auth/login`** lỗi (401, 5xx).
- **CORS:** origin CMS không nằm trong `CORS_ALLOWED_ORIGINS`.
- **`accessToken`** / **`authUser`** không lưu (blocked storage, lỗi JS).
- User không có **role/permissions** trong DB — kiểm tra seed và `/auth/me`.

---

## Scripts npm (`cms/package.json`)

| Mục | Lệnh |
|-----|------|
| Dev | `npm run dev` (port **3001**, Webpack) |
| Build | `npm run build` |
| Start production | `npm run start` (port **3001**) |

---

## Liên quan

- Deploy API: [`backend/docs/deploy-backend-checklist.md`](../../backend/docs/deploy-backend-checklist.md)
- Deploy web public: [`web/docs/deploy-web-checklist.md`](../../web/docs/deploy-web-checklist.md)
- Smoke test auth web (không áp dụng Google cho CMS): [`web/docs/beta-auth-smoke-test.md`](../../web/docs/beta-auth-smoke-test.md)