Project-Pro/orderPRO
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: generate codebase map in .paul/codebase/

Browse Source 
INDEX, STACK, ARCHITECTURE, CONVENTIONS, TESTING, INTEGRATIONS, CONCERNS
This commit is contained in:
Jacek Pyziak
2026-04-26 21:39:12 +02:00
parent 4b998ea5be
commit b1b2cc5827
7 changed files with 625 additions and 1544 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
.paul/codebase/INDEX.md
View File

@@ -1,73 +1,38 @@
# Codebase Map — orderPRO
# orderPRO — Codebase Map
> Generated: 2026-03-12
> Branch: main
**Generated:** 2026-04-26 | **Version:** 3.1.0-dev | **Milestone:** v3.1 Operational Enhancements
## What is this project?
## What Is This Project
**orderPRO** is a custom PHP 8.4 order management system (OMS) that aggregates and manages orders from multiple sales channels (Allegro marketplace, shopPRO e-commerce platform). It handles order import, status synchronization, shipment management, and product data enrichment. The system is entirely self-contained — no Composer runtime dependencies — built on a hand-rolled micro-framework.
orderPRO is a **multi-channel order management system** for Polish e-commerce. It aggregates orders from Allegro (OAuth2) and shopPRO platforms, manages shipments via Apaczka and InPost APIs, generates PDF receipts/invoices, sends automated emails, and exposes a REST API for a Windows print client.
---
## Documents
## Quick Navigation
| Document | Contents |
|----------|----------|
| [STACK.md](./STACK.md) | Language, framework, DB, integrations, build tools, dependencies |
| [ARCHITECTURE.md](./ARCHITECTURE.md) | Directory layout, layers, request flow, domain model, all 24 DB tables |
| [CONVENTIONS.md](./CONVENTIONS.md) | Naming rules, design patterns, DB access style, frontend conventions, testing |
| [CONCERNS.md](./CONCERNS.md) | Tech debt, bugs, security gaps, incomplete features — with severity levels |
| [STACK.md](STACK.md) | PHP 8.4, custom framework, PDO, SCSS, PHPUnit, Composer deps |
| [ARCHITECTURE.md](ARCHITECTURE.md) | MVC + Repository + Service layers, modules, routing, data flows |
| [CONVENTIONS.md](CONVENTIONS.md) | Naming, code patterns, security, UI rules (from CLAUDE.md) |
| [TESTING.md](TESTING.md) | PHPUnit 11.5, test patterns, coverage areas |
| [INTEGRATIONS.md](INTEGRATIONS.md) | Allegro, shopPRO, Apaczka, InPost, Email, Print queue |
| [CONCERNS.md](CONCERNS.md) | Tech debt, SonarQube issues, known bugs, performance |
---
## Key Directories
## Quick Reference
```
src/Core/ Custom framework (router, PDO, session, logger, CSRF)
src/Modules/ 13 feature modules (Orders, Shipments, Accounting, Email, …)
routes/web.php All ~80 routes in one file
resources/views/ PHP templates organized by module
resources/scss/ SCSS sources → public/assets/css/
database/migrations/ 84 SQL migration files (timestamped)
tests/Unit/ PHPUnit tests for services
.paul/docs/ ARCHITECTURE.md, DB_SCHEMA.md, TECH_CHANGELOG.md
```
### Stack
- **PHP 8.4**, zero Composer runtime deps, hand-rolled framework in `src/Core/`
- **MySQL** via raw PDO prepared statements (no ORM)
- **Frontend**: plain PHP views, SCSS → CSS via Dart Sass, jQuery + custom alert module
- **Tests**: PHPUnit 11 (currently zero active test coverage)
## Current State
### External Integrations
| Integration | Purpose |
|-------------|---------|
| **Allegro** | OAuth 2.0, order import, status sync, shipment management |
| **shopPRO** | API key auth, order/product import |
| **Apaczka** | HMAC-signed REST, multi-carrier shipping aggregator |
| **InPost ShipX** | Bearer token REST, parcel lockers (settings only — shipments route via Allegro WZA workaround) |
| **GS1** | Barcode/product data (bin scripts) |
### Architecture in One Sentence
`public/index.php` → `Application` → `Router` → middleware pipeline → controller (in `src/Modules/`) → service → repository (raw PDO) → plain PHP view.
### Top Concerns to Address
1. **OAuth refresh duplicated** across 4 Allegro services → extract `AllegroTokenRefreshService`
2. **Utility methods duplicated** 15+ times across repositories → shared trait or utility class
3. **Zero test coverage** — `tests/` directory is empty
4. **Known bug**: `AllegroShipmentService.php:255` — ZPL branch always returns `'A6'` (dead conditional)
5. **InPost shipment provider stub** — settings exist, no `ShipmentProviderInterface` implementation
6. **No `CURLOPT_SSL_VERIFYPEER`** set in any cURL client — implicit trust of TLS certs
---
## Module Overview
| Module | Path | Responsibility |
|--------|------|----------------|
| Auth | `src/Modules/Auth/` | Login, session management |
| Orders | `src/Modules/Orders/` | Order list, detail, filters, status updates |
| Settings | `src/Modules/Settings/` | Integration config, carrier mapping, status groups |
| Shipments | `src/Modules/Shipments/` | Shipment creation, label printing, provider dispatch |
| Cron | `src/Modules/Cron/` | Cron job runner, schedule management |
| Users | `src/Modules/Users/` | User management |
---
## Entry Points
| Entry | Path |
|-------|------|
| Web app | `public/index.php` |
| Route definitions | `routes/web.php` |
| CLI scripts | `bin/` (8 scripts) |
| DB migrations | `database/migrations/` |
- **Active phase:** 107 — Automation Email Send Once (planning)
- **Last completed:** Phase 106 — Customer Return Alert (2026-04-22)
- **Total migrations:** 84 (latest: `20260425_000102_create_automation_email_once_deliveries_table`)
- **God classes to watch:** `OrdersRepository` (1221 LOC), `OrdersController` (1187 LOC), `AutomationService` (834 LOC)