diff --git a/specs/001-fraud-detection-engine/tasks.md b/specs/001-fraud-detection-engine/tasks.md new file mode 100644 index 0000000..4b72920 --- /dev/null +++ b/specs/001-fraud-detection-engine/tasks.md @@ -0,0 +1,346 @@ +# Tasks: Motor de Detecção de Fraudes Bancárias + +**Input**: Design documents from `/specs/001-fraud-detection-engine/` +**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/api.yaml, quickstart.md + +**Tests**: MANDATORY per constitution Principle III (Test-First NON-NEGOTIABLE). All detection logic requires tests before implementation. + +**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. + +## Format: `- [ ] [ID] [P?] [Story] Description` + +- **[P]**: Can run in parallel (different files, no dependencies) +- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3, US4) +- Include exact file paths in descriptions + +## Path Conventions + +- **Web app**: `backend/src/` → `backend/fraudshield/`, `frontend/src/` +- See `plan.md` for full directory structure + +--- + +## Phase 1: Setup (Shared Infrastructure) + +**Purpose**: Project initialization, dependencies, and tooling + +- [ ] T001 Create backend project structure per plan.md (all directories under backend/fraudshield/) +- [ ] T002 [P] Create frontend project structure per plan.md (all directories under frontend/src/) +- [ ] T003 Initialize Python project with uv and pyproject.toml in backend/pyproject.toml with dependencies: fastapi, uvicorn, sqlalchemy, asyncpg, alembic, pydantic-settings, redis, python-jose, passlib, pytest, pytest-asyncio, httpx +- [ ] T004 [P] Initialize Node project with npm in frontend/package.json with dependencies: react, react-dom, react-router-dom, recharts, tailwindcss, @tanstack/react-query, openapi-fetch +- [ ] T005 [P] Configure Vite + TypeScript + Tailwind in frontend/vite.config.ts, frontend/tsconfig.json, frontend/tailwind.config.ts +- [ ] T006 [P] Create docker-compose.yml at repo root with PostgreSQL 16 and Redis 7 services +- [ ] T007 [P] Configure Alembic in backend/alembic/ with async PostgreSQL support via backend/alembic/env.py +- [ ] T008 [P] Configure pytest in backend/pyproject.toml with asyncio mode and coverage settings + +--- + +## Phase 2: Foundational (Blocking Prerequisites) + +**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented + +**⚠️ CRITICAL**: No user story work can begin until this phase is complete + +- [ ] T009 Create configuration class in backend/fraudshield/config.py using pydantic-settings (DATABASE_URL, REDIS_URL, JWT_SECRET, JWT_ALGORITHM, API_KEY, ALERT_THRESHOLD) +- [ ] T010 [P] Create database engine and session factory in backend/fraudshield/db.py (async SQLAlchemy 2.0 with asyncpg) +- [ ] T011 [P] Create SQLAlchemy Base and mixins (UUID pk, timestamps) in backend/fraudshield/models/base.py +- [ ] T012 Create FastAPI application factory in backend/fraudshield/main.py with CORS, health check router, OpenAPI docs, and lifespan events +- [ ] T013 Create Alembic initial migration for all tables (Transaction, DetectionRule, FraudAlert, AuditLog, RuleSnapshot) per data-model.md +- [ ] T014 [P] Create JWT auth module in backend/fraudshield/auth.py (token validation, role extraction from claims, OAuth2 scheme) +- [ ] T015 [P] Create API dependency injection in backend/fraudshield/api/deps.py (get_db session, get_current_user, require_role) +- [ ] T016 [P] Create health check endpoint in backend/fraudshield/api/health.py (GET /health -> {status, version}) +- [ ] T017 [P] Create frontend API client from OpenAPI spec using openapi-fetch in frontend/src/api/client.ts +- [ ] T018 [P] Create frontend auth context and hook in frontend/src/contexts/AuthContext.tsx and frontend/src/hooks/useAuth.ts +- [ ] T019 [P] Create frontend layout shell in frontend/src/components/layout/Shell.tsx and frontend/src/components/layout/Navbar.tsx with role-based navigation +- [ ] T020 Create frontend App with routing in frontend/src/App.tsx (login, alerts, rules, dashboard routes with auth guards) +- [ ] T021 [P] Create frontend LoginPage in frontend/src/pages/LoginPage.tsx + +**Checkpoint**: Foundation ready - user story implementation can now begin in parallel + +--- + +## Phase 3: User Story 1 - Analista avalia alerta e toma decisão (Priority: P1) 🎯 MVP + +**Goal**: Analyst can view alert queue, open alert detail with full explanation, and submit decision (confirm fraud / false positive / escalate) + +**Independent Test**: Login as analyst, see pending alerts, open one, review explanation, submit decision. Full flow testable without ingestion pipeline (seed data). + +### Tests for User Story 1 ⚠️ + +> **NOTE: Write these tests FIRST, ensure they FAIL before implementation (TDD)** + +- [ ] T022 [P] [US1] Contract test for GET /alerts with filters in backend/tests/contract/test_alerts_api.py +- [ ] T023 [P] [US1] Contract test for GET /alerts/{id} in backend/tests/contract/test_alerts_api.py +- [ ] T024 [P] [US1] Contract test for POST /alerts/{id}/decide in backend/tests/contract/test_alerts_api.py +- [ ] T025 [P] [US1] Integration test for alert review + decision workflow in backend/tests/integration/test_alert_workflow.py + +### Models for User Story 1 + +- [ ] T026 [P] [US1] Create FraudAlert model in backend/fraudshield/models/alert.py (all fields from data-model.md: id, transaction_id FK, score, triggered_rules JSONB, explanation, status with CHECK constraint, assigned_to, decision, decided_by, decided_at, justification, created_at, ruleset_version) + +### Schemas for User Story 1 + +- [ ] T027 [P] [US1] Create Pydantic schemas for alerts in backend/fraudshield/schemas/alert.py (AlertSummary, AlertDetail, AlertDecisionRequest, AlertListResponse per contracts/api.yaml) + +### Services for User Story 1 + +- [ ] T028 [US1] Create alert service in backend/fraudshield/services/alerts.py (list_alerts with filters/pagination, get_alert, decide_alert with status validation and audit logging) + +### API for User Story 1 + +- [ ] T029 [US1] Create alerts API router in backend/fraudshield/api/alerts.py (GET /alerts with query params, GET /alerts/{id} with explanation, POST /alerts/{id}/decide with role check: analyst or senior) + +### Frontend for User Story 1 + +- [ ] T030 [P] [US1] Create useAlerts hook in frontend/src/hooks/useAlerts.ts (fetch queue, fetch detail, submit decision, filter/pagination state) +- [ ] T031 [P] [US1] Create AlertCard component in frontend/src/components/alerts/AlertCard.tsx (score badge, amount, merchant, top rule, timestamp, status) +- [ ] T032 [P] [US1] Create AlertQueue component in frontend/src/components/alerts/AlertQueue.tsx (filter bar, paginated list of AlertCards, empty state) +- [ ] T033 [US1] Create AlertDetail component in frontend/src/components/alerts/AlertDetail.tsx (transaction info, full explanation, triggered rules breakdown, decision buttons with justification modal for false_positive/escalated) +- [ ] T034 [US1] Create AlertsPage in frontend/src/pages/AlertsPage.tsx (split view: queue left, detail right, responsive) + +**Checkpoint**: User Story 1 fully functional - analyst can review and decide on alerts independently + +--- + +## Phase 4: User Story 2 - Sistema ingere transações e aplica regras (Priority: P1) + +**Goal**: API receives transactions, rule engine evaluates them, composite score calculated, alerts created when score > threshold. Audit log records everything. + +**Independent Test**: POST a transaction via API, verify it appears in DB, verify rules were evaluated, verify alert created (if above threshold) or only logged (if below). + +### Tests for User Story 2 ⚠️ + +- [ ] T035 [P] [US2] Unit test for rule evaluator with mock rules in backend/tests/unit/test_evaluator.py +- [ ] T036 [P] [US2] Unit test for explainer generating natural language in backend/tests/unit/test_explainer.py +- [ ] T037 [P] [US2] Unit test for amount anomaly rule in backend/tests/unit/test_rules/test_amount.py +- [ ] T038 [P] [US2] Unit test for location rule in backend/tests/unit/test_rules/test_location.py +- [ ] T039 [P] [US2] Unit test for time-based rule in backend/tests/unit/test_rules/test_time.py +- [ ] T040 [P] [US2] Contract test for POST /transactions/ingest in backend/tests/contract/test_transactions_api.py +- [ ] T041 [P] [US2] Contract test for GET /transactions/{id} in backend/tests/contract/test_transactions_api.py +- [ ] T042 [P] [US2] Integration test for full ingestion pipeline (API -> queue -> evaluation -> alert) in backend/tests/integration/test_ingestion_pipeline.py + +### Models for User Story 2 + +- [ ] T043 [P] [US2] Create Transaction model in backend/fraudshield/models/transaction.py (id, external_id UNIQUE, amount DECIMAL, merchant_name, merchant_category, latitude/longitude nullable, customer_id, channel CHECK, transaction_at, ingested_at, ruleset_version, raw_payload JSONB) +- [ ] T044 [P] [US2] Create AuditLog model in backend/fraudshield/models/audit.py (id, trace_id, event_type, event_at, actor, payload JSONB, ruleset_version) with immutability trigger (no UPDATE/DELETE) + +### Schemas for User Story 2 + +- [ ] T045 [P] [US2] Create Pydantic schemas for transactions in backend/fraudshield/schemas/transaction.py (TransactionIngestRequest with validators, TransactionAccepted, TransactionDetail) + +### Engine for User Story 2 + +- [ ] T046 [US2] Create abstract rule base class in backend/fraudshield/engine/rules/base.py (evaluate(transaction, context) -> RuleResult with score, triggered boolean, explanation) +- [ ] T047 [P] [US2] Create amount anomaly rule in backend/fraudshield/engine/rules/amount.py (compares amount vs customer avg_amount_30d * multiplier) +- [ ] T048 [P] [US2] Create location anomaly rule in backend/fraudshield/engine/rules/location.py (distance from customer common locations, new state/country) +- [ ] T049 [P] [US2] Create time-based rule in backend/fraudshield/engine/rules/time.py (hour range, day of week, night transactions) +- [ ] T050 [P] [US2] Create pattern anomaly rule in backend/fraudshield/engine/rules/pattern.py (new merchant category, new channel, velocity checks) +- [ ] T051 [US2] Create rule loader in backend/fraudshield/engine/loader.py (load active rules from DB, build rule instances, cache in memory, reload on signal) +- [ ] T052 [US2] Create rule evaluator in backend/fraudshield/engine/evaluator.py (iterate active rules, compute weighted composite score, return list of triggered rules with scores) +- [ ] T053 [US2] Create explainer in backend/fraudshield/engine/explainer.py (generate composite natural language explanation from triggered rules list, format JSON + text) + +### Services for User Story 2 + +- [ ] T054 [US2] Create ingestion service in backend/fraudshield/services/ingestion.py (validate payload, create Transaction record, enqueue to Redis Stream for async processing) +- [ ] T055 [US2] Create detection service in backend/fraudshield/services/detection.py (dequeue from Redis Stream, load CustomerProfile from cache, run evaluator, compute score, create alert if > threshold, write audit log) + +### API for User Story 2 + +- [ ] T056 [US2] Create transactions API router in backend/fraudshield/api/transactions.py (POST /transactions/ingest with API key auth, GET /transactions/{id} with Bearer auth) + +**Checkpoint**: Pipeline functional end-to-end - ingest transaction → evaluate rules → create alert (or log only). Alerts from US2 feed into US1 queue. + +--- + +## Phase 5: User Story 3 - Administrador gerencia regras de detecção (Priority: P2) + +**Goal**: Admin can create, edit, activate, deactivate, and test detection rules. Rule changes create audit log entries and trigger ruleset snapshots. + +**Independent Test**: Login as admin, create new rule, test it against historical data, review results, activate it. Verify rule applies to new transactions. + +### Tests for User Story 3 ⚠️ + +- [ ] T057 [P] [US3] Contract test for CRUD rule endpoints in backend/tests/contract/test_rules_api.py +- [ ] T058 [P] [US3] Integration test for rule lifecycle (create → test → activate → deactivate) in backend/tests/integration/test_rule_lifecycle.py + +### Models for User Story 3 + +- [ ] T059 [P] [US3] Create DetectionRule model in backend/fraudshield/models/rule.py (id, name UNIQUE, description, condition TEXT, weight CHECK 0-100, threshold CHECK 0-100, is_active, version, created_by, created_at, updated_at) +- [ ] T060 [P] [US3] Create RuleSnapshot model in backend/fraudshield/models/rule_snapshot.py (version PK, rules_json JSONB, created_at, created_by) + +### Schemas for User Story 3 + +- [ ] T061 [P] [US3] Create Pydantic schemas for rules in backend/fraudshield/schemas/rule.py (DetectionRule, CreateRuleRequest, UpdateRuleRequest, TestRuleRequest, TestRuleResponse per contracts/api.yaml) + +### Services for User Story 3 + +- [ ] T062 [US3] Create rules service in backend/fraudshield/services/rules.py (CRUD with audit logging, activate with snapshot generation, deactivate, test against historical data with score distribution and false positive estimation) + +### API for User Story 3 + +- [ ] T063 [US3] Create rules API router in backend/fraudshield/api/rules.py (GET /rules, POST /rules, GET /rules/{id}, PUT /rules/{id}, POST /rules/{id}/activate, POST /rules/{id}/deactivate, POST /rules/{id}/test) with role check: admin only + +### Frontend for User Story 3 + +- [ ] T064 [P] [US3] Create RuleList component in frontend/src/components/rules/RuleList.tsx (table with columns: name, weight, status badge, version, actions) +- [ ] T065 [P] [US3] Create RuleForm component in frontend/src/components/rules/RuleForm.tsx (name, description, condition builder/editor, weight slider, threshold slider, save = inactive) +- [ ] T066 [P] [US3] Create RuleTestResults component in frontend/src/components/rules/RuleTestResults.tsx (total evaluated, would trigger count/%, score distribution chart, sample alerts table) +- [ ] T067 [US3] Create RulesPage in frontend/src/pages/RulesPage.tsx (list view with create/edit/test slide-over panels) + +**Checkpoint**: Admin can manage rules end-to-end. Rules created via US3 are immediately used by US2 engine. + +--- + +## Phase 6: User Story 4 - Dashboard e relatórios (Priority: P3) + +**Goal**: Manager views real-time metrics dashboard and exports compliance reports in PDF/CSV. + +**Independent Test**: Login as admin/manager, view dashboard with pre-seeded data, verify metrics match DB queries, export report and verify contents. + +### Tests for User Story 4 ⚠️ + +- [ ] T068 [P] [US4] Contract test for GET /dashboard/metrics in backend/tests/contract/test_dashboard_api.py +- [ ] T069 [P] [US4] Contract test for GET /dashboard/report in backend/tests/contract/test_dashboard_api.py +- [ ] T070 [P] [US4] Integration test for dashboard metrics accuracy in backend/tests/integration/test_dashboard.py + +### Schemas for User Story 4 + +- [ ] T071 [P] [US4] Create Pydantic schemas for dashboard in backend/fraudshield/schemas/dashboard.py (DashboardMetrics with nested types per contracts/api.yaml) + +### Services for User Story 4 + +- [ ] T072 [US4] Create dashboard service in backend/fraudshield/services/dashboard.py (aggregate metrics from DB + Redis: total transactions, alerts by status, fraud rate, false positive rate, avg decision time, alerts by hour, top rules, score distribution using Redis counters + PostgreSQL queries) + +### API for User Story 4 + +- [ ] T073 [US4] Create dashboard API router in backend/fraudshield/api/dashboard.py (GET /dashboard/metrics with period filter, GET /dashboard/report with date range + format) + +### Frontend for User Story 4 + +- [ ] T074 [P] [US4] Create useDashboard hook in frontend/src/hooks/useDashboard.ts (fetch metrics, period filter state, auto-refresh) +- [ ] T075 [P] [US4] Create MetricCard component in frontend/src/components/dashboard/MetricCard.tsx (label, value, delta indicator, loading state) +- [ ] T076 [P] [US4] Create AlertsByHour component in frontend/src/components/dashboard/AlertsByHour.tsx (bar chart using Recharts) +- [ ] T077 [P] [US4] Create TopRules component in frontend/src/components/dashboard/TopRules.tsx (horizontal bar chart, rule name + alert count) +- [ ] T078 [P] [US4] Create ScoreDistribution component in frontend/src/components/dashboard/ScoreDistribution.tsx (pie or donut chart: low/medium/high/critical) +- [ ] T079 [US4] Create DashboardPage in frontend/src/pages/DashboardPage.tsx (period selector, metric cards row, charts grid, export button) + +**Checkpoint**: Dashboard functional with real-time metrics and PDF/CSV export. + +--- + +## Phase 7: Polish & Cross-Cutting Concerns + +**Purpose**: Improvements that affect multiple user stories + +- [ ] T080 [P] Create dev data seeder in backend/fraudshield/seed.py (5 default rules, 1000 synthetic transactions with varied fraud patterns, sample alerts with decisions) +- [ ] T081 [P] Create backend Dockerfile in backend/Dockerfile (multi-stage: uv sync, copy source, entrypoint with alembic upgrade + uvicorn) +- [ ] T082 [P] Create frontend Dockerfile in frontend/Dockerfile (multi-stage: npm build, nginx serve) +- [ ] T083 [P] Add structured logging with structlog in backend/fraudshield/main.py (JSON format, trace ID propagation) +- [ ] T084 [P] Add audit log immutability trigger via Alembic migration (REVOKE UPDATE/DELETE on audit_log table) +- [ ] T085 [P] Add input sanitization middleware in backend/fraudshield/main.py (XSS prevention, SQL injection already handled by SQLAlchemy) +- [ ] T086 [P] Add CustomerProfile materialized view migration and periodic refresh via pg_cron or application-level scheduler +- [ ] T087 Run quickstart.md smoke test end-to-end (ingest transaction → verify alert → decide → check dashboard) +- [ ] T088 [P] Performance test: verify 500 transactions/minute at p95 < 2s latency + +--- + +## Dependencies & Execution Order + +### Phase Dependencies + +- **Setup (Phase 1)**: No dependencies - can start immediately +- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories +- **User Story 1 (Phase 3)**: Depends on Foundational - No dependencies on US2 (can use seed data) +- **User Story 2 (Phase 4)**: Depends on Foundational - Feeds alerts into US1 queue +- **User Story 3 (Phase 5)**: Depends on Foundational - Rules created here are used by US2 engine +- **User Story 4 (Phase 6)**: Depends on Foundational + US1 + US2 (needs alert/transaction data) +- **Polish (Phase 7)**: Depends on all user stories being complete + +### User Story Dependencies + +- **User Story 1 (P1)**: Can start after Foundational - Independent (seed data for alerts) +- **User Story 2 (P2)**: Can start after Foundational - Independent (creates own data) but US1 benefits from real alerts +- **User Story 3 (P3)**: Can start after Foundational + US2 engine/rules exist (needs rule infrastructure) +- **User Story 4 (P4)**: Can start after US1 + US2 data exists (needs transactions and alerts to display) + +### Within Each User Story + +- Tests MUST be written FIRST and FAIL before implementation (TDD per Constitution III) +- Models before services +- Services before API endpoints +- API endpoints before frontend components +- Core implementation before integration +- Story complete (all tests green) before moving to next priority + +### Parallel Opportunities + +- All Setup tasks marked [P] can run in parallel (T002, T004, T005, T006, T007, T008) +- All Foundational tasks marked [P] can run in parallel (T010, T011, T014, T015, T016, T017, T018, T019, T021) +- Within US1: T022-T025 (tests) can run in parallel; T026-T027 (models + schemas) can run in parallel; T030-T032 (frontend hooks + components) can run in parallel +- Within US2: T035-T042 (tests) can run in parallel; T043-T044 (models) can run in parallel; T047-T050 (rules) can run in parallel +- Within US3: T057-T058 (tests) can run in parallel; T059-T060 (models) can run in parallel; T064-T066 (frontend components) can run in parallel +- Within US4: T068-T070 (tests) can run in parallel; T074-T078 (frontend hooks + components) can run in parallel +- US5+US6 (P4 stories if added later): Can run in parallel with each other + +--- + +## Parallel Example: User Story 1 + +```bash +# Launch all tests for User Story 1 together: +Task: "Contract test for GET /alerts with filters in backend/tests/contract/test_alerts_api.py" +Task: "Contract test for GET /alerts/{id} in backend/tests/contract/test_alerts_api.py" +Task: "Contract test for POST /alerts/{id}/decide in backend/tests/contract/test_alerts_api.py" +Task: "Integration test for alert review + decision workflow in backend/tests/integration/test_alert_workflow.py" + +# After tests fail (TDD): Launch all models + schemas for User Story 1 together: +Task: "Create FraudAlert model in backend/fraudshield/models/alert.py" +Task: "Create Pydantic schemas for alerts in backend/fraudshield/schemas/alert.py" +``` + +--- + +## Implementation Strategy + +### MVP First (User Story 1 + 2) + +1. Complete Phase 1: Setup +2. Complete Phase 2: Foundational (CRITICAL - blocks all stories) +3. Complete Phase 3 + 4 (US1 + US2 in parallel if team capacity, or US2 → US1 sequentially): + - US2 first (ingestion pipeline) to generate real alerts + - US1 to review and decide on those alerts +4. **STOP and VALIDATE**: Full pipeline works end-to-end +5. Deploy/demo MVP + +### Incremental Delivery + +1. Complete Setup + Foundational → Foundation ready +2. Add User Story 2 (ingestion) → Test independently → Transactions flowing +3. Add User Story 1 (alerts) → Test independently → Analysts can work (MVP!) +4. Add User Story 3 (rules) → Test independently → Admins can customize +5. Add User Story 4 (dashboard) → Test independently → Managers have visibility +6. Each story adds value without breaking previous stories + +### Parallel Team Strategy + +With 2 developers: +1. Both complete Setup + Foundational together +2. Once Foundational is done: + - Developer A: User Story 2 (ingestion + engine) + - Developer B: User Story 1 (alerts + decisions) — using seed data initially +3. After US1+US2 done: + - Developer A: User Story 3 (rules) + - Developer B: User Story 4 (dashboard) + +--- + +## Notes + +- [P] tasks = different files, no dependencies on incomplete tasks +- [Story] label maps task to specific user story for traceability +- Each user story must be independently completable and testable +- Verify tests fail before implementing (TDD) +- Commit after each task or logical group +- Stop at any checkpoint to validate story independently +- Total: 88 tasks across 7 phases (4 user stories + setup + foundational + polish) +- Tests: 19 test tasks (mandatory per Constitution III)