项目概览、参与者管理初步优化（未接入真实数据）

backend/alembic.ini

@@ -0,0 +1,36 @@
+[alembic]
+script_location = alembic
+
+sqlalchemy.url = postgresql+asyncpg://postgres:postgres@db:5432/ctms
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s

backend/alembic/env.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import pool
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from app.core.config import settings
+from app.db.base import Base
+
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def _get_database_url() -> str:
+    url = os.getenv("DATABASE_URL", settings.DATABASE_URL)
+    if url and url.startswith("postgresql+asyncpg://"):
+        return url
+    return url
+
+
+def run_migrations_offline() -> None:
+    url = _get_database_url()
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection) -> None:
+    context.configure(connection=connection, target_metadata=target_metadata)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_migrations_online() -> None:
+    configuration = config.get_section(config.config_ini_section, {})
+    configuration["sqlalchemy.url"] = _get_database_url()
+
+    connectable = async_engine_from_config(
+        configuration,
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    asyncio.run(run_migrations_online())

backend/alembic/versions/20240501_000003_drop_visit_name_from_visits.py

@@ -0,0 +1,22 @@
+"""drop visit_name from visits"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision = "20240501_000003"
+down_revision = "20240501_000002"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.drop_column("visits", "visit_name")
+
+
+def downgrade() -> None:
+    op.add_column(
+        "visits",
+        sa.Column("visit_name", sa.String(length=200), nullable=False, server_default=""),
+    )

backend/alembic/versions/20240501_000004_add_visit_template_to_studies.py

@@ -0,0 +1,25 @@
+"""add visit template fields to studies"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision = "20240501_000004"
+down_revision = "20240501_000003"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("studies", sa.Column("visit_interval_days", sa.Integer(), nullable=True))
+    op.add_column("studies", sa.Column("visit_total", sa.Integer(), nullable=True))
+    op.add_column("studies", sa.Column("visit_window_start_offset", sa.Integer(), nullable=True))
+    op.add_column("studies", sa.Column("visit_window_end_offset", sa.Integer(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("studies", "visit_window_end_offset")
+    op.drop_column("studies", "visit_window_start_offset")
+    op.drop_column("studies", "visit_total")
+    op.drop_column("studies", "visit_interval_days")

backend/alembic/versions/20240501_000005_add_consent_date_to_subjects.py

@@ -0,0 +1,19 @@
+"""add consent_date to subjects"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision = "20240501_000005"
+down_revision = "20240501_000004"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("subjects", sa.Column("consent_date", sa.Date(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("subjects", "consent_date")

backend/app/api/v1/subject_histories.py

@@ -34,7 +34,7 @@ async def create_history(
 ) -> SubjectHistoryRead:
     await _ensure_study_exists(db, study_id)
     if history_in.subject_id != subject_id:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="受试者不匹配")
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="参与者不匹配")
     history = await history_crud.create_history(db, study_id, history_in, created_by=current_user.id)
     await audit_crud.log_action(
         db,

backend/app/api/v1/subjects.py

@@ -42,7 +42,7 @@ async def create_subject(
         entity_type="subject",
         entity_id=subject.id,
         action="CREATE_SUBJECT",
-        detail=f"受试者 {subject.subject_no} 已创建",
+        detail=f"参与者 {subject.subject_no} 已创建",
         operator_id=current_user.id,
         operator_role=current_user.role,
     )
@@ -81,7 +81,7 @@ async def get_subject(
     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="受试者不存在")
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="参与者不存在")
     return subject
 
 
@@ -100,7 +100,7 @@ async def update_subject(
     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="受试者不存在")
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="参与者不存在")
     old_status = subject.status
     updated = await subject_crud.update_subject(db, subject, subject_in)
     # auto-generate visits when enrolled
@@ -108,14 +108,14 @@ async def update_subject(
         await subject_crud.generate_default_visits(db, updated)
     detail = None
     if subject_in.status and subject_in.status != old_status:
-        detail = f"受试者 {updated.subject_no} 状态 {old_status} -> {subject_in.status}"
+        detail = f"参与者 {updated.subject_no} 状态 {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 "受试者已更新",
+        detail=detail or "参与者已更新",
         operator_id=current_user.id,
         operator_role=current_user.role,
     )
@@ -136,7 +136,7 @@ async def delete_subject(
     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="受试者不存在")
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="参与者不存在")
     await subject_crud.delete_subject(db, subject)
     await audit_crud.log_action(
         db,
@@ -144,7 +144,7 @@ async def delete_subject(
         entity_type="subject",
         entity_id=subject_id,
         action="DELETE_SUBJECT",
-        detail=f"受试者 {subject_id} 已删除",
+        detail=f"参与者 {subject_id} 已删除",
         operator_id=current_user.id,
         operator_role=current_user.role,
     )

backend/app/api/v1/visits.py

@@ -6,6 +6,7 @@ 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.crud import visit as visit_crud
 from app.schemas.visit import VisitCreate, VisitRead, VisitUpdate
 
@@ -15,7 +16,7 @@ router = APIRouter()
 async def _ensure_subject(db: AsyncSession, study_id: uuid.UUID, subject_id: uuid.UUID):
     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="受试者不存在")
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="参与者不存在")
     return subject
 
 
@@ -49,16 +50,28 @@ async def create_visit(
 ) -> VisitRead:
     subject = await _ensure_subject(db, study_id, subject_id)
     if visit_in.subject_id != subject_id:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="受试者不匹配")
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="参与者不匹配")
     visit = await visit_crud.create_visit(
         db,
         study_id=study_id,
         visit_in=visit_in,
         subject=subject,
         visit_code=visit_in.visit_code,
-        visit_name=visit_in.visit_name,
         planned_date=visit_in.planned_date,
     )
+    if visit_in.visit_code == "V1" and visit_in.planned_date:
+        study = await study_crud.get(db, study_id)
+        if study:
+            await visit_crud.create_followup_visits(
+                db,
+                study_id=study_id,
+                subject=subject,
+                base_date=visit_in.planned_date,
+                visit_total=study.visit_total,
+                visit_interval_days=study.visit_interval_days,
+                window_start_offset=study.visit_window_start_offset,
+                window_end_offset=study.visit_window_end_offset,
+            )
     await audit_crud.log_action(
         db,
         study_id=study_id,

backend/app/crud/ae.py

@@ -28,7 +28,7 @@ async def _validate_site_subject(db: AsyncSession, study_id: uuid.UUID, site_id:
         result = await db.execute(select(Subject).where(Subject.id == subject_id))
         subj = result.scalar_one_or_none()
         if not subj or subj.study_id != study_id:
-            raise ValueError("受试者不属于当前项目")
+            raise ValueError("参与者不属于当前项目")
 
 
 async def create_ae(

backend/app/crud/study.py

@@ -16,6 +16,10 @@ async def create(db: AsyncSession, study_in: StudyCreate, *, created_by: uuid.UU
         protocol_no=study_in.protocol_no,
         phase=study_in.phase,
         status=study_in.status,
+        visit_interval_days=study_in.visit_interval_days,
+        visit_total=study_in.visit_total,
+        visit_window_start_offset=study_in.visit_window_start_offset,
+        visit_window_end_offset=study_in.visit_window_end_offset,
         created_by=created_by,
     )
     db.add(study)

backend/app/crud/subject.py

@@ -6,6 +6,8 @@ from sqlalchemy import select, update as sa_update
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.crud import visit as visit_crud
+from app.models.study import Study
+from app.models.visit import Visit
 from app.models.site import Site
 from app.models.subject import Subject
 from app.schemas.subject import SubjectCreate, SubjectUpdate
@@ -26,6 +28,7 @@ async def create_subject(db: AsyncSession, study_id: uuid.UUID, subject_in: Subj
         subject_no=subject_in.subject_no,
         status="SCREENING",
         screening_date=subject_in.screening_date,
+        consent_date=subject_in.consent_date,
         enrollment_date=None,
         completion_date=None,
         drop_reason=None,
@@ -41,7 +44,6 @@ async def create_subject(db: AsyncSession, study_id: uuid.UUID, subject_in: Subj
         visit_in=None,
         subject=subject,
         visit_code="V0",
-        visit_name="Screening",
         planned_date=subject.screening_date,
     )
     return subject
@@ -74,25 +76,44 @@ async def generate_default_visits(db: AsyncSession, subject: Subject) -> None:
     # Baseline + Follow-up visits based on enrollment_date
     if not subject.enrollment_date:
         return
+    result = await db.execute(select(Study).where(Study.id == subject.study_id))
+    study = result.scalar_one_or_none()
+    if not study:
+        return
+
+    visit_total = study.visit_total or 3
+    visit_interval_days = study.visit_interval_days or 30
+    window_start_offset = study.visit_window_start_offset
+    window_end_offset = study.visit_window_end_offset
     baseline_date = subject.enrollment_date
-    follow1 = baseline_date + timedelta(days=30)
-    follow2 = baseline_date + timedelta(days=60)
-    visits_data = [
-        ("V1", "Baseline", baseline_date),
-        ("FU1", "Follow-up 1", follow1),
-        ("FU2", "Follow-up 2", follow2),
-    ]
-    for code, name, plan_date in visits_data:
+
+    result = await db.execute(select(Visit.visit_code).where(Visit.subject_id == subject.id))
+    existing_codes = {row[0] for row in result.all()}
+    if "V1" not in existing_codes:
+        window_start = baseline_date + timedelta(days=window_start_offset) if window_start_offset is not None else None
+        window_end = baseline_date + timedelta(days=window_end_offset) if window_end_offset is not None else None
         await visit_crud.create_visit(
             db,
             study_id=subject.study_id,
             visit_in=None,
             subject=subject,
-            visit_code=code,
-            visit_name=name,
-            planned_date=plan_date,
+            visit_code="V1",
+            planned_date=baseline_date,
+            window_start=window_start,
+            window_end=window_end,
         )
 
+    await visit_crud.create_followup_visits(
+        db,
+        study_id=subject.study_id,
+        subject=subject,
+        base_date=baseline_date,
+        visit_total=visit_total,
+        visit_interval_days=visit_interval_days,
+        window_start_offset=window_start_offset,
+        window_end_offset=window_end_offset,
+    )
+
 
 async def update_subject(db: AsyncSession, subject: Subject, subject_in: SubjectUpdate) -> Subject:
     update_data = subject_in.model_dump(exclude_unset=True)

backend/app/crud/subject_history.py

@@ -13,7 +13,7 @@ async def _ensure_subject(db: AsyncSession, study_id: uuid.UUID, subject_id: uui
     result = await db.execute(select(Subject).where(Subject.id == subject_id))
     subject = result.scalar_one_or_none()
     if not subject or subject.study_id != study_id:
-        raise ValueError("受试者不属于当前项目")
+        raise ValueError("参与者不属于当前项目")
 
 
 async def create_history(

backend/app/crud/visit.py

@@ -1,4 +1,5 @@
 import uuid
+from datetime import date, timedelta
 from typing import Sequence
 
 from sqlalchemy import select, update as sa_update
@@ -16,19 +17,19 @@ async def create_visit(
     visit_in: VisitCreate | None,
     subject: Subject,
     visit_code: str,
-    visit_name: str,
     planned_date,
+    window_start: date | None = None,
+    window_end: date | None = None,
 ) -> Visit:
     visit = Visit(
         study_id=study_id,
         subject_id=subject.id,
         visit_code=visit_code,
-        visit_name=visit_name,
         planned_date=planned_date,
         actual_date=None,
         status="PLANNED",
-        window_start=visit_in.window_start if visit_in else None,
-        window_end=visit_in.window_end if visit_in else None,
+        window_start=window_start if window_start is not None else (visit_in.window_start if visit_in else None),
+        window_end=window_end if window_end is not None else (visit_in.window_end if visit_in else None),
         notes=None,
     )
     db.add(visit)
@@ -49,6 +50,12 @@ async def get_visit(db: AsyncSession, visit_id: uuid.UUID) -> Visit | None:
 
 async def update_visit(db: AsyncSession, visit: Visit, visit_in: VisitUpdate) -> Visit:
     update_data = visit_in.model_dump(exclude_unset=True)
+    if "actual_date" in update_data and update_data["actual_date"] is not None and "status" not in update_data:
+        actual_date = update_data["actual_date"]
+        if (visit.window_start and actual_date < visit.window_start) or (visit.window_end and actual_date > visit.window_end):
+            update_data["status"] = "OVERDUE"
+        else:
+            update_data["status"] = "DONE"
     if update_data:
         await db.execute(
             sa_update(Visit)
@@ -63,3 +70,44 @@ async def update_visit(db: AsyncSession, visit: Visit, visit_in: VisitUpdate) ->
 async def delete_visit(db: AsyncSession, visit: Visit) -> None:
     await db.delete(visit)
     await db.commit()
+
+
+async def create_followup_visits(
+    db: AsyncSession,
+    *,
+    study_id: uuid.UUID,
+    subject: Subject,
+    base_date: date,
+    visit_total: int | None,
+    visit_interval_days: int | None,
+    window_start_offset: int | None,
+    window_end_offset: int | None,
+) -> Sequence[Visit]:
+    if not visit_total or not visit_interval_days or visit_total < 2:
+        return []
+
+    result = await db.execute(select(Visit.visit_code).where(Visit.subject_id == subject.id))
+    existing_codes = {row[0] for row in result.all()}
+    created: list[Visit] = []
+    for index in range(2, visit_total + 1):
+        code = f"V{index}"
+        if code in existing_codes:
+            continue
+        planned_date = base_date + timedelta(days=visit_interval_days * (index - 1))
+        window_start = (
+            planned_date + timedelta(days=window_start_offset) if window_start_offset is not None else None
+        )
+        window_end = planned_date + timedelta(days=window_end_offset) if window_end_offset is not None else None
+        created.append(
+            await create_visit(
+                db,
+                study_id=study_id,
+                visit_in=None,
+                subject=subject,
+                visit_code=code,
+                planned_date=planned_date,
+                window_start=window_start,
+                window_end=window_end,
+            )
+        )
+    return created

backend/app/main.py

@@ -75,7 +75,7 @@ def create_app() -> FastAPI:
             {"name": "attachments", "description": "通用附件"},
             {"name": "audit-logs", "description": "审计日志"},
             {"name": "dashboard", "description": "项目总览与统计"},
-            {"name": "subjects", "description": "受试者"},
+            {"name": "subjects", "description": "参与者"},
             {"name": "visits", "description": "访视"},
             {"name": "aes", "description": "不良事件"},
             {"name": "finance", "description": "费用管理"},

backend/app/models/study.py

@@ -1,7 +1,7 @@
 import uuid
 from datetime import datetime
 
-from sqlalchemy import DateTime, ForeignKey, String, func
+from sqlalchemy import DateTime, ForeignKey, Integer, String, func
 from sqlalchemy.dialects.postgresql import UUID
 from sqlalchemy.orm import Mapped, mapped_column
 
@@ -18,5 +18,9 @@ class Study(Base):
     protocol_no: Mapped[str | None] = mapped_column(String(100), nullable=True)
     phase: Mapped[str | None] = mapped_column(String(50), nullable=True)
     status: Mapped[str] = mapped_column(String(20), nullable=False, default="DRAFT")
+    visit_interval_days: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    visit_total: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    visit_window_start_offset: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    visit_window_end_offset: Mapped[int | None] = mapped_column(Integer, nullable=True)
     created_by: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, server_default=func.now())

backend/app/models/subject.py

@@ -18,6 +18,7 @@ class Subject(Base):
     subject_no: Mapped[str] = mapped_column(String(50), nullable=False)
     status: Mapped[str] = mapped_column(String(20), nullable=False, default="SCREENING")
     screening_date: Mapped[date | None] = mapped_column(Date, nullable=True)
+    consent_date: Mapped[date | None] = mapped_column(Date, nullable=True)
     enrollment_date: Mapped[date | None] = mapped_column(Date, nullable=True)
     completion_date: Mapped[date | None] = mapped_column(Date, nullable=True)
     drop_reason: Mapped[str | None] = mapped_column(Text, nullable=True)

backend/app/models/visit.py

@@ -15,7 +15,6 @@ class Visit(Base):
     study_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("studies.id"), nullable=False)
     subject_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("subjects.id"), index=True, nullable=False)
     visit_code: Mapped[str] = mapped_column(String(50), nullable=False)
-    visit_name: Mapped[str] = mapped_column(String(200), nullable=False)
     planned_date: Mapped[date | None] = mapped_column(Date, nullable=True)
     actual_date: Mapped[date | None] = mapped_column(Date, nullable=True)
     status: Mapped[str] = mapped_column(String(20), nullable=False, default="PLANNED")

backend/app/schemas/study.py

@@ -14,6 +14,10 @@ class StudyCreate(BaseModel):
     protocol_no: Optional[str] = None
     phase: Optional[str] = None
     status: StudyStatus = "DRAFT"
+    visit_interval_days: Optional[int] = None
+    visit_total: Optional[int] = None
+    visit_window_start_offset: Optional[int] = None
+    visit_window_end_offset: Optional[int] = None
 
 
 class StudyUpdate(BaseModel):
@@ -23,6 +27,10 @@ class StudyUpdate(BaseModel):
     protocol_no: Optional[str] = None
     phase: Optional[str] = None
     status: Optional[StudyStatus] = None
+    visit_interval_days: Optional[int] = None
+    visit_total: Optional[int] = None
+    visit_window_start_offset: Optional[int] = None
+    visit_window_end_offset: Optional[int] = None
 
 
 class StudyRead(BaseModel):
@@ -33,6 +41,10 @@ class StudyRead(BaseModel):
     protocol_no: Optional[str]
     phase: Optional[str]
     status: StudyStatus
+    visit_interval_days: Optional[int]
+    visit_total: Optional[int]
+    visit_window_start_offset: Optional[int]
+    visit_window_end_offset: Optional[int]
     created_by: Optional[uuid.UUID]
     created_at: datetime
 

backend/app/schemas/subject.py

@@ -9,10 +9,12 @@ class SubjectCreate(BaseModel):
     site_id: uuid.UUID
     subject_no: str
     screening_date: Optional[date] = None
+    consent_date: Optional[date] = None
 
 
 class SubjectUpdate(BaseModel):
     status: Optional[str] = None
+    consent_date: Optional[date] = None
     enrollment_date: Optional[date] = None
     completion_date: Optional[date] = None
     drop_reason: Optional[str] = None
@@ -25,6 +27,7 @@ class SubjectRead(BaseModel):
     subject_no: str
     status: str
     screening_date: Optional[date]
+    consent_date: Optional[date]
     enrollment_date: Optional[date]
     completion_date: Optional[date]
     drop_reason: Optional[str]

backend/app/schemas/visit.py

@@ -8,7 +8,6 @@ from pydantic import BaseModel, ConfigDict
 class VisitCreate(BaseModel):
     subject_id: uuid.UUID
     visit_code: str
-    visit_name: str
     planned_date: Optional[date] = None
     window_start: Optional[date] = None
     window_end: Optional[date] = None
@@ -25,7 +24,6 @@ class VisitRead(BaseModel):
     study_id: uuid.UUID
     subject_id: uuid.UUID
     visit_code: str
-    visit_name: str
     planned_date: Optional[date]
     actual_date: Optional[date]
     status: str

backend/requirements.txt

@@ -2,6 +2,7 @@ fastapi==0.104.1
 uvicorn[standard]==0.24.0.post1
 sqlalchemy==2.0.23
 asyncpg==0.29.0
+alembic==1.13.1
 pydantic-settings==2.1.0
 python-jose[cryptography]==3.3.0
 passlib[bcrypt]==1.7.4