This commit is contained in:
Shubhankar45
2026-10-27 12:03:31 +00:00
parent 2ed3945b5d
commit 4e5e95775d
104 changed files with 5210 additions and 606 deletions
+330 -52
View File
@@ -2,6 +2,22 @@
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.
Plan / end-of-day rules (P1-P5):
P1 A PLAN lists the visits the MR intends to make; it carries no outcomes, and its
times are planned times, so they may be later than "now".
P2 An ACTUAL (end-of-day) report can be created only once the PLAN for that date is
APPROVED by the Area Manager; it is linked to that plan.
P3 Every planned doctor/chemist must, before submit, either have a visit recorded on
the end-of-day report or a short note saying why it was missed.
P4 Recording a visit for a doctor/chemist drops any "missed" note for them.
P5 Visits not on the plan may still be added to the end-of-day report.
Area Manager's own report (S1-S3):
S1 An Area Manager files one SELF report per date, for one headquarters they manage;
it needs no plan.
S2 Its visits may be to any active doctor or chemist of that headquarters.
S3 There is no approval: submitting it makes it final (APPROVED, locked, PDF stored).
"""
import uuid
@@ -13,30 +29,37 @@ 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.auth.dependencies import active_hq_ids_for_am, assert_can_view_dcr, visible_hq_ids
from app.chemists.models import Chemist, ChemistAssignment
from app.common.enums import (
FIELD_ROLES,
AuditAction,
DCRStatus,
EntityType,
MasterApproval,
ReportType,
Role,
WorkflowAction,
FIELD_ROLES,
)
from app.common.exceptions import (
ConflictError,
ForbiddenError,
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.models import ChemistCall, DailyCallReport, DoctorCall, MissedVisit
from app.reports.repository import DCRRepository
from app.reports.schemas import ChemistCallCreate, DCRCreate, DoctorCallCreate
from app.reports.schemas import ChemistCallCreate, DCRCreate, DoctorCallCreate, MissedVisitSet
from app.reports.serializers import planned_visits
from app.users.models import User
#: Audit fields — the columns worth recording on a state change.
_AUDIT_FIELDS = [
"report_type",
"status",
"report_date",
"mr_remarks",
@@ -49,6 +72,15 @@ _AUDIT_FIELDS = [
]
#: Who files (and alone may edit or submit) each type of report.
_OWNER_ROLE = {ReportType.PLAN: FIELD_ROLES, ReportType.ACTUAL: FIELD_ROLES, ReportType.SELF: frozenset({Role.AM})}
_LABEL = {
ReportType.PLAN: "Daily Call Report (Plan)",
ReportType.ACTUAL: "Daily Call Report (Done)",
ReportType.SELF: "Daily Call Report (Self)",
}
def _clean(value: str | None) -> str | None:
"""Trimmed text, with blank input stored as NULL."""
value = (value or "").strip()
@@ -65,13 +97,15 @@ class DCRService:
# Validation helpers
# ------------------------------------------------------------------
def _validate_report_date(self, report_date: date) -> None:
def _validate_report_date(self, report_date: date, report_type: ReportType) -> None:
today = local_today()
# V2 — no future reports.
if report_date > today:
# V2 — no future reports, except a plan, which may be made PLAN_AHEAD_DAYS ahead.
ahead = settings.PLAN_AHEAD_DAYS if report_type == ReportType.PLAN else 0
latest = today + timedelta(days=ahead)
if report_date > latest:
raise ValidationError(
"Report date cannot be in the future",
{"report_date": report_date.isoformat(), "today": today.isoformat()},
f"A plan can be made at most {ahead} days ahead" if ahead else "Report date cannot be in the future",
{"report_date": report_date.isoformat(), "latest_allowed": latest.isoformat()},
)
# V3 / A10 / Q8 — back-dating window.
earliest = today - timedelta(days=settings.BACKDATING_WINDOW_DAYS)
@@ -91,17 +125,49 @@ class DCRService:
{"report_date": report_date.isoformat(), "deadline": deadline.isoformat()},
)
async def _allowed_doctor_ids(self, dcr: DailyCallReport) -> set[uuid.UUID]:
"""V6 — an MR's assigned doctors; for a SELF report, those of its headquarters (S2)."""
if dcr.report_type != ReportType.SELF:
return await self._assigned_doctor_ids(dcr.mr_user_id)
stmt = select(Doctor.id).where(
Doctor.headquarters_id == dcr.headquarters_id,
Doctor.is_active.is_(True),
Doctor.approval_status == MasterApproval.APPROVED,
)
return set((await self.db.execute(stmt)).scalars().all())
async def _allowed_chemist_ids(self, dcr: DailyCallReport) -> set[uuid.UUID]:
if dcr.report_type != ReportType.SELF:
return await self._assigned_chemist_ids(dcr.mr_user_id)
stmt = select(Chemist.id).where(
Chemist.headquarters_id == dcr.headquarters_id,
Chemist.is_active.is_(True),
Chemist.approval_status == MasterApproval.APPROVED,
)
return set((await self.db.execute(stmt)).scalars().all())
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),
# A doctor the MR added is visitable only once the Area Manager has approved it.
stmt = (
select(DoctorAssignment.doctor_id)
.join(Doctor, Doctor.id == DoctorAssignment.doctor_id)
.where(
DoctorAssignment.mr_user_id == mr_user_id,
DoctorAssignment.effective_to.is_(None),
Doctor.approval_status == MasterApproval.APPROVED,
)
)
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),
stmt = (
select(ChemistAssignment.chemist_id)
.join(Chemist, Chemist.id == ChemistAssignment.chemist_id)
.where(
ChemistAssignment.mr_user_id == mr_user_id,
ChemistAssignment.effective_to.is_(None),
Chemist.approval_status == MasterApproval.APPROVED,
)
)
return set((await self.db.execute(stmt)).scalars().all())
@@ -111,12 +177,21 @@ class DCRService:
# 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 is not in this report's headquarters"
if dcr.report_type == ReportType.SELF
else "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)})
# P1 — a planned visit has not happened yet, so it has no outcome.
is_plan = dcr.report_type == ReportType.PLAN
if not is_plan and payload.call_outcome is None:
raise ValidationError(
"call_outcome is required for a visit on a Daily Call Report (Done)",
{"doctor_id": str(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(
@@ -127,10 +202,11 @@ class DCRService:
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),
call_outcome=None if is_plan else payload.call_outcome,
conversion_status=None if is_plan else payload.conversion_status,
product_promote=payload.product_promote,
product_sample=payload.product_sample,
gift=None if is_plan else payload.gift,
remarks=payload.remarks,
)
@@ -139,7 +215,10 @@ class DCRService:
) -> ChemistCall:
if payload.chemist_id not in assigned:
raise ValidationError(
"Chemist is not assigned to this MR", {"chemist_id": str(payload.chemist_id)}
"Chemist is not in this report's headquarters"
if dcr.report_type == ReportType.SELF
else "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)})
@@ -158,30 +237,47 @@ class DCRService:
async def create(
self, data: DCRCreate, actor: User, ip: str | None = None
) -> DailyCallReport:
if actor.role != Role.MR or actor.headquarters_id is None:
if data.report_type == ReportType.SELF:
if actor.role != Role.AM:
raise ForbiddenError("Only an Area Manager files a Daily Call Report (Self)")
headquarters_id = await self._self_report_hq(actor, data.headquarters_id)
elif actor.role not in FIELD_ROLES:
raise ForbiddenError("Only an MR files a Daily Call Report (Plan) or (Done)")
elif actor.headquarters_id is None:
raise ValidationError("Only an MR with a headquarters can create a report")
else:
headquarters_id = actor.headquarters_id # snapshot (A1)
self._validate_report_date(data.report_date)
self._validate_report_date(data.report_date, data.report_type)
# 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):
if await self.repo.get_for_date(actor.id, data.report_date, data.report_type):
raise ConflictError(
"A report already exists for this date",
{"report_date": data.report_date.isoformat()},
f"A {_LABEL[data.report_type]} already exists for this date",
{
"report_date": data.report_date.isoformat(),
"report_type": data.report_type.value,
},
)
plan_id = None
if data.report_type == ReportType.ACTUAL:
plan_id = (await self._approved_plan(actor.id, data.report_date)).id
dcr = DailyCallReport(
id=uuid.uuid4(),
mr_user_id=actor.id,
headquarters_id=actor.headquarters_id, # snapshot (A1)
headquarters_id=headquarters_id,
report_date=data.report_date,
report_type=data.report_type,
plan_id=plan_id,
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)
doctor_ids = await self._allowed_doctor_ids(dcr)
chemist_ids = await self._allowed_chemist_ids(dcr)
seen_doctors: set[uuid.UUID] = set()
for payload in data.doctor_calls:
@@ -217,7 +313,8 @@ class DCRService:
except IntegrityError as exc:
await self.db.rollback()
raise ConflictError(
"A report already exists for this MR and date", {"cause": "uq_dcr_mr_date"}
"A report of this type already exists for this MR and date",
{"cause": "uq_dcr_mr_date_type"},
) from exc
return await self.repo.get_full(dcr.id)
@@ -247,7 +344,7 @@ class DCRService:
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)
assigned = await self._allowed_doctor_ids(dcr)
call = await self._build_doctor_call(dcr, payload, assigned)
self._validate_visit_time(dcr, payload.visit_time)
self.db.add(call)
@@ -264,6 +361,7 @@ class DCRService:
{"doctor_id": str(payload.doctor_id), "cause": "uq_call_dcr_doctor"},
) from exc
await self._drop_missed_note(dcr, doctor_id=payload.doctor_id)
await self.audit.log(
actor_user_id=actor.id,
entity_type=EntityType.DCR,
@@ -279,7 +377,7 @@ class DCRService:
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)
assigned = await self._allowed_chemist_ids(dcr)
call = await self._build_chemist_call(dcr, payload, assigned)
self._validate_visit_time(dcr, payload.visit_time)
self.db.add(call)
@@ -293,6 +391,7 @@ class DCRService:
{"chemist_id": str(payload.chemist_id), "cause": "uq_call_dcr_chemist"},
) from exc
await self._drop_missed_note(dcr, chemist_id=payload.chemist_id)
await self.audit.log(
actor_user_id=actor.id,
entity_type=EntityType.DCR,
@@ -305,8 +404,8 @@ class DCRService:
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():
"""V11 — a visit time on today's report cannot be in the future (P1: plans excepted)."""
if dcr.report_type != ReportType.PLAN and 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":
@@ -333,6 +432,79 @@ class DCRService:
await self.db.commit()
return await self.repo.get_full(dcr.id)
async def set_missed_reason(
self, dcr_id: uuid.UUID, payload: MissedVisitSet, actor: User, ip: str | None = None
) -> DailyCallReport:
"""P3 — record (or reword) why a planned doctor/chemist was not visited."""
dcr = await self._get_owned_editable(dcr_id, actor)
if dcr.report_type != ReportType.ACTUAL or dcr.plan is None:
raise ValidationError("Missed-visit notes belong on a Daily Call Report (Done)")
if (payload.doctor_id is None) == (payload.chemist_id is None):
raise ValidationError("Give exactly one of doctor_id or chemist_id")
reason = _clean(payload.reason)
if reason is None:
raise ValidationError("Say briefly why the visit was missed")
target_id = payload.doctor_id or payload.chemist_id
line = next((p for p in planned_visits(dcr) if p.target_id == target_id), None)
if line is None:
raise ValidationError(
"This doctor or chemist is not on the plan", {"target_id": str(target_id)}
)
if line.status == "VISITED":
raise ConflictError(
"A visit is already recorded for this doctor or chemist; remove it first",
{"target_id": str(target_id)},
)
note = next(
(m for m in dcr.missed_visits if (m.doctor_id or m.chemist_id) == target_id), None
)
before = {"reason": note.reason} if note else None
if note is None:
self.db.add(
MissedVisit(
dcr_id=dcr.id,
doctor_id=payload.doctor_id,
chemist_id=payload.chemist_id,
reason=reason,
)
)
else:
note.reason = reason
await self.audit.log(
actor_user_id=actor.id,
entity_type=EntityType.DCR,
entity_id=dcr.id,
action=AuditAction.UPDATE,
before=before,
after={"missed_visit": str(target_id), "reason": reason},
ip_address=ip,
)
await self.db.commit()
return await self.repo.get_full(dcr.id)
async def clear_missed_reason(
self, dcr_id: uuid.UUID, missed_id: uuid.UUID, actor: User, ip: str | None = None
) -> DailyCallReport:
dcr = await self._get_owned_editable(dcr_id, actor)
note = next((m for m in dcr.missed_visits if m.id == missed_id), None)
if note is None:
raise NotFoundError(
"Missed-visit note not found on this report", {"id": str(missed_id)}
)
await self.db.delete(note)
await self.audit.log(
actor_user_id=actor.id,
entity_type=EntityType.DCR,
entity_id=dcr.id,
action=AuditAction.DELETE,
before={"missed_visit": str(note.doctor_id or note.chemist_id), "reason": note.reason},
ip_address=ip,
)
await self.db.commit()
return await self.repo.get_full(dcr.id)
# ------------------------------------------------------------------
# Workflow transitions
# ------------------------------------------------------------------
@@ -344,19 +516,18 @@ class DCRService:
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
if dcr.mr_user_id != actor.id or actor.role not in _OWNER_ROLE[dcr.report_type]:
raise ForbiddenError("Only the report's owner can submit it")
raise ForbiddenError("Only the owning MR can submit this report")
if dcr.report_type == ReportType.SELF:
return await self._finalise_self_report(dcr, actor, ip)
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_submit_contents(dcr)
self._check_submission_deadline(dcr.report_date)
before = snapshot(dcr, _AUDIT_FIELDS)
@@ -378,6 +549,36 @@ class DCRService:
await self.db.commit()
return await self.repo.get_full(dcr.id)
async def _finalise_self_report(
self, dcr: DailyCallReport, actor: User, ip: str | None
) -> DailyCallReport:
"""S3 — an Area Manager's own report is final once submitted; nobody approves it."""
if dcr.status == DCRStatus.APPROVED:
return dcr # already submitted (a double click)
assert_editable(dcr.status)
self._check_submit_contents(dcr)
self._check_submission_deadline(dcr.report_date)
before = snapshot(dcr, _AUDIT_FIELDS)
dcr.status = DCRStatus.APPROVED
dcr.submitted_at = dcr.approved_at = utcnow()
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,
)
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)
async def return_report(
self, dcr_id: uuid.UUID, reason: str, actor: User, ip: str | None = None
) -> DailyCallReport:
@@ -447,16 +648,33 @@ class DCRService:
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:
async def _hq_scope(
self, actor: User, headquarters_id: uuid.UUID | None
) -> set[uuid.UUID] | None:
"""The headquarters a manager's lists cover: all they may see, or the one they chose —
narrowed, never widened (one outside their scope gives nothing)."""
allowed = await visible_hq_ids(self.db, actor)
if headquarters_id is None:
return allowed
return {headquarters_id} if allowed is None or headquarters_id in allowed else set()
async def list_for(
self, actor: User, headquarters_id: uuid.UUID | None = None, **filters
) -> list[DailyCallReport]:
# An Area Manager's SELF list is their own reports, not their headquarters'.
if actor.role in FIELD_ROLES or (
actor.role == Role.AM and filters.get("report_type") == ReportType.SELF
):
return await self.repo.list_scoped(mr_user_id=actor.id, **filters)
hq_ids = await visible_hq_ids(self.db, actor)
hq_ids = await self._hq_scope(actor, headquarters_id)
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:
async def counts_for(
self, actor: User, headquarters_id: uuid.UUID | None = None
) -> dict[str, int]:
if actor.role in FIELD_ROLES:
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))
return await self.repo.status_counts(hq_ids=await self._hq_scope(actor, headquarters_id))
# ------------------------------------------------------------------
# Internals
@@ -468,13 +686,22 @@ class DCRService:
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")
if dcr.mr_user_id != actor.id or actor.role not in _OWNER_ROLE[dcr.report_type]:
raise ForbiddenError("Only the report's owner can modify report data")
assert_editable(dcr.status)
return dcr
async def _self_report_hq(self, actor: User, headquarters_id: uuid.UUID | None) -> uuid.UUID:
"""S1 — one of the headquarters this Area Manager manages; implied when there is one."""
managed = await active_hq_ids_for_am(self.db, actor.id)
if headquarters_id is None and len(managed) == 1:
return next(iter(managed))
if headquarters_id is None:
raise ValidationError("Choose the headquarters this report is for")
if headquarters_id not in managed:
raise ForbiddenError("You do not manage this headquarters")
return headquarters_id
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:
@@ -482,11 +709,62 @@ class DCRService:
await assert_can_view_dcr(self.db, actor, dcr)
return dcr
def _check_submit_contents(self, dcr: DailyCallReport) -> None:
if dcr.report_type == ReportType.PLAN:
if not dcr.doctor_calls and not dcr.chemist_calls:
raise ValidationError("Plan at least one doctor or chemist visit to submit")
return
# P3 — every planned visit is either recorded or explained.
pending = [p for p in planned_visits(dcr) if p.status == "PENDING"]
if pending:
raise ValidationError(
"Record a visit or add a missed-visit note for every planned doctor and chemist",
{"pending": [p.name for p in pending]},
)
# V4 — at least one doctor call, unless the planned visits were all explained.
if not dcr.doctor_calls and not dcr.missed_visits:
raise ValidationError("A report must contain at least one doctor call to submit")
async def _approved_plan(self, mr_user_id: uuid.UUID, report_date: date) -> DailyCallReport:
"""P2 — the end-of-day report follows an Area-Manager-approved plan."""
plan = await self.repo.get_for_date(mr_user_id, report_date, ReportType.PLAN)
if plan is None:
raise ValidationError(
"Create your Daily Call Report (Plan) for this date first; "
"the Done report follows it",
{"report_date": report_date.isoformat()},
)
if plan.status != DCRStatus.APPROVED:
raise ValidationError(
"Your Daily Call Report (Plan) for this date must be approved "
"by the Area Manager first",
{"report_date": report_date.isoformat(), "plan_status": plan.status.value},
)
return plan
async def _drop_missed_note(
self,
dcr: DailyCallReport,
doctor_id: uuid.UUID | None = None,
chemist_id: uuid.UUID | None = None,
) -> None:
"""P4 — a recorded visit replaces any note saying it was missed."""
for note in dcr.missed_visits:
if (doctor_id and note.doctor_id == doctor_id) or (
chemist_id and note.chemist_id == chemist_id
):
await self.db.delete(note)
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),
# Recorded only; any Area Manager of the headquarters may act on the report.
stmt = (
select(AMHeadquarters.area_manager_user_id)
.where(
AMHeadquarters.headquarters_id == headquarters_id,
AMHeadquarters.effective_to.is_(None),
)
.order_by(AMHeadquarters.effective_from, AMHeadquarters.created_at)
)
return (await self.db.execute(stmt)).scalars().first()