Files
celtic-life-science/app/reports/service.py
T
Shubhankar45 8fdd20b29f Production
2026-09-22 06:23:46 +00:00

493 lines
20 KiB
Python

"""Daily Call Report business rules — validation rules V1-V12 all live here.
Routers never contain rules; repositories never contain rules. This module is the
single place a reviewer needs to read to understand what the system enforces.
"""
import uuid
from datetime import date, timedelta
from sqlalchemy import select
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession
from app.approvals.state_machine import assert_editable, assert_transition
from app.audit.service import AuditService
from app.auth.dependencies import assert_can_view_dcr, visible_hq_ids
from app.chemists.models import Chemist, ChemistAssignment
from app.common.enums import (
AuditAction,
DCRStatus,
EntityType,
Role,
WorkflowAction,
)
from app.common.exceptions import (
ConflictError,
NotFoundError,
ValidationError,
)
from app.common.utils import local_now, local_today, snapshot, utcnow
from app.config.settings import settings
from app.doctors.models import Doctor, DoctorAssignment
from app.reports.models import ChemistCall, DailyCallReport, DoctorCall
from app.reports.repository import DCRRepository
from app.reports.schemas import ChemistCallCreate, DCRCreate, DoctorCallCreate
from app.users.models import User
#: Audit fields — the columns worth recording on a state change.
_AUDIT_FIELDS = [
"status",
"report_date",
"mr_remarks",
"stockist_visit",
"order_value",
"return_reason",
"returned_by_role",
"submitted_at",
"approved_at",
]
def _clean(value: str | None) -> str | None:
"""Trimmed text, with blank input stored as NULL."""
value = (value or "").strip()
return value or None
class DCRService:
def __init__(self, db: AsyncSession) -> None:
self.db = db
self.repo = DCRRepository(db)
self.audit = AuditService(db)
# ------------------------------------------------------------------
# Validation helpers
# ------------------------------------------------------------------
def _validate_report_date(self, report_date: date) -> None:
today = local_today()
# V2 — no future reports.
if report_date > today:
raise ValidationError(
"Report date cannot be in the future",
{"report_date": report_date.isoformat(), "today": today.isoformat()},
)
# V3 / A10 / Q8 — back-dating window.
earliest = today - timedelta(days=settings.BACKDATING_WINDOW_DAYS)
if report_date < earliest:
raise ValidationError(
f"Report date is older than the {settings.BACKDATING_WINDOW_DAYS}-day "
"back-dating window",
{"report_date": report_date.isoformat(), "earliest_allowed": earliest.isoformat()},
)
def _check_submission_deadline(self, report_date: date) -> None:
"""A16 / Q9 — report for date D must be submitted by end of D + N days."""
deadline = report_date + timedelta(days=settings.SUBMISSION_DEADLINE_DAYS)
if local_today() > deadline:
raise ValidationError(
"Submission deadline for this report date has passed",
{"report_date": report_date.isoformat(), "deadline": deadline.isoformat()},
)
async def _assigned_doctor_ids(self, mr_user_id: uuid.UUID) -> set[uuid.UUID]:
stmt = select(DoctorAssignment.doctor_id).where(
DoctorAssignment.mr_user_id == mr_user_id,
DoctorAssignment.effective_to.is_(None),
)
return set((await self.db.execute(stmt)).scalars().all())
async def _assigned_chemist_ids(self, mr_user_id: uuid.UUID) -> set[uuid.UUID]:
stmt = select(ChemistAssignment.chemist_id).where(
ChemistAssignment.mr_user_id == mr_user_id,
ChemistAssignment.effective_to.is_(None),
)
return set((await self.db.execute(stmt)).scalars().all())
async def _build_doctor_call(
self, dcr: DailyCallReport, payload: DoctorCallCreate, assigned: set[uuid.UUID]
) -> DoctorCall:
# V6 — only doctors currently assigned to this MR may be called.
if payload.doctor_id not in assigned:
raise ValidationError(
"Doctor is not assigned to this MR",
{"doctor_id": str(payload.doctor_id)},
)
doctor = await self.db.get(Doctor, payload.doctor_id)
if doctor is None:
raise NotFoundError("Doctor not found", {"doctor_id": str(payload.doctor_id)})
# V7 — conversion status is meaningful only for core doctors.
if payload.conversion_status is not None and not doctor.is_core_doctor:
raise ValidationError(
"conversion_status may only be set for a core doctor",
{"doctor_id": str(doctor.id), "is_core_doctor": False},
)
return DoctorCall(
dcr_id=dcr.id,
doctor_id=payload.doctor_id,
visit_time=payload.visit_time,
call_outcome=payload.call_outcome,
conversion_status=payload.conversion_status,
product_promote=_clean(payload.product_promote),
product_sample=_clean(payload.product_sample),
remarks=payload.remarks,
)
async def _build_chemist_call(
self, dcr: DailyCallReport, payload: ChemistCallCreate, assigned: set[uuid.UUID]
) -> ChemistCall:
if payload.chemist_id not in assigned:
raise ValidationError(
"Chemist is not assigned to this MR", {"chemist_id": str(payload.chemist_id)}
)
if await self.db.get(Chemist, payload.chemist_id) is None:
raise NotFoundError("Chemist not found", {"chemist_id": str(payload.chemist_id)})
return ChemistCall(
dcr_id=dcr.id,
chemist_id=payload.chemist_id,
visit_time=payload.visit_time,
pob=_clean(payload.pob),
remarks=payload.remarks,
)
# ------------------------------------------------------------------
# Commands
# ------------------------------------------------------------------
async def create(
self, data: DCRCreate, actor: User, ip: str | None = None
) -> DailyCallReport:
if actor.role != Role.MR or actor.headquarters_id is None:
raise ValidationError("Only an MR with a headquarters can create a report")
self._validate_report_date(data.report_date)
# V1 pre-check for a friendly 409; the unique constraint below is the guarantee.
if await self.repo.get_for_date(actor.id, data.report_date):
raise ConflictError(
"A report already exists for this date",
{"report_date": data.report_date.isoformat()},
)
dcr = DailyCallReport(
id=uuid.uuid4(),
mr_user_id=actor.id,
headquarters_id=actor.headquarters_id, # snapshot (A1)
report_date=data.report_date,
status=DCRStatus.DRAFT,
mr_remarks=data.mr_remarks,
)
self.db.add(dcr)
doctor_ids = await self._assigned_doctor_ids(actor.id)
chemist_ids = await self._assigned_chemist_ids(actor.id)
seen_doctors: set[uuid.UUID] = set()
for payload in data.doctor_calls:
if payload.doctor_id in seen_doctors:
raise ConflictError(
"Duplicate doctor call in the same report",
{"doctor_id": str(payload.doctor_id)},
)
seen_doctors.add(payload.doctor_id)
self.db.add(await self._build_doctor_call(dcr, payload, doctor_ids))
seen_chemists: set[uuid.UUID] = set()
for payload in data.chemist_calls:
if payload.chemist_id in seen_chemists:
raise ConflictError(
"Duplicate chemist call in the same report",
{"chemist_id": str(payload.chemist_id)},
)
seen_chemists.add(payload.chemist_id)
self.db.add(await self._build_chemist_call(dcr, payload, chemist_ids))
await self.audit.log(
actor_user_id=actor.id,
entity_type=EntityType.DCR,
entity_id=dcr.id,
action=AuditAction.CREATE,
after=snapshot(dcr, _AUDIT_FIELDS),
ip_address=ip,
)
try:
await self.db.commit()
except IntegrityError as exc:
await self.db.rollback()
raise ConflictError(
"A report already exists for this MR and date", {"cause": "uq_dcr_mr_date"}
) from exc
return await self.repo.get_full(dcr.id)
async def update_details(
self, dcr_id: uuid.UUID, changes: dict[str, str | None], actor: User, ip: str | None = None
) -> DailyCallReport:
"""Change the report-level free text: MR remarks, stockist visit, order."""
dcr = await self._get_owned_editable(dcr_id, actor)
before = snapshot(dcr, _AUDIT_FIELDS)
for field in ("mr_remarks", "stockist_visit", "order_value"):
if field in changes:
setattr(dcr, field, _clean(changes[field]))
await self.audit.log(
actor_user_id=actor.id,
entity_type=EntityType.DCR,
entity_id=dcr.id,
action=AuditAction.UPDATE,
before=before,
after=snapshot(dcr, _AUDIT_FIELDS),
ip_address=ip,
)
await self.db.commit()
return await self.repo.get_full(dcr.id)
async def add_doctor_call(
self, dcr_id: uuid.UUID, payload: DoctorCallCreate, actor: User, ip: str | None = None
) -> DailyCallReport:
dcr = await self._get_owned_editable(dcr_id, actor)
assigned = await self._assigned_doctor_ids(actor.id)
call = await self._build_doctor_call(dcr, payload, assigned)
self._validate_visit_time(dcr, payload.visit_time)
self.db.add(call)
# Flush the insert on its own so the unique-violation surfaces HERE, as a
# clean 409, rather than escaping from the audit flush or the final commit.
try:
await self.db.flush()
except IntegrityError as exc:
await self.db.rollback()
# V5 — the doctor is already on this report.
raise ConflictError(
"This doctor has already been called on this report",
{"doctor_id": str(payload.doctor_id), "cause": "uq_call_dcr_doctor"},
) from exc
await self.audit.log(
actor_user_id=actor.id,
entity_type=EntityType.DCR,
entity_id=dcr.id,
action=AuditAction.UPDATE,
after={"added_doctor_call": str(payload.doctor_id)},
ip_address=ip,
)
await self.db.commit()
return await self.repo.get_full(dcr.id)
async def add_chemist_call(
self, dcr_id: uuid.UUID, payload: ChemistCallCreate, actor: User, ip: str | None = None
) -> DailyCallReport:
dcr = await self._get_owned_editable(dcr_id, actor)
assigned = await self._assigned_chemist_ids(actor.id)
call = await self._build_chemist_call(dcr, payload, assigned)
self._validate_visit_time(dcr, payload.visit_time)
self.db.add(call)
try:
await self.db.flush()
except IntegrityError as exc:
await self.db.rollback()
raise ConflictError(
"This chemist has already been called on this report",
{"chemist_id": str(payload.chemist_id), "cause": "uq_call_dcr_chemist"},
) from exc
await self.audit.log(
actor_user_id=actor.id,
entity_type=EntityType.DCR,
entity_id=dcr.id,
action=AuditAction.UPDATE,
after={"added_chemist_call": str(payload.chemist_id)},
ip_address=ip,
)
await self.db.commit()
return await self.repo.get_full(dcr.id)
def _validate_visit_time(self, dcr: DailyCallReport, visit_time) -> None:
"""V11 — a visit time on today's report cannot be in the future."""
if dcr.report_date == local_today():
# Visit times are entered in the company's local time (APP_TIMEZONE), so they
# must be compared with local "now" — not the server's UTC clock.
if visit_time > local_now().time() and settings.ENVIRONMENT == "production":
raise ValidationError(
"Visit time cannot be in the future", {"visit_time": str(visit_time)}
)
async def delete_call(
self, dcr_id: uuid.UUID, call_id: uuid.UUID, actor: User, ip: str | None = None
) -> DailyCallReport:
dcr = await self._get_owned_editable(dcr_id, actor)
call = await self.db.get(DoctorCall, call_id) or await self.db.get(ChemistCall, call_id)
if call is None or call.dcr_id != dcr.id:
raise NotFoundError("Call not found on this report", {"call_id": str(call_id)})
await self.db.delete(call)
await self.audit.log(
actor_user_id=actor.id,
entity_type=EntityType.DCR,
entity_id=dcr.id,
action=AuditAction.DELETE,
before={"removed_call": str(call_id)},
ip_address=ip,
)
await self.db.commit()
return await self.repo.get_full(dcr.id)
# ------------------------------------------------------------------
# Workflow transitions
# ------------------------------------------------------------------
async def submit(
self, dcr_id: uuid.UUID, actor: User, ip: str | None = None
) -> DailyCallReport:
dcr = await self.repo.get_full(dcr_id)
if dcr is None:
raise NotFoundError("Report not found", {"id": str(dcr_id)})
await assert_can_view_dcr(self.db, actor, dcr)
if dcr.mr_user_id != actor.id:
from app.common.exceptions import ForbiddenError
raise ForbiddenError("Only the owning MR can submit this report")
if dcr.status == DCRStatus.PENDING_AM:
return dcr # already submitted (a double click): nothing more to do
transition = assert_transition(dcr.status, WorkflowAction.SUBMIT, actor.role)
# V4 — at least one doctor call is required to submit.
if not dcr.doctor_calls:
raise ValidationError("A report must contain at least one doctor call to submit")
self._check_submission_deadline(dcr.report_date)
before = snapshot(dcr, _AUDIT_FIELDS)
dcr.status = transition.to_status
dcr.submitted_at = utcnow()
dcr.return_reason = None
dcr.returned_by_role = None
dcr.current_am_user_id = await self._current_am_for_hq(dcr.headquarters_id)
await self.audit.log(
actor_user_id=actor.id,
entity_type=EntityType.DCR,
entity_id=dcr.id,
action=AuditAction.SUBMIT,
before=before,
after=snapshot(dcr, _AUDIT_FIELDS),
ip_address=ip,
)
await self.db.commit()
return await self.repo.get_full(dcr.id)
async def return_report(
self, dcr_id: uuid.UUID, reason: str, actor: User, ip: str | None = None
) -> DailyCallReport:
dcr = await self._get_in_scope(dcr_id, actor)
transition = assert_transition(dcr.status, WorkflowAction.RETURN, actor.role)
before = snapshot(dcr, _AUDIT_FIELDS)
dcr.status = transition.to_status
dcr.return_reason = reason
dcr.returned_by_role = actor.role # data, not a separate status
await self.audit.log(
actor_user_id=actor.id,
entity_type=EntityType.DCR,
entity_id=dcr.id,
action=AuditAction.RETURN,
before=before,
after=snapshot(dcr, _AUDIT_FIELDS),
comment=reason,
ip_address=ip,
)
await self.db.commit()
return await self.repo.get_full(dcr.id)
async def approve(
self, dcr_id: uuid.UUID, comment: str | None, actor: User, ip: str | None = None
) -> DailyCallReport:
"""Area Manager final approval. APPROVED is terminal and immutable."""
dcr = await self._get_in_scope(dcr_id, actor)
if dcr.status == DCRStatus.APPROVED and actor.role == Role.AM:
return dcr # already approved (a double click): the report stays as it is
transition = assert_transition(dcr.status, WorkflowAction.APPROVE, actor.role)
before = snapshot(dcr, _AUDIT_FIELDS)
dcr.status = transition.to_status
dcr.approved_at = utcnow()
await self.audit.log(
actor_user_id=actor.id,
entity_type=EntityType.DCR,
entity_id=dcr.id,
action=AuditAction.APPROVE,
before=before,
after=snapshot(dcr, _AUDIT_FIELDS),
comment=comment,
ip_address=ip,
)
# PDF is generated synchronously — it takes about a second, and adding a task
# queue for one one-second job is infrastructure you must then operate.
from app.pdf.service import PDFService
full = await self.repo.get_full(dcr.id)
dcr.pdf_path = await PDFService(self.db).render_and_store(full, approver=actor)
await self.db.commit()
return await self.repo.get_full(dcr.id)
# ------------------------------------------------------------------
# Queries
# ------------------------------------------------------------------
async def get_for_view(self, dcr_id: uuid.UUID, actor: User) -> DailyCallReport:
dcr = await self.repo.get_full(dcr_id)
if dcr is None:
raise NotFoundError("Report not found", {"id": str(dcr_id)})
await assert_can_view_dcr(self.db, actor, dcr)
return dcr
async def list_for(self, actor: User, **filters) -> list[DailyCallReport]:
if actor.role == Role.MR:
return await self.repo.list_scoped(mr_user_id=actor.id, **filters)
hq_ids = await visible_hq_ids(self.db, actor)
return await self.repo.list_scoped(hq_ids=hq_ids, **filters)
async def counts_for(self, actor: User) -> dict[str, int]:
if actor.role == Role.MR:
return await self.repo.status_counts(mr_user_id=actor.id)
return await self.repo.status_counts(hq_ids=await visible_hq_ids(self.db, actor))
# ------------------------------------------------------------------
# Internals
# ------------------------------------------------------------------
async def _get_owned_editable(self, dcr_id: uuid.UUID, actor: User) -> DailyCallReport:
"""Owner + editable-status guard for every data-changing operation (V9/V10)."""
dcr = await self.repo.get_full(dcr_id)
if dcr is None:
raise NotFoundError("Report not found", {"id": str(dcr_id)})
await assert_can_view_dcr(self.db, actor, dcr)
if actor.role != Role.MR or dcr.mr_user_id != actor.id:
from app.common.exceptions import ForbiddenError
raise ForbiddenError("Only the owning MR can modify report data")
assert_editable(dcr.status)
return dcr
async def _get_in_scope(self, dcr_id: uuid.UUID, actor: User) -> DailyCallReport:
dcr = await self.repo.get_full(dcr_id)
if dcr is None:
raise NotFoundError("Report not found", {"id": str(dcr_id)})
await assert_can_view_dcr(self.db, actor, dcr)
return dcr
async def _current_am_for_hq(self, headquarters_id: uuid.UUID) -> uuid.UUID | None:
from app.organization.models import AMHeadquarters
stmt = select(AMHeadquarters.area_manager_user_id).where(
AMHeadquarters.headquarters_id == headquarters_id,
AMHeadquarters.effective_to.is_(None),
)
return (await self.db.execute(stmt)).scalars().first()