fraudshield/specs/001-fraud-detection-engine/tasks.md

# 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)