Mas Game Sign

游戏社区签到

核心要义

签到是凭据驱动的批量外部请求，不是脚本适配。它的风险集中在三处：用户凭据、上游风控、重复触发。改动时先确认属于哪一层：

1. 平台适配层（app/tools/<platform>.py）：单个社区的登录、角色发现、签到请求、风控退避。上游 API 知识来自被致谢的第三方项目，文件头的 AGPL/致谢声明必须保留。
2. 编排层（app/tools/game_sign.py）：账号遍历、平台注册表、并发、锁、日期标记、凭据回写、结果归一。
3. 消费层（app/tools/game_sign_notify.py、game_sign_result.py、API、前端）：结果展示与通知。

新增或修改平台时，只应动第 1 层加注册表一行。若发现必须改编排层才能容纳新平台，先停下来确认是不是抽象放错了位置。

当前架构

平台注册表是唯一入口

app/tools/game_sign.py 的 _GAME_SIGN_PROVIDERS 是不可变元组，每项 _GameSignProvider(frozen=True) 声明五件事：

当前四项：SklandToken/森空岛、MiyousheToken/米游社、KuroToken/库街区、TaygedoToken/塔吉多。

GAME_SIGN_TOKEN_FIELDS 由注册表派生，has_game_sign_credentials() 又由它派生。不要另写一份平台或字段清单：调度台跳过账号、前端判空、通知分组都应回到注册表。

只有塔吉多使用动态 resolve_platforms（_resolve_taygedo_platforms）：一份凭据可能同时覆盖塔吉多与云异环两个平台名。其余三家用 _fixed_platforms(...) 返回单元素元组。新增「一份凭据对多平台」的社区时照塔吉多写，不要在 runner 里硬编码平台名。

后端文件职责

app/tools/__init__.py 的 __all__ 只有四项：run_all_sign_in、format_sign_results、login_skland_with_password、skland_sign_in。其余符号按需从具体模块导入，且多数调用点使用函数内延迟导入以避免启动期循环依赖；沿用这个写法，不要为了「统一出口」把签到模块提到包顶层导入。

前端表面

useGameSignApi.ts 是薄封装：每个方法一行转发到 @/api 的生成客户端。新增路由时在此加一行并从返回对象导出，不要在此写状态、缓存或错误吞掉逻辑。

新增一个签到平台

按此顺序，每步都能独立自查：

1. 写平台适配模块 app/tools/<platform>.py。对外只暴露一个「跑一次签到」的入口与必要的凭据解析/校验函数。若参考了第三方项目的接口知识，按现有模块的写法在文件头加致谢与许可声明。
2. 加凭据字段：在 app/models/config.py 的 GameSignAccountGroup 增加 <Name>Token，section 固定为 "GameSignAccount"，validator 必须是 EncryptValidator()，并在字段上方写 ## GameSignAccount - <说明> (DPAPI 加密) 注释。
3. 加 schema 字段：app/models/schema.py 的 GameSignAccountGroupConfig 增加同名可选字段。这是 API 出入口，字段名与配置项保持一致。
4. 写 provider runner：在 game_sign.py 加 _run_<platform>_provider()，返回 _ProviderRun(results=..., platforms=..., credential_updates=...)。
5. 注册：在 _GAME_SIGN_PROVIDERS 追加一项。GAME_SIGN_TOKEN_FIELDS、has_game_sign_credentials()、并发执行、凭据回写、日期标记全部自动生效。
6. 通知排序：在 game_sign_notify.py 的 _PLATFORM_ORDER 追加平台名。缺失时该平台会落到排序尾部而不是报错，容易漏掉。
7. 重新生成 OpenAPI 客户端，再在 TabGameSign.vue 加录入入口。禁止手改 frontend/src/api/**。

凭据与安全

签到是本仓少数直接持有用户账号密码的路径，规则从严：

1. 所有凭据字段用 EncryptValidator()（DPAPI 加密落盘）。新增凭据字段没有例外。
2. 一次性登录请求的密码字段用 SecretStr，用 .get_secret_value() 取值，不落盘、不进日志。
3. 登录路由的 except Exception 分支禁止 exc_info / logger.exception / 回显上游响应，只返回固定文案。参见 login_taygedo / login_skland 的注释：避免密码、请求对象或上游响应进入日志。
4. ValueError 才允许把消息带给用户（凭据不完整、格式错误等可预期原因）；其他异常统一返回泛化文案。
5. 登录成功后必须校验凭据完整性再落盘（塔吉多校验 accessToken/refreshToken/uid，森空岛校验 oauthToken/token/cred），缺字段视为登录失败。
6. 凭据刷新走 _ProviderRun.credential_updates：编排层在并发完成后统一比对新旧值并写回，值未变则跳过。不要在 runner 内部直接写 account.set()。
7. 读取凭据统一用 _read_game_sign_token()：它容忍旧账号对象缺少新增字段（AttributeError / KeyError 均返回空串）。直接 account.get(...) 会在旧配置上炸。

并发与重复触发

两把锁，语义不同，不要合并：

两把锁都是快速失败而非等待：if lock.locked(): raise。API 层把 GameSignInProgressError 映射为 code=409；timer 层降级为 logger.info 后跳过本次触发。新增触发入口时必须选一种处理，不要静默 await 到锁释放。

森空岛另有模块级 _skland_sign_lock（公共别名 skland_sign_lock，skland.py）：签到全流程与养成练度源（app/task/MAA/tools/cultivate/skland.py）共用，互斥签名 token 的两个独立轮换写者。练度源的凭据回写走注入的 save_credential 回调（core/config.py），不进 _ProviderRun.credential_updates——它不是注册表 runner；改这两条链路时必须保住这把互斥锁，否则会把对方刚回写的 token 作废（community_sign.py 收尾回写前重读存量、发现已被轮换即跳过，也是防同一件事）。

通知必须在流程锁外发送。慢渠道会阻塞后续操作，这是锁边界画在落盘之后的原因。

日期标记有两层，不要混用：

• 账号级 GameSignAccount.LastSignDate：_run_all_sign_in 内按账号写。自动模式（force=False）即使失败也标记当天，避免后续 MAS 任务反复请求上游；手动模式（force=True）仅在该账号所有已配置平台完成后才标记。
• 全局 GameSign.LastSignDate：由调用方在所有启用且有凭据的账号都完成后才写。

多账号串行签到可能跨越 0 点，写入时重新取当前日期而不是复用循环开始时的 today。改这段逻辑要保留这个行为。