153 lines
7.6 KiB
JSON
153 lines
7.6 KiB
JSON
{
|
|
"task_id": "ARCH-GATEWAY-COMPLIANCE-001",
|
|
"summary": "Refactor 6 Gateway classes that violate the Gateway contract by wrapping Services instead of adapting single external dependencies (repository, settings, HTTP API, scope).",
|
|
"assumptions": [
|
|
"Gateway definition: adapter for a single external dependency. No orchestration, no Service injection.",
|
|
"Gateways that are pure pass-throughs to a Service should either be collapsed into the calling Service or re-wired to depend on the Repository/external dependency directly.",
|
|
"Existing tests for Settings gateways will guide the refactoring pattern."
|
|
],
|
|
"scope": {
|
|
"in": [
|
|
"lib/Service/Access/PermissionGateway.php — wraps PermissionService, should depend on PermissionRepository",
|
|
"lib/Service/Auth/AuthAvatarGateway.php — wraps UserAvatarService, should depend on Repository or be collapsed",
|
|
"lib/Service/Settings/SettingsAppGateway.php — mixes Gateway + ThemeConfigService dependency",
|
|
"lib/Service/AddressBook/AddressBookDirectoryGateway.php — orchestrates 3 Services (TenantService, DepartmentService, RoleService)",
|
|
"lib/Service/Auth/AuthSavedFilterGateway.php — wraps UserSavedFilterService",
|
|
"lib/Service/Auth/AuthTenantSsoGateway.php — wraps TenantSsoService",
|
|
"All Factory registrars that wire the above gateways",
|
|
"All callers of the above gateways (update injection sites)"
|
|
],
|
|
"out": [
|
|
"Settings gateways (SettingsMetadataGateway, SettingsSmtpGateway etc.) — already correctly wired",
|
|
"Auth gateways that depend on repositories/scope (AuthScopeGateway, AuthCryptoGateway) — compliant",
|
|
"New feature work or UI changes",
|
|
"Test coverage for unrelated components"
|
|
]
|
|
},
|
|
"guardrails": {
|
|
"required_guard_ids": [
|
|
"GR-CORE-001",
|
|
"GR-CORE-002",
|
|
"GR-TEST-001",
|
|
"GR-TEST-002",
|
|
"GR-LANG-001",
|
|
"GR-LANG-002"
|
|
],
|
|
"required_quality_gate_ids": [
|
|
"QG-001",
|
|
"QG-002",
|
|
"QG-003",
|
|
"QG-004",
|
|
"QG-006"
|
|
]
|
|
},
|
|
"success_criteria": [
|
|
{
|
|
"id": "SC-001",
|
|
"criterion": "No Gateway in lib/Service/ injects a *Service class. All Gateway constructors receive only Repository interfaces, other Gateways, or framework abstractions."
|
|
},
|
|
{
|
|
"id": "SC-002",
|
|
"criterion": "All 6 identified gateway files are either refactored to depend on repositories/externals or collapsed into their parent Service."
|
|
},
|
|
{
|
|
"id": "SC-003",
|
|
"criterion": "PHPUnit (QG-001), PHPStan (QG-002), and Architecture Contract (QG-003) pass green."
|
|
},
|
|
{
|
|
"id": "SC-004",
|
|
"criterion": "Structural rg checks (QG-004) show zero new violations for Service instantiation in gateways."
|
|
},
|
|
{
|
|
"id": "SC-005",
|
|
"criterion": "Existing tests for callers of refactored gateways still pass with no behavioral regression; wiring-level test adjustments (mock type/method updates) are allowed."
|
|
}
|
|
],
|
|
"implementation_steps": [
|
|
{
|
|
"id": "S1",
|
|
"title": "Audit and classify each gateway violation",
|
|
"description": "For each of the 6 gateways, determine the correct fix: (A) re-wire to Repository dependency, (B) collapse into parent Service, or (C) split into multiple single-dependency gateways. Document decision per gateway.",
|
|
"guard_refs": ["GR-CORE-001"]
|
|
},
|
|
{
|
|
"id": "S2",
|
|
"title": "Refactor PermissionGateway",
|
|
"description": "Replace PermissionService dependency with PermissionRepository (and RolePermissionRepository if needed). Update PermissionGateway methods to call repository directly. Update Factory registrar.",
|
|
"guard_refs": ["GR-CORE-001", "GR-CORE-002"]
|
|
},
|
|
{
|
|
"id": "S3",
|
|
"title": "Refactor AuthAvatarGateway",
|
|
"description": "Replace UserAvatarService dependency with the underlying repository or collapse gateway into AuthService. Update Factory registrar and all callers.",
|
|
"guard_refs": ["GR-CORE-001", "GR-CORE-002"]
|
|
},
|
|
{
|
|
"id": "S4",
|
|
"title": "Refactor SettingsAppGateway",
|
|
"description": "Remove ThemeConfigService dependency. If theme resolution is needed, inject the underlying repository/settings gateway instead. Keep SettingsMetadataGateway dependency (compliant).",
|
|
"guard_refs": ["GR-CORE-001", "GR-CORE-002"]
|
|
},
|
|
{
|
|
"id": "S5",
|
|
"title": "Refactor AddressBookDirectoryGateway",
|
|
"description": "This gateway orchestrates 3 Services — split into single-dependency gateways or move orchestration into AddressBookService. Remove redundant pass-through methods.",
|
|
"guard_refs": ["GR-CORE-001", "GR-CORE-002"]
|
|
},
|
|
{
|
|
"id": "S6",
|
|
"title": "Refactor AuthSavedFilterGateway and AuthTenantSsoGateway",
|
|
"description": "Replace Service dependencies with Repository interfaces. Both are thin wrappers — re-wire to underlying repositories.",
|
|
"guard_refs": ["GR-CORE-001", "GR-CORE-002"]
|
|
},
|
|
{
|
|
"id": "S7",
|
|
"title": "Update Factory registrars and DI wiring",
|
|
"description": "Update all Container/Registrars/ files that wire the refactored gateways. Ensure no circular dependencies introduced.",
|
|
"guard_refs": ["GR-CORE-002", "GR-LANG-001"]
|
|
},
|
|
{
|
|
"id": "S8",
|
|
"title": "Add/update tests for refactored gateways",
|
|
"description": "Write unit tests for each refactored gateway verifying the new dependency wiring and behavior preservation.",
|
|
"guard_refs": ["GR-TEST-001", "GR-TEST-002"]
|
|
},
|
|
{
|
|
"id": "S9",
|
|
"title": "Run all quality gates",
|
|
"description": "Execute QG-001 through QG-006. Fix any regressions.",
|
|
"guard_refs": ["GR-LANG-002"]
|
|
}
|
|
],
|
|
"tests": [
|
|
"tests/Service/Access/PermissionGatewayTest.php — verify gateway uses repository directly",
|
|
"tests/Service/Auth/AuthAvatarGatewayTest.php — verify refactored dependency",
|
|
"tests/Service/Settings/SettingsAppGatewayTest.php — update existing test for removed ThemeConfigService dep",
|
|
"tests/Service/AddressBook/AddressBookDirectoryGatewayTest.php — verify single-dependency contract",
|
|
"tests/Service/Auth/AuthSavedFilterGatewayTest.php — verify refactored dependency",
|
|
"tests/Service/Auth/AuthTenantSsoGatewayTest.php — verify refactored dependency",
|
|
"tests/Architecture/CoreStarterkitContractTest.php — must stay green"
|
|
],
|
|
"acceptance_checks": [
|
|
"SC-001: grep -r 'Service' lib/Service/**/*Gateway.php constructors shows zero Service type-hints (only Repository, Gateway, framework interfaces)",
|
|
"SC-002: All 6 files listed in scope are either refactored or removed with functionality merged upstream",
|
|
"SC-003: docker compose exec php vendor/bin/phpunit exits 0 AND docker compose exec php vendor/bin/phpstan analyse exits 0",
|
|
"SC-004: QG-004 structural rg checks return 0 for gateway service-injection pattern",
|
|
"SC-005: Full test suite green with no behavioral regression; wiring-level test updates are allowed"
|
|
],
|
|
"risks": [
|
|
{
|
|
"risk": "Circular dependency introduced when gateways switch from Service to Repository dependency",
|
|
"mitigation": "Map full dependency graph before refactoring. Use PHPStan to detect cycles. Refactor one gateway at a time with QG-001+QG-002 after each."
|
|
},
|
|
{
|
|
"risk": "AddressBookDirectoryGateway split creates too many small gateways",
|
|
"mitigation": "Prefer moving orchestration into AddressBookService over splitting. Only split if single-responsibility is clearly better."
|
|
},
|
|
{
|
|
"risk": "Behavioral regression in callers that depend on gateway method signatures",
|
|
"mitigation": "Keep method signatures stable (same public API). Only change internal wiring. Existing caller tests catch regressions."
|
|
}
|
|
]
|
|
}
|