WordPress Plugin Workflow — MIDDAG Account Development Lifecycle

Workflow end-to-end para desenvolvimento, teste e distribuicao do middag-account. Claude Code: seguir este workflow ao trabalhar no plugin middag-account.

Companion Rules

Rule	Foco
`wp-plugin-best-practices.md`	Checklist de qualidade (15 secoes)
`wp-plugin-patterns.md`	Padroes de arquitetura
`wp-plugin-testing-strategy.md`	Piramide de testes e cobertura
`wp-plugin-security-checklist.md`	Deep-dive de seguranca

Phase 1: Project Setup

1.1 Scaffold

bash

# Estrutura de diretorios (ja existente no middag-account)
mkdir -p src/{Core,Domain,Api,Integration,UI,WordPress/{Hook,Admin,Email,Cron,Repository,Rest,Frontend,Database}} \
         templates/{emails,blocks} \
         tests/{Unit,Integration,fixtures} \
         ui/src/{Pages,Components,Layouts} \
         languages \
         assets/dist \
         docs/{adrs,use-cases} \
         migration

1.2 Composer Init

json

{
    "autoload": { "psr-4": { "Middag\\Account\\": "src/" } },
    "autoload-dev": { "psr-4": { "Middag\\Account\\Tests\\": "tests/" } },
    "require": {
        "php": "^8.4",
        "symfony/dependency-injection": "^7.4",
        "ramiroestrella/chatwoot-php-sdk": "^1.0"
    },
    "require-dev": {
        "brain/monkey": "^2.6",
        "phpunit/phpunit": "^12",
        "phpstan/phpstan": "^2.1",
        "friendsofphp/php-cs-fixer": "^3.80",
        "rector/rector": "^2.1",
        "php-stubs/wordpress-stubs": "^6.9",
        "php-stubs/woocommerce-stubs": "^10.7"
    }
}

1.3 Required Files Checklist

Arquivo	Proposito
`middag-account.php`	Main plugin file com header completo
`uninstall.php`	Cleanup destrutivo no delete do plugin
`composer.json`	PSR-4, scripts, dependencias
`phpunit.xml`	Configuracao de testes
`.php-cs-fixer.dist.php`	Code style
`.phpstan.neon`	Static analysis
`ui/package.json`	Frontend build (React 19 + Inertia.js v2)
`ui/vite.config.ts`	Vite 6 para IIFE output
`.distignore`	Exclusoes de distribuicao
`.gitattributes`	Exclusoes Git archive
`bitbucket-pipelines.yml`	CI/CD pipeline

Phase 2: Architecture Setup

2.1 Core Infrastructure

Arquivo	Descricao
`src/Core/Container.php`	Symfony DI wrapper
`src/Core/Kernel.php`	Boot + activation/deactivation
`src/Core/ServiceProvider.php`	Auto-discovery por sufixo
`src/WordPress/Hook/HookInterface.php`	Hook contract
`src/WordPress/Hook/HookRegistrar.php`	Auto-discover `*Hooks` classes
`src/WordPress/Rest/RestControllerInterface.php`	REST contract
`src/WordPress/Rest/RestResponse.php`	Respostas API consistentes
`src/WordPress/Rest/RouteRegistrar.php`	Auto-register controllers

2.2 Inertia.js Setup

Arquivo	Descricao
`src/UI/InertiaAdapter.php`	Adapter PHP para Inertia.js v2
`src/UI/PageControllerInterface.php`	Contract para page controllers
`src/UI/Middleware/OrganizationMiddleware.php`	Resolve Organization do request
`ui/src/app.tsx`	React 19 entry point com Inertia
`ui/src/Layouts/AuthenticatedLayout.tsx`	Layout principal admin

2.3 Integration Layer

Arquivo	Descricao
`src/Integration/HubSpot/HubSpotClient.php`	HTTP client HubSpot
`src/Integration/Stripe/StripeClient.php`	HTTP client Stripe
`src/Integration/BancoInter/BancoInterGateway.php`	Gateway boleto/PIX
`src/Integration/ISSNet/ISSNetService.php`	NFS-e emission
`src/Integration/Cloudflare/CloudflareService.php`	DNS/SSL management

2.4 ADR Foundation

ADRs ja existentes em docs/adrs/:

ADR	Topico
ADR-101	WordPress backend + NextJS portal
ADR-102	DDD light + Symfony DI + namespace `src/`
ADR-103	wp_posts como persistencia
ADR-108	Camada WordPress como abstracao
ADR-109	Inertia.js + React admin UI
ADR-208	Entitlement — agregador central
ADR-209	Service — projetos Labs/Dev
ADR-210	ServiceRequest — solicitacoes
ADR-211	Environment — instalacoes gerenciadas
ADR-306	SolidAffiliate — programa de parceiros

Phase 3: Development Cycle

3.1 Feature Implementation Order (por dominio)

1. Domain entity + status enum (pure PHP)
2. Repository interface (Domain/)
3. Repository implementation — wp_posts (WordPress/Repository/)
4. Repository implementation — CCT (WordPress/Repository/Cct*)
5. Service layer (Domain/)
6. Hook classes (WordPress/Hook/)
7. REST controller (Api/) — ~5-6 endpoints por dominio
8. Integration layer (Integration/) — se aplicavel
9. Inertia page controller (UI/) — admin pages
10. React pages (ui/src/Pages/) — admin frontend
11. Email classes (WordPress/Email/) — se aplicavel
12. Tests — Unit (Domain) + Integration (API, webhook, multi-tenant)

3.2 Per-Feature Checklist

[ ] Domain logic tem zero WP imports
[ ] Toda interacao WP atraves da camada WordPress/
[ ] Constructor injection — sem static service calls
[ ] Hook class implementa HookInterface
[ ] REST routes tem permission_callback
[ ] Toda entrada sanitizada, toda saida escaped
[ ] Organization boundary enforced em toda query
[ ] JWT auth suportada em endpoints externos
[ ] Strings traduzveis usam __() com text domain middag-account
[ ] Hook prefix: middag/
[ ] Unit test para domain logic
[ ] Integration test para WP layer
[ ] Multi-tenant isolation test

3.3 New Domain Checklist

Ao adicionar novo dominio ao middag-account:

1. Criar Domain/{Name}/ — Entity, RepositoryInterface, Service, Enums
2. Criar WordPress/Repository/{Name}Repository.php — wp_posts mapping
3. Criar WordPress/Repository/Cct{Name}Repository.php — JetEngine CCT mapping
4. Criar Api/{Name}Controller.php — REST endpoints
5. Criar UI/{Name}PageController.php — Inertia pages
6. Criar ui/src/Pages/{Name}/ — React components
7. Criar WordPress/Hook/{Name}Hooks.php — WP hooks
8. Criar tests/Unit/Domain/{Name}/ — Domain tests
9. Criar tests/Integration/Api/{Name}ControllerTest.php
10. Registrar CPT em WordPress/Cpt/{Name}CptRegistrar.php
11. Atualizar docs/domain-map.md
12. Criar/atualizar ADR se decisao arquitetural nova

Phase 4: Quality Gate

4.1 Local Checks (antes do commit)

bash

composer check     # test + style + rector + phpstan
composer fix       # auto-fix style + rector + UI build
composer i18n      # regenerar .pot + .mo
composer ui:npm:build  # build React -> assets/dist/

4.2 CI Pipeline Stages (Bitbucket Pipelines)

Stage	Trigger	Steps
Quality Gate	Todo push para develop, main, PRs	`composer check`
Build Assets	Tag push	`npm ci && npm run build` em ui/
Create ZIP	Tag push (apos assets)	`composer install --no-dev` + rsync + zip
Deploy	Tag push (apos ZIP)	Deploy para ambiente

4.3 Release Flow

develop --> PR --> main (quality gate) --> Manual "Release" step --> Tag --> Build + ZIP + Deploy

Phase 5: Distribution

5.1 Build Command

bash

composer dist:build   # check + i18n + ui:build + composer --no-dev

5.2 ZIP Contents Validation

ZIP DEVE conter:

vendor/ (production only)
assets/dist/ (built JS/CSS — app.js via Vite IIFE)
languages/ (.pot + .po + .mo)
templates/ (todos)
src/ (todo PHP)
Main plugin file + uninstall.php

ZIP NAO DEVE conter:

tests/, docs/, ui/src/, .claude/, .aiox-core/
.git/, node_modules/, .cache/
composer.json, phpunit.xml, bitbucket-pipelines.yml
migration/ (scripts de migracao)
classes/ (legacy, nao distribuir)
RSA private keys

Phase 6: Maintenance

6.1 Version Bumping

Gerenciado pelo CI pipeline — le versao do plugin header, incrementa patch, commita, tageia.

6.2 Dependency Updates

bash

composer update --dry-run   # preview
composer update             # apply
cd ui && npm update         # frontend

6.3 WC Compatibility Updates

Apos cada major release do WooCommerce:

Atualizar WC tested up to no plugin header
Rodar suite completa de testes
Testar integracao com Banco Inter gateway
Testar email templates com nova versao WC

6.4 Integration Maintenance

Integracao	Verificar	Frequencia
HubSpot	API version, webhook format	A cada HubSpot release
Stripe	API version, webhook events	A cada Stripe major
Banco Inter	Certificados, API changes	Trimestral
ISSNet	Schema NFS-e, prefeitura updates	Semestral
Cloudflare	API changes	A cada Cloudflare release
SolidAffiliate	Plugin updates, hook changes	A cada update do plugin

6.5 Migration Monitoring

bash

# Verificar status da migracao CCT -> wp_posts
wp option get middag_migration_complete

# Scripts de migracao em migration/
# Manual de operacao PROD em migration/

MIDDAG Account WordPress Plugin Workflow v1.0 — Morgan (@pm), Abril 2026

WordPress Plugin Workflow — MIDDAG Account Development Lifecycle ​

Companion Rules ​

Phase 1: Project Setup ​

1.1 Scaffold ​

1.2 Composer Init ​

1.3 Required Files Checklist ​

Phase 2: Architecture Setup ​

2.1 Core Infrastructure ​

2.2 Inertia.js Setup ​

2.3 Integration Layer ​

2.4 ADR Foundation ​

Phase 3: Development Cycle ​

3.1 Feature Implementation Order (por dominio) ​

3.2 Per-Feature Checklist ​

3.3 New Domain Checklist ​

Phase 4: Quality Gate ​

4.1 Local Checks (antes do commit) ​

4.2 CI Pipeline Stages (Bitbucket Pipelines) ​

4.3 Release Flow ​

Phase 5: Distribution ​

5.1 Build Command ​

5.2 ZIP Contents Validation ​

Phase 6: Maintenance ​

6.1 Version Bumping ​

6.2 Dependency Updates ​

6.3 WC Compatibility Updates ​

6.4 Integration Maintenance ​

6.5 Migration Monitoring ​

WordPress Plugin Workflow — MIDDAG Account Development Lifecycle

Companion Rules

Phase 1: Project Setup

1.1 Scaffold

1.2 Composer Init

1.3 Required Files Checklist

Phase 2: Architecture Setup

2.1 Core Infrastructure

2.2 Inertia.js Setup

2.3 Integration Layer

2.4 ADR Foundation

Phase 3: Development Cycle

3.1 Feature Implementation Order (por dominio)

3.2 Per-Feature Checklist

3.3 New Domain Checklist

Phase 4: Quality Gate

4.1 Local Checks (antes do commit)

4.2 CI Pipeline Stages (Bitbucket Pipelines)

4.3 Release Flow

Phase 5: Distribution

5.1 Build Command

5.2 ZIP Contents Validation

Phase 6: Maintenance

6.1 Version Bumping

6.2 Dependency Updates

6.3 WC Compatibility Updates

6.4 Integration Maintenance

6.5 Migration Monitoring