Files
myrzx_bot/analysis/WEB_V2_CONTRACT.md
T

16 KiB
Raw Blame History

Web 2.0.0.dev1 协作契约

基线:main / v1.2.0 / 7fe4c0f。工作分支:develop/v2.0.0。 不合并 main、不发布正式版本;本轮 API owner 不提交、不推送,验证后由 Main 按既有授权 决定推送 develop/v2.0.0 供用户测试。保留桌面兼容;Web 导入链不得包含 PySide6、gui 或 *_gui。现有功能按原页面 1:1 迁移,未知业务给出具体原因。 Windows 本地验证后部署 Linux Docker;所有验证使用 temporary + fake / 离线演示, 不测试真实游戏 API,不读取或修改私有 local_state 账户。

文件归属

Owner 文件 / 范围
API ranch_web/__init__.py、__main__.py、app.py、config.py、requirements.txt、tests/__init__.py、tests/test_api.py、tests/test_auth.py、本契约
Runtime service.py、账户线程 / 调度 / 凭据 / 运行时测试
Views / actions policies.py、views.py、actions.py、相关离线测试
Frontend static/ 原生 ES modules、HTML、CSS,无 npm 编译
Deploy updates.py、Docker / host updater / Windows launcher、部署测试及文档
Main 协调最终契约、代码审核、离线集成和浏览器实测

协作 agent IDs:runtime 01a1c454-a71b-7fb2-bffd-590ca032c00e;views 01a1c454-a76c-7901-8d67-f05fb95cb172;api 01a1c454-a7d5-71c2-96d8-ffcb2831d520; frontend 01a1c454-a828-7f01-83f7-8a657ccc9211;deploy 01a1c454-a872-7702-8ec3-01651883b0f2。接口有变化立即同步相关 owner 和 Main, 小 patch 协作,不覆盖其他 owner 文件。

Python 接口

create_app(data_dir=None, manager=None, config=None, updates=None)  # ranch_web.app

WebManager(root, *, start_scheduler=True, catalog=None,
           engine_factory=None, login_factory=None)  # ranch_web.service
manager.list_accounts() -> list[summary]
manager.create_account(label="", demo=True) -> summary
manager.remove_account(account_id)
manager.status(account_id) -> summary
manager.get_config(account_id) -> {"config": ..., "revision": ...}
manager.set_config(account_id, config, revision=None) -> {"config": ..., "revision": ...}
manager.view(account_id, page, query=None) -> {"data": ..., "loading": bool,
                                             "job_id": str | None, "revision": ...}
manager.submit(account_id, operation, payload=None) -> job
manager.job(account_id, job_id) -> job
manager.logs(account_id, after=0, debug=False) -> {"entries": [...], "next": ...}
manager.log_detail(account_id, entry_id) -> publicJSON  # 单条懒加载脱敏网络详情
manager.close()

default_config(), validate_config(config), apply_config(engine, config)
export_config(config, snapshot=None), import_config(value, snapshot=None)  # ranch_web.policies
build_view(engine, page, config, query=None), schema(catalog)  # ranch_web.views
execute_action(worker, operation, payload)  # ranch_web.actions

UpdateService(root, current_version)  # ranch_web.updates;root 为 Web 数据根
updates.status() -> publicJSON
updates.check() -> publicJSON
updates.request_update(version=None) -> publicJSON

FastAPI 使用 lifespan;只 close 自己创建的 manager / updates,对注入对象不取得所有权。 同步服务调用在线程池执行,游戏操作仅提交队列,HTTP 202 + job 轮询;GET 视图立即 返回缓存,首访 loading=true,不得等待战斗。状态、日志、健康和 meta 不被长任务阻塞。 单账号一个线程串行,多账号并行;停止立即取消未发请求和可取消等待。配置串行生效并 自动保存;重启、恢复会话、导入配置均保持策略关闭。导入导出及批量资料处理也经 job。 Runtime 已说明 set_config 忙时返回 {config,revision,pending:true,job_id,job},其中 config/revision 是当前已生效值;API 对此返回 202,frontend 必须轮询 job 后再读新 revision, 不得当作已经应用。非 pending 的响应仍为 200。

账户 summary:

{"id":"opaque-account-id","label":"账号1","connected":false,"demo":true,
 "running":false,"busy":false,"player":{"name":"","level":0,"exp":0,
 "next_exp":0,"money":0,"ke":0,"ti":0},"revision":0,"error":null}

job:{id,status,operation,result,error};status 只允许 queued/running/succeeded/failed/cancelled,result 仅 publicJSON。外发禁止 token、key、reqid、password、原始快照、服务器文件路径。错误使用中文,禁止堆栈。 has_saved_password 是允许的布尔元数据;游戏会话展示仅使用不含秘密的 session 元数据。

页面与控件

页面 key 固定:login,incubator,bag,ranch,daily,hatching,mainline,battles,gifts, commissions,exploration,maps,statistics,plans,yields。 保持菜单、账号 tabs、顶部玩家数值 / 随机刷新 / 绿开启红停止、底部可调隐藏日志。 背包分类:蛋 / 可用 / 消耗 / 材料 / 其他 / 装备。牧场支持平铺与分组;主线默认当前主线; 地图默认折叠,保留矿洞、难度、次数、工具库存;统计使用真实统计数据绘 SVG。

统一视图 DTO:

{"page":"bag","title":"背包","columns":[{"key":"enabled","label":"启用",
 "type":"boolean","edit":{"path":["policy","egg_rules","100","enabled"],
 "type":"boolean"}}],"rows":[{"id":"100","enabled":true}],"summary":{},
 "filters":[],"form":[],"details":{}}

summary/filters/form/details 按页可选。路径示例仅说明 shape,真实路径取 views schema。 schema(catalog) 包含中文 label、类型、options、config path;渲染真实控件,所有控件 经相同配置路径 PUT 并自动保存,不使用纯 JSON 编辑器替代原功能。具体样例由 views owner 同步 frontend,API 只传递已脱敏公共 DTO。

REST

方法 路径 返回
GET /api/health {status:"ok",version},无游戏副作用
GET /api/meta version、gameVersion、access、features、updates
GET /api/schema views.schema(catalog)
GET / POST /api/accounts GET 为 summary 数组;POST {label?,demo?},201 summary
DELETE /api/accounts/{id} 204
GET /api/accounts/{id}/status summary
GET / PUT /api/accounts/{id}/config PUT {config,revision?};返回 {config,revision}
GET /api/accounts/{id}/views/{page} {data,loading,job_id,revision}
POST /api/accounts/{id}/actions/{operation} payload 对象,202 job
GET /api/accounts/{id}/jobs/{job_id} job
GET /api/accounts/{id}/logs?after=0&debug=false {entries,next}
GET /api/accounts/{id}/logs/{entry_id} 选中单条后取脱敏网络详情;不随普通日志轮询发送大 body
GET /api/accounts/{id}/debug/{entry_id} 相同详情兼容路径,frontend 可用;manager.log_detail / debug_entry 等价
GET /api/accounts/{id}/config/export 提交 export_config,202 job
POST /api/accounts/{id}/config/import 上传 portable document(兼容 {config:document}),API 包装为 action 的 {config:document},202 job
GET /api/system/updates updates.status(),不联网检查
POST /api/system/updates/check 在线程池 check(),仅检查 GitHub 正式版本
POST /api/system/updates/apply {version?},202,提交受控更新请求
GET /api/auth/status {required,authenticated,access_mode}
POST /api/auth/login {password},设置 HttpOnly / SameSite=Strict cookie
POST /api/auth/logout 撤销管理会话并清除 cookie

视图 query:推荐 ?query=<JSON object>;同时支持简单 query 参数;两种形式不可混用。 不允许客户端指定任意磁盘文件路径;资料导入使用内存内容 / 已有业务 schema。 API 默认 JSON body 上限 1 MiB;唯一例外是严格匹配账户 ID 的 POST /api/accounts/{id}/actions/import_yields,其 JSON body 上限为 12 MiB,容纳 8 MiB 文件的 base64 与 JSON 开销。声明长度与流式读取均执行相同上限;其他方法 / 路径仍使用 默认 1 MiB(或显式配置的普通 body 上限)。action 按解码后字节数严格限制 8 MiB。 账户与 job ID 为 1–80 位 ASCII 字母、数字、_、-。 API 错误统一 {error:{code,message},detail:message},不回显请求 body 或验证错误值。

手动 action allowlist:refresh,refresh_maps,refresh_tasks,claim_daily,lock,unlock,sell, feed,quote_expansion,expand,export_config,import_config,import_yields,reset_map_pending。 login,enter_server,restore_session,logout,forget_login,start,stop 由 service 实现。 如原业务迁移需要其他 action,先同步 API owner 加入 allowlist。

游戏 login payload:{account,password,remember},result 含 servers:[{id,name,role_name}] 和布尔 has_saved_password。 enter_server:{server_id};restore_session:{session_id}。凭据只在服务器内存或加密 存储,严禁浏览器 localStorage、cookie 或 DTO 含游戏秘密。

认证、部署与更新边界

默认 127.0.0.1:8765,数据根 local_state/ranch_web,独立于桌面;Docker 显式 /data。 CLI:python -m ranch_web [--host ...] [--port ...] [--data-dir ...] [--demo] [--no-browser]。 默认启动不自动创建 demo;--demo 仅显式创建离线演示账号。 Web 依赖仅 fastapi、uvicorn、requests、cryptography、openpyxl,不含 Qt。

非 loopback 绑定必须配置 RANCH_WEB_PASSWORD 或 RANCH_WEB_PASSWORD_HASH; loopback 无密码模式只允许 loopback 客户端。每个请求严格校验 Host;写 API 校验 Origin 与 Sec-Fetch-Site,禁止 wildcard CORS、DNS rebinding 与跨站登录 / 账户操作。 未带 Origin 的本机 CLI 可调用;携带 Origin 时必须同源或是明确配置的允许源。 反代域名通过 RANCH_WEB_ALLOWED_HOSTS 指定,外部源通过 RANCH_WEB_ALLOWED_ORIGINS 指定;不信任客户端 X-Forwarded-Host。HTTPS 反代设置 RANCH_WEB_SECURE_COOKIE=1。 管理会话仅内存,随机 opaque token,12 小时 TTL;重启后失效。 管理登录每个来源在 60 秒内最多保留 10 个失败 / 在途校验名额;锁内原子预留,PBKDF 在锁外并行运行,成功仅撤销自身名额。来源记录最多 1024 条,不串行阻塞其他来源或已有会话。 密码 hash 格式:pbkdf2_sha256$600000$salt$base64_digest,salt 为 UTF-8 文本。 可用 ranch_web.config.hash_password() 生成;明文配置使用常量时间比较。

updates.status() 与 meta 不触发 GitHub 请求;check 显式 / 定时调用,不能访问游戏 API。 apply 仅向部署 owner 管理的 host updater 提交规范 v2.x.y 稳定版本号请求(不接受前导零、 开发版、其他主版本或裸版本号,与 UpdateService 一致);Web 容器不得持有 Docker socket,不执行任意 git / shell。未配置部署器要明确解释,不能宣称更新成功。 host 目录的具体协议由 deploy owner 维护,API 只调用 request_update(version),frontend 只读取公开状态,不直接使用目录路径;需与 deploy / frontend 同步具体 DTO。 更新 DTO 与 deploy/web/UPDATE_PROTOCOL.md 完全同名:API 显式选择公开更新字段并保留 经过协议校验的 request={request_id,version,requested_at,status} 和 host_status={request_id,status,version,updated_at,error}。此例外仅适用于更新接口及 meta.updates,不放宽普通游戏数据的 request / reqid / request_id / key / token 脱敏。

API owner 集成记录

  • 首次检查:仓库为 7fe4c0f,尚无 ranch_web;API 创建包初始化文件。
  • 当前 API owner 工具列表没有 send_input / agent 通信工具,已在会话告知;暂以本文件 共享接口,在工具可用时立即直接同步相关 owner。
  • 按 Main 调试 1:1 要求,API 添加 GET logs/{entry_id} 对接 manager.log_detail(account_id, entry_id)。正常轮询只发摘要,详情仅点击后加载; 详情保留请求 / 响应 / body 结构并递归遮罩秘密,普通响应禁止原始快照。 请 runtime / frontend 采用此方法名和路径;运行时未实现时 API 明确返回 501。
  • CLI / Docker / launcher 统一环境变量:RANCH_WEB_HOST、RANCH_WEB_PORT、 RANCH_WEB_DATA_DIR;API 不使用 RANCH_WEB_ROOT。CLI 参数覆盖环境变量。
  • 可运行骨架及离线验证结果完成后追加在此,不改写其他 owner 文件。

API owner 冻结交接(2026-11-10)

状态:分配范围实现完成,API owner freeze,未提交 / 推送。Main 可进行独立审核、浏览器 实测及按既有授权安排 develop 测试分支。后续只响应集成缺陷修复,不扩展本轮范围。

交付文件:ranch_web/{__init__,__main__,app,config}.py、requirements.txt、 ranch_web/tests/{__init__,test_api,test_auth}.py、本共享契约。其他 owner 的文件未修改。

已验证:Windows Python 3.13.15、FastAPI 0.162.2、uvicorn 0.54.0、httpx 0.28.1。

python -m unittest ranch_web.tests.test_api ranch_web.tests.test_auth -q
Ran 40 tests ... OK
python -m compileall -q ranch_web/app.py ranch_web/config.py ranch_web/__main__.py ranch_web/tests/test_api.py ranch_web/tests/test_auth.py
git diff --check

测试覆盖:生命周期仅释放自建对象 / 启动失败清理 / 全部对象清理尝试,HTTP 202 job、 缓存视图、配置 revision / pending、portable 导入导出、中文错误 / 堆栈 / 路径脱敏, 摘要与延迟调试详情,输入与路径 allowlist、body 大小 / 流式正文限制,Host / Origin / DNS rebinding,免密仅限本机,明文与 PBKDF2 密码,HttpOnly / SameSite Strict / Secure cookie, 退出后的 cookie 重放、管理会话实例隔离、登录限流、后台检查不阻塞 event loop。 测试均使用临时目录与 fake / demo,requests 网络 guard 实测调用次数为 0。

真实 WebManager + 原 Engine 的临时 demo 集成:15 个页面都成功返回 DTO(收益 749 行), columns / filters / schema.pages 的 key 保留;配置队列保存 interval、导出后以 portable 文档重新导入成功,策略仍关闭。独立进程验证导入无 PySide6 / *_gui。 CLI --help、--data-dir --demo --no-browser 生命周期验证通过,不打开浏览器。

Main 需知的接口细节:

  • set_config pending 返回 202;轮询 job 后读取最新 config / revision。
  • 日志详情同时支持 /logs/{entry_id} 与 frontend 已使用的 /debug/{entry_id}; 对接 manager.log_detail,兼容 manager.debug_entry,只有选中条目才加载 body。
  • config/import 接受 portable document 或 {config:document};提交 action 时统一包装。
  • apply 版本号只接受部署模块的规范 v2.x.y;未配置部署器返回真实 unavailable 状态。
  • 环境变量统一 HOST / PORT / DATA_DIR;HTTPS 反代要显式设置允许的 Host、Origin 和 RANCH_WEB_SECURE_COOKIE=1。CLI 不信任任意 forwarded header,关闭访问日志避免查询泄密。

验证边界:未调用真实游戏 API 或真实 GitHub 检查;未读取 / 修改桌面账户数据; Linux Python 3.12 / Docker、浏览器交互与生产 updater 由 Main / deploy 继续验证。 本轮没有宣称线上业务成功、容器更新完成或正式发布。

Main 最终集成修复补记:仅修改 API owner 的 app.py、test_api.py、本契约。 新增 4 项测试覆盖专用 12 MiB body 的 Content-Length 边界、真实多块 ASGI 流式边界、 其他路由仍为 1 MiB,以及原 action 恰好 8 MiB CSV 成功 / 多 1 字节失败且保留原配置。 真实 UpdateService + 临时 executor 心跳 / 固定 GitHub release 替身验证 check → pending → applying,HTTP 与 meta 的 request / request_id / version / status 均完整;游戏 DTO 仍 过滤这些秘密键。DTO 未改名,frontend 无需适配。39 项 API / auth 测试通过后再次 freeze。

Independent review 2 修复补记:API 的 metadata 上下文补齐 tabs,仅保留这类控件的合法 key;真实 manager 的隔离 demo API 回归断言主线 status/policy 两个 tab 与孵蛋策略 三个 tab 的 key 完整,主线策略表单可用。登录限流改为锁内检查并预留、锁外 PBKDF, 失败不再回写旧计数,成功仅释放自身预留。确定性事件门控测试验证 12 个并发错误请求 恰好得到 10 个 401 + 2 个 429,随后仍限流;同时已有会话查询、另一来源正确登录均 及时完成。以上两项均先复现再修复。40 项 API / auth 测试、编译、diff 检查通过,再次 freeze。 本次仅修改 API owner 的 app.py、test_api.py、test_auth.py、本契约;未提交 / 推送。