pos/INSTRUCTIONS.md

# INSTRUCTIONS.md — Local Development Guide

## Prerequisites

- Node.js 20+
- npm 10+
- Docker + Docker Compose (for containerized runs)

---

## Local Development (No Docker)

### 1. Server

```bash
cd server
cp .env.example .env        # edit DATABASE_URL and JWT_SECRET
npm install
npx prisma migrate dev      # creates SQLite DB and runs migrations
npm run db:seed             # seeds demo vendor + admin user
npm run dev                 # starts API on :8080 with hot-reload
```

Default demo credentials: `admin@demo.com` / `password123`

### 2. Client

```bash
cd client
npm install
npm run dev                 # starts Vite dev server on :5173
```

The Vite dev server proxies `/api` to `http://localhost:8080`.
Open `http://localhost:5173` in your browser.

---

## Docker (Single Container + SQLite)

```bash
docker build -t vendor-pos:latest .
docker run --rm -p 8080:8080 \
  -e NODE_ENV=production \
  -e PORT=8080 \
  -e DATABASE_URL=file:/data/pos.db \
  -e JWT_SECRET=change-me \
  -v pos_data:/data \
  vendor-pos:latest
```

Admin UI: `http://localhost:8080`
API: `http://localhost:8080/api/v1`

---

## Docker Compose (App + PostgreSQL)

```bash
cp .env.example .env        # set JWT_SECRET
docker compose up --build
```

App: `http://localhost:8080`

---

## API Overview

All endpoints live under `/api/v1`.

| Method | Path                              | Auth          | Description                        |
|--------|-----------------------------------|---------------|------------------------------------|
| GET    | /health                           | None          | Health check                       |
| POST   | /auth/login                       | None          | Obtain tokens                      |
| POST   | /auth/refresh                     | None          | Rotate refresh token               |
| POST   | /auth/logout                      | Bearer        | Invalidate tokens                  |
| GET    | /auth/me                          | Bearer        | Current user info                  |
| GET    | /vendors                          | Bearer        | List vendor                        |
| PUT    | /vendors/:id                      | owner         | Update vendor settings             |
| GET    | /users                            | manager+      | List users                         |
| POST   | /users                            | manager+      | Create user                        |
| PUT    | /users/:id                        | manager+      | Update user                        |
| DELETE | /users/:id                        | manager+      | Delete user                        |
| GET    | /users/roles/list                 | Bearer        | List available roles               |
| GET/POST/PUT/DELETE | /categories, /taxes, /products | manager+ | Catalog CRUD       |
| GET    | /catalog/sync?since=              | Bearer        | Delta sync for Android             |
| POST   | /transactions/batch               | Bearer        | Batch upload (idempotent)          |
| GET    | /transactions                     | manager+      | List transactions                  |
| GET    | /transactions/:id                 | manager+      | Get transaction detail             |
| POST   | /transactions/:id/refund          | manager+      | Refund a completed transaction     |
| GET    | /transactions/:id/receipt         | Bearer        | Structured receipt payload         |
| GET    | /transactions/reports/summary     | manager+      | Revenue/tax/top-product summary    |
| GET    | /transactions/reports/shift       | manager+      | Shift window totals + avg tx value |

---

## Environment Variables

| Variable       | Required | Default       | Description                            |
|----------------|----------|---------------|----------------------------------------|
| PORT           | No       | 8080          | HTTP port                              |
| NODE_ENV       | No       | development   | `development` or `production`          |
| DATABASE_URL   | Yes      | —             | Prisma connection string               |
| JWT_SECRET     | Yes      | —             | Secret for signing JWT tokens          |
| LOG_LEVEL      | No       | info          | Logging verbosity                      |
| CORS_ORIGIN    | No       | *             | Allowed CORS origin                    |

For SQLite: `DATABASE_URL=file:./dev.db`
For Postgres: `DATABASE_URL=postgresql://user:pass@host:5432/db`

---

## Database Migrations

```bash
# Create a new migration (dev only)
cd server && npx prisma migrate dev --name <migration-name>

# Apply pending migrations (production)
cd server && npx prisma migrate deploy

# Open Prisma Studio (GUI)
cd server && npx prisma studio
```