ORM vs ERP Boundaries
Sumeru keeps a hard line between ORM core and ERP behavior. Crossing that line is how frameworks become unmaintainable.
ORM core owns
- Model registry and field definitions
- CRUD (
Create,Update,Unlink,Search*) - Domains → SQL
- ACL (
sys.access) and record rules (sys.rule) - Field-level write ACL (
sys.field.access) - Transactions and row locking for secure mutations
- Audit hooks and outbox rows (side-effect contracts)
- Schema sync for declared fields
ERP modules own (via composition)
- Workflow / stage approvals
- Company policies and multi-company UX
- Mail / chatter / activity panel
- Automation (event subscribers)
- Import pipelines and business validation
Use interceptors, events, and services — do not grow core/orm with business concepts.
##RPC vs Go-native internals
| Layer | Contract |
|---|---|
HTTP POST /api/rpc | shapes (model, method, args, kwargs, optional params) |
| Internal Go API | Native: PrepareValues, Update(ctx, model, domain, values), SearchPage |
Compatibility stops at the boundary. Internal design is Go-first.
Security is query-shaped
Authorization decisions must not sit in a check-then-mutate window:
- Compile ACL + record rules into SQL predicates (and/or use
SELECT … FOR UPDATEin the same transaction). - Mutate with
WHERE id = ? AND. - Treat zero rows affected as access denied / not found (no existence leak).
Values pipeline (create / write)
request → model lookup → field whitelist → field ACL → type coercion → validation → record rules → SQLPrepareValues is the shared sanitizer for Create, Update, and Upsert.
SQL identifiers (injection safety)
Sumeru uses a two-layer rule:
- Identifiers (tables, columns, ORDER BY fields) — validated and quoted via
QuotedTableForModel,QuotedColumnForModel,QuotedPermColumnForOp, or compile-timeMustQuotedTableName. - Values (user input, domain literals, limits) — always bound with
$1,$2, … placeholders. Never interpolate request strings into SQL text.
Logical model names are lowercase segments joined only by . (e.g. core.user, sys.config.parameter). No underscores, whitespace, or other symbols in the logical name. Physical tables replace . with _ after validation (ModelToTableName / QuotedTableName).
Every dynamic SQL path must:
- Resolve tables via
QuotedTableForModel/QuotedTableName(registered + validated). - Resolve columns via
QuotedColumnForModel(whitelist against registered field metadata +id) orQuotedPermColumnForOpfor ACL permission columns. - Bind all values with
$nplaceholders — never interpolate user strings into SQL.
Forbidden: building WHERE/ORDER BY/LIMIT from unchecked strings; splicing model or field names from HTTP/RPC/domain without validation.
Allowed: fmt.Sprintf("SELECT * FROM %s WHERE %s", quotedTable, whereClause) when quotedTable comes from Quoted* helpers and whereClause uses only $n placeholders.
Run make check-sql before committing raw SQL changes when that target is available in your checkout.
Side effects
Business mutation, audit, and outbox event rows commit together via runMutationTx / execute*Mutation in crud_mutate.go. All Create, Update, and Unlink paths enter this pipeline — no autocommit business-row mutations outside it (except documented bootstrap/schema bypass). Publishing to the in-process bus happens after commit (or via the outbox drain worker). Never emit record.* for data that did not commit.
Side-effect failures are logged with status=partial via applog.Warn.
Deliberate limits (not bugs)
| Feature | Limit |
|---|---|
Cron code | Go handlers via RegisterCronHandler only — no Python/safe_eval |
| Server actions | Declarative publish: / write: prefixes only — no script engine |
| Pivot view | Read-only HTML aggregation (500-row cap); no graph view or export |
XML noupdate | Skips existing xml ids on -u; inline views/menus still reload |
Structured logging
ORM mutations, module sync, web handlers, and RPC emit JSON via sumeru/core/applog (Event API). See Logging for the canonical field schema (message, component, operation, status, nested context).
Globals / Runtime
Package-level orm.DB and orm.Registry remain for bootstrap compatibility. New code should prefer runtime.Runtime (DB, registry wrapper, security cache, events, modules). Do not add new package-level singletons without documenting why.