group_xinghuo_jinrong/app/api/convert_admin.py

"""基金转换对外接口（T-9 · **路径与字段一律以 PRD 为准**）。

PRD §5.5 / §5.7 给出的三条契约路径，分挂两族前缀：

- `/api/simulate/trade/convert/...`：**撤单**（§5.5）+ **查询**（§5.7）——
  交易动作与查询，延续 simulate 网关语义（与 §5.1 `POST /api/simulate/trade` 同族）；
- `/api/admin/convert/confirm`：**确认批处理触发**（§5.7）—— 运维接口。

> ⚠️ **路径出处**：本模块路径**不是自拟**。开发计划 T-9 初稿曾自拟
> `/api/convert/{gid}/cancel` 等三条路径，与 PRD 原文完全不同；经用户
> 2026-09-11 裁定**以 PRD 为准**（见开发计划 §1.3 裁定 11）。
> 三轮独立审查当时未发现该差异，根因与补救见开发计划 §9 第 10 条。

**鉴权：两道闸门严格分离（红线 7，不可合并）**

====================  ==========================================  ==========================
接口                 闸门                                        理由
====================  ==========================================  ==========================
撤单（§5.5）         **交易 owner**（本人或 `risk_demo`）        撤单是资金动作，与下单同权限
查询（§5.7）         **查询 scope**（`assert_customer_access`）  本人 / 已分配顾问 / risk_officer
确认（§5.7）         **admin 级**（`risk_officer`）              触发全量批处理，非客户动作
====================  ==========================================  ==========================

**错误体**：convert 服务层异常（`ConvertError` 子类）本身即 `ApiError`，由
`utils/response.register_error_handlers` 统一转 `{error_code, message, trace_id,
request_id}`（结构性附加字段 `extra` 自动展开，见该模块 T-9 注释）——
故本层**不捕获、不重包**，避免把 409/503 漂移成 500。

**确认接口的参数名与语义**（开发计划 §1.3 裁定 12）：参数名沿用 PRD 的
`accept_date`，**语义取 PRD §5.7 表格口径「业务日」**（= 业务确认日 T+1），
直接映射 `confirm_batch(as_of=accept_date)`。PRD 代码块注释写「按受理日批量确认」
与同节表格口径「可指定业务日」**字面冲突**，取后者（与 R-1 实现一致）。
⚠️ 批处理的捞单窗口是「受理日 ∈ [业务日上推 SLA 个交易日, 业务日]」的**批量**语义，
**不是**「精确某一天受理」。
"""

from __future__ import annotations

import logging
from datetime import datetime
from typing import Any

from fastapi import APIRouter, Depends, Query

from app.api.deps import (
    AuthContext,
    assert_customer_access,
    deny,
    get_auth_context,
)
from app.repository.convert_request_repository import (
    REMARK_FULL_TRANSFER,
    STATUS_CONFIRMED,
)
from app.repository.core_ro import CoreReadOnlyRepository
from app.repository.risk_repository import RiskRepository
from app.service.convert.confirm_service import confirm_batch
from app.service.convert.convert_service import (
    cancel_convert,
    rebuild_convert_response,
    t1_t2_dates,
)
from app.service.convert.errors import (
    ConcurrentConflict,
    ConvertRequestNotFound,
)
from app.service.convert.format import D2, q
from app.service.convert.types import to_decimal, to_datetime
from app.utils.exceptions import ApiError

logger = logging.getLogger(__name__)

#: 撤单 + 查询（PRD §5.5 / §5.7 · 延续 simulate 网关语义）。
simulate_convert_router = APIRouter(
    prefix="/api/simulate/trade/convert", tags=["convert"]
)
#: 确认批处理触发（PRD §5.7 · 运维接口）。
admin_convert_router = APIRouter(prefix="/api/admin/convert", tags=["convert-admin"])

#: PRD §5.3.2 确认结果中**仅确认段才产生**的折算字段白名单。
#: 未确认的单不得出现这些键（Q2：确认前不返回折算金额）。
_CONFIRMED_ONLY_FIELDS = (
    "out_trade_id",
    "out_nav",
    "out_amount",
    "lot_count",
    "lot_breakdown",
    "redeem_fee",
    "in_trade_id",
    "in_nav",
    "convert_amount",
    "diff_fee",
    "in_amount",
    "in_qty",
    "rounding_diff",
    "out_subscribe_fee_rate",
    "in_subscribe_fee_rate",
    "nav_date",
    "nav_stale",
    "forced_full_transfer",
)


def _core() -> CoreReadOnlyRepository:
    """只读仓储（测试 monkeypatch 点）。"""
    return CoreReadOnlyRepository()


def _repo() -> RiskRepository:
    """审计仓储（deny 留痕用；测试 monkeypatch 点）。"""
    return RiskRepository()


def _require_trade_owner(
    auth: AuthContext, customer_id: str, risk_repo: RiskRepository
) -> None:
    """**交易 owner 闸门**（撤单用）· 与 `simulate.py` 下单闸门口径一致。

    仅「`risk_demo` 演示角色」或「客户本人」放行 —— 代理人（advisor）是
    **查询 scope** 的受益者，**不得**替客户撤单（红线 7：两类闸门不可合并）。
    """
    if auth.has_role("risk_demo") or (
        auth.is_customer() and auth.customer_id == customer_id
    ):
        return
    deny(
        auth,
        "AUTH_403_ROLE",
        risk_repo,
        customer_id=customer_id,
        message="risk_demo or owner customer only",
        agent_type="platform",  # 网关越权与放行审计同口径（simulate 复审 P3）
    )


def _load_request_or_404(
    convert_group_id: str, core: CoreReadOnlyRepository
) -> dict[str, Any]:
    """读受理单；不存在 → 404 `CONVERT_REQUEST_NOT_FOUND`（PRD §8.3）。"""
    row = core.get_convert_request(convert_group_id)
    if row is None:
        raise ConvertRequestNotFound(f"受理单不存在：{convert_group_id}")
    return row


def _query_response(
    row: dict[str, Any], core: CoreReadOnlyRepository
) -> dict[str, Any]:
    """查询响应（PRD §5.3.2；未确认 → 仅受理字段，**无折算金额** · Q2）。

    `requested_qty` 的取值说明：受理段已把「强制全转」收敛为实转量并记入
    `core_convert_request.qty`，**原始申请量不外存**（审计 summary 有，
    但表内无列）→ 此处 `requested_qty` 即 `qty`（受理承诺量），
    `actual_qty` 取列值（确认段部分成交才写，未确认为 `None`）。
    这是**如实映射**，不臆造「原始申请量」字段。
    """
    gid = str(row["convert_group_id"])
    status = str(row["status"])
    accept_date = to_datetime(row["requested_at"]).date()
    confirm_date, available_date = t1_t2_dates(accept_date, core)
    remark = str(row.get("remark") or "")
    qty = to_decimal(row["qty"])

    resp: dict[str, Any] = {
        "convert_group_id": gid,
        "client_request_id": row.get("client_request_id"),
        "status": status,
        "customer_id": str(row["customer_id"]),
        "from_product_id": str(row["from_product_id"]),
        "to_product_id": str(row["to_product_id"]),
        # 受理承诺量（受理段已收敛强制全转）；确认段可能因部分成交更小
        "requested_qty": q(qty, D2),
        "actual_qty": q(to_decimal(row["actual_qty"]), D2)
        if row.get("actual_qty") is not None
        else None,
        "accept_date": str(accept_date),
        "confirm_date": confirm_date,
        "available_date": available_date,
        "cancel_deadline": str(row["cancel_before"])
        if row.get("cancel_before") is not None
        else None,
        "requested_at": str(row["requested_at"]),
        "confirmed_at": str(row["confirmed_at"])
        if row.get("confirmed_at") is not None
        else None,
        "remark": remark or None,
        "confirmed": status == STATUS_CONFIRMED,
    }
    # 受理段的强制全转决策**可从未确认的单读出**（`remark` 由受理落库传承）
    resp["forced_full_transfer"] = REMARK_FULL_TRANSFER in remark.split(";")

    if status == STATUS_CONFIRMED:
        detail = rebuild_convert_response(gid, core_ro=core)
        if detail is None:
            # 状态已 confirmed 但流水不足：属数据完整性异常，留痕不猜数
            logger.error("查询：受理单已 confirmed 但 Core 流水不足，无法重建折算结果：%s", gid)
        else:
            resp.update({k: detail[k] for k in _CONFIRMED_ONLY_FIELDS if k in detail})
            resp["confirmed"] = True
    return resp


@simulate_convert_router.post("/{convert_group_id}/cancel")
def cancel_convert_api(
    convert_group_id: str,
    auth: AuthContext = Depends(get_auth_context),
) -> Any:
    """撤单（PRD §5.5 / FR-C22 · R-9）：T 日 15:00 前且 `accepted` → `cancelled`。

    - 受理单不存在 → 404；非 `accepted` 或已过窗口 → **409 `CANCEL_NOT_ALLOWED`**
      （含「已确认后再撤」—— 状态闸门先于时间闸门，语义更准）；
    - 鉴权：**交易 owner 闸门**（本人 / `risk_demo`），代理人不可撤（红线 7）；
    - 占用释放：由「未终态受理单」推导（R-3），状态迁到 `cancelled` 即离开该集合，
      **无需写任何份额**（不新增冻结列）。
    """
    core = _core()
    repo = _repo()
    row = _load_request_or_404(convert_group_id, core)
    _require_trade_owner(auth, str(row["customer_id"]), repo)
    return cancel_convert(
        convert_group_id, core_ro=core, risk_repo=repo, actor_id=auth.actor_id
    )


@simulate_convert_router.get("/{convert_group_id}")
def query_convert_api(
    convert_group_id: str,
    auth: AuthContext = Depends(get_auth_context),
) -> Any:
    """查询受理单与确认结果（PRD §5.7 / §5.3.2）。

    鉴权：**查询 scope 闸门**（`assert_customer_access`：本人 / 已分配顾问 /
    `risk_officer`）—— 与撤单的 owner 闸门**不可合并**（代理人可查不可撤）。
    """
    core = _core()
    repo = _repo()
    row = _load_request_or_404(convert_group_id, core)
    assert_customer_access(auth, str(row["customer_id"]), core, repo)
    return _query_response(row, core)


@admin_convert_router.post("/confirm")
def confirm_convert_api(
    accept_date: str = Query(
        ...,
        description=(
            "业务确认日（YYYY-MM-DD）。⚠️ 参数名沿用 PRD §5.7（`accept_date`），"
            "语义取同节表格口径「业务日」= 业务确认日 T+1（裁定 12）。"
        ),
        pattern=r"^\d{4}-\d{2}-\d{2}$",
    ),
    auth: AuthContext = Depends(get_auth_context),
) -> Any:
    """触发 T+1 确认批处理（PRD §5.7 / FR-C23 · R-1）。

    - 鉴权：**admin 级**（`risk_officer`）—— 触发全量批处理，非客户动作；
    - 串行、单笔容错、整批判处理锁 `convert:confirm:{as_of}`（防双跑）；
    - **未抢到锁** → 409 `CONCURRENT_CONFLICT`（而非静默返回 `confirmed=0` 的空成功，
      后者会被误读成「今日无待确认单」）；
    - 缺 T 日净值 → 该单 `nav_pending`，本轮跳过，**不 reject、不降级**（FR-C27）。
    """
    if not auth.has_role("risk_officer"):
        deny(auth, "AUTH_403_ROLE", _repo(), message="risk_officer only")
    as_of = _parse_as_of(accept_date)
    result = confirm_batch(as_of, actor_id=auth.actor_id)
    if not result.get("locked", True):
        # 服务层对「未抢到锁」的既有语义是「让路、本轮不处理」（返回 locked=False，
        # 不抛异常 —— 它是批处理内部的防双跑机制）。API 层将其显式化为 409，
        # 让调用方区分「锁占用」与「确实没有待确认单」。
        raise ConcurrentConflict(
            f"{as_of} 的确认批处理正在执行中（未抢到批处理锁），本轮未处理"
        )
    return result


def _parse_as_of(raw: str) -> Any:
    """`accept_date` query 参数 → `date`（格式错误 → 400，不走业务异常）。"""
    try:
        return datetime.strptime(raw, "%Y-%m-%d").date()
    except ValueError as exc:
        raise ApiError(
            400, "BAD_REQUEST", f"accept_date 需为 YYYY-MM-DD 格式，实际 {raw!r}"
        ) from exc


__all__ = ["simulate_convert_router", "admin_convert_router"]