PayrollManagementSystem/backend/app/services/personnel_service.py

"""营销人员管理业务编排（需求 2.1.1：人员档案 + 辐射区域 + 拓展计划）。

业务规则（前端会做提示，**后端校验是唯一防线**）：

- 岗位必须存在且启用 —— 岗位决定计提公式模板，挂到停用/不存在的岗位
  会让 M3 核算找不到模板
- 直属经理是可空的档案参考；实际绩效按业务分管及冻结核算资料归属。
  新选经理不能是自己，须在职且使用启用的经理计提岗位；旧参考关系保留供核对
- 删除保护：被团队成员（personnel.manager_id）或客户归属
  （customers.owner_personnel_id）引用的人员**禁删**，应改为离职 ——
  历史核算与客户归属都要能回溯到人，物理删除会留下悬空引用
- 金额红线：salary_standard 以字符串进出、服务层转 Decimal，全程不经 float

辐射区域与拓展计划为整表替换维护：先删、立即 flush、再插入
（防御同一 flush 先 INSERT 后 DELETE 撞唯一键，见 personnel_repository）。
"""

import logging
from datetime import date
from decimal import Decimal

from sqlalchemy.exc import IntegrityError
from sqlalchemy.orm import Session

from app.core.constants import (
    ACTION_CREATE,
    ACTION_DELETE,
    ACTION_UPDATE,
    MODULE_PERSONNEL,
)
from app.core.exceptions import BadRequestError, NotFoundError
from app.core.response import PageResult
from app.models import BusinessRole, Personnel, PersonnelPlan, PersonnelRegion, User
from app.models.personnel import PERSONNEL_STATUS_ACTIVE
from app.repositories import business_role_repository, personnel_repository
from app.schemas.personnel import (
    PersonnelCreateIn,
    PersonnelDetailOut,
    PersonnelOut,
    PersonnelPlanOut,
    PersonnelQuery,
    PersonnelRegionOut,
    PlanReplaceIn,
    RegionReplaceIn,
)
from app.services import audit_service, calc_templates
from app.services.audit_service import AuditRecord, RequestMeta

logger = logging.getLogger(__name__)

# 删除保护的统一文案：三种引用（团队成员/客户归属/业务归属）共享同一提示，
# 引导管理员走「离职」而非删除
_DELETE_BLOCKED = "存在团队成员、客户归属或业务归属引用，请改为离职而非删除"


def ensure_active(session: Session, personnel_id: int, *, label: str) -> Personnel:
    """归属人员必须存在且在职，返回人员行（业务/客户两侧归属校验共用）。

    「不存在」与「已离职」合并为同一文案：人员 ID 是否有效不构成需要向
    调用方区分的信息（同登录防枚举的思路）；label 落文案（负责/协助/归属）。
    收口单点：在职状态值取 models.personnel.PERSONNEL_STATUS_ACTIVE，
    此前 business/customer 两 service 各持常量与校验，仅靠注释维持同步。

    :raises BadRequestError: {label}人员不存在或已离职
    """
    person = personnel_repository.get_by_id(session, personnel_id)
    if person is None or person.status != PERSONNEL_STATUS_ACTIVE:
        raise BadRequestError(f"{label}人员不存在或已离职")
    return person


def list_personnel(session: Session, query: PersonnelQuery) -> PageResult[PersonnelOut]:
    """分页查询人员（含离职）。"""
    rows = personnel_repository.list_personnel(session, query)
    total = personnel_repository.count_personnel(session, query)
    return PageResult[PersonnelOut](
        records=[
            _to_out(personnel, role_name, manager_name)
            for personnel, role_name, manager_name in rows
        ],
        total=total,
        page_num=query.page_num,
        page_size=query.page_size,
    )


def get_detail(session: Session, personnel_id: int) -> PersonnelDetailOut:
    """人员详情（含区域与拓展计划，供编辑抽屉回显）。

    :raises NotFoundError: 人员不存在
    """
    row = personnel_repository.get_with_names(session, personnel_id)
    if row is None:
        raise NotFoundError("人员不存在")
    personnel, role_name, manager_name = row
    return PersonnelDetailOut(
        **_to_out(personnel, role_name, manager_name).model_dump(),
        salary_history_json=personnel.salary_history_json,
        regions=[
            PersonnelRegionOut.model_validate(item)
            for item in personnel_repository.list_regions(session, personnel_id)
        ],
        plans=[
            PersonnelPlanOut.model_validate(item)
            for item in personnel_repository.list_plans(session, personnel_id)
        ],
    )


def create_personnel(
    session: Session,
    payload: PersonnelCreateIn,
    *,
    operator: User,
    meta: RequestMeta | None = None,
) -> PersonnelOut:
    """新增人员，默认在职。

    :raises BadRequestError: 岗位不存在或已停用 / 直属经理不合法
    """
    with audit_service.audit(
        session,
        operator=operator,
        record=AuditRecord(
            module=MODULE_PERSONNEL,
            action=ACTION_CREATE,
            summary=f"新增人员 {payload.personnel_name}",
            request_data=payload.model_dump(exclude_none=True),
        ),
        meta=meta,
    ):
        # 引用校验放在审计上下文内：失败同样要留痕（与 update_personnel 口径
        # 一致）——「谁在何时试图把人挂到停用岗位/离职经理上」是审计对象，
        # 校验留在上下文外会让这类失败操作无据可查
        role, manager_name = _validate_refs(
            session, payload.business_role_id, payload.manager_id, None
        )
        personnel = Personnel(
            personnel_name=payload.personnel_name,
            business_role_id=payload.business_role_id,
            manager_id=payload.manager_id,
            phone=payload.phone,
            hire_date=payload.hire_date,
            is_probation=payload.is_probation,
            probation_start_date=payload.probation_start_date,
            regularization_date=payload.regularization_date,
            resignation_date=payload.resignation_date,
            salary_standard=_parse_salary(payload.salary_standard),
            status=1,
            remark=payload.remark,
        )
        try:
            personnel_repository.create(session, personnel)
            from app.services.personnel_salary import save_version

            save_version(personnel, payload.salary_effective_date or payload.hire_date or date.today())
            out = _to_out(personnel, role.role_name, manager_name)
            session.commit()
        except IntegrityError as exc:
            # 先查后写不是原子操作：岗位/经理行被并发删除时 FK RESTRICT 令写入失败
            session.rollback()
            raise BadRequestError("岗位或直属经理引用已失效，请刷新后重试") from exc

        logger.info("新增人员 | personnel_id=%s | name=%s", personnel.id, payload.personnel_name)
        return out


def update_personnel(
    session: Session,
    personnel_id: int,
    payload: PersonnelCreateIn,
    *,
    operator: User,
    meta: RequestMeta | None = None,
) -> PersonnelOut:
    """编辑人员（全量替换，不含状态）。

    经理自引用校验以**被编辑人员的 id** 为准：把经理改成自己是环引用。

    :raises NotFoundError: 人员不存在
    :raises BadRequestError: 岗位不存在或已停用 / 直属经理不合法
    """
    row = personnel_repository.get_with_names(session, personnel_id)
    with audit_service.audit(
        session,
        operator=operator,
        record=AuditRecord(
            module=MODULE_PERSONNEL,
            action=ACTION_UPDATE,
            summary=f"修改人员 {row[0].personnel_name if row else f'#{personnel_id}'}",
            request_data=payload.model_dump(exclude_none=True),
        ),
        meta=meta,
    ):
        if row is None:
            raise NotFoundError("人员不存在")
        personnel = session.get(Personnel, personnel_id, with_for_update=True, populate_existing=True)
        role, manager_name = _validate_refs(
            session, payload.business_role_id, payload.manager_id, personnel.id
        )
        from app.services.personnel_salary import FIELDS, begin_update, save_version

        salary_changed = any(str(getattr(personnel, key)) != str(getattr(payload, key)) for key in FIELDS)
        effective = payload.salary_effective_date or date.today()
        history = begin_update(session, personnel, effective) if salary_changed else None
        personnel.personnel_name = payload.personnel_name
        personnel.business_role_id = payload.business_role_id
        personnel.manager_id = payload.manager_id
        personnel.phone = payload.phone
        personnel.hire_date = payload.hire_date
        personnel.is_probation = payload.is_probation
        personnel.probation_start_date = payload.probation_start_date
        personnel.regularization_date = payload.regularization_date
        personnel.resignation_date = payload.resignation_date
        personnel.salary_standard = _parse_salary(payload.salary_standard)
        personnel.remark = payload.remark
        if salary_changed:
            save_version(personnel, effective, history)
        # 响应与后置动作全部在 commit 之前完成（见 user_service 顶部说明）
        out = _to_out(personnel, role.role_name, manager_name)
        session.commit()
        logger.info("修改人员 | personnel_id=%s", personnel_id)
        return out


def delete_personnel(
    session: Session,
    personnel_id: int,
    *,
    operator: User,
    meta: RequestMeta | None = None,
) -> None:
    """删除人员。有团队成员或客户归属引用时禁删，引导走「离职」。

    查询走 ``FOR UPDATE`` 锁行：校验与删除之间若发生并发引用，锁行使
    并发外键写入在删除时失败（可见的 400）而非引用被静默悬空。

    :raises NotFoundError: 人员不存在
    :raises BadRequestError: 存在团队成员或客户归属引用
    """
    personnel = personnel_repository.get_by_id(session, personnel_id, for_update=True)
    with audit_service.audit(
        session,
        operator=operator,
        record=AuditRecord(
            module=MODULE_PERSONNEL,
            action=ACTION_DELETE,
            summary=f"删除人员 {personnel.personnel_name if personnel else f'#{personnel_id}'}",
        ),
        meta=meta,
    ):
        if personnel is None:
            raise NotFoundError("人员不存在")

        ids = [personnel_id]
        if (
            personnel_repository.count_team_members(session, ids)
            or personnel_repository.count_customer_ownerships(session, ids)
            or personnel_repository.count_business_roles_refs(session, ids)
        ):
            # 业务归属引用（负责/协助）随业务表就位一并纳入删除保护——
            # 漏检会让删除以 FK RESTRICT 的 500 暴露而非可读的 400
            raise BadRequestError(_DELETE_BLOCKED)

        name = personnel.personnel_name  # 固化：对象随删除失效
        try:
            personnel_repository.delete(session, personnel)
            session.commit()
        except IntegrityError as exc:
            # 校验与删除之间并发新增了团队成员/客户归属，FK RESTRICT 令删除失败
            session.rollback()
            raise BadRequestError(_DELETE_BLOCKED) from exc
        logger.info("删除人员 | personnel_id=%s | name=%s", personnel_id, name)


def set_status(
    session: Session,
    personnel_id: int,
    status: int,
    *,
    effective_date: date | None = None,
    operator: User,
    meta: RequestMeta | None = None,
) -> PersonnelOut:
    """在职/离职切换。

    人员语义不用「启用/禁用」词表，action 记 ACTION_UPDATE、摘要写明去向。

    :raises NotFoundError: 人员不存在
    """
    row = personnel_repository.get_with_names(session, personnel_id)
    verb = "设为在职" if status == 1 else "设为离职"
    with audit_service.audit(
        session,
        operator=operator,
        record=AuditRecord(
            module=MODULE_PERSONNEL,
            action=ACTION_UPDATE,
            summary=f"{verb} {row[0].personnel_name if row else f'#{personnel_id}'}",
            request_data={"status": status},
        ),
        meta=meta,
    ):
        if row is None:
            raise NotFoundError("人员不存在")
        _, role_name, manager_name = row
        personnel = session.get(Personnel, personnel_id, with_for_update=True, populate_existing=True)
        from app.services.personnel_salary import begin_update, save_version

        effective = effective_date or date.today()
        history = begin_update(session, personnel, effective)
        previous_status = personnel.status
        personnel.status = status
        if status == 0:
            personnel.resignation_date = effective
        else:
            personnel.resignation_date = None
            if previous_status == 0:
                personnel.hire_date = effective
        save_version(personnel, effective, history)
        out = _to_out(personnel, role_name, manager_name)
        session.commit()
        logger.info("变更人员状态 | personnel_id=%s | status=%s", personnel_id, status)
        return out


def replace_regions(
    session: Session,
    personnel_id: int,
    payload: RegionReplaceIn,
    *,
    operator: User,
    meta: RequestMeta | None = None,
) -> None:
    """全量替换辐射区域，空列表即清空。

    :raises NotFoundError: 人员不存在
    """
    row = personnel_repository.get_with_names(session, personnel_id)
    with audit_service.audit(
        session,
        operator=operator,
        record=AuditRecord(
            module=MODULE_PERSONNEL,
            action=ACTION_UPDATE,
            summary=f"维护辐射区域 {row[0].personnel_name if row else f'#{personnel_id}'}",
            request_data=payload.model_dump(),
        ),
        meta=meta,
    ):
        if row is None:
            raise NotFoundError("人员不存在")
        rows = [
            PersonnelRegion(
                personnel_id=personnel_id, region_name=item.region_name, remark=item.remark
            )
            for item in payload.items
        ]
        personnel_repository.replace_regions(session, personnel_id, rows)
        session.commit()
        logger.info("维护辐射区域 | personnel_id=%s | 条目数=%s", personnel_id, len(rows))


def replace_plans(
    session: Session,
    personnel_id: int,
    payload: PlanReplaceIn,
    *,
    operator: User,
    meta: RequestMeta | None = None,
) -> None:
    """全量替换拓展计划，空列表即清空。

    :raises NotFoundError: 人员不存在
    """
    row = personnel_repository.get_with_names(session, personnel_id)
    with audit_service.audit(
        session,
        operator=operator,
        record=AuditRecord(
            module=MODULE_PERSONNEL,
            action=ACTION_UPDATE,
            summary=f"维护拓展计划 {row[0].personnel_name if row else f'#{personnel_id}'}",
            request_data=payload.model_dump(),
        ),
        meta=meta,
    ):
        if row is None:
            raise NotFoundError("人员不存在")
        rows = [
            PersonnelPlan(
                personnel_id=personnel_id,
                plan_period=item.plan_period,
                plan_content=item.plan_content,
                target_desc=item.target_desc,
            )
            for item in payload.items
        ]
        personnel_repository.replace_plans(session, personnel_id, rows)
        session.commit()
        logger.info("维护拓展计划 | personnel_id=%s | 条目数=%s", personnel_id, len(rows))


def _to_out(personnel: Personnel, role_name: str | None, manager_name: str | None) -> PersonnelOut:
    """ORM 对象转响应模型。禁止把 ORM 对象直接当 response_model。"""
    return PersonnelOut(
        id=personnel.id,
        personnel_name=personnel.personnel_name,
        business_role_id=personnel.business_role_id,
        role_name=role_name,
        manager_id=personnel.manager_id,
        manager_name=manager_name,
        phone=personnel.phone,
        hire_date=personnel.hire_date,
        is_probation=personnel.is_probation,
        probation_start_date=personnel.probation_start_date,
        regularization_date=personnel.regularization_date,
        resignation_date=personnel.resignation_date,
        salary_standard=(
            str(personnel.salary_standard) if personnel.salary_standard is not None else None
        ),
        status=personnel.status,
        remark=personnel.remark,
    )


def _validate_refs(
    session: Session,
    business_role_id: int,
    manager_id: int | None,
    self_id: int | None,
) -> tuple[BusinessRole, str | None]:
    """新选经理须在职且绑定启用的经理计提岗位；原有参考关系保留供核对。

    ``self_id`` 编辑时传被编辑人员的 id、新增时传 None（新增不存在「自己」）。
    返回岗位行与经理姓名供响应 DTO 复用，避免提交后再查一次。

    :raises BadRequestError: 岗位不存在或已停用 / 直属经理不合法
    """
    role = business_role_repository.get_by_id(session, business_role_id)
    if role is None or role.status != 1:
        raise BadRequestError("岗位不存在或已停用")

    manager_name: str | None = None
    if manager_id is not None:
        if manager_id == self_id:
            raise BadRequestError("直属经理不能是自己")
        manager = personnel_repository.get_by_id(session, manager_id)
        if manager is None:
            raise BadRequestError("直属经理不存在或已离职")
        original = session.get(Personnel, self_id) if self_id is not None else None
        unchanged = original is not None and original.manager_id == manager_id
        if manager.status != 1 and not unchanged:
            raise BadRequestError("直属经理不存在或已离职")
        manager_role = business_role_repository.get_by_id(session, manager.business_role_id)
        if not unchanged and (
            manager_role is None or manager_role.status != 1
            or calc_templates.formula_type_of(session, manager_role.calc_template) != "manager_share"
        ):
            raise BadRequestError("直属经理须选择在职且使用经理计提模板的启用岗位人员")
        manager_name = manager.personnel_name
    return role, manager_name


def _parse_salary(value: str | None) -> Decimal | None:
    """入参字符串转 Decimal 存库。

    格式、非负与容量已在 schema 层校验，此处只做类型转换 ——
    金额红线：全程 Decimal，不经 float。
    """
    return Decimal(value) if value is not None else None