u

.agents/skills/project-overview/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: project-overview
+description: Architecture and conventions for the dashback + dashdbschema (libdashstore) monorepo. Use for any backend/store task: providers, store modules, routes, auth, ledger/stock, error mapping, testing.
+---
+
+# Project Overview — dashback + dashdbschema
+
+Multi-root workspace:
+
+- `/home/seb/src/dashback` — Express backend (`dashback`, ESM, `type: module`). Depends on `libdashstore` via `file:../dashdbschema`.
+- `/home/seb/src/dashdbschema` — `libdashstore` library: MSSQL schema + domain store API. One class, methods mirror `src/store/<domain>/<action>.js`.
+- `/home/seb/src/dashback/quixpos2jtl/` — separate JTL/QuixPOS bridge (own `package.json`, Electron/CLI). Ignore unless task mentions JTL.
+
+## libdashstore (`dashdbschema`)
+
+Entry: `src/index.js` → `export default class LibDashStore`. Constructor requires a provider with `query/transaction/initialize/purge`. Namespaces are wired there, e.g. `this.stock = { adjust: stockAdjust(provider) }`, `this.ledger = { add, listByManifestarticleId, listBySku }`, plus `article, category, company, companyuser, delivery, order, quote, warehouse, ledger, stock, numbers, printer, labeltemplate, posterminal, supplier, articlesupplier, entity*, tax, unit, brand, lang, pic, manifestattachment, propertyname/articleproperty/categoryproperty, attributename/attributevalue/... , articlelist, optionslist`.
+
+### Provider abstraction
+
+- `src/providers/provider.js` — contract (`query(sql, params)`, `transaction(fn)`, `initialize()`, `purge()`).
+- `src/providers/mssql/` — production. Raw SQL in `queries/<domain>.js`, DDL in `schema.js` (`IF NOT EXISTS`, `SCHEMA_SCRIPTS`). Uses `OUTPUT INSERTED.*`, `TOP 1`, `WITH (UPDLOCK, HOLDLOCK)`.
+- `src/providers/sqlite3/` — dev/test (`BetterSqlite3Provider`, `better-sqlite3`). Mostly `import * as source from '../../mssql/queries/<x>.js'` + `translateQueries(source, '<domain>')`. DDL in `sqlite3/schema.js` (`RETURNING`, `LIMIT 1`). Auto-migrates `article.track_stock`, `ledger.created_at/warehouse_id` in `sqlite3/index.js`.
+- `bindParams` (sqlite): strips leading `@/:$`, maps `Date→ISO`, `boolean→1/0`, `null/undefined→null`. Both `@sku` and `sku` keys work.
+- `src/store/runner.js` (`makeRunner(provider, tx)`) — normalizes pool / tx / callable runner. Store code calls `runner.query(sql, params)` or `runner(sql, params)`. `runner.dialect === 'sqlite3'` selects query set. MSSQL legacy pool wrapped via `wrapMssql`.
+
+### Store conventions
+
+- Every store module: `export default function <action>(provider) { ...; return async (googleAuthId, input, tx) => {...} }`.
+- `googleAuthId` is always `google_auth.id`, never `companyuser.id`.
+- Company scoping: no `companyId` arg. `resolveSelectedCompanyAccess(provider)` reads `google_auth.selected_company` → `{ companyId, companyuserId, rootCategoryId }`. Missing → throw `No company selected`. Exceptions taking explicit `companyId`: `setSelectedCompany`, `companyuser.add`, `company.delete`, internals.
+- SKU resolution: `store/article/resolveArticleBySku.js` (`RESOLVE_ARTICLE_ACCESS_BY_SKU`) checks company + membership. Throws `Article not found` / `Parent not found` / `Not authorized`.
+- Errors are plain `Error` with exact message strings; HTTP mapping happens in `dashback` route `*ErrorStatus()` functions. Keep messages stable/greppable. Conflict → `409` (e.g. `EAN already in use`, `Warehouse in use in ledger`, `Stock tracking is disabled...`).
+- Manifest docs (`delivery/order/quote/adjustment`): header in `manifest`, lines in `manifestarticle`, helpers in `src/store/manifestLines.js` (`normalizeLines`, `insertLines`, `parseDate`, `shapeLine`) and `manifestDoc/helpers.js`. `insertLines` rejects father articles (`A father article cannot be booked on documents (SKU)`), resolves name/pu, ensures tax.
+- Numbers: `store/numbers/nextNumber.js`, types `sku, entity, delivery, adjustment`.
+
+### Ledger + stock (important)
+
+- `ledger` is append-only, tamper-chained: `hash_version=1`, `prev_hash = SHA-512(canonical JSON of prev row)` or `TODO_TSE_BASED_INITHASH` for genesis. See `store/ledger/add.js` (`shape`, `computePrevHash`, `INIT_HASH`).
+- Stock is **derived**: `SUM(ledger.amount) GROUP BY warehouse`, joined `ledger → manifestarticle → manifest`, matched on `ma.sku = article.sku OR ma.sku IN (SELECT sku FROM articlesupplier WHERE article_id = ...)`, filtered by `m.company_id`. See `providers/*/queries/article.js` (`warehousesJson`/`stock_calc`) and `posterminal.js` (`fBestand`). No `stock` column on article.
+- `store/stock/adjust.js` creates implicit manifest `type='adjustment'` (number from `adjustment` scheme) + one `manifestarticle` line per item (`amount: abs(amount)`) + one `ledger` row per item (`amount: signed`) + `articlehistory` (`Bestandskorrektur ±n (text)`). Validates: father → `A father article cannot have stock (SKU)`; Stückliste (`articlelist_id != null`) → `A Stückliste cannot have manual stock adjustments (SKU)`; **`track_stock==0` → `Stock tracking is disabled for article (SKU)`** (added as bugfix; checked before number allocation/manifest write, so batch is all-or-nothing).
+- `store/ledger/add.js` enforces the same guard for **any warehouse-scoped entry** (`warehouse_id != null` + line has SKU): looks up `article` by `sku` or `articlesupplier.sku` in same company, rejects if any match has `track_stock==0`. Non-warehouse entries (e.g. `PAYMENT`, memo `NOTE`) are still allowed. Guard runs before `GET_LATEST_ROW`/`INSERT_ROW`, inside the same runner/tx.
+- `POST /ledger` with `warehouse_id` is therefore also blocked for untracked articles; delivery receipts booked via ledger go through the same check.
+- `article.track_stock`: `BIT/INTEGER DEFAULT 1`. Managed via `article.createUnderParent({track_stock})`, `updateBySku`, `setTrackStockBySku`, `POST /article` (`track_stock`/`trackStock`, default true). `toggleFather` sets `track_stock=0` when becoming father. POS surfaces it as `use_stock '1'/'0'` (`store/posterminal/getProductList.js`).
+
+## dashback (Express API)
+
+- `src/index.js` → `src/api/index.js` (`startApi/stopApi`). Env in `src/config/env.js` (`.env`: `PORT` default 4208, `HTTPS_PORT`, `GOOGLE_CLIENT_ID`, `JWT_SECRET`, `CORS_ORIGINS`, `DB_PROVIDER=mssql|sqlite`, `SQLITE_PATH`, `MSSQL_*`).
+- Routes auto-loaded: `loadRoutes()` walks `src/api/routes/**/*.js`, calls `register(app, basePath)`. Each route file owns its `@openapi` JSDoc + `*ErrorStatus(error)` mapper + `requireSelectedCompany(req)`.
+- `src/db/store.js` — lazy singleton provider+store (`ensureConnection`), wraps every namespace method with timing logs (`libstore <ns>.<method> (Nms)` / `FAILED`). `src/db/<domain>.js` thin wrappers (`store.stock.adjust`, `store.ledger.add`, ...).
+- Auth: `src/api/middleware/auth.js` (Google SSO + JWT cookie/session, `req.user.{id, selectedCompanyId}`), `src/api/routes/auth/*`, `scripts/manageUsers.js` (allowlist). `src/api/middleware/logger.js` colors `>=400`.
+- Docs: `npm run docs:api` (`scripts/generateApiDocs.js` + `src/api/openapi.js` swagger) → `docs/api/routes.md` + `docs/api/routes/`. Per-route `x-markdown` hints.
+- SSE: `src/api/sse.js` (`emit`), `routes/events.js`. Stock adjust emits `stock`, `ledger`, `articles`, `article-<sku>`.
+- `src/v1/` — legacy POS compat (`/v1/...`, `posAuth`, static `use_stock: '0'` defaults in some stubs). `src/util/` — `cert.js` (self-signed), `errorLog.js`. `certs/`, `data/` (sqlite + `storage/content|fullbinary|thumbavif|thumbbinary`), `logs/errors/`.
+- HTTP status conventions per route file: `No company selected→400`, `Not authorized→403`, `*not found→404`, validation→400 (often via `includes()`), uniqueness/in-use→409, else 500 + `console.error`. Stock/ledger map `Stock tracking is disabled...→409` (fix for reported bug: `POST /stock/adjust` on `track_stock:false` returned `201` and wrote manifest+ledger; now `409` before any write).
+
+## Tests / scripts
+
+- Automated (sqlite temp DB, exit cleanly): `dashdbschema/scripts/test-ledger.js`, `test-stueckliste-stock.js`, `test-sqlite-storage.js`, `test-variant-flow.js`, `test-tombstone.js`, etc. Run with `cd /home/seb/src/dashdbschema && node scripts/test-ledger.js`.
+- **Do NOT run `scripts/test-api.js` for verification** — it is an interactive `@clack/prompts` menu (MSSQL) that hangs waiting for input.
+- `dashdbschema` scripts: `init-schema`, `purge-db`, `reset-db`, `benchmark`, `generate-api-doc.js`, `generate-schema-graph.js`. `dashback` scripts: `manageUsers.js`, `generateApiDocs.js`, `testImageCrop.js`. `dashback` has no `npm test`.
+- Quick regression pattern (sqlite in-memory/temp): create provider → `new LibDashStore(provider)` → `google_auth.add` → `company.create` → `setSelectedCompany` → `unit.upsert` → `warehouse.create` → `article.createUnderParent({track_stock:false})` → assert `stock.adjust` throws, `ledger.listBySku` empty, tracked article still adjusts.
+
+## Agent tips
+
+- Add stock invariants in `dashdbschema/src/store/` (not routes) so both `stock.adjust` and direct `ledger.add` are covered; mirror the error string in `dashback/src/api/routes/{stock,ledger,delivery}.js` mappers if a new status is needed.
+- When touching SQL, update **both** `mssql/queries/*` and check `sqlite3/queries/*` translation; watch `OUTPUT INSERTED` vs `RETURNING`, `TOP 1` vs `LIMIT 1`.
+- Prefer `runner.query('SELECT ..., track_stock FROM article WHERE id = @articleId', { articleId })` for per-article flags; for ledger-by-SKU use the `article OR articlesupplier.sku` lookup scoped by `company_id`.
+- Keep `API.*.md` in `dashdbschema/` (generated via `npm run api-doc`) in mind but edit JSDoc source, not the markdown.
+
+

src/api/routes/ledger.js

@@ -16,6 +16,7 @@ function ledgerErrorStatus(error) {
     if (error.message === 'Invalid ledger entry') return 400;
     if (error.message === 'Invalid manifest article id') return 400;
     if (error.message === 'Invalid SKU') return 400;
+    if (error.message?.includes('Stock tracking is disabled')) return 409;
     return 500;
 }
 

src/api/routes/stock.js

@@ -21,6 +21,7 @@ function stockErrorStatus(error) {
     if (error.message?.includes('Invalid amount')) return 400;
     if (error.message === 'No items to adjust') return 400;
     if (error.message?.includes('cannot have stock') || error.message?.includes('A father article cannot have') || error.message?.includes('father article') || error.message?.includes('Stückliste')) return 400;
+    if (error.message?.includes('Stock tracking is disabled')) return 409;
     return 500;
 }