Files

246 lines
16 KiB
Markdown
Raw Permalink 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.
# 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 接口
```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:
```json
{"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:
```json
{"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。
```text
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、本契约;未提交 / 推送。