#Client · NS App、CLI 与门户实现规格

Client 是用户与 NSIO Next 交互的产品层，包含桌面/移动 NS App、ns CLI、租户管理控制台和成员应用门户。Client 负责收集意图、展示事实和引导恢复，不拥有网络授权或路由算法。

每项能力的用户入口、状态组合和角色预演见产品能力目录与实现闭环；AccessRequest、角色、Capability、Share、Posture 等管理流程以控制资源生命周期为权威，逐功能实现证据以功能闭环总账为权威。Client 必须消费这些结构化事实，不能复制下层求值或状态机。

#1. 产品表面

#2. Client 不变量

• App 不接触密码，使用系统浏览器完成 Authorization Code + PKCE；
• App 缓存只能优化展示，启动和授权始终读取 daemon/NSD 权威；
• ACL、CIDR containment、gateway supports_scope、route conflict 由下层返回结构化结果；
• 成功、等待、拒绝、读取失败、协议不兼容分别展示；
• 安全降级必须由用户明确触发，不能自动恢复本地直出；
• 未连接时仍可登录、查看本地配置、导出诊断和恢复平台状态。
• App/CLI 只连接唯一 ns runtime；版本不兼容时只提供诊断和签名升级，不启动第二个引擎。
• 桌面 App/CLI 只能控制绑定到当前 OS principal 的 user-owned runtime；非所有者既不能使用其网络身份，也不能看到其租户状态。

#3. NS App 信息架构

#3.1 首页

首页只回答：是否连接、当前连接范围/质量、可以访问什么。

纵向结构：

1. 横向连接卡：状态、当前 Organization/Network、主按钮；
2. 必要状态条：出口、外部 VPN/IPv6、投影故障、待处理审批；
3. 最近节点和 Service；
4. 查看全部入口。

首页不放独立 Gateway 功能卡、不展示装饰性指标、不把读取失败画成空列表。

#3.2 Nodes

列表显示节点名称、owner/assigned principal（有权限时）、系统、在线、路径和可用动作。详情显示 Node FQDN/IP、最近连接、被授权端口/协议摘要和诊断。点击 SSH/RDP/Ping 是明确命令，不把 Node 当 Service 自动打开浏览器。

#3.3 Services

紧凑列表保持统一高度，标题行可带清晰类型标识：Service、Gateway Egress、内部/公开。域名过长中间省略并可复制完整值。筛选使用单选菜单或 segmented control，当前值始终显示；协议与服务类型是两个独立筛选维度。

详情/弹层显示协议、域名、状态、标签和主动作。成员看不到 backend、完整策略或无权资源。

#3.4 Publish

发布向导步骤：选择后端类型 → 输入地址/端口或发现本机服务 → 健康测试 → 名称/协议 → 可见性和本地授权上限 → 影响预览 → 提交。

结果区分本地保存、等待 NSD、等待管理员、在线、后端失败和本地拒绝。取消远端审批不删除本地草稿；停止发布要求选择仅停 Endpoint 或删除 Service 声明。

#3.5 Settings

分组：Account/Profile、Connection、Internet Exit、DNS/Proxy、Service Host、Privacy/Diagnostics、Advanced。高级平台选项不在普通流程中展开；存在 CLI 非默认配置时显示只读摘要，写入前必须 read-modify-write，读取不完整则禁止覆盖。

Account 同时提供个人数据导出、登录方式/会话和账号注销；Organization 删除只在租户控制台提供并展示 ownership、Billing、Device、Service、审计和 Legal Hold 影响。Billing、发票、SLA、状态页和支持入口按角色显示，不能让普通成员看到财务资料。

#4. 首次使用

Open App
  → choose/control NSD endpoint
  → open system browser
  → login/register
  → callback to App
  → show Organization/Network if multiple
  → create Enrollment Request
  → approval or immediate Grant
  → start runtime
  → show connected + available resources

浏览器返回只建立用户会话；Device 注册仍需 Device Key + Enrollment Grant。登录成功但审批未完成时显示“账号已登录，设备等待批准”，不能显示“已连接”。

取消后保留账号会话，撤销本次 Enrollment Request，清理对应 staging key。重启 App 可凭 request ID 和 staging key 恢复。

#5. 连接按钮

点击连接的状态机：

App 使用 operation stream，不用假进度条。标准连接建立但出口候选尚未到达时，应显示“已连接，私网服务可用；正在获取互联网出口”，不隐藏真实连接。

#6. Internet Exit

出口是连接设置，不是首页模块。设置中一个“互联网出口”开关表达用户意图；打开会将数据面要求设为 TUN/VPN。未选择出口也允许点击连接：先建立标准连接、获取授权候选，再弹出选择。

候选弹窗：单选列表，显示 gateway name（缺失回退 ID）、范围和 availability；失效当前项不预选。提交直接调用 runtime configure，由权威校验，不能先本地比对制造 TOCTOU。

流量文案必须依据 capture 与 scope：ready 才说“出口范围内流量已阻断/已转发”；inactive/not_ready 只说“未经过公司出口”。external_unmanaged 明确显示“IPv6 由其他 VPN 管理，未经过公司出口”。

#7. 多 Organization / Network

登录后只有一个空间时直接进入；多个空间显示名称与角色。当前 Profile 持久化为用户偏好，但 daemon 仍验证其存在和权限。

切换前 App 请求影响预览：将断开的 Node/Service、DNS/route 冲突、正在运行的 Exit 和未保存发布草稿。用户确认后 runtime 完成停止、切 Profile、启动；失败时恢复原 Profile 或进入明确 blocked，不形成 UI 与 runtime 分叉。

#7.1 多 OS 用户共用桌面

多 Organization/Profile 是同一 OS principal 的产品能力，不等于多个 OS 用户可以共用一个系统级隧道。桌面首版遵守发行生命周期的 single-active-OS-user 规则：

非 owner 不显示 Connect、Disconnect、Profile switch、Publish、Exit、诊断导出或完整卸载动作。可以显示版本、更新和“联系本机管理员/等待另一用户退出”的恢复说明。客户端不能通过缓存重现 owner 的最后目录或名称。

#8. CLI

CLI 文本适合人读，--json 只输出结构化 payload 到 stdout，日志到 stderr。非交互环境不弹浏览器、不自动选择第一个 Network、不把暂时不可用返回成功。

#9. 管理控制台

租户控制台导航：Overview、Members、Devices、Networks、Services、Access、Capabilities、Public Applications、Routes、Gateways、Roles、Audit、Settings/Billing。角色控制导航和 API，隐藏菜单不等于授权。

控制台直接渲染服务端权威对象及 allowed actions：Access 分别展示 AccessGrant 与 AccessRequest/TemporaryAccessGrant；Capabilities 展示 Policy eligibility、逐实例 Activation、Availability、projection 和 quota allocation；Roles 编辑 AdminRoleBinding 的明确 action/resource scope；Share 展示 Offer/Federation/Binding 三段状态；Devices 分开显示 ownership、Membership、Posture 和 key rotation。页面不得把这些轴压成一个 active 开关。

关键交互：

• Overview 只显示待处理事实，每个数字进入已过滤列表；
• Access 以“谁 → 从哪台设备/环境 → 访问什么 → 做什么 → 条件”编辑，只覆盖 Node/Service/Route/ExitProfile，保存前调用生产编译器 dry-run 模拟影响；
• Capabilities 以“谁可申请什么 → 最大范围 → 是否自动批准”编辑；每个实例仍显示独立 Activation 审批、配额和 lease；
• Public Applications 从已有 Service 创建，认证方法明确选择 OIDC/API Key/Service Credential/Signed URL/mTLS/Anonymous，并与内部 Access 状态并排展示；
• Roles 单独编辑 AdminRoleBinding，不提供万能 administer 开关；
• Access Request 的 approve/reject/revoke、Capability 的 approve/suspend/revoke、Share 的 accept/revoke、Posture provider/claim 失效都使用服务端返回的 allowed actions、expected revision 和 impact digest；Client 不猜状态转移；
• Service/Route/Gateway 详情同时显示声明、授权、投影和 runtime 健康，不合成一个 Active；
• 删除/撤销先从服务端取 impact digest，确认时重新校验；
• 读取失败保留最后结果并显示 stale + request ID，不展示空状态；
• 平台 Admin 不能通过同一 API 绕过租户角色。

#10. Member Portal

Portal 只返回成员自己需要的最小数据：已授权 Service、由这些 Service 推导的站点/节点摘要、自己的 Device 和身份安全设置。不得返回完整 policies、全量机器、无归属节点或管理员对象。

打开 Service 时优先使用 NS App/deep link；Web 应用可复制 FQDN 或打开浏览器。MFA、Passkey、恢复码和 API Token（若产品开放）必须有真实操作入口，按钮不能只渲染文案。

#11. Client 状态架构

Controller/ViewModel 保存结构化模型：local runtime ownership、session、profile、daemon lifecycle、membership、directory freshness、connection readiness、exit intent/readiness、operations 和 errors。派生 UI 状态必须是纯函数，禁止在 build/render 中执行网络副作用。

每个异步操作有 operation ID、phase、cancelability 和 retry policy。互斥操作期间禁用连接/设置按钮；失败后偏好与 runtime 必须一起回滚或明确标记 pending repair。

#12. 缓存规则

可缓存：上次显示名称、最近目录、筛选偏好、窗口布局、非敏感 onboarding 进度。不可作为权威：授权、Gateway 候选、当前 runtime、有效 Membership、Entitlement。

缓存项携带 source/profile、revision 和 observed_at。source 不匹配时不展示可能误导的资源名；连接后立即以权威结果覆盖。

#13. 错误与文案

Client 穷尽匹配已知 error code；未知 code 显示“组件版本不兼容或发生未知错误”并附 request ID，不回落成网络失败。

文案规则：

• no_authorized_candidates：管理员尚未分配；
• temporarily_unavailable：已授权资源当前不可用，不猜离线还是停用；
• read_failed：暂时无法获取，可重试；
• source_mismatch：保存配置属于另一个连接；
• route_conflict：显示冲突 CIDR/软件，不建议强制覆盖；
• projection_outdated：展示已应用 revision、待应用 revision，以及旧投影仍有效/已过期事实。
• runtime_owned_by_another_local_user：只说明本机另一用户正在使用，不泄露对方身份或网络；
• runtime_owner_inactive：说明因本机用户切换已暂停，原 owner 可明确重连；
• runtime_owner_release_required：要求原 owner 释放，或由管理员确认破坏性 reset；
• concurrent_interactive_sessions_unsupported：保持断开，说明首版不支持多交互用户共享系统隧道。

#14. 平台权限

App 在真正需要 TUN/VPN、helper 或防火墙能力时才请求系统权限，并提前说明系统将显示什么原生提示。权限拒绝不影响登录、目录和 Proxy-only 能力。Windows 输入法、窗口 focus 和 UAC 必须通过原生 runner 生命周期测试，避免连接时整窗闪烁或第三方 IME 崩溃。

Windows session change、macOS console user change 和 Linux logind 事件是安全输入，不是普通 UI hint。Client 只展示 daemon 的结构化 owner state，不自行猜测当前用户是否可以接管。平台没有可靠的 session-change hook 或不能证明网络先撤后切时，user-owned 连接入口保持禁用。

移动端使用平台 VPN API；后台限制、Always-On、休眠和网络切换状态必须映射到 runtime，而不是由 UI 定时器猜测。

#15. 可访问性与国际化

所有状态不能只靠颜色；图标有语义标签和 tooltip；键盘可完成登录后所有桌面操作；动态文本不改变固定工具栏/列表尺寸。中英文 key 同步由测试检查，删除功能同时删除孤儿文案。

#16. 隐私与遥测

遥测默认不含访问的业务域名、完整 Node/Service 名称、IP、用户目录或错误 payload。崩溃报告需要用户/组织策略同意并脱敏。诊断导出前显示包含内容，生成后可本地检查。

产品分析只使用服务运营规格定义的 allowlist 和激活状态转移。App Store/Play 披露、用户同意和实际 payload 必须一致。更新、企业托管和卸载交互以发行生命周期为权威。

#17. 测试与完成条件

• ViewModel/state reducer 对所有 authority/projection/runtime 组合做表驱动测试；
• 注入自动安全降级、故障变空列表或缓存驱动启动时测试必须失败；
• 新/旧一版 Next daemon 的可选字段与未知 major 行为；
• 商店/官网/MDM 安装升级、唯一 daemon、卸载清理、账号/组织导出删除和 Billing 角色；
• 两个 OS 用户、快速切换、并发交互会话和 managed-device 模式；非 owner UI/CLI 不出现租户数据或控制动作；
• 冷启动、登录后手动/自动连接和 managed-device 无人值守恢复；后台 daemon 自启不被 UI 误报为 user-owned 网络已连接；
• 登录 callback、Device Code、Enrollment 恢复和多个 Network；
• 连接/取消/失败恢复、出口首次选择/更换/关闭；
• 服务筛选、长域名、类型标签、空/错/stale 状态；
• Windows/macOS/Linux 桌面，iOS/Android VPN 生命周期真机；
• 屏幕阅读器、键盘、200% 缩放和中英文长文本；
• Portal 成员边界精确集合测试。
• AccessRequest、TemporaryAccessGrant、AdminRoleBinding、CapabilityActivation、Share/Federation、MachinePrincipal、Posture 和 key rotation 的全状态、allowed-action 与错误映射。

Client 完成的标准不是页面能点击，而是每次操作都能追踪到权威命令、runtime 结果、失败恢复和审计证据。