Migration Status — EC-CUBE 4.3 → BEAR.Sunday + Be Framework

Documentation

Migration Status — EC-CUBE 4.3 → BEAR.Sunday + Be Framework

Living document. Update the relevant row/cell whenever a layer’s status changes. Updated 2026-06-09 JST against 1.x commit f4d77609, alps.json, be/src, src/Resource, var/templates, var/sql, docs/api/openapi.json, and the Web E2E evidence set.

The migration runs through 5 layers. ALPS is the source of truth; the lower layers implement it. “Done / partial / pending” is judged against the ALPS spec, route-gate coverage, and the explicit residual boundary, not optimistically.

1. Summary

Test baseline: after the PR closeout and API doc refresh, GitHub Actions on 1.x passes composer psalm and composer test; PHPUnit reports 1734 tests, 26059 assertions. The latest Web E2E evidence set (20260608-canonical-resource-routes-web-e2e) runs html-prod-hal-api-app against an actual DB and records 181 pass / 2 fail / 3 out-of-scope across 186 features with 140 retained screenshots. Target-engine SQL portability still needs explicit MariaDB 10.11 verification where noted in §4.

2. Feature matrix

Rows = flow-* feature areas (see docs/tag.md for the tag taxonomy). Columns = the 5 layers. Counts are ALPS transitions per flow. ✓ done · ~ partial · ✗ pending.

Layer-specific notes:

• ALPS: 217 transitions — the older 144-transition snapshot has been superseded by route-gate additions and several behavioral descriptors that make route/fallback decisions explicit.
• SQL: 150/150 — every #[DbQuery] id has a matching SQL file under var/sql/, and the smoke coverage test enforces this pairing.
• HTML: storefront ✓ / admin ✓ (in scope) — var/templates holds 133 .html.twig files: 43 storefront/non-admin pages, 72 admin pages/partials, 15 Block widgets, and 3 frames (base.html.twig, admin-base.html.twig, admin-login-base.html.twig). The remaining admin Store/Plugin install/search subtree is out of scope because the plugin runtime is excluded. The render-diff fidelity tests (tests/Resource/*HtmlRenderTest.php) activate only when the gitignored tools/ec-cube-source/ 4.3 clone is present.
• flow-manage-cms Resource — Admin/Template/TemplateList.php + TemplateAdd exist for the CMS template feature; layout/block resources are present but the CMS template-management surface is partial — unverified in full.

2.1 Rendered forms without a write handler

Two admin resources still render a <form method="post"> that no method answers. The markup was ported ahead of the handler, so the button reaches BEAR\Resource and comes back 405. Reproduce any row with composer page -- post <path>.

Each of the remaining two needs a scope decision before a transition: file-manager needs a multipart file-I/O design, and two-factor-auth-edit needs the admin-editing-another-member 2FA semantics worked out (issue #143).

Page/Admin/Product/CsvProduct.html.twig was an earlier entry. Its upload posted to its own screen URL instead of /admin/product-csv, where ProductCsv::onPost already implements the import (the router turns an import_file upload into the csv parameter). Repointing the action was the whole fix — no new transition.

Admin/CustomerDeliveryEdit.php, Admin/Customer.php, and Admin/Product/ProductClass.php were three more entries, fixed for #143: each gained an admin-specific Be Input/Final (AdminCreateCustomerDeliveryAddressInput, AdminUpdateCustomerDeliveryAddressInput, AdminDeleteCustomerDeliveryAddressInput, AdminUpdateCustomerInput, AdminRegisterProductClassInput) distinct from the storefront transitions — UpdateCustomerAddressInput omits customerId on purpose and derives the owner from the customer session, which is the opposite of an administrator editing someone else’s row.

tests/Router/TemplateFormActionTest.php holds the same list and fails both ways: a third dead form breaks the build, and so does an entry that is no longer dead. The other 121 POST forms resolve to a resource that writes.

2.2 #[Alps] references the profile does not define

alps.json is the SSOT and #[Alps('id')] is a resource claiming to implement one of its transitions. Nothing checked that the id exists — asd --validate validates the profile, not the references into it — and 19 had drifted; 15 were resolved for #143. tests/Alps/AlpsReferenceTest.php now holds the remaining list and fails on a fifth as well as on an entry that has since been resolved.

The four: doCreateMailTemplate, goAdminContentFileManager, goAdminTwoFactorAuthEdit, goShoppingShippingMultipleEdit.

goShoppingShippingMultipleEdit is not a rename — it is an editor screen distinct from the goShoppingShippingMultiple (list) transition it links to.

Two of the four are also the two remaining §2.1 dead forms (goAdminContentFileManager / goAdminTwoFactorAuthEdit), so for those the read descriptor, the write descriptor and the handler land together.

Resolved for #143: the route-gate/fallback ids (doActionRedirect, goUnsupportedRoute, +6) and the placeholder goAdminEmptyPage dropped #[Alps] — a client cannot discover a URL EC-CUBE has that BeMart deliberately does not model as an application transition. goAdminLog / goAdminOrderOrderPdf / goAdminOrderMailConfirm / goAdminTemplateTemplateAdd were renamed (the last two to existing profile ids goOrderMailConfirm / goTemplateInstall; the first two to new descriptors goLog / goOrderPdf, since goAdminOrderOrderPdf is not a rename of goExportOrderPdf — it is the distinct options-form screen that links to it). goAdminCustomerDeliveryEdit / goAdminProductProductClass became goCustomerDeliveryEdit / goProductClass alongside the §2.1 dead-form fixes above.

3. Phase log

ALPS remediation (f01e1ae, per docs/phases/alps-audit-phase3.md) happened during Phase 3: it re-tagged Favorite and added transitions that Phase A’s domain never saw. Later route-gate work made hard route/fallback decisions explicit in ALPS, so the current profile is larger than the Phase-A/Phase-3 snapshots.

4. Outstanding work

Punch-list, roughly highest-effort first:

1. Admin HTML Tier-2 — rendered, two write handlers missing. Admin Tier-1 plus every in-scope Tier-2 editor wave is ported as markup: flow-manage-system, Customer delivery-edit, Setting/System, Setting/Shop, Order, Product, and Store template_add. Current admin inventory is 72 admin page/partial templates. Two of those screens post to a resource that cannot answer — §2.1 lists them, and until each gains a write handler the editor is display-only. The remaining Store/Plugin install/search subtree is out of scope because plug-ins are excluded from this migration. Per-section history: docs/phases/admin-fanout-plan.md and var/templates/README.md “Fan-out status”.
2. HTML enrichment backlog. Phase 3 flagged data pages whose resource bodies are too thin for a faithful EC-CUBE port; each needs the Cart-style re-derive (ALPS → Entity/SQL/Fake enrich → template wiring). Done: Mypage History (a31f8d8/3c1b03d), Shopping confirm/complete (1177e0d/2f8d17a). Still open: Mypage dashboard, Favorite, Address, Contact.
3. Block/* widget templates — done. ✓ Done. The logo and footer Block widgets are ported (var/templates/Block/, f3df0d4). The remaining Block regions (cart/login/search) stay EC-CUBE-runtime residuals; Block is intentionally not modelled in ALPS.
4. Phase-3 remediation transitions — all implemented. ✓ Done. The named transitions the Phase-3 ALPS remediation added are implemented in be/src (doSortNoMove, doToggleVisible, doUpdateTrackingNumber, doSendShippingNotifyMail, doResendActivationMail — domain + storage/mailer + JSON resource + tests). Later route-gate descriptors are tracked separately from this remediation set.
5. Phase-A stub / compatibility residuals. goExportOrderPdf is now the Issue #24 compatibility pilot: Resource reachability, download headers, and %PDF- body generation are implemented through an isolated EC-CUBE/TCPDF service, but full EC-CUBE fidelity (delivery-note layout parity, dtb_order_pdf saved settings, multi-shipping template reproduction) is intentionally left as a tracked residual. doImportCategoryCsv and doImportShippingCsv are real — CategoryCsvImported parses the 4-column EC-CUBE format and upserts/deletes via CategoryStorageInterface (+ CategoryIdQueryInterface for new ids); AdminShippingCsvImported resolves each row’s order and writes the tracking number through the same ShippingAddressStorageInterface::updateTrackingNumber surface as the inline doUpdateTrackingNumber (durable persistence covered by the SQL suite; Fake writes are no-ops). doUpdateCsv is consumed end-to-end — the export Finals overlay saved dtb_csv configuration on their default column vector via CsvColumnLayout::resolve, preserving default output when config is absent or enables no known columns. doCreateOrder and doCheckout now converge on PurchaseFlow + dtb_order_item snapshot writes — admin order creation and storefront checkout both freeze line items through OrderItemCommandInterface::register, with domain wiring pinned by AdminOrderCreatedTest / CheckoutCompletedSnapshotTest. ⚠ SQL verification caveat: the durable order-item SQL path still needs a green target-engine run of DATABASE_URL=... vendor/bin/phpunit --testsuite sql; order_item_register.sql uses JSON_TABLE while the target is documented as MariaDB 10.11, so portability must be confirmed or the INSERT rewritten without JSON_TABLE. The alps.json contract was synced to match (OrderItemInput, regenerated HTML/SVG artifacts). Still stubbed / intentionally-not-modelled: doImportProductCsv (intentionally not migrated — the route is export-only), doInstallPlugin (plugin scope, out of scope).
6. #[Input]-vs-Form refactor. Noted from MyVendor.Cms issue #37 — reconcile Be Framework #[Input] with the Ray.WebFormModule AbstractForm. Unverified here — confirm against that issue before acting.
7. Production DB bring-up. Phase 2c shipped the seed script and prod SqlModule binding; an actual production database bring-up / cutover is still pending.
8. Hard ActionRedirect routes — connected. ✓ Done. The 22 Hard rows that Issue #24 parked on ActionRedirect (docs/eccube-feature-alps-status.html) are now wired to concrete Be/BEAR resources with the Be domain transition implemented: 認証/credential (doChangePassword / doVerifyTwoFactorAuth / doSetTwoFactorAuth / doUpdateSecurity), コンテンツ/file (doClearCache / doUpdateContentCss / doUpdateContentJs / doToggleMaintenance), マスタデータ (doSelectMasterData / doUpdateMasterData), 規格CSV (goExportClassName / goExportClassCategory / doImportClassNameCsv / doImportClassCategoryCsv), Store/template (doSelectTemplate / doDeleteTemplate / doDownloadTemplate / doInstallTemplate). Each side-effect (credential hash, TOTP, config/cache/asset files, CSV encode/parse, template zip/install) is isolated behind a be/src/Reason/Service/*Interface boundary with an src/Compatibility/Eccube/ default + a Fake — the Issue #24 PDF-pilot pattern. Full EC-CUBE fidelity for those side-effects (real file writes, byte-exact CSV, persisted TOTP secret) is the tracked production-cutover residual. Difficulty stays Hard; the routes are now 実装済み, so the Hard-ActionRedirect count is 0. ⚠ 2FA setup pre-auth residual (PR #28 review — TwoFactorAuthSet::onPut): the device-setup page is reached PRE-AUTH (anonymous login-context), so it currently takes loginId + the candidate TOTP secret from the request body, and TwoFactorAuthInterface::enable() overwrites the secret for that loginId with no ownership check — a caller who passes another admin’s loginId could replace that admin’s 2FA device. The production cutover must bind a server-generated secret + the pending login identity into a pre-auth session/challenge state at credential-verification time and consume it here instead of trusting the client values; until then the route relies on CSRF + the documented enable() contract. Do not widen this surface (e.g. expose it post-auth for an arbitrary loginId) before the challenge state lands.

5. Where things live