Handoff: SVC-021-legacy-admin-audit-backfill-report audit-service legacy admin audit backfill report

Scope

• Service/area: audit-service
• Task pack: docs/agents/service-tasks/audit-service.md
• Goal: accept the bounded SVC-021 slice for legacy admin AuditLog backfill report evidence, append-only replay semantics, and non-default admin audit compatibility route proof.
• Non-goals: default /api/admin/operations/audit promotion, browser/runtime smoke, producer outbox retries, organization-membership producer semantics, or changes to legacy source under /Users/velikho/Desktop/WORKING/HOCTAPAZ/.

Docs Read

• go-platform/docs/architecture/service-responsibility-matrix.md
• go-platform/docs/agents/service-agent-execution-queue.json
• go-platform/docs/agents/service-agent-closeout-ledger.json
• go-platform/docs/agents/service-workflow-test-matrix.md
• go-platform/docs/agents/service-tasks/audit-service.md
• go-platform/docs/agents/agent-handoff-format.md
• go-platform/docs/qa/service-agent-goal-completion-audit.md
• go-platform/docs/qa/service-agent-readiness-smoke.md

Legacy Evidence Read

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/admin/operations.controller.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/admin/feature-maintenance.service.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/prisma/schema.prisma

Files Changed

• go-platform/docs/agents/handoffs/SVC-021-legacy-admin-audit-backfill-report.md
• go-platform/docs/agents/service-agent-execution-queue.json
• go-platform/docs/agents/service-agent-execution-queue.md
• go-platform/docs/agents/service-agent-closeout-ledger.json
• go-platform/docs/agents/service-agent-closeout-ledger.md

Behavior Implemented

• Existing audited implementation exposes POST /v1/audit-events/legacy-admin-log/batch in services/audit-service/internal/http/server.go.
• Existing audited usecase ProjectLegacyAuditLogs returns processed, created, replayed, failed, item, and per-row failure counts without mutating legacy storage.
• Existing audited command services/audit-service/cmd/legacy-admin-audit-backfill reads legacy "AuditLog" rows in read-only transactions, supports -dry-run, posts already-shaped rows to audit-service, and prints an aggregate report.
• Existing audited compatibility preview GET /v1/admin/operations/audit-compat preserves legacy admin operations audit shape for non-default route rehearsal.

Tests And Verification

• Command: GOTOOLCHAIN=go1.25.11 go test ./services/audit-service/...
• Result: passed.
• Evidence: all audit-service packages passed, including internal/http and internal/repository.
• Command: GOTOOLCHAIN=go1.25.11 go test ./services/audit-service/internal/http -run 'TestLegacyAdminAuditLogProjectionMapsAndReplays|TestLegacyAdminAuditLogBatchProjectionReport|TestLegacyAdminAuditCompatibilityPreviewMatchesOperationsShape' -count=1 -v
• Result: passed.
• Evidence: focused legacy projection, batch report, replay, and compatibility-preview tests passed.
• Command: make test-audit-admin-compat-routes
• Result: passed.
• Evidence: default route table remained legacy, while Compose and localhost non-default examples route GET /api/admin/operations/audit to audit-service with ADMIN principal requirements.
• Command: AUDIT_SERVICE_POSTGRES_TEST_DATABASE_URL=postgres://... GOTOOLCHAIN=go1.25.11 go test ./services/audit-service/internal/repository -run TestPostgresAuditAndSecurityIntegration -count=1 -v
• Result: not run in this handoff because no live Postgres URL was provided.
• Evidence: optional DB-backed verification remains open before default/public promotion.

Route State

• Legacy route: /api/admin/operations/audit remains default-backed by the broad legacy/admin route in deploy/gateway/routes.json.
• Native route: non-default examples route GET /api/admin/operations/audit to /v1/admin/operations/audit-compat.
• Gateway state: make test-audit-admin-compat-routes confirms deploy/gateway/routes.audit-admin-compat-native-example.json and deploy/gateway/routes.audit-admin-compat-native-localhost-example.json are valid rehearsals and require ADMIN.
• Rollback: keep using deploy/gateway/routes.json; do not promote the audit-service route until browser/runtime proof, rollback evidence, legacy response parity, and backfill report evidence are attached.

Data Notes

• Tables touched: audit-service append-only audit_events and security_events only in tests; legacy "AuditLog" is read-only evidence.
• Migration run: none in this handoff.
• Validation report: not applicable because no live migration/backfill was executed.

Risks / Blockers

• Browser/runtime smoke for the non-default audit compatibility route is still missing.
• Optional Postgres integration proof was not run because AUDIT_SERVICE_POSTGRES_TEST_DATABASE_URL was not available.
• Legacy response parity and a real admin AuditLog backfill run report remain required before public route promotion.
• A separate legacy security-event backfill/report source is not accepted in this handoff; legacy schema review found RefreshToken and AuditLog, but no dedicated SecurityEvent model.
• Producer outbox retry semantics for additional services remain future work.

Next Step

• Add runtime/browser proof and a real or production-like admin AuditLog backfill report for the audit compatibility route before any default gateway promotion, then define a separate security-event source if legacy evidence supports one.