unis_hrms/app/api/crud.py

493 lines
20 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

"""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