lcp 0.1.0

data/docs/guides/workflow.md

@@ -0,0 +1,692 @@
+# Workflows
+
+Workflows add state machine behavior to enum fields — enforced transitions, guard conditions, role restrictions, auto-set fields, events, and a dedicated audit trail. This guide walks through setting up a workflow from scratch.
+
+## Prerequisites
+
+You need a model with an enum field. The workflow governs how that field changes.
+
+```yaml
+# config/lcp_ruby/models/purchase_order.yml
+model:
+  name: purchase_order
+  fields:
+    - { name: title, type: string, validations: [{ type: presence }] }
+    - { name: description, type: text }
+    - name: total_amount
+      type: decimal
+      column_options: { precision: 12, scale: 2 }
+    - name: status
+      type: enum
+      default: draft
+      enum_values:
+        - { value: draft, label: Draft }
+        - { value: pending_approval, label: Pending Approval }
+        - { value: approved, label: Approved }
+        - { value: rejected, label: Rejected }
+    - { name: submitted_at, type: datetime }
+    - { name: submitted_by, type: integer }
+    - { name: approved_at, type: datetime }
+  options:
+    timestamps: true
+    auditing: true
+    label_method: title
+```
+
+## Step 1: Define the Workflow
+
+Create a workflow file that references the model and its enum field:
+
+```yaml
+# config/lcp_ruby/workflows/purchase_order.yml
+workflow:
+  name: purchase_order_workflow
+  model: purchase_order
+  field: status
+  version: 1
+  audit_log: true
+
+  states:
+    draft:
+      initial: true
+      category: draft
+      color: gray
+      icon: file-text
+
+    pending_approval:
+      category: waiting
+      color: blue
+      icon: clock
+      readonly_fields: [title, total_amount]
+      on_entry: [notify_approvers]
+
+    approved:
+      category: terminal
+      color: green
+      icon: check-circle
+      readonly_fields: all
+
+    rejected:
+      category: rejected
+      color: red
+      icon: x-circle
+
+  transitions:
+    submit:
+      from: draft
+      to: pending_approval
+      label: "Submit for Approval"
+      icon: send
+      style: primary
+      roles: [author, admin]
+      guard:
+        all:
+          - { field: title, operator: present }
+          - { field: total_amount, operator: gt, value: 0 }
+      set_fields:
+        submitted_at: { date: now }
+        submitted_by: { current_user: id }
+      events: [po_submitted]
+      confirm: true
+
+    approve:
+      from: pending_approval
+      to: approved
+      label: "Approve"
+      icon: check
+      style: success
+      roles: [admin]
+      set_fields:
+        approved_at: { date: now }
+
+    reject:
+      from: pending_approval
+      to: rejected
+      label: "Reject"
+      icon: x
+      style: danger
+      roles: [admin]
+      require_comment: true
+
+    rework:
+      from: rejected
+      to: draft
+      label: "Return to Draft"
+      icon: rotate-ccw
+      roles: [author, admin]
+```
+
+Key points:
+- **One initial state** — `draft` is marked `initial: true`. New records start here.
+- **States define behavior** — `readonly_fields` locks fields, `on_entry` fires events.
+- **Transitions define allowed paths** — `submit` can only go from `draft` to `pending_approval`.
+- **Guards** use the same condition syntax as `visible_when` and `record_rules`.
+- **`set_fields`** auto-populates fields during the transition (timestamps, user IDs).
+
+## Step 2: Set Up Audit Logging
+
+If you set `audit_log: true`, you need an audit log model. Generate it:
+
+```bash
+rails generate lcp_ruby:workflow_audit_log
+```
+
+This creates:
+- `config/lcp_ruby/models/workflow_audit_log.yml`
+- `config/lcp_ruby/presenters/workflow_audit_logs.yml`
+- `config/lcp_ruby/permissions/workflow_audit_log.yml`
+
+Restart the server to create the table.
+
+## Step 3: Set Up Permissions
+
+Your permissions YAML controls who can do what. The workflow's `roles` key restricts which roles can trigger each transition, but the user still needs `update` permission on the model.
+
+```yaml
+# config/lcp_ruby/permissions/purchase_order.yml
+permissions:
+  model: purchase_order
+  roles:
+    admin:
+      crud: [index, show, create, update, destroy]
+      fields: { readable: all, writable: all }
+      scope: all
+    author:
+      crud: [index, show, create, update]
+      fields:
+        readable: all
+        writable: [title, description, total_amount]
+      scope: all
+    viewer:
+      crud: [index, show]
+      fields: { readable: all, writable: [] }
+      scope: all
+  default_role: author
+```
+
+Transition access is the intersection of:
+- Permission system: user has `update` CRUD permission
+- Workflow roles: user's role is in `transition.roles`
+- Guard: condition passes
+
+## Step 4: Create the Presenter
+
+No special configuration needed. Transition buttons appear automatically on the show page:
+
+```yaml
+# config/lcp_ruby/presenters/purchase_orders.yml
+presenter:
+  name: purchase_orders
+  model: purchase_order
+  slug: purchase-orders
+
+  index:
+    columns:
+      - { field: title }
+      - { field: total_amount }
+      - { field: status }
+      - { field: submitted_at }
+
+  show:
+    sections:
+      - title: "Details"
+        fields:
+          - { field: title }
+          - { field: description }
+          - { field: total_amount }
+          - { field: status }
+          - { field: submitted_at }
+
+  form:
+    sections:
+      - title: "Order"
+        fields:
+          - { field: title }
+          - { field: description }
+          - { field: total_amount }
+
+  actions:
+    single:
+      - { name: show, type: built_in }
+      - { name: edit, type: built_in }
+      - { name: destroy, type: built_in }
+```
+
+Transition buttons are added alongside the other action buttons. You can customize or hide them:
+
+```yaml
+actions:
+  single:
+    # Override transition appearance
+    - name: submit
+      style: primary
+
+    # Hide a transition from this presenter
+    - name: rework
+      visible: false
+```
+
+## What Happens at Runtime
+
+1. **User creates a record** — status defaults to `draft`, `workflow_version` is set to `1`.
+
+2. **User clicks "Submit for Approval"** — the engine:
+   - Checks guard: `title` present AND `total_amount > 0`
+   - Checks role: user is `author` or `admin`
+   - Sets `submitted_at` to current time, `submitted_by` to user ID
+   - Updates `status` to `pending_approval`
+   - Saves in a transaction
+   - Writes audit log entry
+   - Fires `notify_approvers` event (via `on_entry`)
+   - Fires `po_submitted` event (transition-level)
+
+3. **Fields are locked** — while in `pending_approval`, `title` and `total_amount` cannot be edited (form fields are disabled, server rejects changes).
+
+4. **Admin clicks "Approve"** — status changes to `approved`, `approved_at` is set, `readonly_fields: all` locks every field.
+
+5. **Alternative: Admin clicks "Reject"** — a comment is required (textarea appears). Status changes to `rejected`.
+
+6. **After rejection: Author clicks "Return to Draft"** — status goes back to `draft`, fields are editable again.
+
+## Using the DSL
+
+The same workflow in Ruby DSL:
+
+```ruby
+# config/lcp_ruby/workflows/purchase_order.rb
+define_workflow :purchase_order_workflow do
+  model :purchase_order
+  field :status
+  version 1
+  audit_log true
+
+  state :draft, initial: true, category: :draft, color: "gray"
+  state :pending_approval, category: :waiting, color: "blue",
+    readonly_fields: [:title, :total_amount],
+    on_entry: [:notify_approvers]
+  state :approved, category: :terminal, color: "green",
+    readonly_fields: :all
+  state :rejected, category: :rejected, color: "red"
+
+  transition :submit, from: :draft, to: :pending_approval,
+    label: "Submit for Approval", icon: "send", style: :primary,
+    roles: [:author, :admin], confirm: true do
+    guard all: [
+      { field: :title, operator: :present },
+      { field: :total_amount, operator: :gt, value: 0 }
+    ]
+    set_fields submitted_at: :now, submitted_by: "current_user.id"
+    fire_events :po_submitted
+  end
+
+  transition :approve, from: :pending_approval, to: :approved,
+    label: "Approve", style: :success, roles: [:admin] do
+    set_fields approved_at: :now
+  end
+
+  transition :reject, from: :pending_approval, to: :rejected,
+    label: "Reject", style: :danger, roles: [:admin], require_comment: true
+
+  transition :rework, from: :rejected, to: :draft,
+    label: "Return to Draft", roles: [:author, :admin]
+end
+```
+
+## Writing Event Handlers
+
+The `on_entry`, `on_exit`, and transition-level `events` all use the standard event handler system:
+
+```ruby
+# app/event_handlers/purchase_order/notify_approvers.rb
+class PurchaseOrder::NotifyApprovers < LcpRuby::Events::HandlerBase
+  def self.handles_event = "notify_approvers"
+
+  def call
+    # record is already in the new state
+    # current_user is the person who triggered the transition
+    AdminMailer.approval_needed(record).deliver_later
+  end
+end
+```
+
+Event dispatch order during a transition (`draft` → `pending_approval`):
+
+1. `on_exit` events for the old state (if any)
+2. `on_entry` events for the new state
+3. Transition-level `events`
+
+All events receive `changes` hash: `{ "status" => ["draft", "pending_approval"] }`.
+
+## System Triggers
+
+Every transition declares **who can fire it** through `trigger:`. The three values cover the full matrix:
+
+| `trigger:` | Shown as UI button | Callable via `execute_transition!` | Typical use |
+|------------|--------------------|-------------------------------------|-------------|
+| `user` *(default)* | yes | yes | Normal user-initiated transitions |
+| `system` | **no** | yes | Approval engine, background jobs, integrations |
+| `both` | yes | yes | Same transition reachable from UI and code |
+
+See the [Transition Attributes reference table](../reference/workflow.md#trigger-values) for the canonical row.
+
+Transitions with `trigger: system` are not shown as UI buttons. They are designed for programmatic use — approval engines, background jobs, or external integrations:
+
+```yaml
+transitions:
+  auto_approve:
+    from: pending_approval
+    to: approved
+    trigger: system
+    set_fields:
+      approved_at: { date: now }
+```
+
+Call them from code:
+
+```ruby
+record.execute_transition!(
+  "auto_approve",
+  user: system_user,
+  evaluator: evaluator,
+  triggered_by: "approval_engine"
+)
+```
+
+The `triggered_by` value is stored in the audit log's `metadata` field.
+
+## Locking Fields per State
+
+### Specific Fields
+
+Lock certain fields while the record is in a state:
+
+```yaml
+states:
+  pending_approval:
+    readonly_fields: [title, total_amount, department_id]
+```
+
+### All Fields
+
+Lock every field (fully frozen record):
+
+```yaml
+states:
+  approved:
+    readonly_fields: all
+```
+
+In both cases:
+- Edit form renders locked fields as disabled
+- Server rejects changes to locked fields in `permitted_params`
+- Admin can still use `force_approve` or similar transitions to bypass
+
+## Guard Conditions
+
+Guards prevent transitions when conditions aren't met. They use the same condition syntax as the rest of the platform:
+
+```yaml
+# Simple: one field check
+guard:
+  field: total_amount
+  operator: gt
+  value: 0
+
+# Compound: multiple conditions
+guard:
+  all:
+    - { field: title, operator: present }
+    - { field: total_amount, operator: gt, value: 0 }
+    - { field: department_id, operator: present }
+
+# With dynamic reference
+guard:
+  field: assigned_to_id
+  operator: eq
+  value: { field_ref: current_user.id }
+```
+
+When a guard fails, the transition button is hidden (not just disabled) and programmatic execution raises `TransitionDeniedError`.
+
+## Requiring Comments
+
+Force users to explain their decision:
+
+```yaml
+transitions:
+  reject:
+    from: pending_approval
+    to: rejected
+    require_comment: true
+```
+
+The UI shows a textarea that must be filled before the transition executes. The comment is stored in the workflow audit log.
+
+## Confirmation Dialogs
+
+Add a confirmation step before execution:
+
+```yaml
+transitions:
+  submit:
+    from: draft
+    to: pending_approval
+    confirm: true
+    confirm_message: "Submit this order for approval? This cannot be undone."
+```
+
+The browser shows a confirmation dialog. Custom message is optional — the default is "Are you sure?".
+
+## Programmatic Access
+
+### Execute a Transition
+
+```ruby
+record = PurchaseOrder.find(1)
+evaluator = LcpRuby::Authorization::PermissionEvaluator.new(perm_def, user, "purchase_order")
+
+result = record.execute_transition!("submit", user: user, evaluator: evaluator)
+result.success?    # => true
+result.from_state  # => "draft"
+result.to_state    # => "pending_approval"
+```
+
+With comment:
+
+```ruby
+record.execute_transition!("reject",
+  user: user,
+  evaluator: evaluator,
+  comment: "Budget exceeded"
+)
+```
+
+### Check Available Transitions
+
+```ruby
+transitions = record.available_transitions(user: user, evaluator: evaluator)
+transitions.map(&:name)  # => ["submit", "cancel"]
+```
+
+### Query Current State
+
+```ruby
+state = record.current_workflow_state
+state.name          # => "draft"
+state.initial?      # => true
+state.terminal?     # => false
+state.all_readonly? # => false
+```
+
+### Query Audit History
+
+```ruby
+record.workflow_audit_logs.each do |log|
+  puts "#{log.transition_name}: #{log.from_state} → #{log.to_state} by user #{log.user_id}"
+end
+```
+
+## Seeding Records in a Known State
+
+`db/seeds.rb`, fixtures, and data migrations frequently need to create records that *start* in a non-initial state (e.g. an already-approved order) without firing the workflow guards or transition callbacks. The workflow enforces transitions through an `update_columns`-bypassable callback chain on the `state` enum, so the recommended approach for seeds is:
+
+```ruby
+# 1. Create the record — workflow lands it in the initial state.
+order = Order.create!(title: "Seeded order", total_amount: 100)
+
+# 2. Re-write the state column directly, skipping callbacks/guards/audit log.
+order.update_columns(status: "approved", approved_at: Time.current, approved_by: 1)
+```
+
+`update_columns` (plural) writes directly to the database. It deliberately:
+
+- skips workflow guards — no `TransitionDeniedError` even if no transition exists from `draft` → `approved`;
+- skips state-machine callbacks — `set_fields:` rules in transitions are NOT applied (you must write any derived columns yourself, as shown above);
+- skips the audit log — no row is added to `workflow_audit_logs`;
+- skips ActiveRecord validations.
+
+Use this **only** in seeds, fixtures, and one-off data migrations. In application code, call `record.execute_transition!(...)` so the workflow's invariants are honoured. A first-class `Workflow.skip_transitions { ... }` API that opts every record inside the block out of the guards (while preserving audit log) is on the roadmap (see [aggregated audit C11](../improve-tasks/aggregated.md#c-medium--13-dny)).
+
+## DB-Backed Workflows
+
+For workflows managed at runtime (e.g., by admin users through a UI):
+
+```ruby
+LcpRuby.configure do |config|
+  config.workflow_source = :model
+  config.workflow_model = "workflow_definition"
+end
+```
+
+Create the model with required fields (name, model_name, field_name, states, transitions, version, active). The `states` and `transitions` fields should be JSON columns containing the same structure as the YAML.
+
+Static (YAML/DSL) workflows are always loaded if files exist. DB workflows are additive. On name conflicts, static wins.
+
+## Host Application Workflows
+
+For complex routing logic that cannot be expressed declaratively:
+
+```ruby
+LcpRuby.configure do |config|
+  config.workflow_source = :host
+  config.workflow_provider = MyWorkflowProvider.new
+end
+```
+
+The provider must implement `workflows_for(model_name)` and `workflow_by_name(name)`.
+
+## i18n
+
+Transition labels support i18n lookup:
+
+```yaml
+# config/locales/en.yml
+en:
+  lcp_ruby:
+    workflows:
+      purchase_order_workflow:
+        transitions:
+          submit: "Submit for Approval"
+          approve: "Approve Order"
+          reject: "Reject Order"
+      comment_placeholder: "Add a comment..."
+      confirm_default: "Are you sure?"
+```
+
+Fallback chain: i18n key → `label` from YAML → humanized transition name.
+
+## Visualizing Workflow Status
+
+Workflow fields are automatically rendered with visual components — no renderer configuration needed.
+
+### Show Page: Timeline
+
+On show pages, the workflow field renders as a linear progress bar:
+
+```
+ ✓ Draft  ──  ● Pending Approval  ──  ○ Approved
+```
+
+The engine auto-detects the workflow and injects `workflow_timeline`. To customize which states appear, add `timeline_states` to the workflow definition:
+
+```yaml
+workflow:
+  name: purchase_order_workflow
+  timeline_states: [draft, pending_approval, approved]  # excludes rejected
+```
+
+Or override per-presenter with explicit options:
+
+```yaml
+show:
+  layout:
+    - section: "Details"
+      fields:
+        - field: status
+          renderer: workflow_timeline
+          options:
+            states: [draft, pending_approval, approved]
+            compact: true
+```
+
+### Index Page: Badge
+
+On index pages, the workflow field renders as a colored badge using the state's `color` from the workflow definition. No configuration needed.
+
+To opt out of auto-detection, set any explicit renderer:
+
+```yaml
+index:
+  table_columns:
+    - field: status
+      renderer: badge   # uses generic badge instead
+      options:
+        color_map: { draft: gray, approved: green }
+```
+
+### Composite Page: Workflow Graph
+
+Add a `workflow_graph` widget to a composite page to show the full state diagram:
+
+```yaml
+page:
+  name: purchase_order_show
+  model: purchase_order
+  layout: composite
+  zones:
+    - name: details
+      area: main
+      type: presenter
+      presenter: purchase_order
+    - name: workflow
+      area: sidebar
+      type: widget
+      widget:
+        type: workflow_graph
+        show_audit_trail: true
+        highlight_available: true
+```
+
+See the [Renderers Guide](display-types.md#workflow-renderers) for full options and the [Pages Reference](../reference/pages.md#workflow_graph) for widget configuration.
+
+## Testing
+
+```ruby
+RSpec.describe "Purchase Order Workflow" do
+  let(:user) { create_user(role: "admin") }
+  let(:evaluator) { build_evaluator(user, "purchase_order") }
+
+  it "transitions from draft to pending_approval" do
+    record = PurchaseOrder.create!(title: "Test", total_amount: 100)
+
+    result = record.execute_transition!("submit", user: user, evaluator: evaluator)
+
+    expect(result.success?).to be true
+    expect(record.reload.status).to eq("pending_approval")
+    expect(record.submitted_at).to be_present
+    expect(record.submitted_by).to eq(user.id)
+  end
+
+  it "blocks direct enum changes" do
+    record = PurchaseOrder.create!(title: "Test", total_amount: 100)
+
+    expect {
+      record.update!(status: "approved")
+    }.to raise_error(LcpRuby::Workflow::TransitionDeniedError)
+  end
+
+  it "enforces guard conditions" do
+    record = PurchaseOrder.create!(title: "Test", total_amount: 0)
+
+    expect {
+      record.execute_transition!("submit", user: user, evaluator: evaluator)
+    }.to raise_error(LcpRuby::Workflow::TransitionDeniedError, /guard condition/)
+  end
+end
+```
+
+## Approval Engine
+
+For multi-step approval processes (sequential/parallel strategies, delegation, bypass, rework), see the [Workflow Approvals Reference](../reference/workflow-approvals.md).
+
+### Quick Setup
+
+1. Generate the approval models: `rails generate lcp_ruby:workflow_approvals`
+2. Add an `approvals` section to your workflow YAML
+3. Define resolution transitions with `trigger: system`
+
+```yaml
+approvals:
+  pending_approval:
+    strategy: sequential
+    resolution:
+      approved: approve_transition
+      rejected: reject_transition
+    steps:
+      - name: manager_review
+        approvers:
+          type: field
+          field: manager_id
+```
+
+Source: `lib/lcp_ruby/workflow/`, `lib/lcp_ruby/workflow/approval/`, `lib/lcp_ruby/model_factory/workflow_applicator.rb`, `lib/lcp_ruby/dsl/workflow_builder.rb`