felipe/fraudshield
1
0
Fork 0
mirror of https://github.com/domfelipe/fraudshield.git synced 2026-08-07 06:36:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
fraudshield/specs/001-fraud-detection-engine/tasks.md
Felipe Domingues 14f2616037 tasks: generate 88 implementation tasks across 7 phases 
Organized by user story: US1 alerts (13 tasks), US2 ingestion (22),
US3 rules (11), US4 dashboard (12). 68 tasks parallelizable [P].
21 test tasks (TDD mandate per Constitution III).
2026-05-12 16:26:33 -03:00

22 KiB
Raw Blame History

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

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