PayrollManagementSystem/backend/app/schemas/business.py

"""业务管理的请求/响应模型（需求 2.2.1/2.2.4）。

金额/数量入参出参一律 str（服务层 Decimal/Fraction，全程禁 float）；
派生值（毛利润额/毛利润率/折算毛利润额）不在写接口入参内 —— 落库列只有
源数据，派生值由毛利润视图实时计算。
"""

from datetime import date, datetime
from decimal import Decimal, InvalidOperation

from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator

from app.core.constants import (
    PRODUCT_CATEGORIES,
    PRODUCT_CATEGORY_MUNICIPAL_WATER,
    PRODUCT_CATEGORY_RAIL_TRANSIT,
)
from app.core.response import PageQuery

# DECIMAL(14,2) 容量上限：整数部分 12 位（同 personnel.py 的金额校验口径）
AMOUNT_MAX = Decimal("999999999999.99")
# DECIMAL(14,4) 容量上限：整数部分 10 位
PRICE_MAX = Decimal("9999999999.9999")


def _check_amount(
    value: str | None, label: str, cap: Decimal, allow_positive_only: bool = False
) -> str | None:
    """字符串金额的通用校验：数字/有限/非负/容量/两位小数。

    小数位超过两位直接拒绝而非静默舍入 —— 舍入即算错钱（工资系统红线）。
    """
    if value is None:
        return None
    try:
        amount = Decimal(value)
    except InvalidOperation:
        raise ValueError(f"{label}须为有效数字") from None
    if not amount.is_finite():
        raise ValueError(f"{label}须为有效数字")
    if allow_positive_only:
        if amount <= 0:
            raise ValueError(f"{label}必须大于 0")
    elif amount < 0:
        raise ValueError(f"{label}不能为负数")
    if amount > cap:
        raise ValueError(f"{label}超出可录入上限")
    if -amount.as_tuple().exponent > 2:
        raise ValueError(f"{label}最多两位小数")
    return value


class BusinessItemIn(BaseModel):
    """业务产品明细行（需求 2.2.1「支持添加多种产品，录入指导价」）。

    product_category 保留蛇形：该值与 M1 参数维度值域同源（枚举码本就是
    蛇形）；其余标识类字段驼峰兼容（snake/驼峰双入，同 customer.py 契约）。
    """

    model_config = ConfigDict(str_strip_whitespace=True)

    product_id: int | None = Field(default=None, ge=1, description="产品ID；空=自由录入")
    product_name: str = Field(min_length=1, max_length=128, description="产品名称")
    spec_model: str | None = Field(
        default=None, max_length=128, description="规格型号，空=空串归一"
    )
    unit: str | None = Field(default=None, max_length=16, description="计量单位")
    product_category: str = Field(
        description="产品类别：municipal_water/rail_transit（行级折算锚点）"
    )
    quantity: str = Field(description="数量，>0")
    sale_price: str | None = Field(default=None, description="销售单价（元）")
    cost_amount: str | None = Field(
        default=None, description="成本额（元）；毛利润额 = 销售额 − 成本额"
    )
    guided_price: str | None = Field(default=None, description="指导价（元）")
    remark: str | None = Field(default=None, max_length=255)

    @field_validator("product_category")
    @classmethod
    def _check_category(cls, value: str) -> str:
        if value not in PRODUCT_CATEGORIES:
            raise ValueError("产品类别不合法")
        return value

    @field_validator("quantity")
    @classmethod
    def _check_quantity(cls, value: str) -> str:
        return _check_amount(value, "数量", AMOUNT_MAX, allow_positive_only=True) or value

    @field_validator("sale_price", "cost_amount", "guided_price")
    @classmethod
    def _check_prices(cls, value: str | None) -> str | None:
        return _check_amount(value, "金额", PRICE_MAX)


class BusinessItemOut(BaseModel):
    """业务产品明细行响应。金额/数量一律 str。"""

    model_config = ConfigDict(from_attributes=True)

    id: int
    product_id: int | None = None
    product_name: str
    spec_model: str | None = None
    unit: str | None = None
    product_category: str
    quantity: str
    sale_price: str | None = None
    sale_amount: str
    cost_amount: str | None = None
    guided_price: str | None = None
    remark: str | None = None


class BusinessOut(BaseModel):
    """业务响应（列表与写操作回包共用）。"""

    model_config = ConfigDict(from_attributes=True)

    id: int
    business_no: str
    customer_id: int
    customer_name: str | None = None
    business_date: date | None = None
    status: int = 1
    owner_personnel_id: int | None = None
    owner_personnel_name: str | None = None
    assistant_personnel_id: int | None = None
    assistant_personnel_name: str | None = None
    is_special: int = 0
    special_note: str | None = None
    total_sale_amount: str | None = None
    total_cost_amount: str | None = None
    total_ship_amount: str | None = None
    total_received_amount: str | None = None
    total_freight_amount: str | None = None
    remark: str | None = None


class BusinessDetailOut(BusinessOut):
    """业务详情：附产品明细行。"""

    items: list[BusinessItemOut] = Field(default_factory=list)


class BusinessCreateIn(BaseModel):
    """创建业务：主表信息 + 明细行数组（明细 ≥1 行）。

    字段名全线蛇形直出（M1 既有契约：前端 api 封装与 schemas 同名对应，
    仅分页信封 list/pageNum 驼峰）。
    """

    model_config = ConfigDict(str_strip_whitespace=True)

    customer_id: int = Field(ge=1, description="客户ID")
    business_date: date | None = Field(default=None, description="业务日期，ISO 格式")
    owner_personnel_id: int | None = Field(
        default=None, ge=1, description="负责营销人员ID，可空=待指定"
    )
    assistant_personnel_id: int | None = Field(default=None, ge=1, description="协助营销人员ID")
    is_special: int = Field(default=0, ge=0, le=1, description="特殊业务标记：1是 0否")
    special_note: str | None = Field(default=None, max_length=255, description="特殊业务说明")
    items: list[BusinessItemIn] = Field(min_length=1, description="产品明细行，至少 1 行")
    remark: str | None = Field(default=None, max_length=255)

    @model_validator(mode="after")
    def _check_special_note(self) -> "BusinessCreateIn":
        """特殊业务须有说明：标记的意义就在于可追溯「特殊在哪」。"""
        if self.is_special == 1 and not self.special_note:
            raise ValueError("特殊业务必须填写说明")
        return self


class BusinessUpdateIn(BaseModel):
    """编辑业务（全量替换明细；归属不在此端点调整，走 /ownership）。"""

    model_config = ConfigDict(str_strip_whitespace=True)

    customer_id: int = Field(ge=1, description="客户ID")
    business_date: date | None = Field(default=None, description="业务日期，ISO 格式")
    owner_personnel_id: int | None = Field(
        default=None,
        ge=1,
        description="负责营销人员ID（编辑端点忽略，仅 /ownership 生效）",
    )
    assistant_personnel_id: int | None = Field(
        default=None,
        ge=1,
        description="协助营销人员ID（编辑端点忽略）",
    )
    is_special: int = Field(default=0, ge=0, le=1, description="特殊业务标记：1是 0否")
    special_note: str | None = Field(default=None, max_length=255, description="特殊业务说明")
    items: list[BusinessItemIn] = Field(
        min_length=1, description="产品明细行，至少 1 行（全量替换）"
    )
    remark: str | None = Field(default=None, max_length=255)

    @model_validator(mode="after")
    def _check_special_note(self) -> "BusinessUpdateIn":
        if self.is_special == 1 and not self.special_note:
            raise ValueError("特殊业务必须填写说明")
        return self


class BusinessStatusIn(BaseModel):
    """状态流转：1执行中 → 2已完成 / 3已终止（终态不可再变更）。"""

    model_config = ConfigDict(str_strip_whitespace=True)

    status: int = Field(ge=1, le=3, description="目标状态：2已完成 3已终止")
    reason: str | None = Field(default=None, max_length=255, description="变更原因（终止时必填）")

    @model_validator(mode="after")
    def _check_reason(self) -> "BusinessStatusIn":
        if self.status == 3 and not self.reason:
            raise ValueError("终止业务必须填写原因")
        return self


class BusinessOwnershipIn(BaseModel):
    """业务归属变更（负责/协助；前后值写入留痕）。"""

    model_config = ConfigDict(str_strip_whitespace=True)

    new_owner_personnel_id: int | None = Field(default=None, ge=1)
    new_assistant_personnel_id: int | None = Field(default=None, ge=1)
    reason: str | None = Field(default=None, max_length=255)


class BusinessQuery(PageQuery):
    """业务列表查询条件（筛选参数驼峰 alias，customer.py 同款契约）。"""

    keyword: str | None = Field(default=None, max_length=32, description="业务编号/公司名称，模糊")
    status: int | None = Field(default=None, ge=1, le=3, description="状态筛选")
    customer_id: int | None = Field(default=None, ge=1, description="客户筛选")
    owner_personnel_id: int | None = Field(default=None, ge=1, description="负责营销人员筛选")
    date_from: date | None = Field(default=None, description="业务日期起（含）")
    date_to: date | None = Field(default=None, description="业务日期止（含）")


class GrossProfitRowOut(BaseModel):
    """毛利润视图行：行级源数据 + 派生值（实时计算，不落库）。"""

    item_id: int
    product_category: str
    product_name: str
    spec_model: str | None = None
    quantity: str
    sale_amount: str
    cost_amount: str | None = None
    """成本缺失（未录入）时为 None，派生列同为 None 并置 missing_reason"""
    profit_amount: str | None = None
    profit_rate: str | None = None
    threshold: str
    converted_profit: str | None = None
    missing_reason: str | None = None


class GrossProfitCategoryOut(BaseModel):
    """按产品类别的毛利润汇总（可计算行聚合；成本缺失行不计入）。"""

    product_category: str
    sale_amount: str
    cost_amount: str
    profit_amount: str
    profit_rate: str
    threshold: str
    converted_profit: str


class GrossProfitOut(BaseModel):
    """毛利润数据视图（需求 2.2.4）：行级 + 类别汇总。

    口径注释（前端须展示）：毛利润率 = 毛利润额 / 销售额，**不含运费**
    （对照表 #2 作废需规含运费公式）；阈值按 asOf 取 M1 参数快照；M3 核算
    实际按回款到账日取参，本视图默认今日仅供录入期核对。
    """

    business_id: int
    as_of: date
    rows: list[GrossProfitRowOut] = Field(default_factory=list)
    categories: list[GrossProfitCategoryOut] = Field(default_factory=list)
    missing_count: int = 0
    note: str = "毛利润率与折算额不含运费；M3 核算按回款到账日取参数版本"


class OwnershipChangeLogOut(BaseModel):
    """业务归属变更留痕（人员删除后姓名为 None，固化 ID 兜底可追溯）。"""

    id: int
    business_id: int
    old_owner_personnel_id: int | None = None
    new_owner_personnel_id: int | None = None
    old_assistant_personnel_id: int | None = None
    new_assistant_personnel_id: int | None = None
    old_owner_name: str | None = None
    new_owner_name: str | None = None
    change_reason: str | None = None
    operator_id: int | None = None
    operator_name: str
    create_time: datetime


class BusinessStatusLogOut(BaseModel):
    """业务状态流转记录（详情页时间线；创建首条 old=new=1）。"""

    model_config = ConfigDict(from_attributes=True)

    id: int
    business_id: int
    old_status: int
    new_status: int
    change_reason: str | None = None
    operator_id: int | None = None
    operator_name: str
    create_time: datetime


# 供 schema 外部引用的两类别常量（类别汇总展示用）
CATEGORY_LABELS = {
    PRODUCT_CATEGORY_MUNICIPAL_WATER: "市政水利",
    PRODUCT_CATEGORY_RAIL_TRANSIT: "轨道交通",
}