Files
myrzx_bot/analysis/WEB_V2_PARITY.md
T

105 lines
12 KiB
Markdown
Raw 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 页面/策略/操作契约与对照
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结果当成在线成功。