Files
summercms/.planning/phases/18-payment-gateway/18-VALIDATION.md
Jakub Zych 63febdde98 docs(18-07): phase 18 validation map validated and Nyquist-compliant
- every per-task row green; Wave 0 and sign-off complete
- gate record: check-phase18.sh --all passed every stage, postgres run on
  a Docker host
- PHP map 72 of 74 (the 2 pgstripe reliability cases are 18.1)
- D-11: no host shop rows supplied; the synthetic fixtures stand in
2026-10-13 17:35:30 +02:00

15 KiB
Raw Blame History

phase, slug, status, nyquist_compliant, wave_0_complete, created, validated
phase slug status nyquist_compliant wave_0_complete created validated
18 payment-gateway validated true true 2026-10-12 2026-10-13

Phase 18 — Validation Strategy

Per-phase validation contract for feedback sampling during execution.


Test Infrastructure

Property Value
Framework Go testing (+ testcontainers-go Postgres), vitest (admin SPA), node --test (vue-paymentgateway-layer)
Config file none for Go; admin/ vitest config exists; layer package.json test script (Wave 0)
Quick run command the after-commit sample: go vet ./... && go test -short ./... in the touched Go repo (summercms.go, sm-paymentgateway-plugin, sm-pgstripe-plugin; in summercms.go scoped to the package under test, go test -short ./modules/cabana), plus npm --prefix admin test -- <the task's spec files> when a task changed admin/ (one or two spec files, no build, no typecheck) and pnpm --dir ../vue-paymentgateway-layer test for the layer
Full suite command bash scripts/check-phase18.sh --all (written in the last plan, modelled on scripts/check-phase17.sh)
Estimated runtime ~60 seconds quick; task-close gates (admin build, OpenAPI, docs checker) up to 10 minutes; several minutes full (Docker)

Sampling Rate

  • After every task commit: Run the quick command in the touched repo
  • After every plan wave: Run go test ./... (Docker) in the touched repos, plus npm --prefix admin run test when admin changed
  • Before /msd-verify-work: bash scripts/check-phase18.sh --all must be green
  • Max feedback latency: 120 seconds for the after-commit sample (the quick command). The per-task <automated> chains of 18-01 and 18-07 that include check-admin-dist.sh (a fresh admin build), the full vitest run, the OpenAPI check, the docs checker or a gate stage are task-close gates: they run once per task before its commit, are bounded at 10 minutes, and are not the after-commit sample (18-01 and 18-07 say so in their <verification> sections).

Per-Task Verification Map

Filled by the planner from the PLAN.md tasks (2026-10-13); the executor flips Status per task. Every command runs from the summercms.go repository root (the go -C ../<repo> idiom for sibling repositories); Docker-backed rows carry the docker info >/dev/null 2>&1 && prefix in the plans and are recorded NOT RUN when no daemon answers. "File Exists" names the plan and task that creates the test (W0 = created by that task; the test does not exist before it).

Area Behavior Test Type Automated Command File Exists Status
D-07 cabana money field compile-only checks, inventories, OpenAPI, typecheck, MoneyField vitest, dist, docs (18-01 T1) unit + gate go vet ./... && go test -count=1 -short -run '^TestMoneyField' -v ./modules/cabana 2>&1 | grep -- '^--- PASS: TestMoneyField' && bash scripts/check-admin-openapi.sh --check && npm --prefix admin run typecheck && npm --prefix admin test -- tests/form/MoneyField.test.ts && bash scripts/check-admin-dist.sh && go test -count=1 -run '^TestDocsTree$' ./cmd/summer && go run ./cmd/summer docs:build --check ✅ (18-01 T1) ✅ green
D-07 money save round trip, 422 keys (18-01 T1) integration (Docker) go test -count=1 -run '^TestMoneyFieldSmoke$' -v ./modules/cabana 2>&1 | grep -- '^--- PASS: TestMoneyFieldSmoke' ✅ (18-01 T1) ✅ green
D-07, F5-F7 money list column, danger flag, Edit rule, kit; CellValue/RecordActions/PreviewView specs (18-01 T2) unit + Docker go test -count=1 -short ./modules/cabana ./modules/pact && npm --prefix admin test -- tests/list/CellValue.test.ts tests/form/RecordActions.test.ts tests/form/PreviewView.test.ts; Docker: go test -count=1 -run '^(TestMoneyListSmoke|TestRecordActionDangerSmoke)$' -v ./modules/cabana ✅ (18-01 T2) ✅ green
D-13, F2-F4 settings secrets (states, keep, clear, env), richeditor on settings, tabs; PasswordField/SettingsFormView specs (18-01 T3) unit + Docker go test -count=1 -short ./modules/cabana && npm --prefix admin test -- tests/form/PasswordField.test.ts tests/views/SettingsFormView.test.ts; Docker: go test -count=1 -run '^(TestSettingsSecretSmoke|TestSettingsRichEditorSmoke)$' -v ./modules/cabana ✅ (18-01 T3) ✅ green
Release framework release gate before the tag decision (18-01 T4) gate go vet ./... && go test -count=1 -short ./... && npm --prefix admin run typecheck && npm --prefix admin test && bash scripts/check-admin-dist.sh && bash scripts/check-admin-openapi.sh --check && go run ./cmd/summer docs:build --check ✅ ✅ green
SC-1 MoneyRight vectors, Amount4 Scan/Value, FSM smoke (18-02 T2) unit go -C ../sm-paymentgateway-plugin test -count=1 -short -run '^(TestMoneyVectorsSmoke|TestAmount4ScanValue)$' ./money/ && go -C ../sm-paymentgateway-plugin test -count=1 -short -run '^TestFSMSmoke$' ./fsm/ ✅ (18-02 T2) ✅ green
SC-1, SC-3 cash order Make → Purchase → Accept → Paid, OrderPaid once, replay no-op (18-02 T2) integration (Docker) go -C ../sm-paymentgateway-plugin test -count=1 -run '^TestPaymentGatewayTracer$' -v . ✅ (18-02 T2) ✅ green
D-11 legacy reader goldens, unknown type, v2 re-encode (18-02 T3) unit go -C ../sm-paymentgateway-plugin test -count=1 -short -run '^TestLegacyCartGoldens$' -v ./cart/ ✅ (18-02 T3) ✅ green
SC-1 refund bridge, reject cancels payments, RecordExternal (18-02 T3) integration (Docker) go -C ../sm-paymentgateway-plugin test -count=1 -run '^(TestPaymentGatewayTracer|TestRefundBridgeSmoke)$' -v . ✅ (18-02 T3) ✅ green
SC-2 notification route paths × methods, de-urlize, mode merge, 404/403 verify-first (18-02 T4) integration (httptest) go -C ../sm-paymentgateway-plugin test -count=1 -short -run '^TestNotificationRoute$' -v . ✅ (18-02 T4) ✅ green
SC-3 NBP/Fixer exact parsing and conversion vectors (18-02 T4) unit (httptest) go -C ../sm-paymentgateway-plugin test -count=1 -short -run '^TestCurrencyProviders$' -v ./currency/ ✅ (18-02 T4) ✅ green
SC-2, SC-3 verified notification accepts, commands by timeout, settings import (18-02 T4) integration (Docker) go -C ../sm-paymentgateway-plugin test -count=1 -run '^(TestNotificationRouteSmoke|TestPGCommandsSmoke|TestImportWinterSmoke)$' -v . ✅ (18-02 T4) ✅ green
SC-3 Orders admin: list labels and money, record actions per state, danger, permissions (18-03 T1) integration (Docker) go -C ../sm-paymentgateway-plugin test -count=1 -run '^TestOrdersAdminSmoke$' -v . ✅ (18-03 T1) ✅ green
SC-3 Payments, Shippings, Quote items admin (18-03 T2) integration (Docker) go -C ../sm-paymentgateway-plugin test -count=1 -run '^(TestPaymentsAdminSmoke|TestShippingsAdminSmoke|TestQuoteablesAdminSmoke)$' -v . ✅ (18-03 T2) ✅ green
SC-3 Quotes create, cart actions, process_quote, asset allowlist (18-03 T3) integration (Docker) go -C ../sm-paymentgateway-plugin test -count=1 -run '^(TestQuotesAdminSmoke|TestOrdersAdminSmoke)$' -v . ✅ (18-03 T3) ✅ green
D-08 PG and Mailer settings pages, required currency, OrderPaid mail after commit (18-04 T1) integration (Docker) go -C ../sm-paymentgateway-plugin test -count=1 -run '^(TestPGSettingsSmoke|TestMailerSettingsSmoke|TestMailTracer)$' -v . ✅ (18-04 T1) ✅ green
SC-3 mailer gating matrix, recipients, locale; mailer keys import (18-04 T2) integration (Docker) go -C ../sm-paymentgateway-plugin test -count=1 -run '^(TestMailersMatrixSmoke|TestImportWinterSmoke)$' -v . ✅ (18-04 T2) ✅ green
SC-4 Checkout operator path on the proof host (18-05 T1) integration (Docker + httptest) go -C ../sm-pgstripe-plugin test -count=1 -run '^TestHostStripeFlow$/^checkout_operator_path$' -v . ✅ (18-05 T1) ✅ green
SC-2, D-14 webhook signature cases, older api_version, minimal decode (18-05 T2) unit (httptest) go -C ../sm-pgstripe-plugin test -count=1 -short -run '^TestStripeWebhook$' -v . ✅ (18-05 T2) ✅ green
SC-4, D-04 full host flow: PaymentIntent, path (b), wrong secret, missing header/secret, replay and race, browser return, refund (18-05 T2) integration (Docker + httptest) go -C ../sm-pgstripe-plugin test -count=1 -run '^TestHostStripeFlow$' -v . (≥ 11 subtests) ✅ (18-05 T2) ✅ green
D-13 Stripe settings never return secrets; import with Laravel decrypt (18-05 T3) integration (Docker) go -C ../sm-pgstripe-plugin test -count=1 -run '^(TestStripeSettingsSmoke|TestStripeImportWinterSmoke)$' -v . ✅ (18-05 T3) ✅ green
D-06, D-17 API tracer: guest/owner access, process cash, 409 (18-06 T2) integration (Docker) go -C ../sm-paymentgateway-plugin test -count=1 -run '^TestCustomerAPITracer$' -v . ✅ (18-06 T2) ✅ green
D-06 layer client, money formatting, redirect contract (18-06 T2) unit (node --test) pnpm --dir ../vue-paymentgateway-layer test (TAP # fail 0, # pass ≥ 1) ✅ (18-06 T2) ✅ green
D-06 full API authz matrix and state guards (18-06 T3) integration (Docker) go -C ../sm-paymentgateway-plugin test -count=1 -run '^(TestCustomerAPI|TestCustomerAPITracer)$' -v . ✅ (18-06 T3) ✅ green
D-06 layer polling, tone map, i18n parity, cart rules; playground prepares (18-06 T4) unit (node --test) pnpm --dir ../vue-paymentgateway-layer test (TAP # pass ≥ 15) && pnpm --dir ../vue-paymentgateway-layer run dev:prepare ✅ (18-06 T4) ✅ green
Gate phase gate stages and self-test (18-07 T1) gate bash scripts/check-phase18.sh --self-test && bash scripts/check-phase18.sh go && bash scripts/check-phase18.sh plugins && bash scripts/check-phase18.sh layers && bash scripts/check-phase18.sh docs; Docker: bash scripts/check-phase18.sh postgres ✅ (18-07 T1) ✅ green
D-07, D-13 framework unit tests: money compile/validate/list, secrets, tabs, richeditor, danger, conformance; all vitest (18-07 T2) unit + Docker go test -count=1 -short ./modules/cabana && npm --prefix admin test && bash scripts/check-phase18.sh go && bash scripts/check-phase18.sh admin; Docker: go test -count=1 -run '^(TestMoneyFieldSave|TestSettingsSecretPostgres|TestPhase10OpenAPIConformance)$' ./modules/cabana ✅ (18-07 T2) ✅ green
SC-1, SC-2, SC-3, D-02, D-11 PHP map (63), matrices, fixtures, registry, hashids, redactor, events, mailers, migrations, commands, import, authz, notification security (18-07 T3) unit + Docker go -C ../sm-paymentgateway-plugin test -count=1 -short ./... && bash scripts/check-phase18.sh plugins; Docker: go -C ../sm-paymentgateway-plugin test -count=1 -run '^(TestMigrations|TestPGCommands|TestImportWinter|TestCustomerAPIAuthz|TestNotificationSecurity)$' ./... ✅ (18-07 T3) ✅ green
SC-4, SC-5, D-02 pgstripe PHP map (9 + 18.1 note), operator unit, SDK pin; layer tests; full gate; validation map (18-07 T4) unit + gate go -C ../sm-pgstripe-plugin test -count=1 -short ./... && pnpm --dir ../vue-paymentgateway-layer test && bash scripts/check-phase18.sh --all; Docker: PHASE18_REQUIRE_POSTGRES=1 bash scripts/check-phase18.sh --all ✅ (18-07 T4) ✅ green
Docs docs checker, OpenAPI, dist (every framework task) gate go test ./cmd/summer -run TestDocsTree && summer docs:build --check && scripts/check-admin-openapi.sh --check && scripts/check-admin-dist.sh ✅ ✅ green

Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky

Gate record (18-07 Task 4, 2026-10-13): bash scripts/check-phase18.sh --all passed every stage on a Docker host: self-test, go, plugins, admin, layers, docs and postgres, with no stage NOT RUN. The postgres stage covers the cabana money, secret, richeditor, danger and conformance suites (9 tests), the 22 Postgres suites of sm-paymentgateway-plugin and the 3 of sm-pgstripe-plugin. The layer ran 69 TAP tests with 0 failures. Every Go repository is green under go vet ./... and go test -short ./.... The admin stage failed once under a host load average of about 35 from other sessions (timeouts in unrelated specs); it passed on a rerun and in the full run. Those failures were flakiness, not a red test.

PHP test map (D-02): 72 of 74 cases are covered by Go tests that name their PHP origin. The 63 paymentgateway cases are covered one to one in sm-paymentgateway-plugin, and the 9 pgstripe security cases in sm-pgstripe-plugin. The 2 pgstripe ReliabilityTest cases cover the subscription job, which is Phase 18.1 scope; TestHostStripeFlow/replay_and_race is this phase's idempotency evidence.

Fixtures (D-11): no host-exported shop rows were supplied (the human's reply at the 18-06 checkpoint was "fixtures: none"). The one anonymized real row and the PHP-generated synthetic rows stay the D-11 evidence. TestLegacyFixtures decodes every file under cart/testdata/legacy/, after the anonymization check, so shop-export-* rows added later are covered.


Wave 0 Requirements

  • New repos sm-paymentgateway-plugin, sm-pgstripe-plugin with go.mod/go.work and an integration_test.go harness copied from sm-journal-plugin (TestMain with flag.Parse() + testing.Short())
  • testdata/legacy/ golden fixtures (the one real legacy row anonymized as legacy-real-1-{cart,details}.json + PHP-generated synthetic-*.json rows; 18-02 T3; the fixture names and contents name no consuming application)
  • money/vectors_test.go seeded from the PHP vectors in 18-RESEARCH.md
  • Shared Stripe httptest fake helper for pgstripe tests
  • vue-paymentgateway-layer scaffold copied from vue-journal-layer
  • scripts/check-phase18.sh (created in the last plan, 18-07 Task 1, per the project rule that unit tests are the last plan of every phase; it is the full-suite gate, not a prerequisite of plans 01 to 06, whose tasks carry their own <automated> commands)

Manual-Only Verifications

Behavior Requirement Why Manual Test Instructions
Real shop-type golden fixtures D-11 Needs anonymized production rows from other apps Asked at the 18-06 checkpoint. The reply was "fixtures: none", because the old apps ran a much older payment gateway. The synthetic rows stand in. Rows exported later go in as shop-export-cart-<n>.json and shop-export-details-<n>.json, and TestLegacyFixtures picks them up
Layer visual check in a playground D-06 Visual layout Run the layer .playground, walk order → checkout redirect

Validation Sign-Off

  • All tasks have <automated> verify or Wave 0 dependencies
  • Sampling continuity: no 3 consecutive tasks without automated verify
  • Wave 0 covers all MISSING references
  • No watch-mode flags
  • Feedback latency < 120s for the after-commit sample (task-close gates are bounded separately, see Sampling Rate)
  • nyquist_compliant: true set in frontmatter

Approval: validated 2026-10-13 by the 18-07 gate run (scripts/check-phase18.sh --all, postgres run on a Docker host)