shutro-erp 0.3.4 → 0.3.5

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, } from './manifest.js';
 export { compareVersions, satisfies } from './semver.js';

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

@@ -415,12 +415,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.
@@ -430,7 +434,73 @@ export interface ModuleInput {
     /** Translations per locale, loaded lazily. */
     readonly i18n?: Readonly<Record<string, () => Promise<unknown>>>;
 }
+/**
+ * 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: ea6308794cf1f163
+// 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;