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)。
This commit is contained in:
yml2213
2026-10-16 19:38:59 +08:00
parent 99e8643d83
commit df8c63b829
32 changed files with 7449 additions and 16 deletions
@@ -0,0 +1,92 @@
"""上传文件台账表 `file_assets`(在线协作的图片落库)。
协作里用户上传的图片本体放对象存储(ECS 与桶同地域时走内网 endpoint,
``oss-<region>-internal.aliyuncs.com``),库里只留 key 与元数据:
- 图片一律经 ``/api/files/object?key=...`` 由后端代理回读,**不下发 OSS 直链**。
参考 order_site 踩过的坑:曾经发过「15 分钟有效的签名链接」,结果入库时把当时的
链接原样存了下来,之后任何不重签的地方过一会儿必然裂图;
- ``object_key`` 里带 12 字节随机段(``scene/yyyy/mm/dd/<24位hex><ext>``),
不可枚举,所以普通链接就够用;
- ``thumbnail_object_key`` / ``medium_object_key`` 为空表示缩略图生成失败,
回读接口按 `.thumb.webp → .thumb.jpg → .thumb.png → 原图` 逐个候选回退。
"""
from __future__ import annotations
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
revision: str = "20261016_0054"
down_revision: str | None = "20261015_0053"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
def _tables(bind) -> set[str]:
return set(sa.inspect(bind).get_table_names())
def upgrade() -> None:
bind = op.get_bind()
if "file_assets" in _tables(bind):
return
op.create_table(
"file_assets",
sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
# 对象存储里的 key:scene/yyyy/mm/dd/<24位随机hex><ext>
sa.Column("object_key", sa.String(length=512), nullable=False),
# 业务场景前缀(collab/… 等),同时决定公开还是私有
sa.Column("scene", sa.String(length=32), nullable=False, server_default="misc"),
sa.Column(
"original_filename",
sa.String(length=255),
nullable=False,
server_default="",
),
sa.Column(
"content_type", sa.String(length=64), nullable=False, server_default=""
),
sa.Column("size_bytes", sa.BigInteger(), nullable=False, server_default="0"),
sa.Column(
"thumbnail_object_key",
sa.String(length=512),
nullable=False,
server_default="",
),
sa.Column(
"medium_object_key",
sa.String(length=512),
nullable=False,
server_default="",
),
sa.Column(
"uploader_type", sa.String(length=32), nullable=False, server_default="user"
),
sa.Column(
"uploader_id", sa.String(length=64), nullable=False, server_default=""
),
sa.Column(
"status", sa.String(length=16), nullable=False, server_default="active"
),
sa.Column("metadata_json", sa.JSON(), nullable=True),
sa.Column("created_at", sa.DateTime(), nullable=False),
sa.Column("updated_at", sa.DateTime(), nullable=False),
)
# 回读接口按 key 精确定位,重复上传同一个 key 也要挡在唯一约束上。
op.create_index(
"ix_file_assets_object_key", "file_assets", ["object_key"], unique=True
)
op.create_index("ix_file_assets_scene", "file_assets", ["scene"])
op.create_index("ix_file_assets_uploader_id", "file_assets", ["uploader_id"])
def downgrade() -> None:
bind = op.get_bind()
if "file_assets" not in _tables(bind):
return
# MySQL 删表会连同索引一起删,不必逐个 drop_index。
op.drop_table("file_assets")
@@ -0,0 +1,147 @@
"""虎牙外部 CK 协作台账表 `huya_external_orders`(替代 Excel 多人协同表)。
**一行 = 一单 = 一个外部 CK**,设计见 ``docs/设计-虎牙外部CK协作台账.md``。
三个不能改错的地方:
1. **CK 独立存本表**(`cookie` / `raw_cookie`),刻意不写 `huya_accounts`、不做外键。
同一个虎牙号可能同时存在于两处、各自过期,那是设计上接受的代价(§2.3),
不是 bug;需要拿去跑任务时人工到工作台重新导入。
2. **`uid` 唯一但可空**:MySQL 的唯一索引允许多个 NULL,于是「先建单、后贴 CK」
与「一个虎牙号只能挂一单」能同时成立。别把它改成 NOT NULL —— 会让
「先建单」这条路直接写不进去。
3. **两套状态各管一摊**:`status`(业务进度)与 `ck_status`(凭据有效性)。
CK 失效不自动改业务状态,所以这两个列不要合并。
`cookie` / `raw_cookie` 同时登记进 `crypto_storage._SENSITIVE_COLUMNS`,
启动时的历史明文回填与落盘加密都靠那份清单。
"""
from __future__ import annotations
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
revision: str = "20261016_0055"
down_revision: str | None = "20261016_0054"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
def _tables(bind) -> set[str]:
return set(sa.inspect(bind).get_table_names())
def upgrade() -> None:
bind = op.get_bind()
if "huya_external_orders" in _tables(bind):
return
op.create_table(
"huya_external_orders",
sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
# Excel B 列:订单编号,台账内唯一。
sa.Column("order_no", sa.String(length=64), nullable=False),
# Excel A 列:店铺。
sa.Column("shop", sa.String(length=64), nullable=False, server_default=""),
# Excel C 列:负责人。
sa.Column("owner_id", sa.Integer(), nullable=True),
# 外部 CK:uid 唯一可空(空 = 还没贴 CK)。
sa.Column("uid", sa.String(length=32), nullable=True),
sa.Column("yyuid", sa.String(length=32), nullable=False, server_default=""),
sa.Column(
"hy_username", sa.String(length=128), nullable=False, server_default=""
),
sa.Column("nickname", sa.String(length=128), nullable=False, server_default=""),
# 加密列(EncryptedText 在应用层加解密,DDL 是普通文本列)。
sa.Column("cookie", sa.Text(), nullable=False),
sa.Column("raw_cookie", sa.Text(), nullable=False),
sa.Column(
"ck_status",
sa.String(length=16),
nullable=False,
server_default="unverified",
),
sa.Column("ck_checked_at", sa.DateTime(), nullable=True),
sa.Column(
"ck_check_message", sa.String(length=256), nullable=False, server_default=""
),
# Excel D 列:绑定斗鱼号。
sa.Column(
"bind_douyu_account",
sa.String(length=128),
nullable=False,
server_default="",
),
sa.Column(
"bind_douyu_uid", sa.String(length=32), nullable=False, server_default=""
),
# Excel E/F 列:截图(OSS object_key 数组;MySQL JSON 列不能带 DEFAULT)。
sa.Column("bind_images", sa.JSON(), nullable=True),
sa.Column("home_images", sa.JSON(), nullable=True),
# Excel G 列(表头写「备注」,实为礼包名)+ 自由备注。
sa.Column(
"gift_name", sa.String(length=128), nullable=False, server_default=""
),
sa.Column("remark", sa.String(length=512), nullable=False, server_default=""),
# 业务进度 + 各节点时间戳(时间戳是「做过」的证据,状态是「卡在哪」)。
sa.Column(
"status", sa.String(length=16), nullable=False, server_default="pending"
),
sa.Column("bound_at", sa.DateTime(), nullable=True),
sa.Column("recharged_at", sa.DateTime(), nullable=True),
sa.Column("scripted_at", sa.DateTime(), nullable=True),
sa.Column("done_at", sa.DateTime(), nullable=True),
sa.Column(
"void_reason", sa.String(length=256), nullable=False, server_default=""
),
# 只读查询快照(不写 huya_accounts)。
sa.Column("points", sa.Integer(), nullable=True),
sa.Column("elite_opened", sa.Boolean(), nullable=True),
sa.Column("snapshot_at", sa.DateTime(), nullable=True),
sa.Column("created_by", sa.Integer(), nullable=True),
sa.Column("updated_by", sa.Integer(), nullable=True),
# 乐观锁版本号(每次写入 +1)。不用 updated_at 当锁:DATETIME 只到秒,
# 同一秒内的两次改动会撞成同一个值,锁会失效。
sa.Column("version", sa.Integer(), nullable=False, server_default="0"),
sa.Column("created_at", sa.DateTime(), nullable=False),
sa.Column("updated_at", sa.DateTime(), nullable=False),
)
# 订单号 / uid 唯一(uid 可空 → 多个 NULL 不冲突)。
op.create_index(
"ix_huya_external_orders_order_no",
"huya_external_orders",
["order_no"],
unique=True,
)
op.create_index(
"ix_huya_external_orders_uid", "huya_external_orders", ["uid"], unique=True
)
# 列表筛选维度。
op.create_index("ix_huya_external_orders_shop", "huya_external_orders", ["shop"])
op.create_index(
"ix_huya_external_orders_owner_id", "huya_external_orders", ["owner_id"]
)
op.create_index(
"ix_huya_external_orders_status", "huya_external_orders", ["status"]
)
op.create_index(
"ix_huya_external_orders_ck_status", "huya_external_orders", ["ck_status"]
)
op.create_index(
"ix_huya_external_orders_created_by", "huya_external_orders", ["created_by"]
)
# updated_at 兼作乐观锁版本号,也是默认排序键。
op.create_index(
"ix_huya_external_orders_updated_at", "huya_external_orders", ["updated_at"]
)
def downgrade() -> None:
bind = op.get_bind()
if "huya_external_orders" not in _tables(bind):
return
# MySQL 删表会连同索引一起删,不必逐个 drop_index。
op.drop_table("huya_external_orders")
@@ -0,0 +1,70 @@
"""`huya_external_orders` 增加「探针读到的绑定对象」快照列。
背景(2026-10-16 真机确认):CK 探针 `check_user_bind_game_account` 返回的是**绑定在该
虎牙号上的游戏账号**(账号昵称 / 角色名 / 平台·区服)。"这单到底绑了哪个号、哪个角色"
只有这里可信 —— 原来的 `bind_douyu_account` 是人工填的自由文本(Excel D 列)。
四个新列都由**探针独占**:每次验证覆盖写入,`bind_snapshot_at` 记读取时间;
人工不直接编辑(所以不在 EDITABLE_FIELDS 里)。
老列 `bind_douyu_account` / `bind_douyu_uid` **保留不动**:Excel 粘贴导入还按它映射,
已填的历史数据也不能丢。
可重复执行:按列判断,缺哪列补哪列。
"""
from __future__ import annotations
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
revision: str = "20261016_0056"
down_revision: str | None = "20261016_0055"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
TABLE = "huya_external_orders"
# (列名, DDL 类型) —— 顺序即 DDL 顺序,方便人工核对。
_NEW_COLUMNS: tuple[tuple[str, sa.types.TypeEngine], ...] = (
("bind_game_account", sa.String(length=128)),
("bind_game_role", sa.String(length=128)),
("bind_game_channel", sa.String(length=128)),
("bind_snapshot_at", sa.DateTime()),
)
def _has_table(bind) -> bool:
return TABLE in set(sa.inspect(bind).get_table_names())
def _columns(bind) -> set[str]:
return {column["name"] for column in sa.inspect(bind).get_columns(TABLE)}
def upgrade() -> None:
bind = op.get_bind()
if not _has_table(bind):
return
existing = _columns(bind)
for name, column_type in _NEW_COLUMNS:
if name in existing:
continue
if name == "bind_snapshot_at":
op.add_column(TABLE, sa.Column(name, column_type, nullable=True))
else:
# 文本快照列必须有 server_default:NOT NULL 且无默认值会让已有行写不进去。
op.add_column(
TABLE, sa.Column(name, column_type, nullable=False, server_default="")
)
def downgrade() -> None:
bind = op.get_bind()
if not _has_table(bind):
return
existing = _columns(bind)
for name, _column_type in reversed(_NEW_COLUMNS):
if name in existing:
op.drop_column(TABLE, name)