OCC 战斗与关卡 · 开发规格：数据与协议 v1

后续内容方案 的实现规格。设计稿回答"做什么、为什么"， 本篇回答"字段叫什么、消息怎么发、函数签名长什么样、怎么断言它对"。

规矩：开发按本篇写代码，不按设计稿猜字段。设计稿里改了意图，先回本篇改字段，再动代码。 基线：2026-10-17 22:00 的代码。

---

0. 阅读顺序

---

1. 存档字段

1.1 新增到 profile（server/store.js）

读取时一律补默认值（沿用 ensureWorlds 那套自愈做法，不要求老玩家重来）：

profile.missions = {
  cleared: {},        // nodeId → { at:ms, bestThreat:int, bestMs:int }
  threat: {},         // nodeId → 已解锁的最高威胁等级（默认 1）
  active: null,       // 进行中的远征，断线续用；null = 没有
  diveBest: 0,        // 深潜最高波次（展示用）
};

// active 的形状（只在远征期间非 null）
profile.missions.active = {
  nodeId: 'battle_sweep_1',
  worldId: 'battle',
  threat: 1,
  startedAt: 1792300000000,
  goal: { kills: 12 },          // 起始目标快照（改表不影响进行中的远征）
  progress: { kills: 4 },
  bossHp: null,                 // 首领节点用
  nestHp: [120, 120, 120],      // 破袭节点用
  extractOpen: false,
  extractAt: 0,                 // 撤离窗口开始的服务器时间
};

profile.blueprints = [];   // 已解锁的模块 id（永久凭据，拾取即写）

🔴 active 必须能断线续用：玩家在战场被踢下线，重连回来要看到同一个进度。 判据是"世界没变 + 未超时"（沿用 lastWorld 那套），不是"重新开始"。

1.2 模块槽挂到 bag.equip（不新开存档树）

bag.equip = {
  weapon: null,   // 已有
  tool: null,     // 已有
  armor: null,    // 已有（仍不开放）
  engine: null,   // 已有（仍不开放）
  modules: [null, null, null, null, null],   // 新增：4 类槽 + 1 超载槽，长度固定 5
};

🔴 为什么不放 profile.loadout：bagWire 已经有一条成型下发通道，且槽位合法性校验 （sanitizeSlot）已经在 bag.js 里，挂在 equip 上等于白拿这两个。新开一条同步路径是纯浪费。

1.3 容量计算（唯一口径：服务端算，客户端只展示）

capacity = 12
         + (tech 含 t3_armor   ? 2 : 0)
         + (tech 含 t4_overload? 3 : 0)
         + (tech 含 pow_core1  ? 2 : 0)
         + (tech 含 pow_core2  ? 3 : 0)
         + (套装 防御×2 ? 2 : 0)

used = Σ 模块.cost  （超载槽里的 ×2）

capacity >= used 才允许装。服务端拒装时回 code:'overCapacity'，客户端不许自己算完就装。

---

2. 任务节点表 MISSION_DEFS

新文件 server/missions.js。一张纯数据表 + 若干纯函数（可单测，不 import DOM / three）。

2.1 字段

{
  id: 'battle_sweep_1',        // 全局唯一，存档 key
  world: 'battle',             // 所属 worldId（节点共用这个世界的地形）
  kind: 'sweep',               // sweep|hunt|hold|sabotage|salvage|prime|dive
  name: '清扫',
  threat: 1,                   // 基础威胁等级
  land: { lat: 18, lon: -40 }, // 🔴 固定着陆点（方案 §1.3 一直缺的那个）
  goal: { kills: 12 },         // 按 kind 解释，见 §2.2
  enemySet: 'battle_t1',       // → §4
  timeLimitSec: 0,             // 0 = 不限时
  extractSec: 20,              // 撤离窗口需要站住的秒数
  next: ['battle_hunt_1'],     // 通关后解锁的节点（图上连线）
  unlock: { need: [], tech: [], gate: 1 },   // need=前置节点, tech=科技 id, gate=星门等级
  reward: {
    first: { blueprints: ['w_spread'], crystal: 6 },
    repeat: { crystal: 4, alloy: 0 },
  },
}

2.2 七种 kind 的 goal 与完成判定

2.3 焦土（T1）的 5 个节点 —— 首发内容

'battle_sweep_1':    { kind:'sweep',    name:'清扫',   goal:{kills:12},
                       land:{lat:18,lon:-40},  next:['battle_hunt_1'],
                       reward:{ first:{blueprints:['w_spread'], crystal:6}, repeat:{crystal:4} } },
'battle_hunt_1':     { kind:'hunt',     name:'猎杀',   goal:{hunt:3},
                       land:{lat:-12,lon:62},  next:['battle_hold_1','battle_sabotage_1'],
                       reward:{ first:{blueprints:['s_mark'], crystal:8}, repeat:{crystal:5} } },
'battle_hold_1':     { kind:'hold',     name:'坚守',   goal:{sec:180},
                       land:{lat:44,lon:120},  next:['battle_prime_1'],
                       reward:{ first:{blueprints:['d_barrier'], crystal:10}, repeat:{crystal:6} } },
'battle_sabotage_1': { kind:'sabotage', name:'破袭',   goal:{nests:3},
                       land:{lat:-48,lon:-96}, next:['battle_prime_1'],
                       reward:{ first:{blueprints:['w_boomerang'], crystal:10}, repeat:{crystal:6} } },
'battle_prime_1':    { kind:'prime',    name:'天罗',   goal:{boss:'p_boss_scorch'},
                       land:{lat:0,lon:0},     next:[],
                       unlock:{ need:['battle_hold_1','battle_sabotage_1'] },
                       reward:{ first:{parts:['boss_core_scorch'], crystal:20, alloy:4}, repeat:{alloy:3} } },

⚠️ 着陆点坐标必须两端口径一致：land 写的是 lat/lon 度数， 服务端 cellToDir、客户端 latLonToDir 必须用同一套换算（沿用现有出生点那套）。 落地后要再做一次"最近陆地吸附"（findSpawn 同款螺旋Search），免得落进水里。

⚠️ 一个节点一个 land，不许随机：方案 §1.3 早就要求"3 个固定着陆点避免落地即被打"， 这一项一直没做。现在按节点给固定点，顺带把它补上。

2.4 深潜（dive）的波次规则

波次 n：敌人在场数 = 基础 × (1 + 0.15(n-1))，血量 × (1 + 0.35(n-1))
间隔：每波 90s 或"场上清空"二者先到
结算：撤离时按波次给料，crystal = 2 + 3n，alloy = n>=5 ? 1 + floor((n-5)/3) : 0
失败：死亡 → 本趟归零（背包掉 50%，不给任何结算）

2.5 进度存储与恢复

---

3. 敌人 archetype 表 ENEMY_ARCH

新文件 server/enemies.js。替代 npc.js 里写死的"普通 / 精英"两档。

{ id, name, hp, shield, speed, fixed, fly,
  dmg, atk:'ram'|'shell'|'flak'|'shotgun'|'kamikaze'|'spawn',
  range, cd, burst,
  weak: null|'back'|'overload',        // 弱点（背面 / 需过载）
  resist: { blast:0.6, pierce:0.4 },   // 抗性系数（缺省 1.0）
  loot: { scrap:[1,2], crystal:[1,3], alloy:[0,1] },
  threatMin: 1 }

🔴 threatMin 决定它从哪个威胁等级开始出现（tab 上第 5 列表）： car 1 / tank 1 / turret 2 / drone 3 / shield 3 / nest 4。 同一张图在 T1 和 T7 刷出来的怪完全不同，这是"同图重打"不腻的物理原因。

---

4. 敌人配置集 ENEMY_SETS

{ npc:n, elite:n, extra:[{arch,n}], boss:id|null, threatScale:true }

⚠️ count 是"全世界总量"，不是"玩家附近"。现有实现是"固定 50 台铺满星球"， 改集的时候别顺手改回收半径（recycleDist 1200 / renderDist 1100 已调过）。

---

5. 模块表 MODULES（22 条）

加在 server/items.js（或新建 server/modules.js 再 export，二选一；推荐后者，22 条会把这个文件撑大）。

{ id, name, cat:'module', slot:'weapon'|'defense'|'mobility'|'support',
  cost, tier, effect:{...}, desc, from:{node:'battle_sweep_1'}|{tech:'w_chain'}|{boss:'boss_core_scorch'} }

5.1 武器系（slot:'weapon'，改发射物行为）

5.2 防御系（slot:'defense'）

5.3 机动系（slot:'mobility'）

5.4 支援系（slot:'support'）

5.5 套装判定（服务端算，随 loadout 下发）

同系计数 = 5 个槽里该 slot 的数量（超载槽也计入）
>= 2 ⇒ 生效：
  weapon   → reloadMul 0.7
  defense  → capacity +2, speedMul 0.95
  mobility → cdMul 0.7（只作用于 mobility 系模块）
  support  → durationMul 1.5

---

6. 物品与配方新增

6.1 物品（server/items.js）

🔴 图纸不需要物品定义。拾取即登记 profile.blueprints，走 lootSend 的 "掉落物视觉 + 拾取动画"，但 store.bagAdd 不接它。理由见方案 §12.2。

6.2 配方（server/sim.js 的 RECIPES + COMMAND_RECIPES）

// Mk1：指挥中心兼职（沿用零到一死锁的解法，玩家拿到第一张图纸就能造）
make_mod_w_spread:  { name:'散花模组',  by:'command',  tier:1, sec:6, in:{shard:4, iron_ingot:3},             out:{mod_w_spread:1} },
make_mod_d_barrier: { name:'屏障模组',  by:'command',  tier:1, sec:6, in:{shard:4, copper_ingot:3},           out:{mod_d_barrier:1} },
make_mod_m_dash:    { name:'冲刺模组',  by:'command',  tier:0, sec:4, in:{shard:2},                           out:{mod_m_dash:1} },

// Mk2：装配机
make_mod_w_chain:   { name:'链弧模组',  by:'assembler', tier:3, sec:14, in:{steel_plate:4, circuit:3, shard:10}, out:{mod_w_chain:1} },
make_mod_d_aegis:   { name:'应急重组',  by:'assembler', tier:4, sec:20, in:{mech_part:3, circuit:6, boss_core_ice:1}, out:{mod_d_aegis:1} },

🔴 配方与图纸的关系只有一条：bldRecipes 下发时按 profile.blueprints 过滤。 已解锁的模块配方才出现在列表里，客户端一行判断都不用写（沿用 recipeIdsOf 那套）。

recipeIdsOf(type, profile) →
  (BUILDING_RUNTIME[type].recipes ?? []).filter(rid =>
    !MODULE_RECIPE_OWNER[rid] || profile.blueprints.includes(MODULE_RECIPE_OWNER[rid]))

⚠️ 改签名的连带影响：recipeIdsOf 现在只被 server.js 的 bldRecipes 用过一次， 加参数安全；但如果之后有人在 sim.js 里直接调，要一起传 profile。

---

7. 世界配置新增字段（server/world-config.js）

每个 worlds[id] 增加：

{
  terrainStyle: 'plains',   // → §8，缺省 'plains'
  seedOffset: 0,            // 🔴 新星域必须给独立值，禁止复用 0
  threat: 1,                // 世界基础威胁（节点可以覆盖）
  enemySet: 'battle_t1',    // → §4
  bossId: 'p_boss_scorch',  // null = 无 Boss
  hazards: [],              // ['cold','slippery','lightning','lava','dust']
  nodes: ['battle_sweep_1', ...],   // 这个星域挂哪些节点（顺序即图上顺序）
  gateLevel: 1,             // 进这个世界需要的星门等级
}

⚠️ 两侧同步：public/src/config.js 的默认值也要加同样的键， 否则客户端拿不到 terrainStyle 时 elevation 会走错分支（§8 的坑 3）。

---

8. 地貌 style 表（public/src/terrain-style.js，新）

8.1 接口

export const STYLES = {
  plains: {
    elevation(noise, d) { /* 🔴 现 terrain-field.js 的 elevation 函数体，逐字复制 */ },
    liquid: 'water',
    oceanRatio: 0.33,
    snowLevelHint: null,
    spawnPrefer: ['grass', 'forest'],
    oreWeights: { copper: 1, iron: 1, tin: 1, oil: 1, stone: 1 },
    slopeLimit: 30,
  },
  wasteland: { /* ... */ },
  // ash / ice / volcanic / rift / ruin
};

terrain-field.js 只改两处：

const style = STYLES[cfg.terrainStyle ?? 'plains'] ?? STYLES.plains;
function elevation(d) { return style.elevation(noise, d); }
// findSpawn 的 prefer 默认值改成 style.spawnPrefer

8.2 六种新地貌的参数方向

8.3 五个坑（每个都会真的出事）

---

9. WS 协议

现有消息分发在 server/server.js 里是一串 if (msg.t === 'xxx')， 新消息加在 lootPick 分支之后（同一缩进层），回包统一 sendTo(ws, {t:'xxxResult', ...})。

9.1 客户端 → 服务端

9.2 服务端 → 客户端（推送）

9.3 登录下包扩展（bag 消息里加）

sendTo(ws, {
  t: 'bag',
  ...store.bagWire(token),        // 已含 bag.equip.modules
  storage, items, recipes, bldRecipes,   // 已有
  site, techs,                     // 已有
  missions: missions.listFor(profile),   // 新增
  blueprints: profile.blueprints,        // 新增
  loadout: missions.loadoutOf(profile),  // 新增（含 capacity/used/sets）
});

⚠️ 三个新键都是小体积（节点 5~30 条、蓝图 ≤22 个字符串），一次发完不用分批。

9.4 一场远征的完整时序

客户端                         服务端
  │ missionList ────────────────▶│ 返回节点列表（含锁定原因）
  │ missionStart{nodeId,threat}─▶│ 校验 → 写 profile.missions.active
  │◀──── missionStartResult ok ──│
  │ （客户端切世界：整页重载 ?w=battle&m=battle_sweep_1）
  │ hello{worldId} ─────────────▶│ 恢复 active（断线也能恢复）
  │◀──── missionGoal 初始进度 ────│
  │  击杀…                        │ onKill → progress.kills++
  │◀──── missionGoal 4/12 ────────│ （节流 200ms）
  │◀──── missionGoal 12/12 + extractOpen ──│
  │  走进撤离圈                   │ canExtract(球面点积, R=820)
  │ extract ────────────────────▶│ 校验圈内 + 站够 extractSec
  │◀──── missionResult ok + rewards ──────│
  │◀──── blueprintGot（若有首通）──│

🔴 切世界是整页重载（现有实现），所以 active 必须落盘 —— 否则重载即丢。 落盘节流 10s，且 missionStart 后立刻强制写一次（这是唯一一次"立刻写"， 因为它后面紧跟重载）。

---

10. 服务端函数签名

10.1 server/missions.js

export const MISSION_DEFS;                 // §2
export function defOf(nodeId)                              // → def | null
export function listFor(profile, worlds)                   // → [{...}] 给客户端的节点态
export function canStart(profile, nodeId, threat, ctx)     // ctx:{tech, gateLevel}
export function start(profile, nodeId, threat)             // → {ok, active} | {ok:false, code}
export function resume(profile, worldId)                   // → active | null（断线续用）
export function onKill(active, enemy)                      // → {advanced:bool, done:bool}
export function onNestHp(active, index, hp)                // → {done}
export function tick(active, dtSec, ctx)                   // → {advanced, done, fail?, hazard?}
export function canExtract(active, dir, R)                 // → bool（圈内 + 窗口开）
export function settle(profile, active, {why})             // → {ok, reason, rewards, blueprints}
export function loadoutOf(profile, tech)                   // → {modules, capacity, used, sets}
export function equipModule(profile, index, id, tech)      // → {ok, code?}
export function attachBlueprint(profile, moduleId)         // → {ok, already, converted}

10.2 server/enemies.js

export const ENEMY_ARCH;    // §3
export const ENEMY_SETS;    // §4
export function setOf(name)                 // → {npc, elite, extra, boss}
export function scaled(arch, threat)        // → {hp, dmg, count}（按威胁曲线放大）
export function immuneMul(arch, ammoKind)   // → 伤害系数（§3 的 resist）

10.3 store.js 新增（都走 markDirty()）

missionsWire(token)                    // listFor + loadoutOf
missionStart(token, nodeId, threat)
missionKill(token, enemy)              // 转 missions.onKill
missionExtract(token)
missionFail(token, reason)
loadoutWire(token)
moduleEquip(token, index, id)
blueprintGrant(token, moduleId)        // 写 profile.blueprints

⚠️ 每个方法都要 ensureWorlds(profile) 之后再取数据 —— 现有 20 多个方法全是这个模式。

10.4 定时器相位

🔴 missions.tick 必须包在现有的 safe() 里（主循环铁律：抛一次错整局冻结）。 且它不许每帧写盘，只改内存。

---

11. 客户端改动

---

12. 纸飞机 6 种 kind 的实现约束

现有状态机：orbit → climb → strike → spent，发射物无物理体（自积分 + ttl + 贴地飞）， 碰撞走 physics.pickAlong() 与 onStrikeSegment()。

🔴 三条铁律（都踩过）：

1. grazing 标记必须跟 onLaunch 广播，新弹种别漏（否则远端看到"从头顶飞过"）。
2. 命中半径按体积归一化（d²/r²），新弹种的爆炸半径别用固定值。
3. 弹药必须在服务端扣。现在的实现里客户端攻击不扣弹（未完成清单 §3 #2），

不修这个，爆破弹就变成免费 AOE，经济直接崩。

---

13. 测试断言矩阵

⚠️ 测试基建的老问题：多个 e2e 共用 _data/state.json，且其中 8 个会 stop/start 服务， 必须顺序跑。服务端已支持 OCC_DATA 覆盖存档路径，新增脚本一律用它（建独立存档）， 别再往共享档上撞（未完成清单 §5 挂了很久）。