Skip to content

feat(api): publish the order config flow's graph so consumers can sequence it - #300

Merged
roncodes merged 2 commits into
dev-v0.6.61from
feat/public-order-config-flow-graph
Aug 23, 2026
Merged

feat(api): publish the order config flow's graph so consumers can sequence it#300
roncodes merged 2 commits into
dev-v0.6.61from
feat/public-order-config-flow-graph

Conversation

@roncodes

Copy link
Copy Markdown
Member

The problem

Http/Resources/v1/OrderConfig::projectFlow() projects each activity down to
code, status, details, color, complete, pod_method and require_pod.

Those describe an activity. None of them describes the flow's shape, so what a
public API consumer receives is an unordered set of activities with no way to put
them in order.

The fields that express the shape are exactly the ones being dropped:

field meaning
activities the codes this activity can transition to — the flow is a directed graph
sequence orders activities reachable from the same parent
logic and/or/not conditions gating availability

OrderConfig::nextActivity()Activity::getNext() walks precisely these
server-side, and the console's internal resource returns flow whole — so the
gap is invisible from the console and only bites API consumers.

Why it matters

It is not cosmetic. A client that renders progress from array position marks an
order complete whenever completed happens to be declared before the order's
current activity. The default transport config on a stock instance returns:

created, enroute, started, completed, dispatched

completed fourth, dispatched last. So a freshly dispatched order shows every
step as done, reports itself complete, and offers no next step at all
— the
driver-facing screen's primary action disappears on a job that has not started.

This was found building the Navigator redesign against a live instance.

The change

projectFlow() now also publishes sequence, activities and logic.

  • These describe the configured workflow, not internal state, so there is
    nothing here a consumer of the config should not already see.
  • Transitions are normalised to a list of codes: flows have been authored both as
    bare codes and as objects carrying a code, and a consumer should not have to
    guess which it was handed. Entries with neither are skipped.
  • The three fields are always present — null or [] rather than absent — so a
    client can read the contract rather than feel for it.

Tests

Three cases added to server/tests/Unit/Http/Resources/OrderConfigResourceTest.php:

  • the graph survives the projection, including a flow declared out of workflow
    order and a branch carrying logic
  • transitions written as objects normalise to codes, and malformed entries drop
  • a legacy activity with none of the three fields still gets all three keys
Tests:  4 passed (14 assertions)

Verified they fail when the projection is wrong, not just pass when it is right.

server/tests/Feature/Http/Api/OrderConfigControllerTest.php fatals locally on a
missing Illuminate\Foundation\Auth\Access\AuthorizesRequests trait. That
reproduces on a clean tree at this base commit and is unrelated to this change,
which touches only a Resource.

…uence it

The public order-config resource projected each activity down to code, status,
details, color, complete, pod_method and require_pod. Those describe an activity
but say nothing about the flow's shape, so what reaches an API consumer is an
unordered set of activities with no way to put them in order.

The stored flow is a directed graph, and the fields that express it were the
ones being dropped: `activities` names the codes an activity can transition to,
`sequence` orders activities reachable from the same parent, and `logic` gates
availability. OrderConfig::nextActivity walks exactly these server-side, and the
console's internal resource returns the flow whole, so the gap is only visible
from the public API.

The consequence is not cosmetic. A client rendering progress from array position
marks an order complete whenever `completed` happens to be declared before the
order's current activity — the default transport config lists `completed` fourth
and `dispatched` last, so a freshly dispatched order shows as finished and
offers no next step at all.

These describe the configured workflow rather than internal state, so there is
nothing here a consumer of the config should not already see. Transitions are
normalised to a list of codes, since flows have been authored both as bare codes
and as objects carrying one, and the three fields are always present — null or
empty rather than absent — so a client can read the contract instead of feeling
for it.
…fields

The compact-resource test pinned the pre-change flow entry, so adding sequence,
activities and logic to the projection made its whole-array comparison fail and
took PHP CI down. Update the expectation to the shape the resource now emits.

Also cover projectTransitions' non-array guard, which no fixture reached — it
was the one statement standing between the new code and the 100% gate.
@roncodes roncodes mentioned this pull request Aug 23, 2026
@roncodes
roncodes changed the base branch from main to dev-v0.6.61 August 23, 2026 03:48
@codecov

codecov Bot commented Aug 23, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (8d301d1) to head (b27d47d).
⚠️ Report is 8 commits behind head on dev-v0.6.61.

Additional details and impacted files
@@               Coverage Diff               @@
##             dev-v0.6.61      #300   +/-   ##
===============================================
  Coverage         100.00%   100.00%           
- Complexity          9815      9823    +8     
===============================================
  Files                523       523           
  Lines              37888     37903   +15     
===============================================
+ Hits               37888     37903   +15     
Flag Coverage Δ
backend 100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@roncodes
roncodes merged commit cf20a07 into dev-v0.6.61 Aug 23, 2026
11 checks passed
@roncodes
roncodes deleted the feat/public-order-config-flow-graph branch August 23, 2026 04:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant