From 58380ab81d0e3adb47f43f1da76c4a0ebb1490f6 Mon Sep 17 00:00:00 2001 From: Alireza Hassani Date: Sun, 2 Aug 2026 17:24:04 +0330 Subject: [PATCH] Add CONTEXT.md with full new-device setup guide. Co-authored-by: Cursor --- CONTEXT.md | 178 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 CONTEXT.md diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..ba98ef4 --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,178 @@ +# Balout Pastry — Backend (setup context) + +NestJS API for شیرینی‌فروشی بلوط. Serves the admin Dashboards SPA (and future customer apps). + +Repo: `https://git.meshkee.com/BaloutPastry/backend.git` +Dashboards repo: `https://git.meshkee.com/BaloutPastry/dashboards.git` + +## Stack + +- NestJS 11 / TypeScript +- Prisma 6 + PostgreSQL 16 (Docker Compose) +- JWT access + refresh tokens (bcrypt password hashes) +- Parspack S3-compatible object storage (prefix `balout/`) + +## Prerequisites + +- Node.js **20+** (LTS recommended) +- npm +- Docker + Docker Compose (for local Postgres) +- S3 credentials if you need media upload (can leave blank for auth/users-only local work) + +## Setup on a new device + +```bash +git clone https://git.meshkee.com/BaloutPastry/backend.git +cd backend + +cp .env.example .env +# Fill S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY if you need uploads +# Change JWT_* secrets before any shared/staging use + +npm install +npm run db:up # Postgres on 127.0.0.1:5434 +npx prisma migrate deploy # apply migrations +npx prisma generate # if client missing after install + +npm run create-super-admin -- --phone 09120000000 --password secret123 +# optional: --first علی --last رضایی --title "جناب آقای" + +npm run start:dev # http://localhost:3100/api/v1 +``` + +Health check: `GET http://localhost:3100/api/v1/auth/me` → `401` without token is expected (server is up). + +### Pair with Dashboards + +1. Keep this API on **3100** +2. In dashboards: `VITE_API_BASE_URL=http://localhost:3100/api/v1` +3. Backend `CORS_ORIGIN` must include `http://localhost:5173` +4. Log in with the super-admin phone/password you created + +## Scripts + +| Command | What it does | +|---------|----------------| +| `npm run start:dev` | Nest watch mode → `http://localhost:3100/api/v1` | +| `npm run start:prod` | Run compiled `dist/main` | +| `npm run build` | Compile Nest → `dist/` | +| `npm run db:up` | `docker compose up -d` (Postgres) | +| `npm run db:down` | Stop Postgres container | +| `npm run prisma:migrate` | Create/apply migrations in dev | +| `npm run prisma:deploy` | Apply existing migrations (CI / new device) | +| `npm run prisma:generate` | Regenerate Prisma Client | +| `npm run create-super-admin` | Create first `superAdmin` user | +| `npm run lint` | ESLint | + +## Environment + +Copy from `.env.example`. Do **not** commit `.env`. + +| Variable | Notes | +|----------|--------| +| `DATABASE_URL` | Prisma connection string (default → local Docker on **5434**) | +| `POSTGRES_*` | Used by Docker Compose | +| `PORT` | API port, default **3100** | +| `CORS_ORIGIN` | Comma-separated origins; include dashboard URL | +| `JWT_ACCESS_SECRET` / `JWT_REFRESH_SECRET` | Change from example values | +| `JWT_ACCESS_EXPIRES_IN` / `JWT_REFRESH_EXPIRES_IN` | e.g. `15m` / `7d` | +| `STORAGE_DISK` | `s3` for Parspack | +| `S3_*` | Endpoint, bucket, public URL, keys | +| `MEDIA_MAX_FILE_SIZE_MB` | Upload size cap | + +Ports are intentional vs Meshkee: API **3100**, Postgres host **5434** (Meshkee uses 3000 / 5432). + +## Auth rules + +- Login: `POST /auth/login` with `{ "cellNumber": "09…", "password": "…" }` +- Only `admin` and `superAdmin` can log in to the admin API/dashboard +- Only `superAdmin` can assign `admin` or `superAdmin` roles +- `customer` users exist for orders / future customer UI +- Access token in `Authorization: Bearer …`; refresh via `POST /auth/refresh` + +## Main routes (`/api/v1`) + +| Area | Methods | +|------|---------| +| Auth | `POST /auth/login`, `/auth/refresh`, `/auth/logout`, `GET /auth/me` | +| Users | CRUD + `PATCH /users/:id/role`, `/password` + addresses under `/users/:id/addresses` | +| Flavors | CRUD | +| Categories | tree CRUD + `GET\|PUT /categories/:id/options` | +| Products | CRUD (options must match category templates); list filters `q`, `categoryId`, `minPrice`, `maxPrice` | +| Orders | `GET /orders`, `GET /orders/:id`, `POST /orders`, `PATCH /orders/:id/status` | +| Media | `POST /media/upload?kind=main\|gallery\|temp` | +| Settings | districts, shipping exceptions, branches | + +Guards: most routes require JWT + `admin`/`superAdmin`. Role changes require `superAdmin`. + +## Orders + +Create body example: + +```json +{ + "customerId": "...", + "deliveryType": "pickup", + "branchId": "...", + "note": "optional", + "items": [ + { "productId": "...", "quantity": 2, "optionIds": ["..."] } + ] +} +``` + +For shipping: `deliveryType: "shipping"` + `shippingAddressId` (from user addresses). Prices/names are snapshotted. Display code: `BL-{number}`. + +## Domain notes + +- Prices are integer **تومان** +- Phone numbers: `09` + 9 digits (English digits) +- User titles/categories are fixed Persian enums in `src/users/users.constants.ts` + +## Project layout + +``` +prisma/ schema + migrations +scripts/ create-super-admin.ts +src/ + auth/ JWT login, refresh, guards, roles + users/ users + addresses + flavors/ + categories/ + products/ + orders/ + media/ uploads + settings/ districts, shipping, branches + storage/ S3 driver + prisma/ PrismaModule / PrismaService + main.ts global prefix api/v1, CORS, ValidationPipe +docker-compose.yml local Postgres +``` + +## Production sketch + +```bash +cp .env.example .env # real secrets, DB, CORS, S3 +npm ci +npx prisma migrate deploy +npm run build +npm run start:prod +``` + +Ensure Postgres is reachable via `DATABASE_URL` and `CORS_ORIGIN` lists the real dashboard origin(s). + +## Common issues + +| Symptom | Likely cause | +|---------|----------------| +| `ECONNREFUSED` / Prisma errors | Postgres not up → `npm run db:up`, check `DATABASE_URL` / port **5434** | +| Port already in use | Another process on 3100 or 5434 | +| Login rejected for valid user | Role is `customer`, or wrong phone format | +| CORS errors from dashboard | `CORS_ORIGIN` missing `http://localhost:5173` | +| Upload fails | Missing/invalid `S3_*` keys or endpoint | +| `User already exists` on create-super-admin | That phone is already in DB | + +## Related + +- Dashboards setup: clone `BaloutPastry/dashboards` and read `CONTEXT.md` +- Short API overview also in `README.md`