33 lines
2.9 KiB
Markdown
33 lines
2.9 KiB
Markdown
# AGENTS.md — dashdbschema (`libdashstore`)
|
|
|
|
MSSQL schema + domain store API. ESM (`type: module`). One class `LibDashStore`; methods mirror `src/store/<domain>/<action>.js`.
|
|
|
|
## Architecture
|
|
|
|
- Entry: `src/index.js` wires namespaces (`article`, `category`, `company`, `delivery`, `order`, `quote`, `ledger`, `stock`, `numbers`, `warehouse`, …).
|
|
- Provider contract: `src/providers/provider.js` (`query`, `transaction`, `initialize`, `purge`). `src/providers/mssql/` production (raw SQL in `queries/<domain>.js`, DDL in `schema.js`, `OUTPUT INSERTED.*`, `TOP 1`, `WITH (UPDLOCK, HOLDLOCK)`); `src/providers/sqlite3/` dev/test (`better-sqlite3`, re-exports mssql queries via `translateQueries`, `RETURNING`/`LIMIT 1`).
|
|
- Store convention: each module `export default function <action>(provider) => async (googleAuthId, input, tx)`. `googleAuthId` is always `google_auth.id`. Company scoping via `resolveSelectedCompanyAccess` (`selected_company`) — no `companyId` arg except `setSelectedCompany`, `companyuser.add`, `company.delete`.
|
|
- Ledger is append-only + hash-chained (`store/ledger/add.js`); stock is derived (`SUM(ledger.amount)` filtered by company, matched via `article.sku` or `articlesupplier.sku`). `store/stock/adjust.js` writes implicit `adjustment` manifest + ledger + `articlehistory`. `track_stock==0` blocks warehouse-scoped writes (`Stock tracking is disabled…`).
|
|
- Errors are plain `Error` with stable strings; HTTP mapping lives in dashback route `*ErrorStatus()`. Keep messages greppable.
|
|
|
|
## Build / Test
|
|
|
|
```bash
|
|
npm install
|
|
npm run reset-db # purge + init → fresh DB (source of truth)
|
|
npm run api-doc # regenerates API.md + API.<module>.md from JSDoc
|
|
node scripts/test-ledger.js # sqlite temp-DB regression (also: test-stueckliste-stock, test-variant-flow, test-sqlite-storage, …)
|
|
```
|
|
|
|
- Never run `scripts/test-api.js` for verification — interactive `@clack/prompts` menu (MSSQL), hangs.
|
|
- Schema changes go directly in DDL (`CREATE TABLE … IF NOT EXISTS`); no migration/upgrade paths in code. Shared-DB fixes are manual `sqlcmd` only. See `.cursor/rules/no-schema-migrations.mdc`.
|
|
- After store changes run `npm run api-doc`; edit JSDoc source, never the generated `API.*.md`.
|
|
|
|
## Conventions
|
|
|
|
- Sibling repos (`../dashback`, `../dashfront`) are **read-only**: may read docs/code + `git -C ../<repo> log --oneline -20`, never write/install/start. Missing HTTP/UI contract → ask human, don't guess. No fallbacks. See `.cursor/rules/sibling-repos.mdc`.
|
|
- Touching SQL → update **both** `mssql/queries/*` and check `sqlite3/queries/*` translation (`OUTPUT INSERTED` vs `RETURNING`, `TOP 1` vs `LIMIT 1`).
|
|
- Stock invariants belong in `src/store/` (covers both `stock.adjust` and direct `ledger.add`); mirror new error strings in dashback route mappers via human.
|
|
- Contracts: `README.md` (conventions), `API.md` (index), `src/store/` (implementation).
|
|
- Full conventions: `/home/seb/src/dashback/.agents/skills/project-overview/SKILL.md`.
|