# 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结果当成在线成功。