Add Web 2 workspace and controlled deployment updates

This commit is contained in:
AttilaNet
2026-11-10 16:33:14 +08:00
parent 7fe4c0ffdf
commit dbb31707ea
58 changed files with 11283 additions and 0 deletions
+245
View File
@@ -0,0 +1,245 @@
# 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、本契约;未提交 / 推送。
+104
View File
@@ -0,0 +1,104 @@
# Web 2.0 页面/策略/操作契约与对照
Owner: views。状态:已freeze,26项focused tests通过,交Main审核。此文件是 frontend / API / runtime 的共享契约;当前会话无 send_input 工具,以共享文件和会话进度同步。
## 固定 Python 接口
- `default_config() -> dict`:桌面六组策略 + interval / overrides / yield_stars / log_visible / log_sizes;所有运行状态由 runtime 管理。
- `validate_config(config) -> dict`:补默认值,严格校验每层字段和动态规则,不接受凭据或未知字段。
- `apply_config(engine, config) -> dict`:原子验证后应用六组 core 策略和收益 overrides;不启动运行。
- `export_config(config, snapshot=None) -> dict` / `import_config(value, snapshot=None) -> dict`:复用纯 Python `policy_io` 可移植 schema 1 / 2,按 species 重映射实例 ID。
- `build_view(engine, page, config, query=None) -> dict`、`schema(catalog) -> dict`;纯读取 DTO 在账号 worker 队列执行;绝不 import GUI。
- `execute_action(worker, operation, payload=None) -> publicJSON`:worker 要有 engine、config、profile_root;运行状态/持久化由 runtime 统一处理。
## DTO 与编辑协议(前端可立即接入)
所有页面:`{page,title,columns:[{key,label,type?,edit?:{path,type,options?}}],rows:[{id,...}],summary,filters,form,details,actions}`。
`form` 为字段列表,字段至少 `{label,type,path,value}`,可带 `options:[{value,label,disabled?,reason?}]` / `min,max,step,group,help`。
行中 `edits` 可覆盖该行列编辑定义;静态列 path 中 `"{id}"` 替换为行 ID。前端把 path 定位的值写回同一份 config,再 PUT;数组/字典由专用列表控件编辑。
例如蛋规则列 `{"key":"keep_count","label":"牧场保留","type":"integer","edit":{"path":["policy","egg_rules","{id}","keep_count"],"type":"integer","min":0,"max":1000}}`,含义是最低保留数量。
动态行规则不存在时 DTO 提供该行 `rule_defaults`;编辑第一格时先把 defaults 合并入对应规则,避免创建不完整规则。
探索队员是完整三选控件:`type:"members"`,path `["explore_policy","teams","{id}","monsters"]`,value 为 `[]`(自动)或三个整数 ID;允许前端保留未完成草稿,仅三人齐全后 PUT。
`filters` 是可用筛选控件列表,字段包含 `key,label,type,value,options`,query 同名;`search` 通用文本筛选。`details` 为按 row.id 索引的安全展示数据。
牧场目标开关的 edit.type=`target`:勾选写整数优先级(default=100),取消删除对应路径,不能把布尔值写进 targets 字典;优先级列使用同一 config path。探索 `members` 提供三个人员选项,只提交完整3人数组或[]。`add_rule` 用选择器添加species规则,不是文本输入。`id_counts` 用逐项编号/数量控件。
支持 page keys:login / incubator / bag / ranch / daily / hatching / mainline / battles / gifts / commissions / exploration / maps / statistics / plans / yields。
bag query.category:eggs / usable / consumables / materials / other / equipment。ranch query.grouped 默认 false,query.room_id 可选。mainline query.category 默认 mainline、query.state 默认 current。maps query.category all / ordinary / resource,query.only_unlocked 默认 true;地区 groups 默认 collapsed。
statistics query:stage_id(兼容stage别名)、level(1/2/3)、source(all/sweep/event;event=奖励事件)、metric(rate/per_stamina;probability 为 rate 别名);chart.series[].value 的rate为0~1比例,frontend乘100绘制百分比;charts 是同一chart的列表形式。
## 手动操作 payload(POST actions/{operation})
| operation | payload | 结果/约束 |
| --- | --- | --- |
| refresh | `{page?:string}` | Engine.poll(自动关闭)或相应本地刷新;不自动执行计划 |
| refresh_maps | `{}` | Engine.refresh_stages |
| refresh_tasks | `{}` | Engine.refresh_progression |
| claim_daily | `{}` | Engine.claim_daily;按 daily_policy.selected 领取 |
| lock / unlock | `{monster_ids:[int]}` | Engine.set_monster_lock |
| sell | `{monster_ids:[int],confirm:true}` | Engine.manage_monsters('sell',...);必须明确确认 |
| feed | `{monster_ids:[int],target_id:int,confirm:true}` | Engine.manage_monsters('feed',...);复用原保护与等级验证 |
| quote_expansion | `{kind:'stack'|'room',currency:'money'|'ke',position?:int}` | 返回 `{quote_id,kind,currency,position,cost,description}`;quote_id 只在该 worker 有效 |
| expand | `{quote_id:string,confirm:true}` | 消费一次性服务器报价;Engine.expand 再核对当前费用与次数 |
| export_config | `{}` | 可移植 dict,不含秘密 |
| import_config | `{config:object}` | 返回 `{config}`;runtime 验证串行应用、保存并停止运行 |
| import_yields | `{filename:string,content_base64:string}` | 只接受上传 CSV/XLSX 的内存内容,不接受客户端磁盘路径;经worker.save_config应用和保存后返回 `{overrides,count,message}` |
| reset_map_pending | `{confirm:true}`(兼容server_verified但不信任) | 仅复用原sweeper.recover_reward_event核对账号/请求/关卡/难度及成功响应,缺证据保留pending;绝不清battle journal |
游戏登录、恢复、开启、停止仍归 runtime;此层不新增构造游戏请求的手动动作。自动赠礼、突破、探险、主线和刷图使用原 Engine 策略调度。
## 对照与验证
所有测试仅 temporary+fake 或显式离线 demo;不读取私有账号目录,不连接真实游戏 API,不修改 ranch_assistant core。
### 已确认的集成约定
- runtime / API:`build_view(...).tabs[].key` 与columns/filters/pages一样保留;两层已修复,主线和孵蛋子页经真实WebManager HTTP与浏览器复核。
- frontend:`members` 三选控件保留未完成浏览器草稿,只提交[]或完整3个ID;自动按钮清空[]。
- frontend:hatching.details.preset是原绿色史莱姆预设;应用patch并整体替换policy.egg_rules为preset.egg_rules后PUT,不开启运行。
- frontend:statistics兼容stage/stage_id;level对象含id/level/value;chart.series[].value为比例(rate)或每体力数量,无样本为null/无series,不当作0%成功。
- 所有合法旧battle_mode(original)先通过core校验再归一experimental,与当前desktop保持一致;未知值仍拒绝。
- API:收益上传action支持8MiB原文件,仅`/api/accounts/{id}/actions/import_yields`路由使用12MiB JSON body上限,其他路由维持原限制;frontend发送filename+content_base64。
### 页面逐项对照
| Web page | 原GUI / 纯核心证据 | DTO / 真实操作 |
| --- | --- | --- |
| login | gui.connection_tab;运行时login_view | 仅登录页公共元数据骨架;密码/区服/恢复由runtime填充,不读取游戏凭据 |
| incubator | gui.render;Snapshot.phase_text/remaining;management.expansion_quote | 11个坑位含未开/VIP、真实成长阶段/资质/剩余时间;选普通坑位money/ke报价,Engine.expand复核并检查新增记录 |
| bag | egg_rules_gui.EggTable;inventory_gui.InventoryTable;Catalog.item_type | 蛋/可用/消耗/材料/其他/装备,同种库存聚合;蛋启用/优先级/去向/补货下限/目标/市场/牧场保留;允许无库存规则;礼物开关和保留数量按资格禁用装备及蛋 |
| ranch | ranch_gui.RanchView;presentation.monster_rows | 平铺/分组/按牧场过滤、容量空位、详情;喂养/赠礼/突破目标开关和1~999优先级真绑定;手动锁/解锁/派遣/指定目标喂养;新建牧场报价 |
| daily | activity_gui.daily_tab/render_daily;daily.entries | 每日礼包/七日/累计/VIP/邮件状态和奖励、选择列表;Engine.claim_daily按选项处理,ledger防重,刷新只预览 |
| hatching | gui.automation_tab/policy_tab/read_policy/gold_preset | 孵蛋/牧场/喂养三个子策略;保留星级/资质/同种更好保护、收取牧场、保留物种/蛋、买蛋预算等现UI字段;原绿色史莱姆预设DTO,应用只保存配置 |
| mainline | progression_gui.prepare_progression_views/render_progression/read_progression_policy | 默认当前主线,类别+生命周期+搜索,任务步骤/NPC/对话/位置/下一步/阻塞;完整现UI策略;旧original先验证再归一experimental,不暴露旧隐藏selector |
| battles | progression_gui.prepare_progression_views | 战斗/扫荡/奖励事件分类、北京时间、中文胜败和阻塞、模式/伤害说明和奖励详情;不公开raw response或journal内部路径 |
| gifts | gui.gifting_tab;GiftPlanner;CultivationSelector | 自动代表、喜欢物品开关、代表/目标名单、好感上限/资质/喜欢物品/冷却;执行继续走原Engine调度 |
| commissions | gui.quests_tab/render_quests;TaskPlanner;progression_rows | 委托金币/氪金奖励、接取/进行中状态、原诊断覆盖原因;交付物品/1级魔物/金币上限/库存保留/战斗限制,按氪金优先 |
| exploration | exploration_gui.prepare_exploration_rows/prepare_exploration_members;ExplorePlanner | 已有队伍/地区/解锁/费用/状态/倒计时;三队员选择含自动排除原因,手动仍允许战斗/培养目标;占用/等级等由原planner检查;领奖与再出发沿原策略 |
| maps | activity_gui.render_maps/resource_cost_text;StageCache;Engine.map_stage_reason | 全部/普通/资源、只解锁、搜索、默认地区折叠;难度选择/勾选/日次数、普通扫荡/挑战诊断;矿洞/门票仅入口难度1,体力及每种工具单次/可用/保留成本 |
| statistics | statistics_gui.render_detail;SweepStatistics.snapshot;drop_statistics.analyze | 原名称“数据分析”;all/sweep/event,关卡难度/次数/奖励,出现率/平均数量/每体力/95%区间/配置与实测;SVG series用真实统计,未知体力样本不算效率 |
| plans | gui.render;Engine.plans | 原名称“执行计划”;仅公开动作kind/description和原planner等待原因,不暴露path/payload或自行执行 |
| yields | gui.yield_tab/render_catalog;Catalog.import_prices | 原749种魔物,星级和搜索、培育时间/金币/经验/每小时/金币经验比;CSV/XLSX通过临时文件调用原导入器,完整验证后才保存overrides |
### 文件与检查记录
仅本owner文件:`ranch_web/policies.py`、`views.py`、`actions.py`、`tests/test_web_policies.py`、`tests/test_web_views_actions.py`、本报告。未修改ranch_assistant core、其他owner文件或私有local_state。
定向测试命令:
```powershell
python -m unittest ranch_web.tests.test_web_policies ranch_web.tests.test_web_views_actions -v
```
- 26项通过:8项策略验证/原子应用/跨账号重映射、18项页面/操作/原始Engine验证。
- 所有15页在temporary demo中JSON序列化成功;非demo Engine +拒绝所有call的fake transport构建15页未触网;独立子进程阻断PySide6与GUI import通过。
- 真实WebManager(temporary、start_scheduler=False)15页异步队列构建成功;quote_expansion→expand、lock/unlock、export/import、refresh_tasks job均succeeded;导入后running=False。
- 扩建测试覆盖费用变化拒绝、一次性报价、错误/未知响应不能重复支付;派遣/喂养沿原保护;每日ledger防重。
- 实际SweepStatistics记录合并验证all/event/sweep与未知体力样本排除;pending测试包含缺证据、错误账号、正确服务器响应、已有battle journal四种情况。
- 没有运行真实游戏API验证,没有打开/更改私有账户;未commit/push。
### 已知边界与Main接手项
- 登录、安全、调度、缓存、前端控件及API请求体/脱敏接口已对齐并冻结。最终测试计数与验证边界以[Web验证说明](../ranch_web/README.md#离线验证)为准。
- 未新增原业务未支持的委托孵蛋联动、未知战斗机制、花钱开探险队或召回;DTO保留核心具体原因。
- pending不提供无证据强制清除;普通挑战/任务journal完全归Engine自动核对。
- 源码核对与验证均为本地离线;未把demo或fake结果当成在线成功。