Files
live-hub-py/web/backend/routers/huya/collab.py
T
yml2213 df8c63b829 feat(huya): 外部 CK 协作台账(S1–S6)+ 图片上传能力
协作台账:新表 huya_external_orders 替代 Excel 多人协同表(设计见
docs/设计-虎牙外部CK协作台账.md),一条 CK 一行,所有人共享、改动留痕。

- 前端 pages/HuyaCollabPage.tsx + 菜单「虎牙 → 外部单协作」/huya/collab:
  内联编辑(带乐观锁 version)、图片缩略图、详情抽屉(字段表单 + 两个图片槽位 +
  操作时间线)、粘贴导入弹窗(带 TSV 预览)、批量/单条验证 CK、页头统计条、筛选
- 两套状态机:业务 pending→bound→recharged→scripted→done(旁路 void)、
  凭据 unverified/valid/invalid/disabled;唯一写入口在 services/huya_collab_service.py,
  字段级审计 + 整数 version 乐观锁(不用 updated_at:DATETIME 只到秒)
- CK 只读探针 check_user_bind_game_account(真机判据:响应非 None 且 status == 200),
  成功即覆盖写绑定快照 bind_game_account/bind_game_role/bind_game_channel(迁移 0056),
  失败只改凭据状态、不动业务状态;人工只能停用/恢复(POST /{id}/ck/status)
- 贴/换/重建 CK、TSV 批量导入(SAVEPOINT 单行隔离,部分失败不整体失败)、
  权限 huya:collab:view/edit/manage(删除只给运营)
- 孤儿图清理脚本 scripts/cleanup_orphan_file_assets.py(默认 --dry-run)

图片上传(协作台账截图用):OSS/本地双后端 + 缩略图变体 + /api/files 代理回读,
权限 file:upload / file:view。

验证:pytest 880 passed / 6 skipped;ruff format 全绿、ruff check 仅剩既有告警;
前端 tsc -b / eslint / vite build 通过;接口端到端冒烟 29 项全绿(TestClient,探针用假客户端);
探针真机冒烟 3 例(有效 CK=True、别人 uid=False、裸 cookie=False)。
2026-10-16 19:38:59 +08:00

372 lines
13 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""虎牙外部 CK 协作台账接口。
设计见 ``docs/设计-虎牙外部CK协作台账.md``。这一层只做三件事:
参数校验、权限、异常翻译;业务规则全在 ``services/huya_collab_service.py``。
权限:
- 查看 = ``huya:collab:view``(运营 + 客服)
- 编辑 = ``huya:collab:edit``(运营 + 客服;共享表,改动靠审计留痕)
- 删除 = ``huya:collab:manage``(**只给运营**)
图片上传不在这里:前端直接调 ``POST /api/files/upload``,把返回的 object_key
提交给本模块的 images 接口。
CK 验证是**只读探针**(``POST .../verify`` 单条、``POST .../ck/verify`` 批量):
人工触发、串行带间隔,不建 ``HuyaAccount``、不改业务状态(设计文档 §5.2)。
"""
from __future__ import annotations
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy.orm import Session
from ...database import get_db
from ...deps import require_permission
from ...models import AuditLog, HuyaExternalOrder, User
from ...schemas import (
HuyaExternalOrderAuditOut,
HuyaExternalOrderCkRequest,
HuyaExternalOrderCkStatusRequest,
HuyaExternalOrderCreate,
HuyaExternalOrderImagesRequest,
HuyaExternalOrderImportRequest,
HuyaExternalOrderListOut,
HuyaExternalOrderOut,
HuyaExternalOrderOwnerOut,
HuyaExternalOrderStatusRequest,
HuyaExternalOrderSummaryOut,
HuyaExternalOrderUpdate,
HuyaExternalOrderVerifyOut,
HuyaExternalOrderVerifyRequest,
)
from ...services import huya_collab_service as collab
router = APIRouter()
_AUDIT_TARGET_PREFIX = "huya_external_order:"
_AUDIT_TIMELINE_LIMIT = 100
def _http_error(exc: collab.CollabError) -> HTTPException:
return HTTPException(status_code=exc.status_code, detail=exc.detail)
def _serialize_one(db: Session, order: HuyaExternalOrder) -> dict:
return collab.serialize_order(order, users=collab.users_by_id(db, [order]))
# --------------------------------------------------------------------------
# 字面量路径必须声明在 /{order_id} 之前,否则 "summary" 会被当成 id
# --------------------------------------------------------------------------
@router.get("/external-orders/summary", response_model=HuyaExternalOrderSummaryOut)
def external_orders_summary(
db: Session = Depends(get_db),
_current: User = Depends(require_permission("huya:collab:view")),
):
"""页头统计条:各业务状态计数 + CK 失效数。"""
return collab.summary(db)
@router.get("/external-orders/owners", response_model=list[HuyaExternalOrderOwnerOut])
def external_orders_owners(
db: Session = Depends(get_db),
_current: User = Depends(require_permission("huya:collab:view")),
):
"""负责人候选:全部活跃用户(不是权限边界,只是筛选/指派用)。"""
rows = (
db.query(User.id, User.username)
.filter(User.is_active.is_(True))
.order_by(User.username)
.all()
)
return [{"id": int(row[0]), "username": str(row[1])} for row in rows]
@router.get("/external-orders/shops", response_model=list[str])
def external_orders_shops(
db: Session = Depends(get_db),
_current: User = Depends(require_permission("huya:collab:view")),
):
"""已用过的店铺列表(筛选下拉)。"""
return collab.list_shops(db)
@router.get("/external-orders", response_model=HuyaExternalOrderListOut)
def list_external_orders(
shop: str = Query("", max_length=64),
owner_id: int | None = Query(None),
status: str = Query("", max_length=16),
ck_status: str = Query("", max_length=16),
keyword: str = Query("", max_length=128),
include_void: bool = Query(False, description="是否包含已作废的行(默认隐藏)"),
page: int = Query(1, ge=1),
page_size: int = Query(50, ge=1, le=200),
db: Session = Depends(get_db),
_current: User = Depends(require_permission("huya:collab:view")),
):
"""共享视图:默认不按人过滤(负责人只是筛选维度,不是权限边界)。"""
rows, total = collab.list_orders(
db,
shop=shop,
owner_id=owner_id,
status=status,
ck_status=ck_status,
keyword=keyword,
include_void=include_void,
page=page,
page_size=page_size,
)
names = collab.users_by_id(db, rows)
return {
"items": [collab.serialize_order(row, users=names) for row in rows],
"total": total,
"page": page,
"page_size": page_size,
}
@router.post("/external-orders", response_model=HuyaExternalOrderOut)
def create_external_order(
req: HuyaExternalOrderCreate,
db: Session = Depends(get_db),
current: User = Depends(require_permission("huya:collab:edit")),
):
"""新建一行(可同时贴一份外部 CK)。订单号唯一,重复会 409。"""
try:
order = collab.create_order(
db,
current,
order_no=req.order_no,
shop=req.shop,
owner_id=req.owner_id,
ck_text=req.ck_text,
bind_douyu_account=req.bind_douyu_account,
gift_name=req.gift_name,
remark=req.remark,
)
except collab.CollabError as exc:
raise _http_error(exc) from exc
return _serialize_one(db, order)
@router.post("/external-orders/import")
def import_external_orders(
req: HuyaExternalOrderImportRequest,
db: Session = Depends(get_db),
current: User = Depends(require_permission("huya:collab:edit")),
):
"""Excel 粘贴批量导入。单行失败只记在 ``errors`` 里,不影响其他行。"""
owners = {
str(name): int(user_id)
for user_id, name in db.query(User.id, User.username)
.filter(User.is_active.is_(True))
.all()
}
return collab.import_orders(db, current, req.text, owner_by_name=owners)
@router.post("/external-orders/ck/verify", response_model=HuyaExternalOrderVerifyOut)
def verify_external_orders_ck(
req: HuyaExternalOrderVerifyRequest,
db: Session = Depends(get_db),
current: User = Depends(require_permission("huya:collab:edit")),
):
"""批量验证 CK(只读探针):人工触发、串行、带间隔,不做定时轮询。
单条失败只记在 ``results`` 里,不影响其他条(AGENTS §2)。探针只读,
**不会**建 ``HuyaAccount``、也不会改业务状态。
"""
try:
orders = collab.list_orders_by_ids(db, req.ids)
return collab.verify_ck_batch(db, current, orders)
except collab.CollabError as exc:
raise _http_error(exc) from exc
# --------------------------------------------------------------------------
# 单行操作
# --------------------------------------------------------------------------
@router.get("/external-orders/{order_id}", response_model=HuyaExternalOrderOut)
def get_external_order(
order_id: int,
db: Session = Depends(get_db),
_current: User = Depends(require_permission("huya:collab:view")),
):
try:
order = collab.get_order(db, order_id)
except collab.CollabError as exc:
raise _http_error(exc) from exc
return _serialize_one(db, order)
@router.get(
"/external-orders/{order_id}/timeline",
response_model=list[HuyaExternalOrderAuditOut],
)
def external_order_timeline(
order_id: int,
db: Session = Depends(get_db),
_current: User = Depends(require_permission("huya:collab:view")),
):
"""操作时间线:直接读 ``audit_logs``,不另建事件表。"""
rows = (
db.query(AuditLog)
.filter(AuditLog.target == f"{_AUDIT_TARGET_PREFIX}{order_id}")
.order_by(AuditLog.id.desc())
.limit(_AUDIT_TIMELINE_LIMIT)
.all()
)
return [
{
"id": row.id,
"action": row.action,
"username": row.username or "",
"detail": row.detail or "",
"success": row.success,
"created_at": row.created_at,
}
for row in rows
]
@router.put("/external-orders/{order_id}", response_model=HuyaExternalOrderOut)
def update_external_order(
order_id: int,
req: HuyaExternalOrderUpdate,
db: Session = Depends(get_db),
current: User = Depends(require_permission("huya:collab:edit")),
):
"""编辑(部分字段)。带 ``expected_version`` 做乐观锁,冲突返回 409。"""
try:
order = collab.get_order(db, order_id)
payload = req.model_dump(exclude_unset=True)
expected_version = payload.pop("expected_version", None)
collab.update_order(
db, current, order, payload, expected_version=expected_version
)
except collab.CollabError as exc:
raise _http_error(exc) from exc
return _serialize_one(db, order)
@router.post("/external-orders/{order_id}/status", response_model=HuyaExternalOrderOut)
def update_external_order_status(
order_id: int,
req: HuyaExternalOrderStatusRequest,
db: Session = Depends(get_db),
current: User = Depends(require_permission("huya:collab:edit")),
):
"""推进/回退业务状态。回退必须显式带 ``rollback=true``。"""
try:
order = collab.get_order(db, order_id)
collab.assert_version(order, req.expected_version)
collab.set_status(
db,
current,
order,
req.status,
reason=req.reason,
rollback=req.rollback,
)
except collab.CollabError as exc:
raise _http_error(exc) from exc
return _serialize_one(db, order)
@router.post("/external-orders/{order_id}/ck", response_model=HuyaExternalOrderOut)
def update_external_order_ck(
order_id: int,
req: HuyaExternalOrderCkRequest,
db: Session = Depends(get_db),
current: User = Depends(require_permission("huya:collab:edit")),
):
"""贴入/换 CK(``action=paste``)或从 raw_cookie 重建(``action=rebuild``)。"""
try:
order = collab.get_order(db, order_id)
collab.assert_version(order, req.expected_version)
if req.action == "rebuild":
collab.rebuild_ck(db, current, order)
else:
collab.set_ck(db, current, order, req.ck_text)
except collab.CollabError as exc:
raise _http_error(exc) from exc
return _serialize_one(db, order)
@router.post(
"/external-orders/{order_id}/ck/status", response_model=HuyaExternalOrderOut
)
def update_external_order_ck_status(
order_id: int,
req: HuyaExternalOrderCkStatusRequest,
db: Session = Depends(get_db),
current: User = Depends(require_permission("huya:collab:edit")),
):
"""人工停用 / 恢复这份 CK(``disabled`` / ``unverified``)。
``valid`` / ``invalid`` **只能**由只读探针给(``POST .../verify``):
人工标「有效」等于绕过验证(设计文档 §4.2)。
"""
try:
order = collab.get_order(db, order_id)
collab.assert_version(order, req.expected_version)
collab.set_manual_ck_status(db, current, order, req.status, message=req.message)
except collab.CollabError as exc:
raise _http_error(exc) from exc
return _serialize_one(db, order)
@router.post("/external-orders/{order_id}/verify", response_model=HuyaExternalOrderOut)
def verify_external_order_ck(
order_id: int,
db: Session = Depends(get_db),
current: User = Depends(require_permission("huya:collab:edit")),
):
"""验证 CK(只读探针):写 ``ck_status`` / ``ck_checked_at`` / ``ck_check_message``。
成功时顺手补 ``bind_douyu_account`` / ``bind_douyu_uid``(**只补空值**)。
CK 失效**不会**自动改业务状态,列表上只做显式提示。
"""
try:
order = collab.get_order(db, order_id)
collab.verify_ck(db, current, order)
except collab.CollabError as exc:
raise _http_error(exc) from exc
return _serialize_one(db, order)
@router.post("/external-orders/{order_id}/images", response_model=HuyaExternalOrderOut)
def update_external_order_images(
order_id: int,
req: HuyaExternalOrderImagesRequest,
db: Session = Depends(get_db),
current: User = Depends(require_permission("huya:collab:edit")),
):
"""整槽替换图片(提交 ``/api/files/upload`` 返回的 object_key 数组)。"""
try:
order = collab.get_order(db, order_id)
collab.assert_version(order, req.expected_version)
collab.set_images(db, current, order, req.slot, req.images)
except collab.CollabError as exc:
raise _http_error(exc) from exc
return _serialize_one(db, order)
@router.delete("/external-orders/{order_id}")
def delete_external_order(
order_id: int,
db: Session = Depends(get_db),
current: User = Depends(require_permission("huya:collab:manage")),
):
"""删除一行(**只给运营**)。只删行,不删 OSS 里的图(交给孤儿清理脚本)。"""
try:
order = collab.get_order(db, order_id)
snapshot = collab.delete_order(db, current, order)
except collab.CollabError as exc:
raise _http_error(exc) from exc
return {"success": True, "order_no": snapshot["order_no"]}