185 lines
7.6 KiB
Markdown
185 lines
7.6 KiB
Markdown
# Construction Delivery Control — QWEN Context
|
||
|
||
## Project Overview
|
||
|
||
**Construction Delivery Control** is a React-based single-page application for managing construction orders across the full lifecycle: order creation, production, logistics, and delivery coordination. It integrates with chatbot channels (VK, Telegram, Messenger Max) for automated customer communication about delivery slots.
|
||
|
||
### Key Features
|
||
|
||
- **OTP authentication** via Supabase Auth with a demo mode when backend is not configured
|
||
- **Role-based dashboard** for 5 roles: Manager, Production Lead, Logistician, Driver, Admin
|
||
- **Order lifecycle management** — creation, editing, status transitions, delivery slot scheduling
|
||
- **Production queue panel** — Kanban-style view for production workflow
|
||
- **Chatbot integration** — unified adapter layer for VK, Telegram, Messenger Max
|
||
- **Client-facing delivery page** — token-based link for customers to confirm/reschedule delivery
|
||
- **Installable PWA** with offline support (service worker + manifest)
|
||
- **Light/dark themes** with responsive, minimalist UI
|
||
- **Supabase backend** — PostgreSQL schema with Row-Level Security (RLS), audit triggers, and Supabase Edge Functions
|
||
|
||
### Tech Stack
|
||
|
||
| Layer | Technology |
|
||
|---|---|
|
||
| Frontend | React 18, React Router 7, Tailwind CSS, Framer Motion |
|
||
| State | React Context (`AuthContext`, `ThemeContext`), local component state |
|
||
| Backend | Supabase (PostgreSQL, Auth, Edge Functions) |
|
||
| Build | Vite 6 |
|
||
| Testing | Vitest |
|
||
| Linting | ESLint 9 |
|
||
| PWA | Custom service worker + Web App Manifest |
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
super-sam/
|
||
├── src/ # Frontend source
|
||
│ ├── components/ # UI components
|
||
│ │ ├── admin/ # Admin panels (users, audit)
|
||
│ │ ├── auth/ # Login / OTP components
|
||
│ │ ├── chat/ # Chat message components
|
||
│ │ ├── client/ # Client-facing delivery page
|
||
│ │ ├── dashboard/ # KPI, production queue panels
|
||
│ │ ├── driver/ # Driver delivery panel
|
||
│ │ ├── logistics/ # Bot control, delivery slots
|
||
│ │ ├── orders/ # Order list, card, editor, history
|
||
│ │ └── UI/ # Shared UI primitives
|
||
│ ├── constants/ # Workflow statuses, transitions
|
||
│ ├── context/ # AuthContext, ThemeContext
|
||
│ ├── data/ # Mock/demo data
|
||
│ ├── hooks/ # useOrders, usePwaStatus, etc.
|
||
│ ├── layouts/ # AppShell (sidebar + content)
|
||
│ ├── lib/ # Utility libraries
|
||
│ ├── pages/ # Route-level pages
|
||
│ ├── services/ # Business logic (pure functions)
|
||
│ │ └── supabase/ # Supabase repository adapters
|
||
│ ├── styles/ # Theme CSS
|
||
│ ├── test/ # Test utilities
|
||
│ └── utils/ # General utilities
|
||
├── supabase/
|
||
│ ├── schema.sql # Full DB schema with RLS policies
|
||
│ └── functions/ # Supabase Edge Functions
|
||
│ ├── chatbot-webhook/ # Inbound webhook handler
|
||
│ ├── send-chatbot-message/ # Outbound message sender
|
||
│ ├── confirm-delivery-choice/
|
||
│ ├── create-delivery-invitation/
|
||
│ ├── get-delivery-invitation/
|
||
│ ├── report-delivery-result/
|
||
│ ├── transfer-to-logistics/
|
||
│ └── _shared/ # Shared modules (chatbot, workflow)
|
||
├── public/
|
||
│ ├── manifest.webmanifest # PWA manifest
|
||
│ ├── service-worker.js # Offline caching
|
||
│ └── icons/ # PWA install icons
|
||
├── docs/
|
||
│ ├── architecture.md # Frontend architecture
|
||
│ ├── chatbot-integration.md # Bot channel integration spec
|
||
│ ├── scenarios.md # Order lifecycle scenarios
|
||
│ ├── operations/ # Operational docs
|
||
│ └── superpowers/ # Feature/agent instructions
|
||
└── docker-compose.yml # Self-hosted Supabase stack
|
||
```
|
||
|
||
## Building and Running
|
||
|
||
### Prerequisites
|
||
|
||
- Node.js 18+
|
||
- npm
|
||
|
||
### Development
|
||
|
||
```bash
|
||
npm install # Install dependencies
|
||
npm run dev # Start Vite dev server (http://localhost:5173)
|
||
```
|
||
|
||
### Production Build
|
||
|
||
```bash
|
||
npm run build # Build for production (dist/)
|
||
npm run preview # Preview production build
|
||
```
|
||
|
||
### Linting
|
||
|
||
```bash
|
||
npm run lint # ESLint check
|
||
```
|
||
|
||
### Testing
|
||
|
||
```bash
|
||
npm run test # Run Vitest tests
|
||
```
|
||
|
||
### Local Supabase Stack
|
||
|
||
```bash
|
||
docker compose up -d # Start self-hosted Supabase
|
||
docker compose down # Stop
|
||
```
|
||
|
||
### Environment Variables
|
||
|
||
Copy `.env.example` to `.env` and configure:
|
||
|
||
```
|
||
VITE_SUPABASE_URL=https://your-project.supabase.co
|
||
VITE_SUPABASE_ANON_KEY=your-anon-key
|
||
```
|
||
|
||
Without these variables, the app runs in **demo mode** with local mock data.
|
||
|
||
## Architecture Highlights
|
||
|
||
### Authentication Flow
|
||
|
||
1. User enters email on `/login`
|
||
2. Supabase sends OTP via email (or demo mode bypasses this)
|
||
3. On success, `AuthContext` loads user profile + role from `public.users` table
|
||
4. Role-based routing guards dashboard access
|
||
|
||
### Order Service Layer
|
||
|
||
- `src/services/orderService.js` — pure functions for order CRUD, status transitions, filtering, metrics, auto-assignment
|
||
- `src/services/supabase/orderRepository.js` — Supabase adapter for real reads/writes
|
||
- The service layer is decoupled: tests mock data without needing a live database
|
||
|
||
### Role-Based Access Control
|
||
|
||
| Role | Permissions |
|
||
|---|---|
|
||
| `manager` | Create/edit own orders, read own orders, manage comments |
|
||
| `production_lead` | Read all orders, manage production queue, update production statuses |
|
||
| `logistician` | Read assigned orders, manage delivery, manage chatbots |
|
||
| `driver` | Read assigned deliveries, update driver statuses (Загружен, В пути, Доставлен) |
|
||
| `admin` | Full access to everything |
|
||
|
||
RLS policies in `schema.sql` enforce these at the database level.
|
||
|
||
### Workflow Statuses
|
||
|
||
Orders move through a defined pipeline:
|
||
`Новый` → `Подтверждён` → `В очереди производства` → `В производстве` → `Готово к доставке` → `Ожидает ответа клиента` → `Доставка согласована` → `Доставка запланирована` → ... → `Доставка завершена`
|
||
|
||
Transitions are gated by role via `src/constants/deliveryWorkflow.js`.
|
||
|
||
### Routing
|
||
|
||
| Route | Component | Description |
|
||
|---|---|---|
|
||
| `/` | → redirect to `/dashboard` | |
|
||
| `/login` | `LoginPage` | Email OTP authentication |
|
||
| `/dashboard` | `DashboardPage` | Role-based control center |
|
||
| `/delivery/:token` | `ClientDeliveryPage` | Client-facing delivery confirmation |
|
||
| `*` | `NotFoundPage` | 404 fallback |
|
||
|
||
## Development Conventions
|
||
|
||
- **ESLint** with `eslint:recommended`, `react`, and `react-hooks` plugins
|
||
- **Tailwind CSS** with `tailwind-merge` + `clsx` for className composition
|
||
- **Framer Motion** for animations and transitions
|
||
- **Module alias**: imports use relative paths from `src/`
|
||
- **Test coverage**: `orderService.js`, `deliveryInvitationApi.js`, `driverDeliveries.js`, `orderViews.js` all have `.test.js` files
|
||
- **Code splitting**: Vite config manually chunks `react`, `supabase`, and `motion` into separate bundles
|