diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..371e624 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,15 @@ + +.git +.github +.env +.env.* +!.env.example +.venv +venv +__pycache__ +*.pyc +.pytest_cache +.DS_Store +backups +benchmark-results +loadtests diff --git a/.env.example b/.env.example index 2b76756..ef20bb6 100644 --- a/.env.example +++ b/.env.example @@ -9,3 +9,5 @@ REDIS_URL=redis://redis:6379/0 OPENAI_API_KEY= OPENAI_MODEL=gpt-5.6-luna USE_FAKE_AI=true +CELERY_BROKER_URL=redis://redis:6379/0 +CELERY_RESULT_BACKEND=redis://redis:6379/0 \ No newline at end of file diff --git a/.gitignore b/.gitignore index 4754a9e..c4c81aa 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,4 @@ benchmark-results/* !benchmark-results/.gitkeep .DS_Store schema.yml +backups/ \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index c35f848..697dcff 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,8 +1,31 @@ + FROM python:3.12-slim -ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 + +ENV PYTHONDONTWRITEBYTECODE=1 \ + PYTHONUNBUFFERED=1 + WORKDIR /app -RUN apt-get update && apt-get install -y --no-install-recommends libpq5 && rm -rf /var/lib/apt/lists/* + +# Install PostgreSQL client dependencies. +RUN apt-get update \ + && apt-get install -y --no-install-recommends libpq5 \ + && rm -rf /var/lib/apt/lists/* + +# Install Python dependencies. COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt -COPY . . -CMD ["gunicorn","config.wsgi:application","--bind","0.0.0.0:8000","--workers","3","--timeout","120"] + +# Create a non-root application user. +RUN groupadd --gid 10001 appgroup \ + && useradd --uid 10001 --gid appgroup \ + --create-home --shell /usr/sbin/nologin appuser + +# Copy application code with non-root ownership. +COPY --chown=appuser:appgroup . . + +# Run application processes without root privileges. +USER appuser + +EXPOSE 8000 + +CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000", "--workers", "3", "--timeout", "120"] diff --git a/README.md b/README.md index e8dbfed..0029532 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,57 @@ # Loan Processing Platform +Backend application for authenticated loan submission, document-text extraction, asynchronous processing, and rule-based underwriting recommendations. Built with Django REST Framework, PostgreSQL, Redis, Celery, Pydantic, and optional OpenAI extraction. -Backend application for loan submission, document data extraction, asynchronous processing, and rule-based underwriting recommendations. Built with Django REST Framework, PostgreSQL, Redis, Celery, Pydantic, and an optional OpenAI extraction step. - -This repository contains the API, background worker, database migrations, tests, and benchmark scripts. The underwriting output is a software-generated recommendation, **not a production lending decision**. +The repository includes an API, background worker, database migrations, automated tests, and benchmark scripts. **The underwriting output is a demonstration recommendation, not a production lending decision.** ## Features -- REST endpoints for loan applications and associated documents -- Submission workflow that queues a Celery processing job in Redis -- Document extraction in deterministic mock mode or optional OpenAI mode -- Pydantic validation for structured extraction results -- Underwriting recommendations based on extracted income, liabilities, and risk indicators -- Processing-job status tracking and saved recommendations in PostgreSQL -- OpenAPI/Swagger documentation and load/benchmark scripts +- Authenticated REST API using Django REST Framework session and HTTP Basic authentication +- Owner-scoped access to loan applications, documents, processing jobs, and underwriting recommendations; staff can review all loans +- Server-assigned loan ownership and staff-only visibility for unassigned legacy loans +- Draft-only submission, required-document validation, and duplicate-submission rejection +- Celery background processing through Redis, dispatched after the loan transaction commits +- Deterministic mock extraction for local development and tests, with optional OpenAI extraction +- Pydantic validation of structured extraction results +- Rule-based underwriting based on income, liabilities, and risk indicators +- Processing-job status, retry attempts, safe error recording, and saved recommendations in PostgreSQL +- Non-root Docker application processes, OpenAPI/Swagger documentation, and benchmark scripts ## Architecture ```mermaid flowchart LR - A[API client] --> B[Django REST Framework] + A[Authenticated API client] --> B[Django REST Framework] B --> C[(PostgreSQL)] B --> D[Redis broker] D --> E[Celery worker] - E --> F[Document extraction] + E --> F[Document-text extraction] F --> G[Pydantic validation] G --> H[Underwriting rules] H --> C C --> B ``` -**Processing path:** create a loan, attach document text, submit it, retrieve the processing job status, and inspect the underwriting recommendation. The API returns a submission response while the worker processes the document independently. +**Processing path:** An authenticated user creates a loan, attaches document text, and submits the draft. The API commits the submission and queues a processing job. Celery extracts structured fields, runs the underwriting rules, and stores the recommendation and final state. The client retrieves the job and loan statuses through the API. + +The worker handles retryable exceptions with Celery autoretry (up to three retries). Exhausted retries mark the job `failed` and return the loan to `review`. Completed jobs are not reprocessed by sequential duplicate deliveries. Unexpected worker-crash recovery and simultaneous-worker behavior require additional hardening and testing. ## Tech stack | Layer | Technologies | |---|---| -| API | Python, Django 5, Django REST Framework, drf-spectacular | -| Database | PostgreSQL, Django ORM | -| Background jobs | Celery, Redis | -| Data extraction | Pydantic, optional OpenAI API | -| Development | Docker Compose, Gunicorn | +| API | Python 3.12, Django 5, Django REST Framework, drf-spectacular | +| Database | PostgreSQL 16, Django ORM | +| Background jobs | Celery, Redis 7 | +| Extraction and validation | Pydantic, optional OpenAI API | +| Runtime and development | Docker Compose, Gunicorn | | Tests and benchmarks | pytest, pytest-django, Locust, custom Python scripts | ## Getting started ### Prerequisites -Python 3.12, Docker with Compose, and a free local port **5433** for PostgreSQL and **6379** for Redis. The API uses port **8000** by default. If another project is using these ports, adjust the mappings before starting; don't stop unrelated containers. +Python 3.12 and Docker with Compose. The development setup uses host ports **5433** (PostgreSQL), **6379** (Redis), and **8000** (API). If these ports are already in use, change this project's port mappings; do not stop unrelated projects or containers. ### 1. Configure the environment @@ -55,7 +59,11 @@ Python 3.12, Docker with Compose, and a free local port **5433** for PostgreSQL cp .env.example .env ``` -The supplied `.env.example` uses Docker-network hostnames (`db` and `redis`). To run Django and Celery **on the host** while keeping database and Redis in Docker, change these in your local `.env`: +Use local-only credentials and keep `USE_FAKE_AI=true` for development. Leave `OPENAI_API_KEY` unset unless intentionally testing paid extraction. Never commit `.env`. + +**Docker Compose:** The `web` and `worker` services explicitly use `db:5432` and `redis:6379` on the project's internal Docker network. Their values override the host addresses in `.env`. + +**Running Python on the Mac/host:** With PostgreSQL and Redis running in Docker, use these values in the local `.env`: ```dotenv POSTGRES_HOST=127.0.0.1 @@ -64,76 +72,117 @@ REDIS_URL=redis://127.0.0.1:6379/0 USE_FAKE_AI=true ``` -Leave `OPENAI_API_KEY` unset for deterministic mock extraction. Do not commit `.env` or use the sample passwords outside local development. +### 2. Start the full Docker stack (recommended) + +```bash +docker compose up -d --build + +docker compose ps +docker compose logs --tail=25 web +docker compose logs --tail=25 worker +``` + +The web startup runs committed Django migrations before starting Gunicorn; it does **not** generate migrations automatically. The web and worker images run as the non-root `appuser` (UID 10001). -### 2. Start dependencies +To verify: ```bash -docker compose up -d db redis +docker compose exec -T web python manage.py check +docker compose exec -T worker celery -A config inspect ping ``` -### 3. Install and migrate +Avoid `docker compose down -v` unless you explicitly intend to delete this project's database volume. + +### Alternative: Run Django and Celery on the host + +Start only the dependencies: ```bash +docker compose up -d db redis python3.12 -m venv .venv source .venv/bin/activate python -m pip install -r requirements.txt python manage.py migrate ``` -### 4. Start the API and worker - -In one terminal: +Start the API in one terminal: ```bash python manage.py runserver 127.0.0.1:8000 ``` -In a second terminal, with `.venv` activated: +Start the worker in a second terminal with the virtual environment activated: ```bash celery -A config worker -l info --pool=solo ``` -Alternatively, use `docker compose up --build` to run the API and worker inside containers with the default Docker-hostname configuration in `.env`. Check existing ports first. +### 3. Create a local API user + +Authentication is required. To create a non-staff user for local testing using the Docker web container: + +```bash +docker compose exec -T web python manage.py shell -c "from django.contrib.auth import get_user_model; User = get_user_model(); User.objects.create_user(username='demo_user', password='replace-with-a-unique-local-password')" +``` + +Replace the example password before running the command. The example command creates a new user and will fail if `demo_user` already exists. For the host-based setup, run the equivalent `python manage.py shell -c ...` command. Use only synthetic applicant and document data. ### API documentation -- Swagger UI: `http://127.0.0.1:8000/api/docs/` -- OpenAPI schema: `http://127.0.0.1:8000/api/schema/` +- Swagger UI: http://127.0.0.1:8000/api/docs/ +- OpenAPI schema: http://127.0.0.1:8000/api/schema/ -## Example API flow +## Example authenticated API flow + +These requests use **HTTP Basic authentication for local development**. Each `curl -u demo_user` request prompts for the password instead of placing it in the shell command. Use HTTPS and an appropriate authentication approach in any deployed environment. **1. Create a loan** ```bash -curl -X POST http://127.0.0.1:8000/api/loans/ \ +curl -i -u demo_user \ -H 'Content-Type: application/json' \ - -d '{"applicant_name":"Alex Morgan","applicant_email":"alex@example.com","requested_amount":"50000.00","purpose":"debt_consolidation"}' + -d '{"applicant_name":"Alex Morgan","applicant_email":"alex@example.test","requested_amount":"50000.00","purpose":"Debt consolidation"}' \ + http://127.0.0.1:8000/api/loans/ ``` -**2. Attach document text** (replace `LOAN_UUID` with the created loan ID): +Copy the `id` from the HTTP `201 Created` response. The loan begins as `draft` and ownership is assigned from the authenticated user; the client does not set `owner`. + +**2. Attach synthetic document text** + +Replace `LOAN_UUID` with the returned ID: ```bash -curl -X POST http://127.0.0.1:8000/api/documents/ \ +curl -i -u demo_user \ -H 'Content-Type: application/json' \ - -d '{"loan":"LOAN_UUID","kind":"paystub","filename":"paystub.txt","text_content":"Monthly income: $8000. Monthly liabilities: $1200. Employment status: employed."}' + -d '{"loan":"LOAN_UUID","kind":"paystub","filename":"synthetic-paystub.txt","text_content":"Synthetic test. Monthly income: 8000. Monthly liabilities: 1200. Employment status: employed."}' \ + http://127.0.0.1:8000/api/documents/ ``` -**3. Submit** +This creates a text-backed document record, **not a binary PDF upload**. Documents must belong to a visible draft loan. The API validates filename extensions and limits document text to 1 MiB. + +**3. Submit the draft** ```bash -curl -X POST http://127.0.0.1:8000/api/loans/LOAN_UUID/submit/ +curl -i -u demo_user -X POST \ + http://127.0.0.1:8000/api/loans/LOAN_UUID/submit/ ``` -**4. Query results** +Submission requires at least one document. A valid request returns HTTP `202 Accepted` with the loan ID and processing-job ID. Repeated submissions of a non-draft loan return HTTP `400 Bad Request`. -```text -GET /api/processing-jobs/?loan=LOAN_UUID -GET /api/recommendations/?loan=LOAN_UUID +**4. Query the processing job and recommendation** + +```bash +curl -i -u demo_user \ + http://127.0.0.1:8000/api/processing-jobs/JOB_UUID/ + +curl -i -u demo_user \ + http://127.0.0.1:8000/api/loans/LOAN_UUID/ + +curl -i -u demo_user \ + 'http://127.0.0.1:8000/api/recommendations/?loan=LOAN_UUID' ``` -The submit action requires at least one document and returns HTTP 202 with a processing-job ID. +The job transitions through `queued` and `running` to `succeeded` or `failed`. The recommendation contains a rule-based result; it is not a lending approval. ## API reference @@ -141,16 +190,20 @@ The submit action requires at least one document and returns HTTP 202 with a pro |---|---| | Loans | `GET/POST /api/loans/`, `GET/PUT/PATCH/DELETE /api/loans/{id}/`, `POST /api/loans/{id}/submit/` | | Documents | `GET/POST /api/documents/`, `GET/PUT/PATCH/DELETE /api/documents/{id}/` | -| Processing | `GET /api/processing-jobs/`, `GET /api/processing-jobs/{id}/` | +| Processing jobs | `GET /api/processing-jobs/`, `GET /api/processing-jobs/{id}/` | | Recommendations | `GET /api/recommendations/`, `GET /api/recommendations/{id}/` | +The API requires authentication. Ordinary users see only their owned loans and related records; staff have broader review access. Resources owned by another user are not exposed through ordinary-user detail endpoints. + ## Extraction modes -`USE_FAKE_AI=true` enables a deterministic parser intended for tests and local development. With `USE_FAKE_AI=false` and a valid `OPENAI_API_KEY`, the application requests structured data from the configured model and validates it against a Pydantic schema. The code falls back to mock extraction when no API key is configured. The mock path should not be interpreted as a measured OpenAI extraction. +With `USE_FAKE_AI=true`, extraction runs a deterministic local parser suitable for development and automated tests. With `USE_FAKE_AI=false` and a valid `OPENAI_API_KEY`, the application requests structured extraction from the configured model and validates the result using Pydantic. With no API key, the extraction function uses the mock parser even when fake mode is otherwise disabled. -## Measured benchmarks +Synthetic extraction results and schema validation are not evidence of real-world document accuracy or underwriting suitability. -Results below are from the saved benchmark output in this repository, not service-level guarantees. Hardware, dataset size, and workload can change the results. +## Measured benchmarks (historical) + +These measurements were collected **before the authentication and ownership update** and are not current service-level guarantees. Hardware, workload, dataset size, and authentication overhead may change the results. ### Structured extraction evaluation @@ -162,19 +215,19 @@ Results below are from the saved benchmark output in this repository, not servic | P95 extraction time | 2.69 seconds | | Maximum extraction time | 8.65 seconds | -Source: `benchmark-results/ai/ai-evaluation.json`. Reproduce with `USE_FAKE_AI=false AI_EVAL_COUNT=100 python benchmarks/ai_evaluation.py` after configuring an API key. A valid schema does not establish factual extraction accuracy. +Source: `benchmark-results/ai/ai-evaluation.json`. Reproduce with `USE_FAKE_AI=false AI_EVAL_COUNT=100 python benchmarks/ai_evaluation.py` after configuring a valid key; this may incur API charges. Schema validity does not establish factual extraction accuracy. ### API load test | Metric | Observed result | |---|---:| -| Requests | **17,256** | +| Requests | 17,256 | | Failures | 0 | | Aggregate throughput | 297.23 requests/second | | Aggregate P95 latency | 21 ms | | Worst endpoint P95 in saved summary | 24 ms | -Measured with Locust. Source: `benchmark-results/api/loan-api_stats.csv`. The output file reports 17,256 requests; this corrects an older README count of 17,392. Run `./benchmarks/api_benchmark.sh` to collect a new sample. +Measured with Locust. Source: `benchmark-results/api/loan-api_stats.csv`. The recorded total of 17,256 corrects an older README count of 17,392. `./benchmarks/api_benchmark.sh` runs a new sample, but anonymous load-test clients will need updating to authenticate against the current API. ### Indexed versus unindexed PostgreSQL lookups @@ -184,17 +237,33 @@ Measured with Locust. Source: `benchmark-results/api/loan-api_stats.csv`. The ou | Applicant email | 0.012 ms | 0.4935 ms | 97.57% | | Document | 0.015 ms | 0.339 ms | 95.58% | -Average measured lookup-time reduction: **97.39%** across three queries. Source: `benchmark-results/database/database-benchmark.json`. These are isolated query timings, not end-to-end API speedups. Rerun `python benchmarks/database_benchmark.py` for a new sample. +Average measured lookup-time reduction: **97.39%** across three queries. Source: `benchmark-results/database/database-benchmark.json`. These are isolated query timings, not end-to-end API speedups. Rerun `python benchmarks/database_benchmark.py` to produce a new measurement. ## Testing +Run the suite against the configured **isolated test PostgreSQL database**: + ```bash python -m pytest -q +python manage.py check +python manage.py makemigrations --check --dry-run ``` -Tests currently cover extracted-data schema validation and underwriting rules. GitHub Actions runs the suite with an isolated PostgreSQL service and mock extraction. Additional API and Celery integration tests remain future work. +**Latest verified local result: 16 tests passed.** The suite covers: + +- Extracted-data schema validation and underwriting rules +- API authentication, loan ownership, and legacy staff access +- Document authorization, text-size and extension validation +- Duplicate loan-submission rejection +- Successful processing and sequential duplicate-delivery handling +- Transient extraction failures, Celery retry recovery, and retry exhaustion +- Terminal job failure, loan review state, and safe exception-type-only error storage + +The reliability tests execute Celery tasks synchronously in the isolated test environment with mocked extraction. Separately, a local Docker Compose end-to-end test processed a synthetic loan through Redis and a running Celery worker, producing a succeeded job and an approved loan. That single result is not a load benchmark. + +GitHub Actions runs the automated suite with a PostgreSQL test service. True simultaneous-worker concurrency and crashed-worker recovery have not been verified. -Generate synthetic loan records using: +To generate synthetic records for development: ```bash python manage.py seed_loans --count 1000 @@ -203,23 +272,35 @@ python manage.py seed_loans --count 1000 ## Repository layout ```text -apps/ # loans, documents, processing, underwriting -config/ # Django and Celery settings, URLs -benchmarks/ # performance and extraction evaluation scripts -benchmark-results/ # saved measurement outputs -loadtests/ # Locust scenario -tests/ # pytest suite +apps/ # loans, documents, processing, underwriting +config/ # Django and Celery settings, API URLs +benchmarks/ # load, database, and extraction benchmarks +benchmark-results/ # saved historical measurement outputs +loadtests/ # Locust scenarios +tests/ # pytest API, processing, schema, underwriting tests docker-compose.yml Dockerfile +.dockerignore requirements.txt manage.py ``` -## Current limitations +## Access control and database migration + +The `loans.0002_loan_owner` migration adds nullable loan ownership for compatibility with existing records. Existing loans with `owner=NULL` remain visible to staff, not ordinary applicants, until an administrator verifies and assigns ownership. New loans are assigned to the authenticated creator automatically. + +Submission is allowed only for draft loans with at least one document. The API queues processing after the database transaction commits. Celery retries failures, records only exception types in the persisted error field, and sets a terminal failure after retry exhaustion. The task performs an atomic database claim of queued jobs and avoids reprocessing terminal successes; it does not yet implement stale-job lease recovery. + +Existing anonymous API clients, seed scripts, and load-test tooling may need changes to authenticate. Take a backup and review the migration before applying it to databases with existing loans. Never apply development commands to an unverified database. + +## Current limitations and security considerations -- Document creation currently accepts document metadata and text content; file upload, PDF parsing, OCR, and object storage are not implemented. -- The underwriting rules and extraction are for demonstration. They are not validated for regulated credit decisions. -- Authentication and role-based permissions are not enforced in the current API; do not expose it publicly as-is. -- Development defaults use broad Django allowed hosts and debug settings. Restrict those before any deployment. -- API load and AI extraction benchmarks use their documented test setups; they are not production claims. +- Documents currently store metadata and text content; binary uploads, PDF parsing, OCR, and object storage are not implemented. +- The underwriting rules and AI extraction are for demonstration, not validated regulated credit decisions. +- HTTP Basic authentication is intended for controlled local development; use HTTPS and a suitable authentication strategy before deployment. +- Worker crashes can leave a job stuck in `running`; no lease-based recovery or watchdog is implemented. +- Simultaneous-worker races and high-concurrency failure behavior need further testing. +- Local defaults are not production-ready: disable Django debug mode, set strong secrets, configure allowed hosts, HTTPS, storage, monitoring, and deployment controls. +- Historical AI and API benchmarks predate the current access controls; they should not be represented as post-upgrade throughput measurements. +Never commit `.env`, production credentials, or actual applicant information. `.dockerignore` excludes local secrets and development artifacts from the image build context. diff --git a/apps/documents/serializers.py b/apps/documents/serializers.py index 5a3fe44..6b5b891 100644 --- a/apps/documents/serializers.py +++ b/apps/documents/serializers.py @@ -1,7 +1,26 @@ from rest_framework import serializers +from apps.loans.permissions import visible_loans from .models import LoanDocument class LoanDocumentSerializer(serializers.ModelSerializer): + def validate_loan(self, loan): + if not visible_loans(self.context['request'].user).filter(pk=loan.pk).exists(): + raise serializers.ValidationError('Loan not found or access denied.') + if loan.status != 'draft': + raise serializers.ValidationError('Documents can only be added to draft loans.') + return loan + + def validate(self, attrs): + content = attrs.get('text_content', '') + if len(content.encode('utf-8')) > 1024 * 1024: + raise serializers.ValidationError({'text_content': 'Maximum 1 MiB.'}) + filename = attrs.get('filename', '') + if filename and not filename.lower().endswith(('.pdf', '.txt', '.jpg', '.jpeg', '.png')): + raise serializers.ValidationError({'filename': 'Unsupported document extension.'}) + if self.instance and 'loan' in attrs and attrs['loan'].pk != self.instance.loan_id: + raise serializers.ValidationError({'loan': 'Changing a document loan is not allowed.'}) + return attrs + class Meta: model=LoanDocument fields=['id','loan','kind','filename','text_content','extracted_data','processed','created_at','processed_at'] diff --git a/apps/documents/views.py b/apps/documents/views.py index 145200a..bc96886 100644 --- a/apps/documents/views.py +++ b/apps/documents/views.py @@ -1,7 +1,21 @@ +from apps.loans.permissions import LoanAccess, visible_loans from rest_framework import viewsets +from rest_framework.exceptions import ValidationError from .models import LoanDocument from .serializers import LoanDocumentSerializer class LoanDocumentViewSet(viewsets.ModelViewSet): - queryset=LoanDocument.objects.select_related('loan').all() + permission_classes=[LoanAccess] + def get_queryset(self): + return LoanDocument.objects.filter(loan__in=visible_loans(self.request.user)).select_related('loan') serializer_class=LoanDocumentSerializer filterset_fields=['loan','kind','processed'] + + def perform_update(self, serializer): + if serializer.instance.loan.status != 'draft': + raise ValidationError('Only draft loan documents can be edited.') + serializer.save() + + def perform_destroy(self, instance): + if instance.loan.status != 'draft': + raise ValidationError('Only draft loan documents can be deleted.') + instance.delete() diff --git a/apps/loans/migrations/0002_loan_owner.py b/apps/loans/migrations/0002_loan_owner.py new file mode 100644 index 0000000..d9683aa --- /dev/null +++ b/apps/loans/migrations/0002_loan_owner.py @@ -0,0 +1,7 @@ +from django.conf import settings +from django.db import migrations, models +import django.db.models.deletion + +class Migration(migrations.Migration): + dependencies = [('loans', '0001_initial'), migrations.swappable_dependency(settings.AUTH_USER_MODEL)] + operations = [migrations.AddField(model_name='loanapplication', name='owner', field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='loan_applications', to=settings.AUTH_USER_MODEL))] diff --git a/apps/loans/models.py b/apps/loans/models.py index dec11ea..1f25f90 100644 --- a/apps/loans/models.py +++ b/apps/loans/models.py @@ -11,6 +11,7 @@ class Status(models.TextChoices): REJECTED='rejected','Rejected' id=models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False) + owner=models.ForeignKey('auth.User', on_delete=models.PROTECT, related_name='loan_applications', null=True, blank=True) applicant_name=models.CharField(max_length=200) applicant_email=models.EmailField(db_index=True) requested_amount=models.DecimalField(max_digits=12, decimal_places=2) diff --git a/apps/loans/permissions.py b/apps/loans/permissions.py new file mode 100644 index 0000000..8581505 --- /dev/null +++ b/apps/loans/permissions.py @@ -0,0 +1,16 @@ +from rest_framework.permissions import BasePermission + +class LoanAccess(BasePermission): + """Staff can inspect all loans; applicants only their own records.""" + def has_permission(self, request, view): + return bool(request.user and request.user.is_authenticated) + + def has_object_permission(self, request, view, obj): + loan = getattr(obj, 'loan', obj) + return bool(request.user.is_staff or loan.owner_id == request.user.pk) + + +def visible_loans(user): + from .models import LoanApplication + qs = LoanApplication.objects.all() + return qs if user.is_staff else qs.filter(owner=user) diff --git a/apps/loans/views.py b/apps/loans/views.py index 751b1c9..94b8934 100644 --- a/apps/loans/views.py +++ b/apps/loans/views.py @@ -1,26 +1,93 @@ + +from django.shortcuts import get_object_or_404 from django.db.models import Count +from django.db import transaction + from rest_framework import viewsets, status +from rest_framework.exceptions import ValidationError from rest_framework.decorators import action from rest_framework.response import Response + +from .permissions import LoanAccess, visible_loans from .models import LoanApplication from .serializers import LoanApplicationSerializer + from apps.processing.models import ProcessingJob from apps.processing.tasks import process_loan + class LoanApplicationViewSet(viewsets.ModelViewSet): - serializer_class=LoanApplicationSerializer - filterset_fields=['status','applicant_email'] - ordering_fields=['created_at','requested_amount'] + serializer_class = LoanApplicationSerializer + permission_classes = [LoanAccess] + + filterset_fields = ['status', 'applicant_email'] + ordering_fields = ['created_at', 'requested_amount'] + def get_queryset(self): - return LoanApplication.objects.annotate(document_count=Count('documents')) + return ( + visible_loans(self.request.user) + .annotate(document_count=Count('documents')) + .order_by('-created_at', '-pk') + ) + + def perform_create(self, serializer): + serializer.save(owner=self.request.user) @action(detail=True, methods=['post']) def submit(self, request, pk=None): - loan=self.get_object() - if not loan.documents.exists(): - return Response({'detail':'Upload at least one document first.'}, status=status.HTTP_400_BAD_REQUEST) - loan.status=LoanApplication.Status.SUBMITTED; loan.save(update_fields=['status','updated_at']) - job=ProcessingJob.objects.create(loan=loan) - async_result=process_loan.delay(str(job.id)) - job.celery_task_id=async_result.id; job.save(update_fields=['celery_task_id']) - return Response({'loan_id':str(loan.id),'job_id':str(job.id),'status':job.status}, status=status.HTTP_202_ACCEPTED) + with transaction.atomic(): + # Return 404 if the loan does not exist or is not accessible. + # Retain the row lock to prevent concurrent submissions. + loan = get_object_or_404( + visible_loans(request.user).select_for_update(), + pk=pk, + ) + + if loan.status != LoanApplication.Status.DRAFT: + raise ValidationError({ + 'detail': 'Only draft loans can be submitted.' + }) + + if not loan.documents.exists(): + raise ValidationError({ + 'detail': 'Upload at least one document first.' + }) + + job = ProcessingJob.objects.create(loan=loan) + + loan.status = LoanApplication.Status.SUBMITTED + loan.save(update_fields=['status', 'updated_at']) + + # Enqueue processing after the database transaction commits. + def enqueue(): + try: + result = process_loan.delay(str(job.id)) + + ProcessingJob.objects.filter( + pk=job.pk, + status=ProcessingJob.Status.QUEUED, + ).update(celery_task_id=result.id) + + except Exception: + ProcessingJob.objects.filter( + pk=job.pk + ).update( + status=ProcessingJob.Status.FAILED, + error='Queue unavailable', + ) + + LoanApplication.objects.filter( + pk=loan.pk, + status=LoanApplication.Status.SUBMITTED, + ).update(status=LoanApplication.Status.REVIEW) + + transaction.on_commit(enqueue) + + return Response( + { + 'loan_id': str(loan.id), + 'job_id': str(job.id), + 'status': job.status, + }, + status=status.HTTP_202_ACCEPTED, + ) diff --git a/apps/processing/tasks.py b/apps/processing/tasks.py index bf388aa..49f8cbb 100644 --- a/apps/processing/tasks.py +++ b/apps/processing/tasks.py @@ -1,51 +1,247 @@ + from celery import shared_task from django.db import transaction from django.utils import timezone + from apps.loans.models import LoanApplication from apps.documents.models import LoanDocument from apps.underwriting.models import Recommendation from apps.underwriting.service import evaluate + from .models import ProcessingJob from .ai import extract from .schemas import ExtractedLoanData -@shared_task(bind=True, autoretry_for=(Exception,), retry_backoff=True, retry_backoff_max=30, retry_jitter=True, max_retries=3) + +@shared_task( + bind=True, + autoretry_for=(Exception,), + retry_backoff=True, + retry_backoff_max=30, + retry_jitter=True, + max_retries=3, +) def process_loan(self, job_id: str): - job=ProcessingJob.objects.select_related('loan').get(id=job_id) - job.status=ProcessingJob.Status.RUNNING - job.started_at=timezone.now(); job.attempts += 1; job.celery_task_id=self.request.id or '' - job.save(update_fields=['status','started_at','attempts','celery_task_id']) - loan=job.loan - LoanApplication.objects.filter(id=loan.id).update(status=LoanApplication.Status.PROCESSING) + task_id = self.request.id or "" + + # Claim the job while holding the row lock. + with transaction.atomic(): + job = ( + ProcessingJob.objects + .select_for_update() + .select_related("loan") + .get(pk=job_id) + ) + + if job.status == ProcessingJob.Status.SUCCEEDED: + return { + "job_id": str(job.id), + "status": "already_completed", + } + + if job.status == ProcessingJob.Status.FAILED: + return { + "job_id": str(job.id), + "status": "already_failed", + } + + if job.status == ProcessingJob.Status.RUNNING: + return { + "job_id": str(job.id), + "status": "already_running", + } + + job.status = ProcessingJob.Status.RUNNING + job.started_at = timezone.now() + job.completed_at = None + job.attempts += 1 + job.celery_task_id = task_id + job.error = "" + + job.save( + update_fields=[ + "status", + "started_at", + "completed_at", + "attempts", + "celery_task_id", + "error", + ] + ) + + loan = job.loan + + LoanApplication.objects.filter(pk=loan.pk).update( + status=LoanApplication.Status.PROCESSING + ) + try: - docs=list(LoanDocument.objects.filter(loan=loan)) - if not docs: raise ValueError('At least one document is required before processing') - extracted=[] + docs = list( + LoanDocument.objects.filter(loan=loan) + ) + + if not docs: + raise ValueError( + "At least one document is required before processing" + ) + + extracted = [] + for doc in docs: - parsed=extract(doc.text_content or doc.filename) - doc.extracted_data=parsed.model_dump() - doc.processed=True; doc.processed_at=timezone.now() - doc.save(update_fields=['extracted_data','processed','processed_at']) + parsed = extract( + doc.text_content or doc.filename + ) + + doc.extracted_data = parsed.model_dump() + doc.processed = True + doc.processed_at = timezone.now() + + doc.save( + update_fields=[ + "extracted_data", + "processed", + "processed_at", + ] + ) + extracted.append(parsed) - income=max((d.monthly_income for d in extracted), default=0) - liabilities=max((d.monthly_liabilities for d in extracted), default=0) - flags=sorted({flag for d in extracted for flag in d.risk_flags}) - confidence=min((d.confidence for d in extracted), default=0) - employment=next((d.employment_status for d in extracted if d.employment_status!='other'),'other') - combined=ExtractedLoanData(monthly_income=income, employment_status=employment, employer=None, monthly_liabilities=liabilities, risk_flags=flags, confidence=confidence) - result=evaluate(combined, loan.requested_amount) + income = max( + (item.monthly_income for item in extracted), + default=0, + ) + + liabilities = max( + (item.monthly_liabilities for item in extracted), + default=0, + ) + flags = sorted({ + flag + for item in extracted + for flag in item.risk_flags + }) + + confidence = min( + (item.confidence for item in extracted), + default=0, + ) + + employment = next( + ( + item.employment_status + for item in extracted + if item.employment_status != "other" + ), + "other", + ) + + combined = ExtractedLoanData( + monthly_income=income, + employment_status=employment, + employer=None, + monthly_liabilities=liabilities, + risk_flags=flags, + confidence=confidence, + ) + + result = evaluate( + combined, + loan.requested_amount, + ) + + new_status = { + "approve": LoanApplication.Status.APPROVED, + "reject": LoanApplication.Status.REJECTED, + "manual_review": LoanApplication.Status.REVIEW, + }[result.decision] + + # Commit the recommendation and final statuses together. with transaction.atomic(): - Recommendation.objects.update_or_create(loan=loan, defaults={ - 'decision':result.decision,'risk_score':result.risk_score,'debt_to_income':result.debt_to_income, - 'monthly_income':income,'monthly_liabilities':liabilities,'risk_flags':result.risk_flags,'reasons':result.reasons, - }) - new_status={'approve':LoanApplication.Status.APPROVED,'reject':LoanApplication.Status.REJECTED,'manual_review':LoanApplication.Status.REVIEW}[result.decision] - LoanApplication.objects.filter(id=loan.id).update(status=new_status) - job.status=ProcessingJob.Status.SUCCEEDED; job.completed_at=timezone.now(); job.error=''; job.save(update_fields=['status','completed_at','error']) - return {'job_id':str(job.id),'decision':result.decision,'risk_score':result.risk_score} + locked_job = ( + ProcessingJob.objects + .select_for_update() + .get(pk=job.pk) + ) + + if locked_job.status != ProcessingJob.Status.RUNNING: + return { + "job_id": str(job.id), + "status": "state_changed", + } + + Recommendation.objects.update_or_create( + loan=loan, + defaults={ + "decision": result.decision, + "risk_score": result.risk_score, + "debt_to_income": result.debt_to_income, + "monthly_income": income, + "monthly_liabilities": liabilities, + "risk_flags": result.risk_flags, + "reasons": result.reasons, + }, + ) + + LoanApplication.objects.filter( + pk=loan.pk + ).update(status=new_status) + + locked_job.status = ProcessingJob.Status.SUCCEEDED + locked_job.completed_at = timezone.now() + locked_job.error = "" + + locked_job.save( + update_fields=[ + "status", + "completed_at", + "error", + ] + ) + + return { + "job_id": str(job.id), + "decision": result.decision, + "risk_score": result.risk_score, + } + except Exception as exc: - job.status=ProcessingJob.Status.FAILED; job.error=str(exc); job.completed_at=timezone.now(); job.save(update_fields=['status','error','completed_at']) - LoanApplication.objects.filter(id=loan.id).update(status=LoanApplication.Status.REVIEW) + final_attempt = ( + self.request.retries >= self.max_retries + ) + + with transaction.atomic(): + locked_job = ( + ProcessingJob.objects + .select_for_update() + .get(pk=job.pk) + ) + + if locked_job.status == ProcessingJob.Status.RUNNING: + if final_attempt: + locked_job.status = ProcessingJob.Status.FAILED + locked_job.error = type(exc).__name__ + locked_job.completed_at = timezone.now() + + locked_job.save( + update_fields=[ + "status", + "error", + "completed_at", + ] + ) + + LoanApplication.objects.filter( + pk=loan.pk + ).update( + status=LoanApplication.Status.REVIEW + ) + + else: + locked_job.status = ProcessingJob.Status.QUEUED + locked_job.save( + update_fields=["status"] + ) + + # Allow Celery's autoretry mechanism to handle the error. raise diff --git a/apps/processing/views.py b/apps/processing/views.py index ca99888..074f0da 100644 --- a/apps/processing/views.py +++ b/apps/processing/views.py @@ -1,7 +1,10 @@ +from apps.loans.permissions import LoanAccess, visible_loans from rest_framework import mixins, viewsets from .models import ProcessingJob from .serializers import ProcessingJobSerializer class ProcessingJobViewSet(mixins.RetrieveModelMixin,mixins.ListModelMixin,viewsets.GenericViewSet): - queryset=ProcessingJob.objects.select_related('loan').all() + permission_classes=[LoanAccess] + def get_queryset(self): + return ProcessingJob.objects.filter(loan__in=visible_loans(self.request.user)).select_related('loan') serializer_class=ProcessingJobSerializer filterset_fields=['loan','status'] diff --git a/apps/underwriting/views.py b/apps/underwriting/views.py index 0786393..08a1cb8 100644 --- a/apps/underwriting/views.py +++ b/apps/underwriting/views.py @@ -1,7 +1,10 @@ +from apps.loans.permissions import LoanAccess, visible_loans from rest_framework import mixins, viewsets from .models import Recommendation from .serializers import RecommendationSerializer class RecommendationViewSet(mixins.RetrieveModelMixin,mixins.ListModelMixin,viewsets.GenericViewSet): - queryset=Recommendation.objects.select_related('loan').all() + permission_classes=[LoanAccess] + def get_queryset(self): + return Recommendation.objects.filter(loan__in=visible_loans(self.request.user)).select_related('loan') serializer_class=RecommendationSerializer filterset_fields=['loan','decision'] diff --git a/config/celery.py b/config/celery.py index 887e159..fe8c6c0 100644 --- a/config/celery.py +++ b/config/celery.py @@ -1,6 +1,12 @@ + import os from celery import Celery -os.environ.setdefault('DJANGO_SETTINGS_MODULE','config.settings') + +os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings') + app = Celery('loan_processing') app.config_from_object('django.conf:settings', namespace='CELERY') -app.autodiscover_tasks() + +app.conf.broker_connection_retry_on_startup = True + +app.autodiscover_tasks() \ No newline at end of file diff --git a/config/settings.py b/config/settings.py index 69d1ce7..dc3008d 100644 --- a/config/settings.py +++ b/config/settings.py @@ -6,9 +6,17 @@ load_dotenv(BASE_DIR / ".env") -SECRET_KEY = os.getenv('DJANGO_SECRET_KEY', 'dev-secret') DEBUG = os.getenv('DJANGO_DEBUG', 'true').lower() == 'true' -ALLOWED_HOSTS = ['*'] +SECRET_KEY = os.getenv('DJANGO_SECRET_KEY', 'dev-secret') +if not DEBUG and SECRET_KEY in ('dev-secret', 'dev-secret-change-me', ''): + raise RuntimeError('Set a secure DJANGO_SECRET_KEY when DJANGO_DEBUG=false') +ALLOWED_HOSTS = [host.strip() for host in os.getenv('DJANGO_ALLOWED_HOSTS', 'localhost,127.0.0.1').split(',') if host.strip()] +CSRF_TRUSTED_ORIGINS = [origin.strip() for origin in os.getenv('DJANGO_CSRF_TRUSTED_ORIGINS', '').split(',') if origin.strip()] +SESSION_COOKIE_SECURE = not DEBUG +CSRF_COOKIE_SECURE = not DEBUG +SECURE_CONTENT_TYPE_NOSNIFF = True +SECURE_HSTS_SECONDS = int(os.getenv('DJANGO_HSTS_SECONDS', '0')) if not DEBUG else 0 +SECURE_SSL_REDIRECT = os.getenv('DJANGO_SSL_REDIRECT', 'false').lower() == 'true' if not DEBUG else False INSTALLED_APPS = [ 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', @@ -52,6 +60,16 @@ 'DEFAULT_FILTER_BACKENDS':['django_filters.rest_framework.DjangoFilterBackend'], 'DEFAULT_PAGINATION_CLASS':'rest_framework.pagination.PageNumberPagination', 'PAGE_SIZE':50, + 'DEFAULT_AUTHENTICATION_CLASSES': [ + 'rest_framework.authentication.SessionAuthentication', + 'rest_framework.authentication.BasicAuthentication', + ], + 'DEFAULT_PERMISSION_CLASSES': ['rest_framework.permissions.IsAuthenticated'], + 'DEFAULT_THROTTLE_CLASSES': [ + 'rest_framework.throttling.AnonRateThrottle', + 'rest_framework.throttling.UserRateThrottle', + ], + 'DEFAULT_THROTTLE_RATES': {'anon': '30/min', 'user': '120/min'}, } SPECTACULAR_SETTINGS={'TITLE':'Loan Processing Platform API','VERSION':'1.0.0'} @@ -64,3 +82,5 @@ OPENAI_API_KEY = os.getenv('OPENAI_API_KEY','') OPENAI_MODEL = os.getenv('OPENAI_MODEL','gpt-5.6-luna') USE_FAKE_AI = os.getenv('USE_FAKE_AI','true').lower() == 'true' + +DATA_UPLOAD_MAX_MEMORY_SIZE = 2 * 1024 * 1024 diff --git a/docker-compose.yml b/docker-compose.yml index 84b6aa1..b24c762 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,3 +1,4 @@ + services: db: image: postgres:16-alpine @@ -5,37 +6,79 @@ services: POSTGRES_DB: ${POSTGRES_DB:-loans} POSTGRES_USER: ${POSTGRES_USER:-loans} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-loans} - ports: ["5433:5432"] - volumes: ["postgres_data:/var/lib/postgresql/data"] + ports: + - "5433:5432" + volumes: + - postgres_data:/var/lib/postgresql/data healthcheck: - test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-loans} -d ${POSTGRES_DB:-loans}"] + test: + - CMD-SHELL + - pg_isready -U ${POSTGRES_USER:-loans} -d ${POSTGRES_DB:-loans} interval: 5s timeout: 5s retries: 10 + redis: image: redis:7-alpine - ports: ["6379:6379"] + ports: + - "6379:6379" healthcheck: - test: ["CMD", "redis-cli", "ping"] + test: + - CMD + - redis-cli + - ping interval: 5s timeout: 3s retries: 10 + web: build: . - env_file: .env - command: sh -c "python manage.py makemigrations loans documents processing underwriting --noinput && python manage.py migrate && gunicorn config.wsgi:application --bind 0.0.0.0:8000 --workers 3 --timeout 120" - volumes: [".:/app"] - ports: ["8000:8000"] + env_file: + - .env + environment: + POSTGRES_HOST: db + POSTGRES_PORT: "5432" + REDIS_URL: redis://redis:6379/0 + CELERY_BROKER_URL: redis://redis:6379/0 + CELERY_RESULT_BACKEND: redis://redis:6379/0 + USE_FAKE_AI: "True" + command: + - sh + - -c + - | + python manage.py migrate --noinput && + exec gunicorn config.wsgi:application \ + --bind 0.0.0.0:8000 \ + --workers 3 \ + --timeout 120 + volumes: + - .:/app + ports: + - "8000:8000" depends_on: - db: {condition: service_healthy} - redis: {condition: service_healthy} + db: + condition: service_healthy + redis: + condition: service_healthy + worker: build: . - env_file: .env + env_file: + - .env + environment: + POSTGRES_HOST: db + POSTGRES_PORT: "5432" + REDIS_URL: redis://redis:6379/0 + CELERY_BROKER_URL: redis://redis:6379/0 + CELERY_RESULT_BACKEND: redis://redis:6379/0 command: celery -A config worker -l info --concurrency=4 - volumes: [".:/app"] + volumes: + - .:/app depends_on: - db: {condition: service_healthy} - redis: {condition: service_healthy} + db: + condition: service_healthy + redis: + condition: service_healthy + volumes: postgres_data: diff --git a/tests/test_api_access.py b/tests/test_api_access.py new file mode 100644 index 0000000..2b20477 --- /dev/null +++ b/tests/test_api_access.py @@ -0,0 +1,69 @@ +"""Auth and ownership regression tests. Run with pytest against isolated test Postgres.""" +import pytest +from django.contrib.auth import get_user_model +from rest_framework.test import APIClient +from apps.loans.models import LoanApplication +from apps.documents.models import LoanDocument + +@pytest.fixture +def users(db): + User = get_user_model() + return (User.objects.create_user(username='applicant_a', password='test-password-a'), + User.objects.create_user(username='applicant_b', password='test-password-b'), + User.objects.create_user(username='reviewer', password='test-password-c', is_staff=True)) + +@pytest.fixture +def loan(db, users): + return LoanApplication.objects.create(owner=users[0], applicant_name='A', applicant_email='a@example.test', requested_amount='5000.00', purpose='Equipment') + +@pytest.mark.django_db +def test_anonymous_loan_list_is_rejected(): + assert APIClient().get('/api/loans/').status_code in (401, 403) + +@pytest.mark.django_db +def test_users_cannot_list_or_fetch_other_users_loans(users, loan): + client = APIClient() + client.force_authenticate(user=users[1]) + r = client.get('/api/loans/') + assert r.status_code == 200 and r.data['count'] == 0 + assert client.get(f'/api/loans/{loan.pk}/').status_code == 404 + assert client.post(f'/api/loans/{loan.pk}/submit/').status_code == 404 + +@pytest.mark.django_db +def test_owner_assigned_server_side(users): + client = APIClient(); client.force_authenticate(user=users[0]) + response = client.post('/api/loans/', {'applicant_name':'A','applicant_email':'a@example.test', 'requested_amount':'1500.00','purpose':'Car'}, format='json') + assert response.status_code == 201 + assert LoanApplication.objects.get(pk=response.data['id']).owner_id == users[0].pk + +@pytest.mark.django_db +def test_staff_can_view_legacy_loan(users): + legacy = LoanApplication.objects.create(applicant_name='Legacy', applicant_email='legacy@example.test', requested_amount='1000', purpose='Legacy') + client = APIClient(); client.force_authenticate(user=users[2]) + assert client.get(f'/api/loans/{legacy.pk}/').status_code == 200 + +@pytest.mark.django_db +def test_document_cannot_link_to_someone_elses_loan(users, loan): + client = APIClient(); client.force_authenticate(user=users[1]) + response = client.post('/api/documents/', {'loan':str(loan.pk), 'kind':'other', 'filename':'note.txt', 'text_content':'Sample'}, format='json') + assert response.status_code == 400 + assert LoanDocument.objects.count() == 0 + +@pytest.mark.django_db +def test_document_size_and_extension_validation(users, loan): + client = APIClient(); client.force_authenticate(user=users[0]) + base = {'loan': str(loan.pk), 'kind':'other'} + assert client.post('/api/documents/', {**base, 'filename':'bad.exe', 'text_content':'sample'}, format='json').status_code == 400 + assert client.post('/api/documents/', {**base, 'filename':'good.txt', 'text_content':'x' * (1024 * 1024 + 1)}, format='json').status_code == 400 + +@pytest.mark.django_db +def test_repeated_submit_is_rejected(users, loan, monkeypatch): + client=APIClient(); client.force_authenticate(user=users[0]) + LoanDocument.objects.create(loan=loan, kind='other', filename='sample.txt', text_content='sample') + class Result: + id='fake-task-id' + monkeypatch.setattr('apps.loans.views.process_loan.delay', lambda *_: Result()) + first = client.post(f'/api/loans/{loan.pk}/submit/') + assert first.status_code == 202 + assert client.post(f'/api/loans/{loan.pk}/submit/').status_code == 400 + assert loan.processing_jobs.count() == 1 diff --git a/tests/test_processing_reliability.py b/tests/test_processing_reliability.py new file mode 100644 index 0000000..d09b3c5 --- /dev/null +++ b/tests/test_processing_reliability.py @@ -0,0 +1,202 @@ + +"""Celery processing reliability regression tests.""" + +import pytest +from django.contrib.auth import get_user_model + +from apps.loans.models import LoanApplication +from apps.documents.models import LoanDocument +from apps.processing.models import ProcessingJob +from apps.processing.tasks import process_loan +from apps.processing.ai import fake_extract +from apps.underwriting.models import Recommendation + + +@pytest.fixture +def processing_job(db): + user = get_user_model().objects.create_user( + username="processing_test_user", + password="test-only-password", + ) + + loan = LoanApplication.objects.create( + owner=user, + applicant_name="Synthetic Applicant", + applicant_email="synthetic@example.test", + requested_amount="15000.00", + purpose="Automated reliability test", + status=LoanApplication.Status.SUBMITTED, + ) + + LoanDocument.objects.create( + loan=loan, + kind=LoanDocument.Kind.PAYSTUB, + filename="sample.txt", + text_content=( + "Monthly income: 6500. " + "Monthly liabilities: 1200. " + "Employment status: employed." + ), + ) + + return ProcessingJob.objects.create(loan=loan) + + +def run_task(job): + # Execute locally and synchronously through Celery. + # This does not publish anything to Redis. + return process_loan.apply( + args=(str(job.pk),), + throw=False, + ) + + +def test_successful_processing(processing_job, monkeypatch): + monkeypatch.setattr( + "apps.processing.tasks.extract", + fake_extract, + ) + + result = run_task(processing_job) + + processing_job.refresh_from_db() + processing_job.loan.refresh_from_db() + + assert result.successful() + assert processing_job.status == ProcessingJob.Status.SUCCEEDED + assert processing_job.attempts == 1 + assert processing_job.error == "" + assert processing_job.completed_at is not None + assert processing_job.loan.status in ( + LoanApplication.Status.APPROVED, + LoanApplication.Status.REJECTED, + LoanApplication.Status.REVIEW, + ) + assert Recommendation.objects.filter( + loan=processing_job.loan + ).count() == 1 + + +def test_completed_job_is_not_reprocessed( + processing_job, + monkeypatch, +): + monkeypatch.setattr( + "apps.processing.tasks.extract", + fake_extract, + ) + + first = run_task(processing_job) + assert first.successful() + + def unexpected_extract(_text): + raise AssertionError( + "Completed job must not run extraction again" + ) + + monkeypatch.setattr( + "apps.processing.tasks.extract", + unexpected_extract, + ) + + second = run_task(processing_job) + + processing_job.refresh_from_db() + + assert second.successful() + assert second.result["status"] == "already_completed" + assert processing_job.attempts == 1 + assert Recommendation.objects.filter( + loan=processing_job.loan + ).count() == 1 + + +def test_running_job_is_not_claimed_again( + processing_job, + monkeypatch, +): + processing_job.status = ProcessingJob.Status.RUNNING + processing_job.save(update_fields=["status"]) + + def unexpected_extract(_text): + raise AssertionError( + "Running job must not be processed twice" + ) + + monkeypatch.setattr( + "apps.processing.tasks.extract", + unexpected_extract, + ) + + result = run_task(processing_job) + + processing_job.refresh_from_db() + + assert result.successful() + assert result.result["status"] == "already_running" + assert processing_job.attempts == 0 + + +def test_temporary_failure_recovers_after_retry( + processing_job, + monkeypatch, +): + calls = {"count": 0} + + def flaky_extract(text): + calls["count"] += 1 + + if calls["count"] == 1: + raise RuntimeError("Temporary extraction failure") + + return fake_extract(text) + + monkeypatch.setattr( + "apps.processing.tasks.extract", + flaky_extract, + ) + + result = run_task(processing_job) + + processing_job.refresh_from_db() + + assert result.successful() + assert calls["count"] == 2 + assert processing_job.attempts == 2 + assert processing_job.status == ProcessingJob.Status.SUCCEEDED + assert Recommendation.objects.filter( + loan=processing_job.loan + ).count() == 1 + + +def test_retry_exhaustion_marks_failure( + processing_job, + monkeypatch, +): + sensitive_message = ( + "Synthetic applicant confidential information" + ) + + def always_fail(_text): + raise RuntimeError(sensitive_message) + + monkeypatch.setattr( + "apps.processing.tasks.extract", + always_fail, + ) + + result = run_task(processing_job) + + processing_job.refresh_from_db() + processing_job.loan.refresh_from_db() + + assert result.failed() + assert processing_job.attempts == 4 + assert processing_job.status == ProcessingJob.Status.FAILED + assert processing_job.loan.status == LoanApplication.Status.REVIEW + assert processing_job.error == "RuntimeError" + assert sensitive_message not in processing_job.error + assert processing_job.completed_at is not None + assert Recommendation.objects.filter( + loan=processing_job.loan + ).count() == 0