Step 6：受试者（Subject）+ 访视（Visit）+ 随访进度

backend/app/api/v1/subjects.py

@@ -0,0 +1,102 @@
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.deps import get_current_user, get_db_session, require_study_member, require_study_roles
+from app.crud import audit as audit_crud
+from app.crud import subject as subject_crud
+from app.crud import study as study_crud
+from app.schemas.subject import SubjectCreate, SubjectRead, SubjectUpdate
+
+router = APIRouter()
+
+
+async def _ensure_study_exists(db: AsyncSession, study_id: uuid.UUID):
+    study = await study_crud.get(db, study_id)
+    if not study:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Study not found")
+    return study
+
+
+@router.post(
+    "/",
+    response_model=SubjectRead,
+    status_code=status.HTTP_201_CREATED,
+    dependencies=[Depends(require_study_roles(["PM", "CRA"]))],
+)
+async def create_subject(
+    study_id: uuid.UUID,
+    subject_in: SubjectCreate,
+    db: AsyncSession = Depends(get_db_session),
+    current_user=Depends(get_current_user),
+) -> SubjectRead:
+    await _ensure_study_exists(db, study_id)
+    try:
+        subject = await subject_crud.create_subject(db, study_id, subject_in)
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+    await audit_crud.log_action(
+        db,
+        study_id=study_id,
+        entity_type="subject",
+        entity_id=subject.id,
+        action="CREATE_SUBJECT",
+        detail=f"Subject {subject.subject_no} created",
+        operator_id=current_user.id,
+        operator_role=current_user.role,
+    )
+    return subject
+
+
+@router.get(
+    "/",
+    response_model=list[SubjectRead],
+    dependencies=[Depends(require_study_member())],
+)
+async def list_subjects(
+    study_id: uuid.UUID,
+    site_id: uuid.UUID | None = None,
+    status_filter: str | None = None,
+    db: AsyncSession = Depends(get_db_session),
+) -> list[SubjectRead]:
+    await _ensure_study_exists(db, study_id)
+    subjects = await subject_crud.list_subjects(db, study_id, site_id=site_id, status=status_filter)
+    return list(subjects)
+
+
+@router.patch(
+    "/{subject_id}",
+    response_model=SubjectRead,
+    dependencies=[Depends(require_study_roles(["PM", "CRA"]))],
+)
+async def update_subject(
+    study_id: uuid.UUID,
+    subject_id: uuid.UUID,
+    subject_in: SubjectUpdate,
+    db: AsyncSession = Depends(get_db_session),
+    current_user=Depends(get_current_user),
+) -> SubjectRead:
+    await _ensure_study_exists(db, study_id)
+    subject = await subject_crud.get_subject(db, subject_id)
+    if not subject or subject.study_id != study_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Subject not found")
+    old_status = subject.status
+    updated = await subject_crud.update_subject(db, subject, subject_in)
+    # auto-generate visits when enrolled
+    if subject_in.status and subject_in.status == "ENROLLED" and (subject_in.enrollment_date or updated.enrollment_date):
+        await subject_crud.generate_default_visits(db, updated)
+    detail = None
+    if subject_in.status and subject_in.status != old_status:
+        detail = f"subject {updated.subject_no} status {old_status} -> {subject_in.status}"
+    await audit_crud.log_action(
+        db,
+        study_id=study_id,
+        entity_type="subject",
+        entity_id=subject_id,
+        action="SUBJECT_STATUS_CHANGE" if detail else "UPDATE_SUBJECT",
+        detail=detail or "Subject updated",
+        operator_id=current_user.id,
+        operator_role=current_user.role,
+    )
+    return updated