协作台账:新表 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)。
372 lines
13 KiB
Python
372 lines
13 KiB
Python
"""虎牙外部 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"]}
|