core/php-commerce
8
0
Fork 0
Code Issues 13 Pull requests Projects Releases Packages Wiki Activity Actions

roadmap: php-commerce production readiness #16

New issue
Closed
opened 2026-02-20 11:11:04 +00:00 by Clotho · 1 comment
Clotho commented 2026-02-20 11:11:04 +00:00
Member
Copy link

Overview

This roadmap tracks all work required to bring php-commerce to production-ready status. Items are grouped by priority and linked to specific issues.

Status: 📊 13 issues created from discovery scan
Created: 2026-02-20 by discovery agent
Source: Comprehensive codebase scan (issue #2)

🔴 P1 - Critical (Must Fix Before Launch)

Code Quality

  • #3 - fix: add declare(strict_types=1) to Services/ files - 9 service files missing strict type declarations

Security

  • #12 - security: validate billing address structure in Order model - Prevent PDF/tax calculation failures
  • #13 - security: add CSRF protection to API billing endpoints - Protect state-changing operations

Outstanding from TODO.md

  • Database transactions for ReferralService::requestPayout() (TODO.md P2)
  • Optimistic locking for Subscription model (TODO.md P2)
  • Partial payment handling in BTCPay (TODO.md P2)

P1 Total: 6 items (3 new issues + 3 from TODO.md)

🟠 P2 - High Priority (Launch Blockers)

Missing Features

  • #15 - refactor: implement provisioning API endpoints - ProductApiController, EntitlementApiController
  • Subscription upgrade/downgrade via API with proration (TODO.md P2)
  • Credit note application to future invoices (TODO.md P2)

Error Handling

  • Retry mechanism for invoice PDF generation (TODO.md P2)
  • Improve checkout failure error messages (TODO.md P2)
  • Alerting for repeated payment failures (TODO.md P2)

Test Coverage

  • #4 - test: add tests for PaymentMethodService
  • #5 - test: add tests for InvoiceService
  • #6 - test: add tests for ReferralService
  • #7 - test: add tests for UsageBillingService
  • #8 - test: add tests for WarehouseService
  • #9 - test: add tests for ProductCatalogService
  • #10 - test: add tests for PermissionMatrixService
  • #11 - test: add integration tests for Stripe webhook handlers
  • Payment method management UI tests (TODO.md P2)
  • Concurrent subscription operation tests (TODO.md P2)
  • Multi-currency order flow tests (TODO.md P2)
  • Referral commission edge case tests (TODO.md P2)

P2 Total: 18 items (8 new issues + 10 from TODO.md)

🟡 P3 - Medium Priority (Production Polish)

Performance

  • Add index on orders.idempotency_key (TODO.md P3)
  • Add index on invoices.workspace_id, status (TODO.md P3)
  • Optimize subscription expiry query with chunking (TODO.md P3)
  • Cache exchange rates in-memory (TODO.md P3)
  • Add eager loading to order/invoice queries (TODO.md P3)

Code Quality

  • Extract TaxResult to Data/ directory (TODO.md P3)
  • Add return type DTOs to gateway contract (TODO.md P3)
  • Create OrderStateMachine class (TODO.md P3)
  • Consolidate customer creation logic (TODO.md P3)
  • Standardize money handling with brick/money (TODO.md P3)

Developer Experience

  • Add commerce:health Artisan command (TODO.md P3)
  • Add commerce:simulate-webhook command (TODO.md P3)
  • #14 - docs: add class-level documentation to SKU services
  • Document SKU format and lineage system in CLAUDE.md (TODO.md P3)
  • Add typed properties to Livewire components (TODO.md P3)

Observability

  • Add metrics for payment success/failure rates (TODO.md P3)
  • Add structured logging to webhook handlers (TODO.md P3)
  • Add tracing spans for checkout flow (TODO.md P3)

P3 Total: 18 items (1 new issue + 17 from TODO.md)

🟢 P4 - Low Priority (Nice to Have)

UI/UX

  • Add loading states to checkout components (TODO.md P4)
  • Add subscription change confirmation modal (TODO.md P4)
  • Improve invoice PDF design (TODO.md P4)
  • Add currency selector persistence (TODO.md P4)

Features

  • Subscription pause scheduling (TODO.md P4)
  • Invoice PDF caching (TODO.md P4)
  • Webhook event viewer in admin (TODO.md P4)
  • Referral analytics dashboard (TODO.md P4)
  • Tax-inclusive pricing support (TODO.md P4)

Technical Debt

  • Rename View/Modal/ to View/Livewire/ (TODO.md P4)
  • Move factories to database/factories/ (TODO.md P4)
  • Update Carbon usage for v3 compatibility (TODO.md P4)

P4 Total: 12 items (all from TODO.md)

Summary Statistics

Discovery Scan Results

  • ✅ 185 PHP files scanned
  • ✅ 0 empty/stub methods found
  • ✅ 0 missing type hints detected
  • ✅ 0 SQL injection vulnerabilities found
  • ✅ 1 TODO comment in code (documented)
  • ⚠️ 9 files missing strict_types
  • ⚠️ 10 services without dedicated tests
  • ⚠️ 2 P1 security items outstanding

Issue Breakdown

  • Created: 13 new issues (#3-#15)
  • Labeled: All with discovery, security items with review
  • Priority: 3 P1, 8 P2, 1 P3, 1 docs

From TODO.md

  • P1 remaining: 3 items
  • P2 remaining: 10 items
  • P3 remaining: 17 items
  • P4 backlog: 12 items

Total Work

Grand Total: 55+ items across all priorities

Next Steps

  1. Immediate: Fix #3 (strict_types) - quick win, high impact
  2. Week 1: Address P1 security issues (#12, #13)
  3. Week 2-3: Implement P2 missing features (#15, provisioning API)
  4. Ongoing: Add test coverage (#4-#11) in parallel with feature work
  5. Polish: P3/P4 items as time permits

Related Issues

  • #2 - Discovery scan task (parent)
  • #3 - Strict types fix
  • #4-#11 - Test coverage
  • #12-#13 - Security
  • #14 - Documentation
  • #15 - Provisioning API

This roadmap will be updated as issues are completed and new requirements emerge.

## Overview This roadmap tracks all work required to bring php-commerce to production-ready status. Items are grouped by priority and linked to specific issues. **Status:** 📊 13 issues created from discovery scan **Created:** 2026-02-20 by discovery agent **Source:** Comprehensive codebase scan (issue #2) --- ## 🔴 P1 - Critical (Must Fix Before Launch) ### Code Quality - [ ] #3 - **fix: add declare(strict_types=1) to Services/ files** - 9 service files missing strict type declarations ### Security - [ ] #12 - **security: validate billing address structure in Order model** - Prevent PDF/tax calculation failures - [ ] #13 - **security: add CSRF protection to API billing endpoints** - Protect state-changing operations ### Outstanding from TODO.md - [ ] Database transactions for ReferralService::requestPayout() (TODO.md P2) - [ ] Optimistic locking for Subscription model (TODO.md P2) - [ ] Partial payment handling in BTCPay (TODO.md P2) **P1 Total:** 6 items (3 new issues + 3 from TODO.md) --- ## 🟠 P2 - High Priority (Launch Blockers) ### Missing Features - [ ] #15 - **refactor: implement provisioning API endpoints** - ProductApiController, EntitlementApiController - [ ] Subscription upgrade/downgrade via API with proration (TODO.md P2) - [ ] Credit note application to future invoices (TODO.md P2) ### Error Handling - [ ] Retry mechanism for invoice PDF generation (TODO.md P2) - [ ] Improve checkout failure error messages (TODO.md P2) - [ ] Alerting for repeated payment failures (TODO.md P2) ### Test Coverage - [ ] #4 - **test: add tests for PaymentMethodService** - [ ] #5 - **test: add tests for InvoiceService** - [ ] #6 - **test: add tests for ReferralService** - [ ] #7 - **test: add tests for UsageBillingService** - [ ] #8 - **test: add tests for WarehouseService** - [ ] #9 - **test: add tests for ProductCatalogService** - [ ] #10 - **test: add tests for PermissionMatrixService** - [ ] #11 - **test: add integration tests for Stripe webhook handlers** - [ ] Payment method management UI tests (TODO.md P2) - [ ] Concurrent subscription operation tests (TODO.md P2) - [ ] Multi-currency order flow tests (TODO.md P2) - [ ] Referral commission edge case tests (TODO.md P2) **P2 Total:** 18 items (8 new issues + 10 from TODO.md) --- ## 🟡 P3 - Medium Priority (Production Polish) ### Performance - [ ] Add index on `orders.idempotency_key` (TODO.md P3) - [ ] Add index on `invoices.workspace_id, status` (TODO.md P3) - [ ] Optimize subscription expiry query with chunking (TODO.md P3) - [ ] Cache exchange rates in-memory (TODO.md P3) - [ ] Add eager loading to order/invoice queries (TODO.md P3) ### Code Quality - [ ] Extract TaxResult to Data/ directory (TODO.md P3) - [ ] Add return type DTOs to gateway contract (TODO.md P3) - [ ] Create OrderStateMachine class (TODO.md P3) - [ ] Consolidate customer creation logic (TODO.md P3) - [ ] Standardize money handling with brick/money (TODO.md P3) ### Developer Experience - [ ] Add commerce:health Artisan command (TODO.md P3) - [ ] Add commerce:simulate-webhook command (TODO.md P3) - [ ] #14 - **docs: add class-level documentation to SKU services** - [ ] Document SKU format and lineage system in CLAUDE.md (TODO.md P3) - [ ] Add typed properties to Livewire components (TODO.md P3) ### Observability - [ ] Add metrics for payment success/failure rates (TODO.md P3) - [ ] Add structured logging to webhook handlers (TODO.md P3) - [ ] Add tracing spans for checkout flow (TODO.md P3) **P3 Total:** 18 items (1 new issue + 17 from TODO.md) --- ## 🟢 P4 - Low Priority (Nice to Have) ### UI/UX - [ ] Add loading states to checkout components (TODO.md P4) - [ ] Add subscription change confirmation modal (TODO.md P4) - [ ] Improve invoice PDF design (TODO.md P4) - [ ] Add currency selector persistence (TODO.md P4) ### Features - [ ] Subscription pause scheduling (TODO.md P4) - [ ] Invoice PDF caching (TODO.md P4) - [ ] Webhook event viewer in admin (TODO.md P4) - [ ] Referral analytics dashboard (TODO.md P4) - [ ] Tax-inclusive pricing support (TODO.md P4) ### Technical Debt - [ ] Rename View/Modal/ to View/Livewire/ (TODO.md P4) - [ ] Move factories to database/factories/ (TODO.md P4) - [ ] Update Carbon usage for v3 compatibility (TODO.md P4) **P4 Total:** 12 items (all from TODO.md) --- ## Summary Statistics ### Discovery Scan Results - ✅ **185 PHP files** scanned - ✅ **0 empty/stub methods** found - ✅ **0 missing type hints** detected - ✅ **0 SQL injection vulnerabilities** found - ✅ **1 TODO comment** in code (documented) - ⚠️ **9 files** missing strict_types - ⚠️ **10 services** without dedicated tests - ⚠️ **2 P1 security items** outstanding ### Issue Breakdown - **Created:** 13 new issues (#3-#15) - **Labeled:** All with `discovery`, security items with `review` - **Priority:** 3 P1, 8 P2, 1 P3, 1 docs ### From TODO.md - **P1 remaining:** 3 items - **P2 remaining:** 10 items - **P3 remaining:** 17 items - **P4 backlog:** 12 items ### Total Work **Grand Total:** 55+ items across all priorities --- ## Next Steps 1. **Immediate:** Fix #3 (strict_types) - quick win, high impact 2. **Week 1:** Address P1 security issues (#12, #13) 3. **Week 2-3:** Implement P2 missing features (#15, provisioning API) 4. **Ongoing:** Add test coverage (#4-#11) in parallel with feature work 5. **Polish:** P3/P4 items as time permits --- ## Related Issues - #2 - Discovery scan task (parent) - #3 - Strict types fix - #4-#11 - Test coverage - #12-#13 - Security - #14 - Documentation - #15 - Provisioning API --- _This roadmap will be updated as issues are completed and new requirements emerge._
Clotho added the
review
discovery
 labels 2026-02-20 11:11:04 +00:00
Charon added
PHP
P3
 and removed
review
discovery
 labels 2026-02-20 12:17:11 +00:00
Charon commented 2026-02-20 12:17:51 +00:00
Member
Copy link

Closing roadmap tracker — individual issues are labelled and triaged. Track progress via P1/P2/P3 labels.

— Charon

Closing roadmap tracker — individual issues are labelled and triaged. Track progress via P1/P2/P3 labels. — Charon
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
feat/phase-0-assessment
dev
No results found.
Labels
Clear labels   
P1

Priority 1 - Critical

  
P2

Priority 2 - Important

  
P3

Priority 3 - Nice to have

  
PHP

PHP codebase

  
agent-ready

   
bug

Bug fix

  
clotho

Assigned to Clotho AI agent

  
discovery

Auto-discovered by agent

  
docs

Documentation

  
refactor

Code quality refactoring

  
review

Needs human review

  
security

Security hardening

  
testing

Test coverage

  
athena

Assign to Athena AI agent (M3 Ultra)

  
athena-gemini

Dispatch to Gemini CLI on M3 Ultra

  
audit

Code audit task

  
clotho

Assign to Clotho AI agent for processing

  
clotho-gemini

Dispatch to Gemini CLI on darbs (AU)

  
codex

Dispatch to Codex CLI on gateway for analysis

  
darbs-claude

Dispatch to Claude on darbs (AU)

  
security

Security review task

  
wiki

Documentation/wiki update

No labels
P1
P2
P3
PHP
agent-ready
bug
clotho
discovery
docs
refactor
review
security
testing
athena
athena-gemini
audit
clotho
clotho-gemini
codex
darbs-claude
security
wiki
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: core/php-commerce#16
No description provided.
Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?