493 lines
20 KiB
Python
493 lines
20 KiB
Python
"""Generic CRUD router factory.
|
||
|
||
Every resource in the system shares the same list/detail/create/update/delete
|
||
contract, so it is described once here and parameterised by the callers. That
|
||
keeps ~30 resources consistent (filtering, paging, sorting, keyword search,
|
||
permission checks and audit-friendly messages) with a handful of hooks.
|
||
"""
|
||
|
||
# NOTE: 不要启用 ``from __future__ import annotations`` —— 本模块的动态端点依赖
|
||
# 闭包变量(spec/model)参与注解求值,延迟注解会让 FastAPI 无法解析 ForwardRef。
|
||
from collections.abc import Awaitable, Callable
|
||
from datetime import date, datetime, time, timedelta
|
||
from typing import Annotated, Any, TypeVar
|
||
|
||
from fastapi import APIRouter, Body, Depends, Query
|
||
from pydantic import BaseModel, create_model
|
||
from sqlalchemy import Select, func, or_, select
|
||
from sqlalchemy.types import Boolean, Date, DateTime, Float, Integer, Numeric, String
|
||
|
||
from ..core.deps import AuthContext, AuthCtx, Session, require_perm
|
||
from ..core.errors import AppError
|
||
from ..core.pagination import Page, like
|
||
|
||
CreateT = TypeVar("CreateT", bound=BaseModel)
|
||
|
||
|
||
def _py_type(column) -> type:
|
||
t = column.type
|
||
if isinstance(t, DateTime):
|
||
return datetime
|
||
if isinstance(t, Date):
|
||
return date
|
||
if isinstance(t, Boolean):
|
||
return bool
|
||
if isinstance(t, (Integer,)):
|
||
return int
|
||
if isinstance(t, (Numeric, Float)):
|
||
return float
|
||
return str
|
||
|
||
|
||
def _coerce(py: type, token: str):
|
||
"""Convert one raw query token to the column python type; ``None`` = 无效值。"""
|
||
try:
|
||
if py is int:
|
||
return int(token)
|
||
if py is float:
|
||
return float(token)
|
||
if py is bool:
|
||
return token.lower() in ("1", "true", "yes", "on")
|
||
if py is date:
|
||
return date.fromisoformat(token[:10])
|
||
if py is datetime:
|
||
return datetime.fromisoformat(token)
|
||
except (ValueError, TypeError):
|
||
return None
|
||
return token
|
||
|
||
|
||
def _split_multi(raw: Any) -> list[str]:
|
||
return [t.strip() for t in str(raw).split(",") if t.strip()]
|
||
|
||
|
||
def _multi_values(values: list):
|
||
"""单个命中值时退化为标量,便于与旧的等值语义保持兼容。"""
|
||
return values[0] if len(values) == 1 else values
|
||
|
||
|
||
def _multi_cond(column, values):
|
||
"""单值走等值、多值走 IN,供表头多选筛选复用。"""
|
||
if len(values) == 1:
|
||
return column == values[0]
|
||
return column.in_(values)
|
||
|
||
|
||
def _make_query_dependency(model, fields: tuple[str, ...]):
|
||
"""Build a FastAPI dependency returning a dict of active equality filters."""
|
||
if not fields:
|
||
|
||
async def _none() -> dict[str, Any]:
|
||
return {}
|
||
|
||
return _none
|
||
|
||
cols = {name: model.__table__.columns[name] for name in fields}
|
||
pytypes = {name: _py_type(col) for name, col in cols.items()}
|
||
|
||
async def _dep(**kwargs: Any) -> dict[str, Any]:
|
||
"""每个筛选字段都接受「逗号分隔多值」:单值 -> 标量,多值 -> list。"""
|
||
out: dict[str, Any] = {}
|
||
for key, raw in kwargs.items():
|
||
if raw is None:
|
||
continue
|
||
values = []
|
||
for token in _split_multi(raw):
|
||
value = _coerce(pytypes[key], token)
|
||
if value is not None:
|
||
values.append(value)
|
||
if values:
|
||
out[key] = _multi_values(values)
|
||
return out
|
||
|
||
import inspect
|
||
|
||
params = [
|
||
inspect.Parameter(
|
||
name,
|
||
inspect.Parameter.KEYWORD_ONLY,
|
||
annotation=str | None,
|
||
default=Query(None, description=f"按{col.name}过滤,多个值用英文逗号分隔"),
|
||
)
|
||
for name, col in cols.items()
|
||
]
|
||
_dep.__signature__ = inspect.Signature(parameters=params, return_annotation=dict[str, Any])
|
||
return _dep
|
||
|
||
|
||
class CrudSpec:
|
||
"""Declarative description of one resource's REST surface."""
|
||
|
||
def __init__(
|
||
self,
|
||
*,
|
||
model: type,
|
||
create: type[BaseModel],
|
||
update: type[BaseModel],
|
||
read: type[BaseModel],
|
||
module: str,
|
||
resource: str,
|
||
label: str,
|
||
prefix: str,
|
||
tag: str,
|
||
search_fields: tuple[str, ...] = (),
|
||
filters: tuple[str, ...] = (),
|
||
date_range_fields: tuple[str, ...] = (),
|
||
in_fields: tuple[str, ...] = (),
|
||
extra_query: tuple[str, ...] = (),
|
||
filter_hook: Callable[[Select, dict, Session], Awaitable[Select]] | None = None,
|
||
dept_scope: str | None = "auto", # auto | self | employee | None
|
||
order_by: str = "id",
|
||
order: str = "desc",
|
||
label_field: str = "name",
|
||
write: bool = True,
|
||
deletable: bool = True,
|
||
options: bool = True,
|
||
employee_scope: str | None = None, # column name holding employee_id
|
||
list_hook: Callable[[Select, Any, Session], Awaitable[Select]] | None = None,
|
||
before_write: Callable[[str, dict, Any, Any, Session], Awaitable[dict]] | None = None,
|
||
after_read: Callable[[Session, list[Any]], Awaitable[None]] | None = None,
|
||
after_write: Callable[[str, Any, Any, Session], Awaitable[None]] | None = None,
|
||
on_delete: Callable[[Any, Any, Session], Awaitable[None]] | None = None,
|
||
create_message: str = "创建成功",
|
||
update_message: str = "保存成功",
|
||
) -> None:
|
||
self.model = model
|
||
self.create = create
|
||
self.update = update
|
||
self.read = read
|
||
self.module = module
|
||
self.resource = resource
|
||
self.label = label
|
||
self.prefix = prefix
|
||
self.tag = tag
|
||
self.search_fields = search_fields
|
||
self.filters = filters
|
||
self.date_range_fields = date_range_fields
|
||
self.in_fields = in_fields
|
||
self.extra_query = extra_query
|
||
self.filter_hook = filter_hook
|
||
self.dept_scope = dept_scope
|
||
self.order_by = order_by
|
||
self.order = order
|
||
self.label_field = label_field
|
||
self.write = write
|
||
self.deletable = deletable
|
||
self.options = options
|
||
self.employee_scope = employee_scope
|
||
self.list_hook = list_hook
|
||
self.before_write = before_write
|
||
self.after_read = after_read
|
||
self.after_write = after_write
|
||
self.on_delete = on_delete
|
||
self.create_message = create_message
|
||
self.update_message = update_message
|
||
|
||
# -- permission helpers -------------------------------------------------
|
||
def perm(self, action: str) -> str:
|
||
return f"{self.module}:{self.resource}:{action}"
|
||
|
||
|
||
def build_router(spec: CrudSpec, *, preface: list[APIRouter] | None = None) -> APIRouter:
|
||
"""Build the CRUD router. ``preface`` routers are registered first so literal
|
||
paths (``/tree``) are not shadowed by the ``/{item_id}`` route."""
|
||
model = spec.model
|
||
router = APIRouter(prefix=spec.prefix, tags=[spec.tag])
|
||
for extra in preface or []:
|
||
router.include_router(extra)
|
||
dept_mode = _dept_mode(model, spec)
|
||
# 部门筛选由统一的 department_id / dept_subtree 通道接管,避免与等值过滤重复下推
|
||
filter_fields = spec.filters
|
||
if dept_mode and "department_id" in filter_fields:
|
||
filter_fields = tuple(f for f in filter_fields if f != "department_id")
|
||
filter_dep = _make_query_dependency(model, filter_fields)
|
||
date_fields = spec.date_range_fields
|
||
in_fields = spec.in_fields
|
||
|
||
async def _base_stmt(session: Session, auth: AuthCtx, keyword: str | None,
|
||
filters: dict[str, Any], extra: dict[str, Any]) -> Select:
|
||
stmt = select(model)
|
||
if keyword and spec.search_fields:
|
||
conds = [getattr(model, f).like(like(keyword)) for f in spec.search_fields]
|
||
stmt = stmt.where(or_(*conds))
|
||
for key, value in filters.items():
|
||
column = getattr(model, key)
|
||
stmt = stmt.where(
|
||
_multi_cond(column, list(value)) if isinstance(value, (list, tuple, set))
|
||
else column == value
|
||
)
|
||
dept_cond = await _dept_condition(session, model, dept_mode, extra)
|
||
if dept_cond is not None:
|
||
stmt = stmt.where(dept_cond)
|
||
for fname in date_fields:
|
||
column = getattr(model, fname)
|
||
start, end = extra.get(f"{fname}_start"), extra.get(f"{fname}_end")
|
||
if start:
|
||
stmt = stmt.where(column >= datetime.combine(start, time.min)
|
||
if isinstance(column.type, DateTime) else start)
|
||
if end:
|
||
# 日期区间按「含首含尾」解释:DateTime 列取到当日 24:00(不含)
|
||
stmt = stmt.where(
|
||
column < datetime.combine(end + timedelta(days=1), time.min)
|
||
if isinstance(column.type, DateTime) else column <= end)
|
||
for fname in in_fields:
|
||
raw = extra.get(fname)
|
||
if raw:
|
||
values = [v for v in str(raw).split(",") if v != ""]
|
||
if values:
|
||
col = getattr(model, fname)
|
||
try:
|
||
values = [int(v) for v in values]
|
||
except ValueError:
|
||
pass
|
||
stmt = stmt.where(col.in_(values))
|
||
if spec.extra_query and spec.filter_hook:
|
||
picked = {k: extra.get(k) for k in spec.extra_query if extra.get(k)}
|
||
if picked:
|
||
stmt = await spec.filter_hook(stmt, picked, session)
|
||
elif spec.filter_hook:
|
||
stmt = await spec.filter_hook(stmt, extra, session)
|
||
if spec.employee_scope:
|
||
from ..core.deps import apply_employee_scope
|
||
|
||
stmt = await apply_employee_scope(session, stmt, auth, getattr(model, spec.employee_scope))
|
||
if spec.list_hook:
|
||
stmt = await spec.list_hook(stmt, auth, session)
|
||
return stmt
|
||
|
||
@router.get("", response_model=Page[spec.read], summary=f"{spec.label}列表") # type: ignore[name-defined]
|
||
async def list_items(
|
||
session: Session,
|
||
auth: Annotated[AuthContext, Depends(require_perm(spec.perm("read")))],
|
||
page: int = Query(1, ge=1),
|
||
page_size: int = Query(20, ge=1, le=500),
|
||
keyword: str | None = Query(None),
|
||
order_by: str | None = Query(None),
|
||
order: str = Query(spec.order, pattern="^(asc|desc)$"),
|
||
filters: dict[str, Any] = Depends(filter_dep),
|
||
extra: dict[str, Any] = Depends(
|
||
_extra_params(model, date_fields, in_fields, spec.extra_query, dept_mode)
|
||
),
|
||
):
|
||
stmt = await _base_stmt(session, auth, keyword, filters, extra)
|
||
col_name = order_by or spec.order_by
|
||
col = getattr(model, col_name, None) or getattr(model, spec.order_by)
|
||
stmt = stmt.order_by(col.asc() if order == "asc" else col.desc(), model.id.desc())
|
||
total = (
|
||
await session.execute(
|
||
select(func.count()).select_from(stmt.order_by(None).subquery())
|
||
)
|
||
).scalar_one()
|
||
rows = list((await session.execute(stmt.limit(page_size).offset((page - 1) * page_size))).scalars().all())
|
||
if spec.after_read:
|
||
await spec.after_read(session, rows)
|
||
return Page.of([spec.read.model_validate(r) for r in rows], int(total), page, page_size)
|
||
|
||
if spec.options:
|
||
|
||
@router.get("/options", summary=f"{spec.label}选项")
|
||
async def list_options(
|
||
session: Session,
|
||
auth: Annotated[AuthContext, Depends(require_perm(spec.perm("read")))],
|
||
keyword: str | None = Query(None),
|
||
limit: int = Query(1000, le=5000),
|
||
filters: dict[str, Any] = Depends(filter_dep),
|
||
):
|
||
stmt = await _base_stmt(session, auth, keyword, filters, {})
|
||
col = getattr(model, spec.order_by, None) or model.id
|
||
stmt = stmt.order_by(col.asc(), model.id.asc()).limit(limit)
|
||
rows = list((await session.execute(stmt)).scalars().all())
|
||
if spec.after_read:
|
||
await spec.after_read(session, rows)
|
||
return [
|
||
{
|
||
"id": r.id,
|
||
"label": str(getattr(r, spec.label_field, r.id)),
|
||
"extra": {
|
||
k: _jsonable(getattr(r, k))
|
||
for k in ("department_id", "status", "code", "is_active", "phone", "has_account")
|
||
if hasattr(r, k)
|
||
},
|
||
}
|
||
for r in rows
|
||
]
|
||
|
||
@router.get("/{item_id:int}", response_model=spec.read, summary=f"{spec.label}详情") # type: ignore[name-defined]
|
||
async def get_item(item_id: int, session: Session, auth: Annotated[AuthContext, Depends(require_perm(spec.perm("read")))]):
|
||
obj = await session.get(model, item_id)
|
||
if not obj:
|
||
raise AppError(f"{spec.label}不存在", "not_found", 404)
|
||
if spec.employee_scope:
|
||
stmt = (await _base_stmt(session, auth, None, {}, {})).with_only_columns(model.id)
|
||
stmt = stmt.where(model.id == item_id).subquery()
|
||
if not (await session.execute(select(stmt.c.id))).first():
|
||
raise AppError(f"没有权限查看该{spec.label}", "forbidden", 403)
|
||
if spec.after_read:
|
||
await spec.after_read(session, [obj])
|
||
return spec.read.model_validate(obj)
|
||
|
||
if spec.write:
|
||
|
||
@router.post("", response_model=spec.read, summary=f"新增{spec.label}") # type: ignore[name-defined]
|
||
async def create_item(
|
||
payload: spec.create, # type: ignore[valid-type]
|
||
session: Session,
|
||
auth: Annotated[AuthContext, Depends(require_perm(spec.perm("create")))],
|
||
):
|
||
data = payload.model_dump(exclude_unset=True)
|
||
if spec.before_write:
|
||
data = await spec.before_write("create", data, None, auth, session)
|
||
obj = model(**data)
|
||
if hasattr(obj, "created_by"):
|
||
obj.created_by = auth.user.id
|
||
session.add(obj)
|
||
await session.flush()
|
||
if spec.after_write:
|
||
await spec.after_write("create", obj, auth, session)
|
||
await session.commit()
|
||
await session.refresh(obj)
|
||
if spec.after_read:
|
||
await spec.after_read(session, [obj])
|
||
return spec.read.model_validate(obj)
|
||
|
||
@router.patch("/{item_id:int}", response_model=spec.read, summary=f"更新{spec.label}") # type: ignore[name-defined]
|
||
@router.put("/{item_id:int}", response_model=spec.read, include_in_schema=False) # type: ignore[name-defined]
|
||
async def update_item(
|
||
item_id: int,
|
||
payload: spec.update, # type: ignore[valid-type]
|
||
session: Session,
|
||
auth: Annotated[AuthContext, Depends(require_perm(spec.perm("update")))],
|
||
):
|
||
obj = await session.get(model, item_id)
|
||
if not obj:
|
||
raise AppError(f"{spec.label}不存在", "not_found", 404)
|
||
data = payload.model_dump(exclude_unset=True)
|
||
if spec.before_write:
|
||
data = await spec.before_write("update", data, obj, auth, session)
|
||
for key, value in data.items():
|
||
setattr(obj, key, value)
|
||
if hasattr(obj, "updated_by"):
|
||
obj.updated_by = auth.user.id
|
||
await session.flush()
|
||
if spec.after_write:
|
||
await spec.after_write("update", obj, auth, session)
|
||
await session.commit()
|
||
await session.refresh(obj)
|
||
if spec.after_read:
|
||
await spec.after_read(session, [obj])
|
||
return spec.read.model_validate(obj)
|
||
|
||
if spec.deletable:
|
||
|
||
@router.delete("/{item_id:int}", summary=f"删除{spec.label}")
|
||
async def delete_item(
|
||
item_id: int,
|
||
session: Session,
|
||
auth: Annotated[AuthContext, Depends(require_perm(spec.perm("delete")))],
|
||
):
|
||
obj = await session.get(model, item_id)
|
||
if not obj:
|
||
raise AppError(f"{spec.label}不存在", "not_found", 404)
|
||
if spec.on_delete:
|
||
await spec.on_delete(obj, auth, session)
|
||
await session.delete(obj)
|
||
await session.commit()
|
||
return {"message": "已删除"}
|
||
|
||
return router
|
||
|
||
|
||
def _jsonable(value: Any) -> Any:
|
||
if isinstance(value, (date, datetime)):
|
||
return value.isoformat()
|
||
if isinstance(value, (str, int, float, bool)) or value is None:
|
||
return value
|
||
return str(value)
|
||
|
||
|
||
def _dept_mode(model, spec) -> str | None:
|
||
"""这张表怎么按部门过滤:自身有 department_id / 走 employee_id / 不支持。"""
|
||
if getattr(spec, "dept_scope", "auto") in (None, "none"):
|
||
return None
|
||
if spec.dept_scope == "self" or "department_id" in model.__table__.c:
|
||
return "self"
|
||
if spec.dept_scope == "employee" or "employee_id" in model.__table__.c:
|
||
return "employee"
|
||
return None
|
||
|
||
|
||
async def _dept_condition(session, model, dept_mode: str | None, extra: dict[str, Any]):
|
||
"""``?department_id=1,2&dept_subtree=1`` -> 部门(可含下级)的过滤条件。
|
||
|
||
挂在自身 department_id 上的资源直接过滤;只有 employee_id 的资源(薪资单、
|
||
福利台账、假期申请……)通过员工表做子查询,语义与前端「部门树」按钮一致。
|
||
"""
|
||
if not dept_mode or not extra.get("department_id"):
|
||
return None
|
||
from ..core.deps import department_subtree
|
||
|
||
picked = [int(v) for v in _split_multi(extra["department_id"]) if v.lstrip("-").isdigit()]
|
||
# 默认等值(与历史 API 语义一致),显式 dept_subtree=1 才展开下级部门
|
||
expand = str(extra.get("dept_subtree") or "").strip().lower() in ("1", "true", "yes", "on")
|
||
ids: list[int] = []
|
||
for dept_id in picked:
|
||
ids.extend(await department_subtree(session, dept_id) if expand else [dept_id])
|
||
ids = sorted(set(ids)) or [-1]
|
||
if dept_mode == "self":
|
||
return model.department_id.in_(ids)
|
||
from ..models.employee import Employee
|
||
|
||
return model.employee_id.in_(select(Employee.id).where(Employee.department_id.in_(ids)))
|
||
|
||
|
||
def _extra_params(model, date_fields: tuple[str, ...], in_fields: tuple[str, ...],
|
||
extra_query: tuple[str, ...] = (), dept_mode: str | None = None):
|
||
import inspect
|
||
|
||
params: list[inspect.Parameter] = []
|
||
if dept_mode:
|
||
params.append(inspect.Parameter(
|
||
"department_id", inspect.Parameter.KEYWORD_ONLY, annotation=str | None,
|
||
default=Query(None, description="部门过滤,逗号分隔多选(支持部门 id 或部门树勾选)"),
|
||
))
|
||
params.append(inspect.Parameter(
|
||
"dept_subtree", inspect.Parameter.KEYWORD_ONLY, annotation=str | None,
|
||
default=Query(None, description="配合 department_id:1=连同下级部门一起过滤,缺省=仅所选部门"),
|
||
))
|
||
for qname in extra_query:
|
||
params.append(inspect.Parameter(
|
||
qname, inspect.Parameter.KEYWORD_ONLY, annotation=str | None,
|
||
default=Query(None, description="扩展过滤,逗号分隔多值"),
|
||
))
|
||
for fname in date_fields:
|
||
for suffix, anno in (("_start", date | None), ("_end", date | None)):
|
||
params.append(
|
||
inspect.Parameter(
|
||
fname + suffix,
|
||
inspect.Parameter.KEYWORD_ONLY,
|
||
annotation=anno,
|
||
default=Query(None),
|
||
)
|
||
)
|
||
for fname in in_fields:
|
||
params.append(
|
||
inspect.Parameter(
|
||
fname,
|
||
inspect.Parameter.KEYWORD_ONLY,
|
||
annotation=str | None,
|
||
default=Query(None, description="逗号分隔的多值过滤"),
|
||
)
|
||
)
|
||
if not params:
|
||
|
||
async def _empty() -> dict[str, Any]:
|
||
return {}
|
||
|
||
return _empty
|
||
|
||
async def _dep(**kwargs: Any) -> dict[str, Any]:
|
||
return {k: v for k, v in kwargs.items() if v is not None}
|
||
|
||
_dep.__signature__ = inspect.Signature(parameters=params, return_annotation=dict[str, Any])
|
||
return _dep
|