@open-mercato/core 0.6.6-develop.6381.1.042df302c3 → 0.6.6-develop.6383.1.27fcc83455

package/src/modules/sales/agentic/standalone-guide.md

@@ -1,104 +0,0 @@
-# Sales Module — Standalone App Guide
-
-Use the sales module for orders, quotes, invoices, shipments, and payments. This module has the most complex business logic in the system.
-
-## Document Flow
-
-```
-Quote → Order → Invoice
-         ↓
-    Shipments + Payments
-```
-
-- Quotes convert to orders — do not create orders without a source quote (unless configured)
-- Orders track shipments and payments independently
-- Each entity has its own status workflow — do not skip states
-- Returns create line-level adjustments and update `returned_quantity`
-
-## Pricing Calculations
-
-Always use the sales calculation service — never inline price math:
-
-```typescript
-const calcService = container.resolve('salesCalculationService')
-```
-
-- Dispatches `sales.line.calculate.*` and `sales.document.calculate.*` events
-- For catalog pricing: use `selectBestPrice` from the catalog module
-- Register custom line/totals calculators or override via DI
-
-## Channel Scoping
-
-All sales documents are scoped to channels. Channel selection affects:
-- Available pricing tiers
-- Document numbering sequences
-- Visibility in admin UI
-
-## Data Model
-
-### Core Entities
-| Entity | Purpose | Key Constraint |
-|--------|---------|---------------|
-| **Sales Orders** | Confirmed customer orders | MUST have a channel and at least one line |
-| **Sales Quotes** | Proposed orders | MUST track conversion status |
-| **Order/Quote Lines** | Individual items | MUST reference valid products |
-| **Adjustments** | Discounts/surcharges | MUST use registered `AdjustmentKind` |
-
-### Fulfillment
-| Entity | Purpose |
-|--------|---------|
-| **Shipments** | Delivery tracking with status workflow |
-| **Payments** | Payment recording with status workflow |
-| **Returns** | Order returns with line selection and automatic adjustments |
-
-### Configuration (do not modify directly)
-Channels, statuses, payment/shipping methods, price kinds, adjustment kinds, and document numbers — configure via admin UI or `setup.ts` hooks.
-
-## Subscribing to Sales Events
-
-```typescript
-// src/modules/<your_module>/subscribers/order-created.ts
-export const metadata = {
-  event: 'sales.order.created',
-  persistent: true,
-  id: 'your-module-order-created',
-}
-
-export default async function handler(payload, ctx) {
-  // React to new orders
-}
-```
-
-Key events: `sales.order.created` / `updated` / `deleted`, `sales.quote.created` / `updated`, `sales.payment.created`, `sales.shipment.created`
-
-## Extending Sales UI
-
-Widget injection spots:
-
-**Order & Quote detail page:**
-- `sales.document.detail.order:details` — order detail page sections
-- `sales.document.detail.quote:details` — quote detail page sections
-- `sales.document.detail.order:tabs` — order detail page tabs
-- `sales.document.detail.quote:tabs` — quote detail page tabs
-- `detail:sales.order:stage-bar` — order stage bar (empty, ready for extension)
-- `detail:sales.quote:stage-bar` — quote stage bar (empty, ready for extension)
-- `detail:sales.order:closure` — order closure section (empty, ready for extension)
-- `detail:sales.quote:closure` — quote closure section (empty, ready for extension)
-
-**Order list:**
-- `data-table:sales.orders:columns` — order list columns
-- `data-table:sales.orders:row-actions` — order row actions
-
-**Order form:**
-- `crud-form:sales.sales_order:fields` — order detail form
-
-**Payments:**
-- `data-table:sales.payments:columns` — payment list columns
-
-**Payment methods:**
-- `crud-form:sales.payment_method:fields` — payment method form fields
-- `crud-form:sales.sales_payment_method:fields` — sales payment method form fields
-
-## Frontend Pages
-
-- `frontend/quote/` — public-facing quote view for customer acceptance

package/src/modules/workflows/agentic/standalone-guide.md

@@ -1,152 +0,0 @@
-# Workflows Module — Standalone App Guide
-
-Use the workflows module for business process automation: defining step-based workflows, executing instances, handling user tasks, and triggering workflows from domain events.
-
-## Using Workflows in Your App
-
-The workflow engine is provided by `@open-mercato/core`. Your standalone app can:
-
-1. **Create workflow definitions** via the visual editor at `/backend/workflows`
-2. **Trigger workflows** from domain events emitted by your modules
-3. **Subscribe to workflow events** for side effects in your modules
-4. **Inject UI widgets** into workflow pages or inject workflow widgets into your pages
-5. **Define user tasks** that require human approval or data entry
-
-## Starting Workflows Programmatically
-
-Resolve the workflow executor via DI — never import lib functions directly:
-
-```typescript
-// In your module's DI-aware context (API route, subscriber, worker)
-const executor = container.resolve('workflowExecutor')
-
-await executor.startWorkflow({
-  workflowId: 'order-approval',  // matches a WorkflowDefinition.workflowId
-  context: {
-    orderId: order.id,
-    orderTotal: order.totalGross,
-    customerName: order.customerName,
-  },
-  organizationId,
-  tenantId,
-})
-```
-
-## Event Triggers
-
-Configure automatic workflow starts from your module's domain events:
-
-1. Create a workflow definition with a `triggers[]` entry in the visual editor or via API
-2. The workflow engine's wildcard subscriber evaluates all non-internal events
-3. Use `filterConditions` to narrow which events match (e.g., only orders above a threshold)
-4. Use `contextMapping` to extract event payload fields into workflow context variables
-5. Use `debounceMs` and `maxConcurrentInstances` to prevent trigger storms
-
-Excluded event prefixes (never trigger workflows): `query_index`, `search`, `workflows`, `cache`, `queue`.
-
-## Subscribing to Workflow Events
-
-React to workflow lifecycle events in your module:
-
-```typescript
-// src/modules/<your_module>/subscribers/workflow-completed.ts
-export const metadata = {
-  event: 'workflows.instance.completed',
-  persistent: true,
-  id: 'your-module-workflow-completed',
-}
-
-export default async function handler(payload, ctx) {
-  // payload.resourceId = instance ID
-  // payload.workflowId = definition ID
-  // payload.context = workflow context variables
-}
-```
-
-Key workflow events your module can subscribe to:
-
-| Event | When it fires |
-|-------|--------------|
-| `workflows.instance.created` | New workflow instance started |
-| `workflows.instance.completed` | Workflow finished successfully |
-| `workflows.instance.failed` | Workflow failed |
-| `workflows.instance.cancelled` | Workflow was cancelled |
-| `workflows.task.created` | User task assigned |
-| `workflows.task.completed` | User task completed |
-| `workflows.step.completed` | Individual step finished |
-
-## Step Types
-
-| Step type | Use case |
-|-----------|----------|
-| `START` | Entry point — every definition has exactly one |
-| `END` | Terminal step — marks workflow as COMPLETED |
-| `USER_TASK` | Human approval or data entry — pauses until task completion |
-| `AUTOMATED` | Executes transition activities immediately and advances |
-| `SUB_WORKFLOW` | Invokes a nested workflow definition |
-| `WAIT_FOR_SIGNAL` | Pauses for an external signal (e.g., payment confirmed) |
-| `WAIT_FOR_TIMER` | Pauses for a configured duration |
-| `PARALLEL_FORK` / `PARALLEL_JOIN` | Splits/merges parallel execution paths |
-
-## Activity Types
-
-Activities execute on transitions between steps:
-
-| Activity type | Use case |
-|---------------|----------|
-| `SEND_EMAIL` | Send templated email |
-| `CALL_API` | Call an internal API endpoint |
-| `CALL_WEBHOOK` | Call an external HTTP endpoint |
-| `UPDATE_ENTITY` | Mutate an entity via the command bus |
-| `EMIT_EVENT` | Emit a domain event |
-| `EXECUTE_FUNCTION` | Run a registered custom function |
-| `WAIT` | Delay execution for a configured duration |
-
-Use `{{context.*}}`, `{{workflow.*}}`, `{{env.*}}`, `{{now}}` for variable interpolation in activity config — never hardcode values.
-
-## Sending Signals
-
-Resume a workflow waiting for an external signal:
-
-```typescript
-const executor = container.resolve('workflowExecutor')
-
-await executor.sendSignal({
-  instanceId: workflowInstanceId,
-  signalName: 'payment_confirmed',
-  payload: { transactionId: '...' },
-  organizationId,
-  tenantId,
-})
-```
-
-## Widget Injection
-
-Inject workflow-related UI into your module's pages, or inject your module's widgets into workflow pages:
-
-```typescript
-// src/modules/<your_module>/widgets/injection-table.ts
-export const widgetInjections = {
-  // Inject into workflow task detail page
-  'workflows.task.detail:after': {
-    widgetId: 'your-module-task-context',
-    priority: 50,
-  },
-}
-```
-
-## Compensation (Saga Pattern)
-
-When a workflow step fails, compensation activities execute in reverse order to undo previous steps. This follows the saga pattern:
-
-- **Sync activities** execute inline and advance immediately
-- **Async activities** enqueue to the `workflow-activities` queue; workflow pauses until completion
-- On failure, compensation runs in reverse — keep activity handlers **idempotent** (check state before mutating)
-
-## Key Rules
-
-- MUST resolve services via DI (`container.resolve('workflowExecutor')`) — never import lib functions directly
-- MUST use `workflowExecutor.startWorkflow()` to create instances — never insert rows directly
-- MUST keep activity handlers idempotent — they may be retried on failure
-- MUST scope all queries by `organization_id` — workflow data is tenant-scoped
-- MUST NOT couple your module to workflow internals — use event triggers and signals for integration