jason
2aa041d45e
- lib/payments.ts: provider-agnostic payment interface; cash (immediate) and card stub (swappable for Square/Stripe Terminal/Tyro) - POST /transactions/:id/refund — manager+, server-authoritative, blocks double-refund - GET /transactions/:id/receipt — structured receipt payload for print/email/SMS - lib/logger.ts: minimal structured JSON logger respecting LOG_LEVEL env var - middleware/requestLogger.ts: per-request method/path/status/ms logging - errorHandler now uses structured logger instead of console.error - Dockerfile: non-root user (appuser), HEALTHCHECK via /api/v1/health, npm cache cleared in runtime stage Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
# 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 |
|
|
|
|
---
|
|
|
|
## 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
|
|
```
|