630 lines
20 KiB
Python
630 lines
20 KiB
Python
"""值班排班领域服务 — docs/superpowers/specs/2026-08-14-duty-schedule-design.md"""
|
||
from __future__ import annotations
|
||
|
||
import calendar
|
||
import secrets
|
||
from datetime import date, datetime
|
||
from typing import Any, Dict, List, Optional, Sequence
|
||
|
||
from sqlalchemy import and_
|
||
from sqlalchemy.orm import Session
|
||
|
||
from app.core.config import settings
|
||
from app.core.utils import generate_id
|
||
from app.models.duty_models import (
|
||
DUTY_STAFF_ROLE_ID,
|
||
DUTY_STAFF_ROLE_NAME,
|
||
LINK_CLOSED,
|
||
LINK_OPEN,
|
||
SHIFT_LABELS,
|
||
SOURCE_ASSIGN,
|
||
SOURCE_GRAB,
|
||
DutyAssignment,
|
||
DutyDay,
|
||
DutySlot,
|
||
)
|
||
from app.models.models import SysRole, SysUser, SysUserRole
|
||
from app.schemas.duty import DutyDaySaveBody, DutySlotSaveIn
|
||
|
||
PERSON_NAME_MAX_LEN = 20
|
||
|
||
|
||
class DutyBizError(ValueError):
|
||
"""业务错误（可映射为 HTTP 400）"""
|
||
|
||
|
||
def normalize_person_name(name: str) -> str:
|
||
raw = (name or "").strip()
|
||
if not raw:
|
||
raise DutyBizError("姓名不能为空")
|
||
if len(raw) > PERSON_NAME_MAX_LEN:
|
||
raise DutyBizError(f"姓名不能超过{PERSON_NAME_MAX_LEN}个字符")
|
||
return raw
|
||
|
||
|
||
def new_access_token() -> str:
|
||
return secrets.token_urlsafe(24)[:64]
|
||
|
||
|
||
def build_public_url(token: str) -> str:
|
||
origin = (settings.PUBLIC_WEB_ORIGIN or "").rstrip("/")
|
||
return f"{origin}/#/public/duty/{token}"
|
||
|
||
|
||
def _assignment_dict(row: DutyAssignment) -> Dict[str, Any]:
|
||
return {
|
||
"id": row.id,
|
||
"source": row.source,
|
||
"userId": row.user_id,
|
||
"personName": row.person_name,
|
||
}
|
||
|
||
|
||
def _slot_dict(slot: DutySlot, assignments: Sequence[DutyAssignment]) -> Dict[str, Any]:
|
||
active = [a for a in assignments if a.del_flag == 0]
|
||
return {
|
||
"id": slot.id,
|
||
"shiftType": slot.shift_type,
|
||
"shiftLabel": SHIFT_LABELS.get(slot.shift_type, slot.shift_type),
|
||
"capacity": slot.capacity,
|
||
"taken": len(active),
|
||
"remark": (slot.remark or "").strip() or None,
|
||
"assignments": [_assignment_dict(a) for a in active],
|
||
}
|
||
|
||
|
||
def _day_dict(
|
||
day: DutyDay,
|
||
slots: Sequence[DutySlot],
|
||
assignments_by_slot: Dict[str, List[DutyAssignment]],
|
||
) -> Dict[str, Any]:
|
||
slot_payload = [
|
||
_slot_dict(s, assignments_by_slot.get(s.id, []))
|
||
for s in sorted(slots, key=lambda x: (x.order_num or 0, x.shift_type or ""))
|
||
if s.del_flag == 0
|
||
]
|
||
return {
|
||
"id": day.id,
|
||
"dutyDate": day.duty_date.isoformat() if day.duty_date else None,
|
||
"linkStatus": day.link_status,
|
||
"accessToken": day.access_token,
|
||
"publicUrl": build_public_url(day.access_token),
|
||
"slots": slot_payload,
|
||
}
|
||
|
||
|
||
def _load_day_by_date(db: Session, tenant_no: str, duty_date: date) -> Optional[DutyDay]:
|
||
return (
|
||
db.query(DutyDay)
|
||
.filter(
|
||
DutyDay.tenant_no == tenant_no,
|
||
DutyDay.duty_date == duty_date,
|
||
DutyDay.del_flag == 0,
|
||
)
|
||
.first()
|
||
)
|
||
|
||
|
||
def _load_day_by_id(db: Session, tenant_no: str, day_id: str) -> Optional[DutyDay]:
|
||
return (
|
||
db.query(DutyDay)
|
||
.filter(DutyDay.id == day_id, DutyDay.tenant_no == tenant_no, DutyDay.del_flag == 0)
|
||
.first()
|
||
)
|
||
|
||
|
||
def _load_slots(db: Session, day_id: str) -> List[DutySlot]:
|
||
return (
|
||
db.query(DutySlot)
|
||
.filter(DutySlot.duty_day_id == day_id, DutySlot.del_flag == 0)
|
||
.all()
|
||
)
|
||
|
||
|
||
def _load_assignments_for_slots(
|
||
db: Session, slot_ids: Sequence[str]
|
||
) -> Dict[str, List[DutyAssignment]]:
|
||
if not slot_ids:
|
||
return {}
|
||
rows = (
|
||
db.query(DutyAssignment)
|
||
.filter(DutyAssignment.duty_slot_id.in_(list(slot_ids)), DutyAssignment.del_flag == 0)
|
||
.all()
|
||
)
|
||
out: Dict[str, List[DutyAssignment]] = {sid: [] for sid in slot_ids}
|
||
for row in rows:
|
||
out.setdefault(row.duty_slot_id, []).append(row)
|
||
return out
|
||
|
||
|
||
def _serialize_day(db: Session, day: DutyDay) -> Dict[str, Any]:
|
||
slots = _load_slots(db, day.id)
|
||
assigns = _load_assignments_for_slots(db, [s.id for s in slots])
|
||
return _day_dict(day, slots, assigns)
|
||
|
||
|
||
def empty_day_skeleton(duty_date: date) -> Dict[str, Any]:
|
||
return {
|
||
"id": None,
|
||
"dutyDate": duty_date.isoformat(),
|
||
"linkStatus": LINK_OPEN,
|
||
"accessToken": None,
|
||
"publicUrl": None,
|
||
"slots": [],
|
||
}
|
||
|
||
|
||
def get_month_summary(db: Session, tenant_no: str, year: int, month: int) -> List[Dict[str, Any]]:
|
||
last_day = calendar.monthrange(year, month)[1]
|
||
start = date(year, month, 1)
|
||
end = date(year, month, last_day)
|
||
days = (
|
||
db.query(DutyDay)
|
||
.filter(
|
||
DutyDay.tenant_no == tenant_no,
|
||
DutyDay.del_flag == 0,
|
||
DutyDay.duty_date >= start,
|
||
DutyDay.duty_date <= end,
|
||
)
|
||
.order_by(DutyDay.duty_date.asc())
|
||
.all()
|
||
)
|
||
result = []
|
||
for day in days:
|
||
payload = _serialize_day(db, day)
|
||
# 月历摘要可精简 assignments 人名
|
||
result.append(payload)
|
||
return result
|
||
|
||
|
||
def get_day_detail(db: Session, tenant_no: str, duty_date: date) -> Dict[str, Any]:
|
||
day = _load_day_by_date(db, tenant_no, duty_date)
|
||
if not day:
|
||
return empty_day_skeleton(duty_date)
|
||
return _serialize_day(db, day)
|
||
|
||
|
||
def soft_delete_assignment(
|
||
db: Session, tenant_no: str, assignment_id: str, operator_id: str = ""
|
||
) -> None:
|
||
row = (
|
||
db.query(DutyAssignment)
|
||
.filter(
|
||
DutyAssignment.id == assignment_id,
|
||
DutyAssignment.tenant_no == tenant_no,
|
||
DutyAssignment.del_flag == 0,
|
||
)
|
||
.first()
|
||
)
|
||
if not row:
|
||
raise DutyBizError("报名记录不存在")
|
||
row.del_flag = 1
|
||
row.update_by = operator_id or None
|
||
row.update_time = datetime.now()
|
||
db.commit()
|
||
|
||
|
||
def set_link_status(
|
||
db: Session, tenant_no: str, day_id: str, status: str, operator_id: str = ""
|
||
) -> Dict[str, Any]:
|
||
if status not in (LINK_OPEN, LINK_CLOSED):
|
||
raise DutyBizError("链接状态无效")
|
||
day = _load_day_by_id(db, tenant_no, day_id)
|
||
if not day:
|
||
raise DutyBizError("值班日不存在")
|
||
day.link_status = status
|
||
day.update_by = operator_id or None
|
||
day.update_time = datetime.now()
|
||
db.commit()
|
||
db.refresh(day)
|
||
return _serialize_day(db, day)
|
||
|
||
|
||
def _count_active_assignments(db: Session, slot_id: str) -> int:
|
||
return (
|
||
db.query(DutyAssignment)
|
||
.filter(DutyAssignment.duty_slot_id == slot_id, DutyAssignment.del_flag == 0)
|
||
.count()
|
||
)
|
||
|
||
|
||
def save_day(
|
||
db: Session,
|
||
tenant_no: str,
|
||
user: Dict[str, Any],
|
||
body: DutyDaySaveBody,
|
||
) -> Dict[str, Any]:
|
||
user_id = (user.get("user_id") or user.get("id") or "") or ""
|
||
dept_id = (user.get("region_id") or user.get("create_dept_id") or "") or ""
|
||
now = datetime.now()
|
||
|
||
# 校验：每个 slot 提交的指定人数不超过 capacity
|
||
seen_types = set()
|
||
for slot_in in body.slots:
|
||
if slot_in.shiftType in seen_types:
|
||
raise DutyBizError("同一天不能重复配置相同班次")
|
||
seen_types.add(slot_in.shiftType)
|
||
assign_count = len(slot_in.assignments or [])
|
||
if assign_count > slot_in.capacity:
|
||
label = SHIFT_LABELS.get(slot_in.shiftType, slot_in.shiftType)
|
||
raise DutyBizError(f"{label}报名人数不能超过名额")
|
||
|
||
day = _load_day_by_date(db, tenant_no, body.dutyDate)
|
||
if not day:
|
||
day = DutyDay(
|
||
id=generate_id(),
|
||
duty_date=body.dutyDate,
|
||
access_token=new_access_token(),
|
||
link_status=body.linkStatus or LINK_OPEN,
|
||
tenant_no=tenant_no,
|
||
create_by=user_id,
|
||
create_dept_id=dept_id,
|
||
create_time=now,
|
||
update_by=user_id,
|
||
update_time=now,
|
||
del_flag=0,
|
||
)
|
||
db.add(day)
|
||
db.flush()
|
||
else:
|
||
if body.linkStatus in (LINK_OPEN, LINK_CLOSED):
|
||
day.link_status = body.linkStatus
|
||
day.update_by = user_id
|
||
day.update_time = now
|
||
|
||
existing_slots = _load_slots(db, day.id)
|
||
existing_by_type = {s.shift_type: s for s in existing_slots}
|
||
incoming_types = {s.shiftType for s in body.slots}
|
||
|
||
# 停用未再提交且已有报名的班次：禁止
|
||
for shift_type, slot in existing_by_type.items():
|
||
if shift_type not in incoming_types:
|
||
taken = _count_active_assignments(db, slot.id)
|
||
if taken > 0:
|
||
label = SHIFT_LABELS.get(shift_type, shift_type)
|
||
raise DutyBizError(f"{label}仍有报名，请先清空后再移除该班次")
|
||
slot.del_flag = 1
|
||
slot.update_by = user_id
|
||
slot.update_time = now
|
||
|
||
order = 0
|
||
for slot_in in body.slots:
|
||
order += 1
|
||
slot = existing_by_type.get(slot_in.shiftType)
|
||
slot_remark = (slot_in.remark or "").strip() or None
|
||
# 已有 slot 上历史 assign 用户可再保存（D4）；新建 slot 必须具备值班人员角色（D7）
|
||
grandfathered_user_ids: set = set()
|
||
if slot is None:
|
||
slot = DutySlot(
|
||
id=generate_id(),
|
||
duty_day_id=day.id,
|
||
shift_type=slot_in.shiftType,
|
||
capacity=slot_in.capacity,
|
||
remark=slot_remark,
|
||
tenant_no=tenant_no,
|
||
order_num=order,
|
||
create_by=user_id,
|
||
create_dept_id=dept_id,
|
||
create_time=now,
|
||
update_by=user_id,
|
||
update_time=now,
|
||
del_flag=0,
|
||
)
|
||
db.add(slot)
|
||
db.flush()
|
||
else:
|
||
taken = _count_active_assignments(db, slot.id)
|
||
# 缩容：不能小于「保留后的报名」——保存时以 body.assignments 为准重建指定项，
|
||
# 但抢班记录不在 body 里时需计入 taken 中不在本次提交删除范围的 grab。
|
||
# 简化策略：先统计将保留的 grab + 新 assign 总数，再与 capacity 比。
|
||
existing_assigns = (
|
||
db.query(DutyAssignment)
|
||
.filter(DutyAssignment.duty_slot_id == slot.id, DutyAssignment.del_flag == 0)
|
||
.all()
|
||
)
|
||
grandfathered_user_ids = {
|
||
a.user_id
|
||
for a in existing_assigns
|
||
if a.source == SOURCE_ASSIGN and a.user_id
|
||
}
|
||
# body.assignments 视为该班次最终「指定」名单；grab 全部保留，除非超容时拒绝缩容
|
||
grab_rows = [a for a in existing_assigns if a.source == SOURCE_GRAB]
|
||
new_assign_count = len(slot_in.assignments or [])
|
||
final_count = len(grab_rows) + new_assign_count
|
||
if final_count > slot_in.capacity:
|
||
label = SHIFT_LABELS.get(slot_in.shiftType, slot_in.shiftType)
|
||
raise DutyBizError(
|
||
f"{label}当前已有 {len(grab_rows)} 人抢班 + {new_assign_count} 人指定，"
|
||
f"超过名额 {slot_in.capacity}，请先删人再缩容"
|
||
)
|
||
slot.capacity = slot_in.capacity
|
||
slot.remark = slot_remark
|
||
slot.order_num = order
|
||
slot.update_by = user_id
|
||
slot.update_time = now
|
||
|
||
# 软删旧的 assign 指定，再写入新的；grab 保留
|
||
for a in existing_assigns:
|
||
if a.source == SOURCE_ASSIGN:
|
||
a.del_flag = 1
|
||
a.update_by = user_id
|
||
a.update_time = now
|
||
|
||
# 新 slot：写入 assignments；已存在 slot：写入新的 assign
|
||
for item in slot_in.assignments or []:
|
||
person_name = (item.personName or "").strip()
|
||
uid = (item.userId or "").strip() or None
|
||
if item.source == SOURCE_ASSIGN and not person_name and not uid:
|
||
continue
|
||
if not person_name:
|
||
raise DutyBizError("指定员工须有姓名")
|
||
person_name = normalize_person_name(person_name) if person_name else person_name
|
||
# 若只有 userId，允许 personName 已由上层填好
|
||
if not person_name:
|
||
raise DutyBizError("指定员工姓名不能为空")
|
||
if item.source == SOURCE_ASSIGN and uid:
|
||
if uid not in grandfathered_user_ids:
|
||
assert_user_is_duty_staff(db, tenant_no, uid)
|
||
db.add(
|
||
DutyAssignment(
|
||
id=generate_id(),
|
||
duty_slot_id=slot.id,
|
||
source=SOURCE_ASSIGN if item.source != SOURCE_GRAB else SOURCE_GRAB,
|
||
user_id=uid,
|
||
person_name=person_name,
|
||
tenant_no=tenant_no,
|
||
create_by=user_id,
|
||
create_dept_id=dept_id,
|
||
create_time=now,
|
||
update_by=user_id,
|
||
update_time=now,
|
||
del_flag=0,
|
||
)
|
||
)
|
||
|
||
# 新建 slot 时也要校验人数
|
||
if slot.id and _count_active_assignments(db, slot.id) > slot.capacity:
|
||
label = SHIFT_LABELS.get(slot.shift_type, slot.shift_type)
|
||
raise DutyBizError(f"{label}报名人数不能超过名额")
|
||
|
||
db.commit()
|
||
db.refresh(day)
|
||
return _serialize_day(db, day)
|
||
|
||
|
||
def resolve_duty_staff_role_id(db: Session, tenant_no: str) -> Optional[str]:
|
||
"""按固定 id 查找「值班人员」角色；找不到再按角色名兜底。"""
|
||
role = (
|
||
db.query(SysRole)
|
||
.filter(
|
||
SysRole.id == DUTY_STAFF_ROLE_ID,
|
||
SysRole.tenant_no == tenant_no,
|
||
SysRole.del_flag == 0,
|
||
)
|
||
.first()
|
||
)
|
||
if role:
|
||
return role.id
|
||
role = (
|
||
db.query(SysRole)
|
||
.filter(
|
||
SysRole.role_name == DUTY_STAFF_ROLE_NAME,
|
||
SysRole.tenant_no == tenant_no,
|
||
SysRole.del_flag == 0,
|
||
SysRole.status == "1",
|
||
)
|
||
.first()
|
||
)
|
||
return role.id if role else None
|
||
|
||
|
||
def list_duty_staff_users(db: Session, tenant_no: str) -> List[Dict[str, str]]:
|
||
"""本租户启用且绑定「值班人员」角色的用户（公开页 users / 管理端 options）。"""
|
||
role_id = resolve_duty_staff_role_id(db, tenant_no)
|
||
if not role_id:
|
||
return []
|
||
rows = (
|
||
db.query(SysUser)
|
||
.join(
|
||
SysUserRole,
|
||
and_(
|
||
SysUserRole.user_id == SysUser.id,
|
||
SysUserRole.role_id == role_id,
|
||
SysUserRole.del_flag == 0,
|
||
SysUserRole.tenant_no == tenant_no,
|
||
),
|
||
)
|
||
.filter(
|
||
SysUser.tenant_no == tenant_no,
|
||
SysUser.del_flag == 0,
|
||
SysUser.status == "1",
|
||
)
|
||
.order_by(SysUser.nick_name.asc(), SysUser.user_no.asc())
|
||
.all()
|
||
)
|
||
out: List[Dict[str, str]] = []
|
||
seen = set()
|
||
for r in rows:
|
||
if r.id in seen:
|
||
continue
|
||
seen.add(r.id)
|
||
label = (r.nick_name or "").strip() or (r.user_no or "").strip()
|
||
if not label:
|
||
continue
|
||
out.append({"id": r.id, "label": label})
|
||
return out
|
||
|
||
|
||
def assert_user_is_duty_staff(db: Session, tenant_no: str, user_id: str) -> None:
|
||
uid = (user_id or "").strip()
|
||
if not uid:
|
||
raise DutyBizError("用户无效或不具备值班人员角色")
|
||
user = (
|
||
db.query(SysUser)
|
||
.filter(
|
||
SysUser.id == uid,
|
||
SysUser.tenant_no == tenant_no,
|
||
SysUser.del_flag == 0,
|
||
SysUser.status == "1",
|
||
)
|
||
.first()
|
||
)
|
||
if not user:
|
||
raise DutyBizError("用户无效或不具备值班人员角色")
|
||
role_id = resolve_duty_staff_role_id(db, tenant_no)
|
||
if not role_id:
|
||
raise DutyBizError("未配置「值班人员」角色，请联系管理员")
|
||
link = (
|
||
db.query(SysUserRole)
|
||
.filter(
|
||
SysUserRole.user_id == uid,
|
||
SysUserRole.role_id == role_id,
|
||
SysUserRole.tenant_no == tenant_no,
|
||
SysUserRole.del_flag == 0,
|
||
)
|
||
.first()
|
||
)
|
||
if not link:
|
||
raise DutyBizError("用户无效或不具备值班人员角色")
|
||
|
||
|
||
def _list_public_users(db: Session, tenant_no: str) -> List[Dict[str, str]]:
|
||
return list_duty_staff_users(db, tenant_no)
|
||
|
||
|
||
def _resolve_grab_user(db: Session, tenant_no: str, user_id: str) -> SysUser:
|
||
uid = (user_id or "").strip()
|
||
if not uid:
|
||
raise DutyBizError("请选择有效用户")
|
||
user = (
|
||
db.query(SysUser)
|
||
.filter(
|
||
SysUser.id == uid,
|
||
SysUser.tenant_no == tenant_no,
|
||
SysUser.del_flag == 0,
|
||
SysUser.status == "1",
|
||
)
|
||
.first()
|
||
)
|
||
if not user:
|
||
raise DutyBizError("用户无效或不存在")
|
||
assert_user_is_duty_staff(db, tenant_no, user.id)
|
||
return user
|
||
|
||
|
||
def get_public_page(db: Session, token: str) -> Dict[str, Any]:
|
||
token = (token or "").strip()
|
||
if not token:
|
||
raise DutyBizError("链接无效或已失效")
|
||
day = (
|
||
db.query(DutyDay)
|
||
.filter(DutyDay.access_token == token, DutyDay.del_flag == 0)
|
||
.first()
|
||
)
|
||
if not day:
|
||
raise DutyBizError("链接无效或已失效")
|
||
payload = _serialize_day(db, day)
|
||
return {
|
||
"dutyDate": payload["dutyDate"],
|
||
"linkStatus": payload["linkStatus"],
|
||
"slots": payload["slots"],
|
||
"closed": day.link_status == LINK_CLOSED,
|
||
"users": _list_public_users(db, day.tenant_no),
|
||
}
|
||
|
||
|
||
def grab(db: Session, token: str, shift_type: str, user_id: str) -> Dict[str, Any]:
|
||
shift_type = (shift_type or "").strip()
|
||
if shift_type not in SHIFT_LABELS:
|
||
raise DutyBizError("班次类型无效")
|
||
|
||
day = (
|
||
db.query(DutyDay)
|
||
.filter(DutyDay.access_token == token, DutyDay.del_flag == 0)
|
||
.with_for_update()
|
||
.first()
|
||
)
|
||
if not day:
|
||
raise DutyBizError("链接无效或已失效")
|
||
if day.link_status == LINK_CLOSED:
|
||
raise DutyBizError("报名已关闭")
|
||
|
||
user = _resolve_grab_user(db, day.tenant_no, user_id)
|
||
name = normalize_person_name((user.nick_name or "").strip() or (user.user_no or "").strip())
|
||
|
||
slot = (
|
||
db.query(DutySlot)
|
||
.filter(
|
||
DutySlot.duty_day_id == day.id,
|
||
DutySlot.shift_type == shift_type,
|
||
DutySlot.del_flag == 0,
|
||
)
|
||
.with_for_update()
|
||
.first()
|
||
)
|
||
if not slot:
|
||
raise DutyBizError("该班次不存在")
|
||
|
||
dup = (
|
||
db.query(DutyAssignment)
|
||
.filter(
|
||
DutyAssignment.duty_slot_id == slot.id,
|
||
DutyAssignment.user_id == user.id,
|
||
DutyAssignment.del_flag == 0,
|
||
)
|
||
.first()
|
||
)
|
||
if dup:
|
||
raise DutyBizError("您已报名该班次")
|
||
|
||
taken = _count_active_assignments(db, slot.id)
|
||
if taken >= slot.capacity:
|
||
raise DutyBizError("名额已满")
|
||
|
||
now = datetime.now()
|
||
row = DutyAssignment(
|
||
id=generate_id(),
|
||
duty_slot_id=slot.id,
|
||
source=SOURCE_GRAB,
|
||
user_id=user.id,
|
||
person_name=name,
|
||
tenant_no=day.tenant_no,
|
||
create_by=user.id,
|
||
create_dept_id="",
|
||
create_time=now,
|
||
update_by=user.id,
|
||
update_time=now,
|
||
del_flag=0,
|
||
)
|
||
db.add(row)
|
||
db.commit()
|
||
return {
|
||
"dutyDate": day.duty_date.isoformat(),
|
||
"shiftType": shift_type,
|
||
"shiftLabel": SHIFT_LABELS.get(shift_type, shift_type),
|
||
"personName": name,
|
||
"userId": user.id,
|
||
"status": "ok",
|
||
}
|
||
|
||
|
||
# re-export for tests
|
||
__all__ = [
|
||
"SHIFT_LABELS",
|
||
"DutyBizError",
|
||
"normalize_person_name",
|
||
"new_access_token",
|
||
"build_public_url",
|
||
"get_month_summary",
|
||
"get_day_detail",
|
||
"empty_day_skeleton",
|
||
"save_day",
|
||
"set_link_status",
|
||
"soft_delete_assignment",
|
||
"get_public_page",
|
||
"grab",
|
||
"resolve_duty_staff_role_id",
|
||
"list_duty_staff_users",
|
||
"assert_user_is_duty_staff",
|
||
]
|