feat(backend): T1.3 月报管理 CRUD — 列表/详情/创建/更新/提交/删除

- 路由：GET/POST/PUT/DELETE /api/v1/reports + POST /reports/{id}/submit - 状态机：draft → submitted → ai_parsed → reviewed - 防重复：同年同月同企业不可重复创建 - 租户隔离：通过 company 关联校验 - 测试：7 个月报测试（总计 33 tests passed）
2026-07-18 22:00:34 +08:00
parent 0bcaafd0eb
commit 263f474c90
5 changed files with 456 additions and 0 deletions
@@ -12,6 +12,7 @@ from fastapi.responses import JSONResponse

 from app.routers.auth import router as auth_router
 from app.routers.companies import router as companies_router
+from app.routers.reports import router as reports_router
 from app.schemas.common import error


@@ -69,3 +70,4 @@ async def health_check():

 app.include_router(auth_router, prefix="/api/v1")
 app.include_router(companies_router, prefix="/api/v1")
+app.include_router(reports_router, prefix="/api/v1")
@@ -0,0 +1,206 @@
+"""月报路由：CRUD + 提交 + AI 解析占位。"""
+
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.database import get_db
+from app.core.dependencies import get_current_user
+from app.models.company import Company
+from app.models.report import MonthlyReport
+from app.models.user import User
+from app.schemas.common import ApiResponse, success
+from app.schemas.report import (
+    MonthlyReportCreate,
+    MonthlyReportListResponse,
+    MonthlyReportResponse,
+    MonthlyReportUpdate,
+)
+
+router = APIRouter(prefix="/reports", tags=["reports"])
+
+
+async def _get_company_or_404(db: AsyncSession, company_id: str, tenant_id: str) -> Company:
+    """验证企业属于当前租户。"""
+    result = await db.execute(
+        select(Company).where(Company.id == company_id, Company.tenant_id == tenant_id)
+    )
+    company = result.scalar_one_or_none()
+    if not company:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="企业不存在")
+    return company
+
+
+@router.get("", response_model=ApiResponse[MonthlyReportListResponse])
+async def list_reports(
+    company_id: str | None = Query(default=None, description="按企业筛选"),
+    page: int = Query(default=1, ge=1),
+    page_size: int = Query(default=20, ge=1, le=100),
+    db: AsyncSession = Depends(get_db),
+    user: User = Depends(get_current_user),
+):
+    """获取月报列表。"""
+    # 获取当前租户的企业 ID 集合
+    company_query = select(Company.id).where(Company.tenant_id == user.tenant_id)
+    if company_id:
+        company_query = company_query.where(Company.id == company_id)
+
+    query = select(MonthlyReport).where(
+        MonthlyReport.company_id.in_(company_query)
+    )
+
+    count_query = select(func.count()).select_from(query.subquery())
+    total_result = await db.execute(count_query)
+    total = total_result.scalar_one()
+
+    offset = (page - 1) * page_size
+    query = query.order_by(MonthlyReport.created_at.desc()).offset(offset).limit(page_size)
+    result = await db.execute(query)
+    reports = result.scalars().all()
+
+    return success(
+        data=MonthlyReportListResponse(
+            items=[MonthlyReportResponse.model_validate(r, from_attributes=True) for r in reports],
+            total=total,
+            page=page,
+            page_size=page_size,
+        )
+    )
+
+
+@router.get("/{report_id}", response_model=ApiResponse[MonthlyReportResponse])
+async def get_report(
+    report_id: str,
+    db: AsyncSession = Depends(get_db),
+    user: User = Depends(get_current_user),
+):
+    """获取月报详情。"""
+    result = await db.execute(
+        select(MonthlyReport)
+        .join(Company, MonthlyReport.company_id == Company.id)
+        .where(MonthlyReport.id == report_id, Company.tenant_id == user.tenant_id)
+    )
+    report = result.scalar_one_or_none()
+    if not report:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="月报不存在")
+    return success(data=MonthlyReportResponse.model_validate(report, from_attributes=True))
+
+
+@router.post("", response_model=ApiResponse[MonthlyReportResponse], status_code=status.HTTP_201_CREATED)
+async def create_report(
+    req: MonthlyReportCreate,
+    db: AsyncSession = Depends(get_db),
+    user: User = Depends(get_current_user),
+):
+    """创建月报。"""
+    await _get_company_or_404(db, req.company_id, user.tenant_id)
+
+    # 检查同企业同年月是否已有月报
+    existing = await db.execute(
+        select(MonthlyReport).where(
+            MonthlyReport.company_id == req.company_id,
+            MonthlyReport.period_year == req.period_year,
+            MonthlyReport.period_month == req.period_month,
+        )
+    )
+    if existing.scalar_one_or_none():
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"{req.period_year}年{req.period_month}月月报已存在",
+        )
+
+    report = MonthlyReport(
+        company_id=req.company_id,
+        period_year=req.period_year,
+        period_month=req.period_month,
+        raw_content=req.raw_content,
+        status="draft",
+    )
+    db.add(report)
+    await db.flush()
+    return success(
+        data=MonthlyReportResponse.model_validate(report, from_attributes=True),
+        message="创建成功",
+    )
+
+
+@router.put("/{report_id}", response_model=ApiResponse[MonthlyReportResponse])
+async def update_report(
+    report_id: str,
+    req: MonthlyReportUpdate,
+    db: AsyncSession = Depends(get_db),
+    user: User = Depends(get_current_user),
+):
+    """更新月报。"""
+    result = await db.execute(
+        select(MonthlyReport)
+        .join(Company, MonthlyReport.company_id == Company.id)
+        .where(MonthlyReport.id == report_id, Company.tenant_id == user.tenant_id)
+    )
+    report = result.scalar_one_or_none()
+    if not report:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="月报不存在")
+
+    update_data = req.model_dump(exclude_unset=True)
+    for key, value in update_data.items():
+        setattr(report, key, value)
+
+    await db.flush()
+    return success(
+        data=MonthlyReportResponse.model_validate(report, from_attributes=True),
+        message="更新成功",
+    )
+
+
+@router.post("/{report_id}/submit", response_model=ApiResponse[MonthlyReportResponse])
+async def submit_report(
+    report_id: str,
+    db: AsyncSession = Depends(get_db),
+    user: User = Depends(get_current_user),
+):
+    """提交月报（状态从 draft → submitted）。"""
+    result = await db.execute(
+        select(MonthlyReport)
+        .join(Company, MonthlyReport.company_id == Company.id)
+        .where(MonthlyReport.id == report_id, Company.tenant_id == user.tenant_id)
+    )
+    report = result.scalar_one_or_none()
+    if not report:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="月报不存在")
+
+    if report.status != "draft":
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"当前状态为 {report.status}，无法提交",
+        )
+
+    report.status = "submitted"
+    report.submitted_by = user.id
+    report.submitted_at = datetime.now(timezone.utc)
+    await db.flush()
+    return success(
+        data=MonthlyReportResponse.model_validate(report, from_attributes=True),
+        message="提交成功",
+    )
+
+
+@router.delete("/{report_id}", response_model=ApiResponse[None])
+async def delete_report(
+    report_id: str,
+    db: AsyncSession = Depends(get_db),
+    user: User = Depends(get_current_user),
+):
+    """删除月报。"""
+    result = await db.execute(
+        select(MonthlyReport)
+        .join(Company, MonthlyReport.company_id == Company.id)
+        .where(MonthlyReport.id == report_id, Company.tenant_id == user.tenant_id)
+    )
+    report = result.scalar_one_or_none()
+    if not report:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="月报不存在")
+
+    await db.delete(report)
+    return success(message="删除成功")
@@ -0,0 +1,52 @@
+"""月报相关 Pydantic schema。"""
+
+from datetime import datetime
+from pydantic import BaseModel, Field
+
+
+class MonthlyReportCreate(BaseModel):
+    """创建月报请求。"""
+
+    company_id: str
+    period_year: int = Field(..., ge=2020, le=2100)
+    period_month: int = Field(..., ge=1, le=12)
+    raw_content: str | None = None
+
+
+class MonthlyReportUpdate(BaseModel):
+    """更新月报请求。"""
+
+    raw_content: str | None = None
+    status: str | None = Field(default=None, description="draft/submitted/ai_parsed/reviewed")
+    structured_data: dict | None = None
+    ai_summary: str | None = None
+    ai_concerns: dict | None = None
+
+
+class MonthlyReportResponse(BaseModel):
+    """月报信息响应。"""
+
+    id: str
+    company_id: str
+    period_year: int
+    period_month: int
+    status: str
+    raw_content: str | None = None
+    structured_data: dict | None = None
+    ai_summary: str | None = None
+    ai_concerns: dict | None = None
+    submitted_by: str | None = None
+    submitted_at: datetime | None = None
+    reviewed_by: str | None = None
+    reviewed_at: datetime | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class MonthlyReportListResponse(BaseModel):
+    """月报列表响应。"""
+
+    items: list[MonthlyReportResponse]
+    total: int
+    page: int
+    page_size: int