shutro-erp 0.3.4 → 0.3.6

package/dist/maintenance_stock/module.js

@@ -0,0 +1,192 @@
+/**
+ * The data layer of the Asset Care ↔ Stockroom bridge (RFC 0021, Asset Care step 2): a maintenance order lists the
+ * spare parts it uses; starting it reserves them in a transfer from the main stock to the Maintenance location,
+ * finishing it consumes them (refused while some are short), cancelling it releases them. Parts cost what they cost
+ * in stock; with `stock_account` they leave Inventory as a stock adjustment.
+ */
+import { maintenanceShutro } from '../maintenance/index.js';
+import { productShutro } from '../product/index.js';
+import { orm } from '../server/orm.js';
+import { defaultLocations, inProductUnit, stockShutro } from '../stock/index.js';
+import { compute, defineModel, defineModule, extendModel, f, onchange, record, } from './.kosh/bindings.js';
+const zero = orm.toDecimal(0);
+export const MaintenancePart = defineModel('maintenance.request.part', {
+    label: 'Spare part',
+    order: ['id asc'],
+    access: {
+        'maintenance.user': ['read', 'write', 'create', 'unlink'],
+        'maintenance.manager': ['read', 'write', 'create', 'unlink', 'export'],
+    },
+    fields: {
+        request: f.many2one('maintenance.request', { required: true, ondelete: 'cascade' }),
+        product: f.many2one('product.product', { required: true, ondelete: 'restrict' }),
+        quantity: f.decimal({ scale: 4, required: true, default: '1' }),
+        uom: f.many2one('uom.uom', { label: 'Unit' }),
+        /** The quantity at the product's cost (in the product's unit). */
+        cost: f.decimal({
+            scale: 2,
+            store: true,
+            label: 'Cost',
+            ...compute('maintenance.request.part', 'cost', [
+                'quantity',
+                'uom.ratio',
+                'uom.category',
+                'uom.name',
+                'uom.rounding',
+                'product.standardPrice',
+                'product.uom.ratio',
+                'product.uom.category',
+                'product.uom.name',
+                'product.uom.rounding',
+            ], (parts) => {
+                for (const p of parts)
+                    p.cost = inProductUnit(p.quantity, p.uom ?? null, p.product.uom ?? null)
+                        .times(p.product.standardPrice)
+                        .toDecimalPlaces(2);
+            }),
+        }),
+    },
+    onchange: {
+        product: onchange('maintenance.request.part', async (d) => {
+            const p = await d.record('product');
+            if (p?.uom)
+                d.set('uom', p.uom.id);
+        }),
+    },
+    sqlConstraints: {
+        positive: { check: orm.sql `quantity > 0`, message: 'A part is used in a positive quantity.' },
+    },
+});
+export const RequestParts = extendModel('maintenance.request', {
+    fields: {
+        parts: f.one2many('maintenance.request.part', 'request', { label: 'Spare parts' }),
+        partsTransfer: f.many2one('stock.picking', { ondelete: 'set null', label: 'Parts transfer' }),
+        partsCost: f.decimal({
+            scale: 2,
+            store: true,
+            label: 'Parts cost',
+            ...compute('maintenance.request', 'partsCost', ['parts.cost'], (requests) => {
+                for (const r of requests)
+                    r.partsCost = [...r.parts].reduce((s, p) => s.plus(p.cost ?? zero), zero);
+            }),
+        }),
+    },
+    overrides: {
+        started: async function (next) {
+            await next();
+            await reserveParts(this);
+        },
+        finishing: async function (next) {
+            await next();
+            await consumeParts(this);
+        },
+        cancelled: async function (next) {
+            await next();
+            await releaseParts(this);
+        },
+    },
+});
+/** The orders' parts transfers (made when missing), reserved; as the system (technicians need no stock rights). */
+async function reserveParts(requests) {
+    const env = requests.env;
+    await env.asSuperuser({ reason: 'maintenance parts' }, async (su) => {
+        const maintenance = (await su
+            .model('stock.location')
+            .search({ where: { usage: 'adjustment', name: 'Maintenance' }, limit: 1 })).ids[0];
+        if (maintenance === undefined)
+            return;
+        for (const r of await su
+            .model('maintenance.request')
+            .browse(requests.ids)
+            .load({ parts: true, partsTransfer: true })) {
+            if (r.parts.length === 0)
+                continue;
+            const transfer = r.partsTransfer;
+            if (transfer === null || transfer.state === 'cancel') {
+                const from = (await defaultLocations(su, 'internal', null, r.company.id)).source;
+                if (from === null)
+                    continue;
+                const made = await su.model('stock.picking').create([
+                    {
+                        kind: 'adjustment',
+                        company: r.company.id,
+                        source: from,
+                        destination: maintenance,
+                        origin: r.name,
+                        moves: {
+                            create: [...r.parts].map((p) => ({
+                                product: p.product.id,
+                                quantity: p.quantity,
+                                uom: p.uom?.id ?? null,
+                            })),
+                        },
+                    },
+                ]);
+                await made.confirm();
+                await su
+                    .model('maintenance.request')
+                    .browse([r.id])
+                    .write({ partsTransfer: made.ids[0] ?? null });
+                continue;
+            }
+            if (transfer.state === 'confirmed')
+                await su.model('stock.picking').browse([transfer.id]).reserve();
+        }
+    });
+}
+/** The parts consumed: their transfer validated, refused while some are short. */
+async function consumeParts(requests) {
+    await reserveParts(requests);
+    const env = requests.env;
+    await env.asSuperuser({ reason: 'maintenance parts used' }, async (su) => {
+        for (const r of await su
+            .model('maintenance.request')
+            .browse(requests.ids)
+            .load({ partsTransfer: { moves: { product: true } } })) {
+            const t = r.partsTransfer;
+            if (t === null || t.state === 'done' || t.state === 'cancel')
+                continue;
+            if (t.availability !== 'full') {
+                const short = [...t.moves]
+                    .filter((m) => (m.reserved ?? zero).lt(m.productQty ?? zero))
+                    .map((m) => `${m.product.name} (${(m.productQty ?? zero).minus(m.reserved ?? zero).toString()})`);
+                throw new orm.ValidationError('maintenance.request', ['parts'], `Parts are short: ${short.join(', ')}.`, 'Wait for them to come in, or use fewer.');
+            }
+            await su.model('stock.picking').browse([t.id]).validate();
+        }
+    });
+}
+/** The parts released: their transfer cancelled. */
+async function releaseParts(requests) {
+    const env = requests.env;
+    await env.asSuperuser({ reason: 'maintenance parts released' }, async (su) => {
+        for (const r of await su
+            .model('maintenance.request')
+            .browse(requests.ids)
+            .load({ partsTransfer: true })) {
+            const t = r.partsTransfer;
+            if (t !== null && (t.state === 'draft' || t.state === 'confirmed'))
+                await su
+                    .model('stock.picking')
+                    .browse([t.id])
+                    .cancel();
+        }
+    });
+}
+export const maintenanceStockShutro = defineModule({
+    name: 'maintenance_stock',
+    version: '0.1.0',
+    depends: [maintenanceShutro, stockShutro, productShutro],
+    groups: [
+        orm.defineGroup({
+            code: 'maintenance_stock.user',
+            label: 'Maintenance with spare parts',
+            implies: ['maintenance.user', 'product.user'],
+        }),
+    ],
+    models: [MaintenancePart],
+    extensions: [RequestParts],
+    data: [
+        record('stock.location', 'location_maintenance', { name: 'Maintenance', usage: 'adjustment', company: null }, { noupdate: true }),
+    ],
+});

package/dist/modules-sdk/index.d.ts

@@ -6,5 +6,5 @@ export { type AppChange, type AppPlan, AppPlanError, type AppReason, type AppSta
 export { idByName, maybeIdByName } from './demo.js';
 export { ModuleDefinitionError, ModuleLoadError } from './errors.js';
 export { type LoadedModules, type LoadOptions, loadModules } from './loader.js';
-export { type AccessLevel, type ApprovalLevelSpec, type ApprovalSpec, type AppSpec, type AutomationActionSpec, type AutomationRuleSpec, type DemoContext, type DemoUser, type DocumentSpec, defineModule, type EventSpec, type ImportTemplateSpec, type InboundAliasSpec, type InboundCall, type InboundWebhookSpec, type KoshModule, type LocalizationSpec, type MenuSpec, type ModuleHooks, type ModuleInput, type PortalActionSpec, type PortalDocumentSpec, type ShutroModuleShape, } from './manifest.js';
+export { type AccessLevel, type ApprovalLevelSpec, type ApprovalSpec, type AppSpec, type AutomationActionSpec, type AutomationRuleSpec, type DemoContext, type DemoUser, type DocumentSpec, defineModule, type EventSpec, type ImportTemplateSpec, type InboundAliasSpec, type InboundCall, type InboundWebhookSpec, type KoshModule, type LocalizationSpec, type MenuSpec, type ModuleHooks, type ModuleInput, type PortalActionSpec, type PortalDocumentSpec, type SettingFieldSpec, type SettingsSectionSpec, type SettingsSpec, type ShutroModuleShape, type StandardWaiver, } from './manifest.js';
 export { compareVersions, satisfies } from './semver.js';

package/dist/modules-sdk/manifest.d.ts

@@ -57,8 +57,17 @@ export interface ApprovalLevelSpec {
     readonly name: string;
     /** A Shutro domain on the record (e.g. `{ amountTotal: { gt: '500000' } }`); empty or omitted: always. */
     readonly condition?: Readonly<Record<string, unknown>>;
-    /** The group or role whose holders (in the record's company) decide. */
+    /**
+     * The group or role whose holders (in the record's company) decide; with `approver`, the role used when there is
+     * nobody (no manager, an empty field).
+     */
     readonly approverRole: string;
+    /** Decided by the requester's manager (Workforce), or the person in a field of the record (RFC 0025). */
+    readonly approver?: 'manager' | {
+        readonly field: string;
+    };
+    /** How many decide: any one (default), all of them, or a number. */
+    readonly quorum?: 'any' | 'all' | number;
 }
 /** A default approval policy of a model. */
 export interface ApprovalSpec {
@@ -69,6 +78,12 @@ export interface ApprovalSpec {
     readonly onApproved?: string;
     /** A transition run when a level rejects. */
     readonly onRejected?: string;
+    /** A transition run when an approver sends the record back for changes. */
+    readonly onSentBack?: string;
+    /** A transition run when the requester withdraws the request. */
+    readonly onWithdrawn?: string;
+    /** A rejection or a sending back must say why (default: yes). */
+    readonly reasonRequired?: boolean;
 }
 /**
  * An automation rule a module ships (RFC 0011, RFC 0012 §5.1): installed by the Automation app as a rule owned by
@@ -297,7 +312,14 @@ export interface InboundAliasSpec {
     readonly subjectField: string;
     /** The field that takes the message text, when any. */
     readonly bodyField?: string;
-    readonly defaults?: Readonly<Record<string, unknown>> | ((env: unknown) => Promise<Readonly<Record<string, unknown>> | null>);
+    /**
+     * The new record's values: fixed, or from the system scope and the sender (a helpdesk ticket names its customer by
+     * the sender's address); `null` quarantines the message.
+     */
+    readonly defaults?: Readonly<Record<string, unknown>> | ((env: unknown, sender: {
+        readonly address: string;
+        readonly name: string | null;
+    }) => Promise<Readonly<Record<string, unknown>> | null>);
 }
 /** An action a module offers to automation rules (RFC 0011 §5.3). */
 export interface AutomationActionSpec {
@@ -415,12 +437,16 @@ export interface ModuleInput {
     readonly events?: readonly EventSpec[];
     /** Endpoints the module receives calls on from outside (RFC 0017 §5.4). */
     readonly inboundWebhooks?: readonly InboundWebhookSpec[];
+    /** The app's own settings, shown in Settings › App settings (RFC 0020). */
+    readonly settings?: SettingsSpec;
     /** What the module shows in the customer and vendor portal (RFC 0015), when `portal` is installed. */
     readonly portal?: {
         readonly documents: readonly PortalDocumentSpec[];
     };
     /** Import templates for the module's models (RFC 0014 §5.4), offered when `import` is installed. */
     readonly importTemplates?: readonly ImportTemplateSpec[];
+    /** The app's overview page: KPIs, charts and lists on its first menu (RFC 0022 §3.2). Needs `reporting`. */
+    readonly overview?: OverviewSpec;
     /**
      * Server routes of this module (admin APIs, custom endpoints). Called once at startup with the server context
      * (`ModuleContext` of `shutro-erp`); typed by the server, so modules declare the parameter type they use.
@@ -429,8 +455,89 @@ export interface ModuleInput {
     readonly hooks?: ModuleHooks;
     /** Translations per locale, loaded lazily. */
     readonly i18n?: Readonly<Record<string, () => Promise<unknown>>>;
+    /**
+     * Exceptions to the module standard (RFC 0023), each with its reason: `pnpm lint` (`scripts/check-modules.ts`)
+     * refuses a module that breaks an enforced rule for a model it has not waived here.
+     */
+    readonly standard?: {
+        readonly waive: readonly StandardWaiver[];
+    };
+}
+/** A rule of the module standard a module does not meet for one model (or at all), and why. */
+export interface StandardWaiver {
+    /** The rule's code (`M2`, `V1`, `P1`…), as RFC 0023 §3 names them. */
+    readonly rule: string;
+    /** The model the waiver is for; none: the whole module. */
+    readonly model?: string;
+    readonly reason: string;
+}
+/**
+ * A card of an app's overview (RFC 0022 §3.2): a live report query within the viewer's rules — a KPI (with the
+ * change against the previous period or last year), a chart, a small pivot, or the top records.
+ */
+export interface OverviewCardSpec {
+    readonly id: string;
+    readonly title: string;
+    readonly kind: 'kpi' | 'chart' | 'pivot' | 'list';
+    readonly model: string;
+    /** `count`, or `op:field` (`sum:amountTotal`, `avg:amountTotal`). */
+    readonly measure: string;
+    readonly groupBy?: string;
+    readonly filter?: Readonly<Record<string, unknown>>;
+    /** KPIs: this month against the previous one, or the same month last year, over this date field. */
+    readonly comparison?: {
+        readonly field: string;
+        readonly mode: 'previous' | 'yoy';
+    };
+    readonly chart?: 'bar' | 'line' | 'area' | 'pie';
+    /** Width in twelfths of the page. */
+    readonly w: 3 | 4 | 6 | 12;
+}
+/**
+ * An app's overview page (RFC 0022 §3.2): installed by `reporting` as a shared dashboard keyed by the module, and
+ * opened by the app's first menu (`<module>.action_overview`, generated). The module depends on `reporting`.
+ */
+export interface OverviewSpec {
+    readonly cards: readonly OverviewCardSpec[];
 }
 /** A defined module: frozen, with its name and version taken from the Shutro module. */
+/**
+ * A setting (RFC 0020 §3.1). In a `company` section, `key` names a `res.company` field the module adds with
+ * `extendModel`: its type, label and default come from the field; `help`, bounds and `visibleWhen` add to it. In an
+ * `installation` section, the setting is a key / value of its own: `type` and `label` are required.
+ */
+export interface SettingFieldSpec {
+    readonly key: string;
+    readonly type?: 'boolean' | 'integer' | 'decimal' | 'char' | 'text' | 'selection' | 'date';
+    readonly label?: string;
+    readonly help?: string;
+    readonly default?: string | number | boolean | null;
+    readonly min?: number;
+    readonly max?: number;
+    /** Selection options (installation settings): value → label. */
+    readonly options?: Readonly<Record<string, string>>;
+    /** Shown only when another setting of the section has this value. */
+    readonly visibleWhen?: {
+        readonly key: string;
+        readonly equals: string | number | boolean;
+    };
+}
+/** A section of an app's settings (RFC 0020 §3.1). */
+export interface SettingsSectionSpec {
+    readonly key: string;
+    readonly label: string;
+    readonly description?: string;
+    /** Words the Settings search also finds it by. */
+    readonly keywords?: string;
+    /** Per company (`res.company` fields) or for the whole installation. */
+    readonly scope: 'company' | 'installation';
+    /** Groups whose holders may change it; Administrators always may. Empty: administrators only. */
+    readonly editors?: readonly string[];
+    readonly fields: readonly SettingFieldSpec[];
+}
+export interface SettingsSpec {
+    readonly sections: readonly SettingsSectionSpec[];
+}
 export interface KoshModule extends Omit<ModuleInput, 'depends'> {
     readonly name: string;
     readonly version: string;

package/dist/modules-sdk/manifest.js

@@ -95,12 +95,46 @@ export function defineModule(input) {
         if (template.columns.length === 0)
             fail(`import template '${template.key}' has no columns.`, 'List the columns of the file.');
     }
+    // The overview (RFC 0022 §3.2): an action and a menu of its own, generated; reporting installs the dashboard.
+    const overviewActions = {};
+    const overviewMenus = [];
+    if (input.overview !== undefined) {
+        if (input.app === undefined)
+            fail('declares an overview without an app.', 'An overview is the first page of an app.');
+        if (!(input.depends ?? []).some((d) => d.name === 'reporting'))
+            fail('declares an overview without depending on reporting.', "Add `reporting` (from '../reporting/index.js') to `depends`.");
+        if (input.overview.cards.length === 0)
+            fail('declares an overview with no cards.', 'Give at least one KPI, chart, pivot or list card.');
+        const cardIds = new Set();
+        for (const card of input.overview.cards) {
+            if (!LEVEL.test(card.id) || cardIds.has(card.id))
+                fail(`overview card id '${card.id}' is not a unique snake_case name.`, "Use e.g. id: 'sales_month'.");
+            cardIds.add(card.id);
+            if (!/^(count|(sum|avg|min|max):[A-Za-z_][A-Za-z0-9_]*)$/.test(card.measure))
+                fail(`overview card '${card.id}' has the measure '${card.measure}'.`, "Use 'count' or 'sum:field'.");
+        }
+        overviewActions[`${name}.action_overview`] = {
+            type: 'client',
+            page: 'reporting.Overview',
+            label: 'Overview',
+        };
+        const root = (input.menus ?? []).find((menu) => menu.parent === undefined && menu.app !== undefined);
+        if (root !== undefined)
+            overviewMenus.push({
+                id: `${name}.overview`,
+                parent: root.id,
+                label: 'Overview',
+                action: `${name}.action_overview`,
+                sequence: 0,
+            });
+    }
     return Object.freeze({
         ...input,
         name,
         version: input.shutro.version,
         depends: Object.freeze([...(input.depends ?? [])]),
         accessLevels: Object.freeze({ ...input.accessLevels }),
-        menus: Object.freeze([...(input.menus ?? [])]),
+        actions: Object.freeze({ ...overviewActions, ...(input.actions ?? {}) }),
+        menus: Object.freeze([...(input.menus ?? []), ...overviewMenus]),
     });
 }

package/dist/mrp/.kosh/bindings.d.ts

@@ -0,0 +1,22 @@
+export { defineModel, defineModule, extendModel, f, replace } from '../../server/orm.js';
+import { type DefinitionHelpers } from '../../server/orm.js';
+import type { DefaultLoaded, Env as CoreEnv, RecordSet as CoreRecordSet, Shutro as CoreShutro } from '../../server/orm.js';
+import type { SchemaView } from './schema.js';
+export type { SchemaView };
+/** Every model visible in this view. */
+export type ModelName = keyof SchemaView & string;
+/** `Env` typed to this view. */
+export type Env = CoreEnv<SchemaView>;
+/** `Shutro` typed to this view. */
+export type Shutro = CoreShutro<SchemaView>;
+/** A recordset of `M`, with the default loaded shape unless `L` is given. */
+export type Records<M extends ModelName, L = DefaultLoaded<SchemaView, M>> = CoreRecordSet<SchemaView, M, L>;
+export declare const compute: DefinitionHelpers<SchemaView>['compute'];
+export declare const check: DefinitionHelpers<SchemaView>['check'];
+export declare const onchange: DefinitionHelpers<SchemaView>['onchange'];
+export declare const records: DefinitionHelpers<SchemaView>['records'];
+export declare const method: DefinitionHelpers<SchemaView>['method'];
+/** Module data (RFC 0017): records, overrides of dependencies' records, and references, typed like creates. */
+export declare const record: DefinitionHelpers<SchemaView>['record'];
+export declare const override: DefinitionHelpers<SchemaView>['override'];
+export declare const ref: DefinitionHelpers<SchemaView>['ref'];

package/dist/mrp/.kosh/bindings.js

@@ -0,0 +1,15 @@
+// GENERATED by `pnpm generate:models` (Shutro’s generator). Do not edit. definitions-hash: 5cfa5bbf11a2ffb6
+// Bindings of module `mrp`: import the definition API from here to get types scoped to what it can see.
+export { defineModel, defineModule, extendModel, f, replace } from '../../server/orm.js';
+import { definitions } from '../../server/orm.js';
+/** Definition callbacks typed against this module's view: no casts in computes, checks, onchange, methods. */
+const helpers = definitions();
+export const compute = helpers.compute;
+export const check = helpers.check;
+export const onchange = helpers.onchange;
+export const records = helpers.records;
+export const method = helpers.method;
+/** Module data (RFC 0017): records, overrides of dependencies' records, and references, typed like creates. */
+export const record = helpers.record;
+export const override = helpers.override;
+export const ref = helpers.ref;