架构与技术设计输入

1. Scope of This Appendix

• 保留从 PRD 主文下沉的详细 P0 边界、架构、功能定义、兼容迁移和评审输入。
• 交互主线仍以主文的 Automatic / Select Service / Manual 为准。
• 图中对象名和组件名用于表达职责关系，可在研发评审后调整。

2. Proposed P0 Scope

2.1 功能范围

2.2 Service Catalog 与 P0 门禁

Catalog 后台统一管理 Provider、Service 与 Service Plan。用户界面在 Select Service 下只选择 VNE 与连接类型（Service Type），随后展示该类型所需输入；公司归属保留为后台元数据。Dynamic / Shared IPv4、Single Fixed IPv4、Fixed IPv4 Prefix 是同一 Service 下不同 Service Plan 对应的 Address Model，不拆成不同 Service Profile。Omada 通用 Address Model 使用 Single Fixed IPv4 与 Fixed IPv4 Prefix；Service Plan 展示运营商实际对外套餐名称。只有运营商明确采用 IP1 / IP8 / IP16 时才保留该套餐别名，并分别映射至通用 Address Model。当前 JP Beta 在未确认具体合同套餐前统一表述为 OCN Virtual Connect Fixed IP。

本项目日本服务目录覆盖下表的 7 个主要 VNE 服务体系；正文、矩阵和原型共用该目录。该范围不代表日本 VNE 总数。零售 ISP 品牌映射至其上游服务。

下表分别记录服务侧 HB46PP 支持、用户输入和 Omada 验证状态。公开资料核验于 2026-10-12：明确支持 HB46PP 的服务来自 v6 Connect、BIGLOBE IPv6 Service（IPIP）、OCX / v6IX；其余四家在已查官方矩阵中仅列专用配置路径，暂不标记为 HB46PP 支持。竞品互通记录不等于 Omada 已发布或已认证。

自动配置与手填分开看：HB46PP 自动获取所需隧道参数；仅在 ISP 要求认证时填写其提供的用户名 / 密码。选择 VNE 的专用路径也可能无需额外输入。表中手动参数是所选路径的基线，自动取得、可靠预置或旧配置已有的值不要求用户重复填写。HB46PP 认证与固定 IP 更新服务器凭据按各自用途处理。HB46PP 依据 · Yamaha 输入项依据

P0 产品建议

1. 现有能力无损迁移

• Controller 对旧格式双读：将现有配置经 Legacy Config Adapter 解析为统一 IPv4OverIPv6Intent；不要求用户重新选择运营商或重填参数。
• 映射以稳定内部 ID 为准，不以 Provider / Profile 显示名称推断；无法识别或 Catalog 不可用时保留原始 Payload 与解析参数快照，以 Imported Legacy Configuration 继续运行。

DS-Lite Auto 是 DS-Lite Engine 内的 AFTR 自动分配，不映射为顶层 Automatic。OCN Fixed Beta 使用其独有字段识别，单独迁移至 OCN Virtual Connect Fixed IP Plan，不与现有 OCN Dynamic / Shared 配置混用。

2. 新增 Service / Service Plan

• OCN Virtual Connect Fixed IP：将已验证 Beta 产品化，输出 Single Fixed IPv4；继续由 OCN-specific Service Profile 绑定对应 MAP-E 实现。Service Plan 文案按实际运营商套餐配置，不在通用产品定义中预设为 IP1。
• Fixed IPv4 Prefix：保留为运营商无关的 Address Model；首期按 P0 门禁选择具备正式规范和真实线路条件的 Service Plan 完成验证，不预先锁定 transix 等具体新增 Plan。

3. 新增 Automatic / HB46PP

• 在日本通过 HB46PP dslite + ipip 提供完整服务自动解析；Automatic 不预选 Service。
• Service Plan 可绑定同一 HB46PP Adapter，供 Select Service 路径按合同选择后自动取参。
• 在 v6 Connect 与第二个独立 VNE 上完成实线互通，第二条优先 BIGLOBE IPv6 Service，避免实现固化为单一客户特例。

4. Fixed Prefix 验证

• 数据模型至少覆盖 /29、/28，并在一条真实多地址线路上完成 Tunnel、本机 Router Service IPv4 与既有 IPv4 功能验证。
• /27、/26 保持模型兼容，但无 Provider 实线证据时不形成对外承诺。

后续 Profile 继续按以下门禁进入迭代：市场覆盖与可复制需求、主流竞品覆盖、Engine / Schema 复用、官方规范与认证条件、测试线路准备度。

2.3 Non-goals

• 不新增 VPN 协议，也不把原生 IPv6 VPN / Server 作为本期阻塞交付。
• 不承诺“覆盖日本所有线路”；按 Provider / VNE family 系统化扩展。
• 不将 Line Auto Detection、HB46PP 完整服务解析、DS-Lite AFTR Auto 与 DHCPv6 S46 参数获取合并为同一层级。
• 不把 Provider-specific 参数塞入 Generic Custom Schema。
• 不将 Fixed Prefix 建模为 WAN Alias，也不在本期宣称完整 IP8 / IP16 Public Subnet Handoff。

3. 产品架构

3.1 核心原则

• Setup Method 是能力驱动的配置入口：Automatic 仅在完整服务解析可用时展示；Select Service 仅在存在适用 Catalog 条目时展示；Manual 按支持的 Engine 展示。
• Resolution Orchestrator 统一参数来源：HB46PP、Service Plan、DHCPv6 AFTR / S46 与 Manual 均输出 Resolved Service Spec。HB46PP 可同时服务 Automatic 与绑定该 Adapter 的 Service Plan。
• 自动化分层：Automatic 不预选 Service；DS-Lite AFTR Auto 与 DHCPv6 S46 是已知 Engine / Service 上下文中的参数自动获取。
• Engine 与 Address Assignment 并列：二者由 Resolved Service Spec 同时确定，再汇合为统一 IPv4 WAN Service。
• 业务绑定保持稳定：Existing IPv4 与 Multi-WAN 功能绑定 logicalServiceId，不直接绑定 HB46PP Session、Profile 或 Tunnel Session。
• 运行状态分层：IPv6 Underlay → Configuration Resolution → Engine Session → IPv4 Service → Internet Reachability。

3.2 End-to-End Architecture

Controller 保存产品意图并下发设备；设备在可用 IPv6 Underlay 上解析服务、建立 Engine Session、完成地址分配并输出统一逻辑 IPv4 WAN。Fixed Prefix 的剩余地址进入 Address Allocation State，供后续 Public Subnet Handoff / DIA / NAT 使用。

3.3 Configuration Surface

保留 Omada 的 WAN 列表、Edit WAN Connection 与 IPv4 / IPv6 双栈表单。IPv4 over IPv6 下选择 Automatic、Select Service 或 Manual：Automatic 按需显示认证；Select Service 只显示 VNE、适用的 Service Type 和必填参数，单一连接类型时隐藏 Service Type 整行；Manual 显示 Tunnel Type 及必要参数。IPv6 设置独立保留，Apply 校验当前输入，Cancel 恢复最近一次已保存配置。后台解析、对象与业务绑定由下文说明，配置页只承载用户选择和填写。

3.4 Controller Architecture

Controller 负责：

• 版本化 Service Catalog（后台 Provider → Service → Service Plan）与动态字段 Schema；
• WAN Service Intent 的 setupMethod、互斥 methodConfig 与稳定 logicalServiceId；Automatic、Select Service、Manual 的可用性分别由完整服务 Resolver、适用 Catalog 条目与 Engine Capability 决定；Select Service 路径条件性保存 catalogVersion 与 planId；
• Legacy Config Adapter：旧格式双读、稳定 ID 映射、原始 Payload 与解析参数快照保留；
• 按单台设备 Capability 选择唯一编辑入口与配置编译器：新能力固件只显示统一入口并接收新对象，旧能力固件保留 MAP-E / DS-Lite 原入口并接收反向编译的旧格式；
• 分层运行状态投影、Reconnect、Re-provision 与诊断导出。

Controller 数据升级仅转换管理对象，不自动下发、不触发 WAN 重连。它不执行 HB46PP、Tunnel 或数据转发。

3.5 Gateway Device Runtime

设备侧由 IPv6 Underlay Manager、Resolution Orchestrator、HB46PP / Service Plan / DHCPv6 AFTR-S46 / Manual Resolver、Engine Manager、Address Assignment Manager、IPv4 WAN Service Adapter 和 Lifecycle / Recovery Orchestrator 组成。HB46PP 到期、IPv6 Prefix 变化或 Engine 重建时，更新 Runtime，但保持 logicalServiceId 与业务绑定。

3.6 Backend Object Model

核心对象关系：

• WanInterface 一对一拥有 IPv6UnderlayIntent 与 IPv4OverIPv6Intent。
• IPv4OverIPv6Intent 保存 setupMethod、互斥的 methodConfig、Underlay 引用与 logicalServiceId；只有 Select Service 的 methodConfig 引用 catalogVersion 与 planId。
• LegacyConfigSnapshot 保存旧格式、稳定映射 ID（如可识别）、原始 Payload 与解析参数快照；未知 Profile 或 Catalog 不可用时仍可作为 Imported Legacy Configuration 运行。
• ProviderCatalog 按 Provider → Service → Service Plan 组织；ServiceSelectionConfig 通过 serviceId 与 servicePlanId 引用目录条目。
• ServicePlan 保存 resolverBinding、enginePolicy、addressModel、formSchema、lifecyclePolicy、routerAddressPolicy；resolverBinding 可引用 HB46PP、DHCPv6 参数 Adapter 或 Provider-specific Resolver。
• ResolutionOrchestrator 根据 Intent、Underlay 与 Service Plan 选择 HB46PP、DHCPv6 AFTR / S46、Service Plan 或 Manual 输入，并统一输出 ResolvedServiceSpec。
• ResolvedServiceSpec 并列输出 engineSpec 与 addressAssignmentSpec。
• EngineSession 与 AddressAllocationState 汇合成 IPv4ServiceRuntime。
• Existing Function Binding 与 Multi-WAN Binding 只引用 logicalServiceId。

3.7 Emulator-based Interactive Prototype

Open the Omada IPv4-over-IPv6 WAN Design Prototype

原型基于当前 Omada Controller Emulator 的 WAN 页面结构，覆盖：

• 在现有 IPv4 Configuration 中提供 Automatic、Select Service、Manual 三条配置路径；
• 7 家 VNE 共用已核实的目录，按连接类型显示必要参数；仅一种连接类型时省去重复选择；
• Automatic 按需填写认证信息；Manual 提供 DS-Lite 与 IPv4-in-IPv6 Tunnel 的必要配置；
• 保留独立 IPv6 Configuration，并演示必填校验、Apply 与 Cancel。

原型仅用于配置交互评审；输入只保留在当前页面内存中，不连接设备或模拟在线结果。产品架构、迁移、诊断及 Multi-WAN 绑定继续在技术附录说明。

4. P0 Core Capabilities

FR-01 · Unified WAN Intent

• 在现有 WAN 对象内新增 IPv4 over IPv6 配置族，不建立区域专用 WAN 类型。
• 可用 Setup Method 使用互斥配置对象，并输出统一 IPv4OverIPv6Intent；不存在对应能力或目录内容的方法不显示、不可保存。
• 保持稳定 logicalServiceId；Profile 变更、Re-provision、Prefix 变化与 Engine 重建不重写既有业务绑定。
• 现有 MAP-E / DS-Lite 配置通过 Legacy Config Adapter 升级为统一 Intent；迁移只更新 Controller 管理对象，不自动下发或改变原值、WAN 身份与业务行为。

FR-02 · Resolution & Automatic Configuration

• 提供统一 Resolution Orchestrator 与可扩展 Adapter 接口，支持 HB46PP、Service Plan、DHCPv6 AFTR / S46 与 Manual 参数源。
• P0 日本通过 HB46PP v1 dslite 与 ipip 提供完整服务 Automatic，处理认证、Capability、TTL / expiry、last-success、retry 和错误状态；Automatic 不要求用户预选 Service。
• Select Service 的 Service Plan 可绑定同一 HB46PP Adapter，按已选合同取得参数。
• DS-Lite AFTR Auto 保留在 DS-Lite Engine 的 AFTR Assignment = Auto / Manual 中；DHCPv6 S46 作为 Engine-level parameter provisioning。二者可复用 Resolution 接口，不映射为顶层 Automatic。
• 所有 Resolver 只生成 Resolved Service Spec，不直接成为 WAN Engine。

FR-03 · Service Catalog

• Catalog 后台采用 Provider → Service → Service Plan 层级并版本化；Select Service 用户界面展示 VNE → Service Type → 必填参数，只有一种连接类型时省去 Service Type。公司归属作为后台元数据。
• Plan 绑定 Resolver、Engine、Address Model、字段 Schema、Lifecycle Policy 与 Router Address Policy。
• Profile Resolver 可使用静态参数、Provider-specific 参数获取、DHCPv6 参数 Adapter 或 HB46PP Adapter。
• 同一 Provider / Service 下的 Dynamic / Shared IPv4、Single Fixed IPv4、Fixed IPv4 Prefix 作为 Plan 管理。

FR-04 · Engines & Address Assignment

• 复用 DS-Lite、MAP-E；新增 Generic IPv4-in-IPv6 Tunnel。
• Custom P0 提供 DS-Lite 与 Generic Tunnel 的标准参数；Provider-specific 字段由 Profile Schema 承载。
• 支持 Dynamic / Shared IPv4、Single Fixed IPv4 与 Fixed IPv4 Prefix。
• Fixed Prefix 保存 assignedCidr、routerServiceIpv4、availablePublicIpv4Range，按运营商合同与 Profile 规则确定本机地址。当前配置原型只展示已核实的接入必填项；多地址的分配与使用方式在对应功能设计中展开。
• IPv6 Address / Prefix 或 Provider 参数变化后，按 Lifecycle Policy 重新解析并重建服务。

FR-05 · Normalized IPv4 WAN & Business Compatibility

• 统一 IPv4 WAN Service 接入 Internet / NAPT、Static / Policy Routing、Firewall / ACL 与现有功能选择器；实际可用项由 Address Model 和 Service Plan Capability 决定。
• Dynamic / Shared IPv4 支持出站 Internet、既有路由与安全策略、VPN 发起端及 Multi-WAN；受 Provider 地址或端口机制限制的入站功能不开放。
• Single Fixed IPv4 与 Fixed IPv4 Prefix 的 Router Service IPv4 支持 Port Forwarding / Virtual Server，以及型号已有的 IPsec Site-to-Site 发起端 / 响应端与 Client-to-Site IPsec。
• 支持作为 Load Balancing、Link Backup / Failover 的成员 WAN，复用现有 Health Check、切换与恢复。
• 支持 Cloud 与 Controller 连接所需的现有 IPv4 路径。

FR-06 · Status, Recovery & Diagnostics

• 展示 IPv6 Underlay、Resolution、Engine Session、IPv4 Service、Internet Reachability 五阶段状态。
• 展示 Service / Service Plan、Provider / VNE 元数据、last-success、失败阶段与 retry；DS-Lite 展示 Provider NAT / AFTR 状态，MAP-E Shared 展示 Shared IPv4 / Port Set，Single Fixed IPv4 / Fixed IPv4 Prefix 展示 Router Service IPv4、Assigned Prefix / Available Range。
• 提供 Reconnect、Re-provision 与诊断导出。
• Tunnel Up 不等同于 Internet Ready；状态与告警按失败阶段定位。

FR-07 · Legacy Config Adapter & Mixed-version Compatibility

• Controller 必须双读旧 MAP-E / DS-Lite 格式，并将其解析为统一 IPv4OverIPv6Intent；八类既有配置按本 PRD 的完整映射表迁移。旧字段（Provider 选择、AFTR、VLAN、IPv6 Underlay、DNS 等）逐项保留。
• 每台设备只显示其适用的一套入口：新能力固件只显示 IPv4 Configuration → IPv4 over IPv6；旧能力固件只显示原 MAP-E / DS-Lite 入口。批量配置与模板复制只提供目标设备 Capability 的交集。
• Config Compiler 按目标设备 Capability 下发：新能力固件接收统一对象，旧能力固件接收可逆编译的旧格式。Controller 管理对象升级不自动下发、不触发 WAN 重连。
• Legacy Profile 映射必须使用稳定内部 ID；Catalog 改名、删除或当前不可用不得静默改变已解析服务的 Engine 或参数。未知 Profile 保留 originalPayload 与 resolvedParameterSnapshot，以 Imported Legacy Configuration 展示并继续运行。
• 可由旧格式完整表达的统一配置允许反向编译、备份恢复、重新接管及设备 / Controller 降级，且保持相同服务语义与稳定引用。使用 HB46PP、Generic IPv4-in-IPv6 Tunnel 或其他旧格式无法表达的能力后，必须阻止降级或要求先显式转换，不得静默丢弃字段。

5. Observable Behavior & Acceptance

5.1 主流程

1. 用户编辑现有 WAN：新能力固件在 IPv4 Configuration 中选择 IPv4 over IPv6，并从当前可用的 Setup Method 中选择一种；Automatic 取决于完整服务 Resolver，Select Service 取决于适用 Catalog 条目，Manual 取决于 Engine Capability。旧能力固件继续使用原 MAP-E / DS-Lite 入口。
2. IPv6 Configuration 建立 Underlay；Resolution Orchestrator 获取或解析服务参数。
3. Resolved Service Spec 并列确定 Engine 与 Address Assignment。
4. 设备建立 Engine Session，并生成具有稳定 logicalServiceId 的 IPv4 WAN Service。
5. Existing IPv4 与 Multi-WAN 功能继续引用该逻辑 WAN；Controller 展示分层状态和恢复操作。

5.2 P0 Acceptance Criteria

• 当前可用的 Automatic、Select Service、Manual 均生成同一逻辑 IPv4 WAN 对象；缺少完整服务 Resolver、Catalog 条目或 Engine Capability 时，对应方法不显示且不能通过接口保存。
• 日本 P0 的 Automatic 无需预选 Service，可由 HB46PP 解析 Service、Engine、Address Model 与参数；Select Service 的 Plan 可绑定同一 HB46PP Adapter。
• DS-Lite AFTR Auto 与 DHCPv6 S46 在 Engine / Service Plan 上下文中完成参数获取，不显示为顶层 Automatic。
• HB46PP dslite 可建立 Dynamic / Shared IPv4 Service；HB46PP ipip 可建立 Single Fixed IPv4 Service。
• HB46PP 至少在 v6 Connect 与第二个独立 VNE 上完成实线互通。
• OCN Virtual Connect Dynamic / Shared 与 Fixed IP 在同一 Service 下按 Service Plan 配置；后者映射为 Single Fixed IPv4 Address Model，并已验证 Beta 路径。
• 经 P0 门禁选定的 Fixed IPv4 Prefix Service Plan 可建立 Generic Tunnel，并在真实线路上完成 CIDR、Router Service IPv4 与 Available Range 解析；具体新增 Provider / Plan 以项目评审和测试条件为准。
• Fixed Prefix 数据模型至少验证 /29 与 /28；本期验证本机 Internet / NAPT 与既有商用功能，不要求将剩余地址交付至 LAN / VLAN。
• Custom 可完成 DS-Lite 与 Generic Tunnel 标准参数配置；Custom 不展示 MAP-E。
• Fixed IPv4 Service 可被 Routing、NAPT、ACL、Port Forwarding 与现有 IPsec 使用。
• IPv4 Service 可加入 Load Balancing 与 Link Backup / Failover，完成 Health Check、切换与恢复。
• 重启、WAN 重连、IPv6 Prefix 变化与 Provisioning 到期后，配置、Runtime 与业务绑定可恢复，logicalServiceId 不变。
• OCN Beta 配置可迁移至正式 Plan。
• 所有在维 Omada Gateway 型号采用相同对象、状态模型与功能范围；允许分批验证与发布。

5.3 Legacy Migration Acceptance Criteria

• 表中八类现有 MAP-E / DS-Lite 配置升级后，不重新输入参数即可保持原有联网行为；DS-Lite Auto 保持 AFTR 自动分配，DS-Lite Manual 的 AFTR Name / IPv6 原值可观察且不变。
• Controller 数据升级后，设备没有自动下发记录、WAN 没有因升级而重连；原 WAN ID、logicalServiceId 及 Routing / NAT / ACL / VPN / Load Balancing / Link Backup 引用均保持不变。
• 在统一页面直接保存迁移对象后，旧字段（Provider、AFTR、VLAN、IPv6 Underlay、DNS 等）与迁移前一致，设备行为无差异。
• 新旧能力固件混跑时，每台设备只显示其适用入口，并由 Compiler 生成对应格式；批量配置和模板复制不会暴露目标设备不支持的字段或能力。
• Catalog 改名、删除或条目缺失不会改变已迁移服务的 Engine、已解析参数或运行状态；未知 Profile 以 Imported Legacy Configuration 展示，并可从原始 Payload 与参数快照继续运行。
• OCN Fixed Beta 仅在其独有字段可靠识别时迁移至 OCN Virtual Connect Fixed IP Plan；现有 OCN Dynamic / Shared 不会被误迁移为 Fixed Plan。
• 旧格式可完整表达的统一配置可反向编译，并经备份恢复、设备重启、重新接管及 Controller / 设备降级后保持相同服务语义与稳定引用。
• 使用旧格式无法表达的能力时，降级被明确阻止或要求先显式转换；Dynamic / Shared IPv4 不会因迁移错误开放公网入站能力。

6. 研发预评审需确认

本轮以范围与架构预评审为目标，不要求在会前冻结详细交互文案或准确排期。