u

2026-07-14 23:30:16 +02:00
parent 245fb047d7
commit 262fa63f1b
109 changed files with 21566 additions and 367 deletions
--- a/jtlsrv-cpp/README.md
+++ b/jtlsrv-cpp/README.md
@@ -0,0 +1,124 @@
+# jtlsrv
+
+Built on **libuv** (event loop), **OpenSSL** (TLS), **llhttp** (HTTP parsing), **unixODBC** + [**ODBC Driver 18 for SQL Server**](https://learn.microsoft.com/en-us/sql/connect/odbc/microsoft-odbc-driver-for-sql-server) (database), and **libvips** (image thumbnails). Blocking work (ODBC queries, image processing) runs on libuv worker threads.
+
+## Requirements
+
+| Dependency | Purpose |
+|---|---|
+| C++17 compiler | gcc or clang |
+| GNU Make | Build |
+| pkg-config | Dependency flags |
+| libuv | Async I/O and thread pool |
+| OpenSSL | TLS |
+| libvips | Product/category image resizing |
+| unixODBC + dev headers | ODBC runtime |
+| [ODBC Driver 18 for SQL Server](https://learn.microsoft.com/en-us/sql/connect/odbc/microsoft-odbc-driver-for-sql-server) | Connect to JTL-Wawi (MSSQL) |
+
+Vendored in `vendor/`: **llhttp**, **nlohmann/json** (no install needed).
+
+### Install on Ubuntu / Debian
+
+```bash
+sudo apt install \
+  build-essential make pkg-config \
+  libuv1-dev libssl-dev libvips-dev unixodbc-dev
+```
+
+Install [Microsoft's ODBC driver](https://learn.microsoft.com/en-us/sql/connect/odbc/microsoft-odbc-driver-for-sql-server) (required for MSSQL):
+
+```bash
+curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | \
+  sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
+
+echo "deb [arch=amd64 signed-by=/usr/share/keyrings/microsoft-prod.gpg] \
+  https://packages.microsoft.com/ubuntu/$(lsb_release -rs)/prod $(lsb_release -cs) main" | \
+  sudo tee /etc/apt/sources.list.d/mssql-release.list
+
+sudo apt update
+sudo ACCEPT_EULA=Y apt install msodbcsql18
+```
+
+## Build
+
+```bash
+make
+```
+
+The binary is written to `./jtlsrv`. After code changes always run `make` before starting the server.
+
+Debug build:
+
+```bash
+make debug
+```
+
+## Configuration
+
+Copy the example env file from the repo root and edit as needed:
+
+```bash
+cp ../.env.example .env
+```
+
+Key settings:
+
+| Variable | Default | Description |
+|---|---|---|
+| `PORT` | `4443` | HTTPS listen port |
+| `PAIRING_CODE` | `307018` | Code shown to the POS during pairing |
+| `AUTH_TOKEN` | (built-in default) | Device auth token after pairing |
+| `MSSQL_*` | — | JTL-Wawi database connection |
+| `MANDANT_*` | — | Mandant metadata returned to the client |
+| `ROOT_CATEGORY_ID` | `1` | Root category for sync |
+| `TAX_ZONE_NAME` | `Zone-EU` | Tax zone for product prices |
+| `LOG_FILE` | `logs/requests.log` | Request log path |
+| `ORDER_LOG_FILE` | `logs/orders.log` | Order log path |
+
+The server starts without MSSQL if `MSSQL_USER` is unset or the connection fails — pairing and handshake still work, but catalog sync from the database is unavailable.
+
+## TLS certificates
+
+Place a certificate and key at `certs/cert.pem` and `certs/key.pem` (relative to the working directory when you run the binary).
+
+```bash
+mkdir -p certs
+openssl req -x509 -newkey rsa:2048 -nodes \
+  -keyout certs/key.pem -out certs/cert.pem -days 3650 \
+  -subj '/CN=localhost/O=JTL POS Sync/C=DE' \
+  -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1,IP:0.0.0.0'
+```
+
+On startup the server prints the pairing code and whether MSSQL connected.
+
+## API endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/v1/client` | Client discovery / pairing |
+| GET | `/v1/init` | Init handshake |
+| GET | `/v1/category` | Category sync |
+| GET | `/v1/product` | Product sync |
+| GET | `/v1/productcomposite` | Composite product sync |
+| GET | `/v1/deletedentity` | Deleted entity sync |
+| GET | `/v1/customergroup` | Customer group sync |
+| POST | `/v1/order` | Submit orders |
+| GET | `/v1/pimage` | Product image (resized) |
+| GET | `/v1/cimage` | Category image (resized) |
+
+## Project layout
+
+```
+Makefile
+src/
+	main.cpp              Entry point, route registration, startup
+	config.hpp            .env loader
+	tls_server.{hpp,cpp}  HTTPS over libuv + OpenSSL
+	http.{hpp,cpp}        llhttp request/response handling
+	router.{hpp,cpp}      Route dispatch
+	pairing.{hpp,cpp}     In-memory pairing store
+	endpoints/            HTTP handlers
+	queries/              SQL query builders (header-only)
+	db/pool.{hpp,cpp}     ODBC connection pool
+vendor/                 llhttp, nlohmann/json
+```