roles guard + docs + logo

2026-05-06 16:37:20 +07:00
parent 797dee5d17
commit 2eb6a1a315
60 changed files with 496 additions and 105 deletions
@@ -1,2 +1,136 @@
-# inapp-pro
-inapp-pro Inventory Dashboard Admin Template
+# TRx WMS
+
+A multi-tenant Warehouse Management System (WMS) built with PHP, MySQL, and vanilla JavaScript. Designed for small-to-medium operations that need barcode-driven stock control, lot/serial traceability, and multi-warehouse support — accessible from any browser without installing a native app.
+
+---
+
+## Features
+
+### Dashboard
+- Live stock overview with key metrics (total SKUs, low-stock count, near-expiry alerts)
+- Low-stock product list with one-click restock shortcut to Stock In
+- Dashboard widgets per warehouse
+
+### Inventory Management
+- **Product master** — SKU, name, unit of measure, barcode, category, cost/price/margin tracking
+- **Categories** — group products for filtering and reporting
+- **Warehouse master** — multi-warehouse support; simple or advanced location mode (warehouse → rack, or warehouse → zone → aisle → rack)
+- **Storage / rack master** — define physical rack locations per warehouse
+- **Product lots** — lot number, expiry date, per-lot traceability across all warehouses
+
+### Stock Control (ICS)
+- **Stock In** — receive stock into a specific location; supports lot, expiry, serial, unit price, and contact (supplier)
+- **Stock Out** — remove stock from a location; cascaded lot/serial dropdowns filtered to available stock
+- **Stock Transfer** — move stock between any two locations (same or different warehouse)
+- **Stock Overview** — real-time balance per SKU across all warehouses and locations
+- Two-step approval flow: transactions created as `pending` and approved separately
+
+### Barcode System
+- **SKU barcode labels** — generate `SKU|{sku}|{lot}|{serial}` labels; print, disable, re-enable per serial
+- **Location barcode labels** — generate `LOC|{warehouse}|{rack}` (simple) or `LOC|{warehouse}|{zone}|{aisle}|{rack}` (advanced) labels
+- **Scanner support** — USB scanner, handheld scanner, phone camera (Html5Qrcode), and clipboard paste all handled by a unified `scanner.js` module
+- Scan-driven stock flows: scan SKU label → scan location label → press F2 to save (no mouse required)
+- Disabled barcodes are rejected at scan time with a clear error message
+
+### Orders
+- **Sales orders** — create, confirm, and track customer orders
+- **Returns** — manage product returns linked to original orders
+- **Invoices** — generate and print invoices per order
+- **Purchase orders (PO)** — create and track supplier purchase orders
+
+### Contacts
+- Supplier and customer contact management
+- Contact types (supplier, customer, other)
+- Linked to stock-in, stock-out, orders, and POs
+
+### Reports
+- **Stock Movement** — full transaction history with in/out/net summary; filterable by date, SKU, warehouse
+- **Product Lots** — lot-level stock balance with expiry dates across all warehouses
+- **Expired / Near Expiry** — products approaching or past their expiry date
+- **Rack Occupancy** — visual overview of which racks are occupied, empty, or locked
+
+### Settings
+- **Company profile** — name, logo, branch details
+- **System config** — location mode (simple/advanced), custom zone/aisle/rack labels, stock uniqueness rules
+- **User management** — invite users by email, assign roles (admin / staff / viewer), remove members
+- **SMTP** — configure outbound email for notifications
+- **Profile** — per-user name, username, password, profile picture
+
+### Multi-Tenant / Branch Support
+- Each company is isolated; users can belong to multiple companies
+- Branch switcher in the topbar for users with access to more than one company
+- All data (products, stock, orders, contacts) is scoped to the active company
+
+### Security
+- Session-based authentication with TOTP-style OTP validation on every API request
+- CSRF token enforcement on all POST requests
+- Role-based access control: `owner`, `admin`, `staff`, `viewer` (see `ROLES.md`)
+- Passwords hashed; profile picture uploads sandboxed to `uploads/profile/`
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Backend | PHP 8.x, Apache |
+| Databases | MySQL — `wms` (system/auth), `wms2` (operational data) |
+| Frontend | Bootstrap 5, jQuery, Flatpickr, ApexCharts, JsBarcode, Html5Qrcode |
+| Build | Vite (`npm run dev` / `npm run build`) |
+| Auth | Session + HMAC-SHA1 OTP + CSRF tokens |
+
+---
+
+## Module Layout
+
+```
+app/
+├── dashboard/          # Dashboard and low-stock widgets
+├── ics/                # Stock In / Out / Transfer, barcode labels
+├── inventory/          # Product, warehouse, rack, category masters
+├── order/              # Sales orders, returns, invoices
+├── po/                 # Purchase orders
+├── reports/            # Stock movement, lots, expiry, rack occupancy
+├── contact/            # Supplier / customer contacts
+├── setting/            # Company, users, SMTP, system config, profile
+├── assets/
+│   ├── js/             # main.js, scanner.js, custom.js
+│   ├── css/            # main.css, custom.css
+│   └── utils/          # db_auth.php, db_helpers.php, shared classes
+└── login/              # Login, OTP, onboarding
+```
+
+---
+
+## Local Development
+
+```bash
+# Front-end assets (Vite)
+npm run dev
+npm run build
+
+# Syntax-check a PHP file
+php -l app/ics/manage_stock_in.php
+
+# Apply a schema migration to the client database
+mysql -uroot -p2618 wms2 < migration.sql
+```
+
+App is served by Apache at `http://localhost/wms/app/`.
+
+---
+
+## Documentation
+
+| File | Contents |
+|------|----------|
+| `CHANGELOG.md` | Version history and notable changes |
+| `docs/ROLES.md` | Role-based access control spec (admin / staff / viewer) |
+| `docs/DATABASE.md` | Full schema for both databases — tables, columns, relationships |
+| `docs/API.md` | All API endpoints — request fields, response format, error codes |
+| `docs/DEPLOYMENT.md` | Installation, Apache/PHP/MySQL setup, environment checklist |
+| `docs/TESTING.md` | Manual test checklists — barcode flow, stock ops, regression |
+| `docs/SECURITY.md` | Auth model, OTP flow, CSRF, session management, XSS/SQL rules |
+| `docs/STOCK.md` | Stock ledger, approval flow, rack lifecycle, StockManager/WarehouseManager |
+| `docs/SCANNER.md` | scanner.js internals, device support, integrating scanning into new pages |
+| `docs/CONTRIBUTING.md` | Patterns for adding new APIs, pages, modules, settings, and schema changes |