fin-micro 从零接入

完成下面四章后，你会得到一个能登录、加载授权菜单、打开订单子应用、编辑详情并保存返回的桌面后台。子应用也能独立登录运行。教程统一使用 my-host、order-app、appId order，所有命令、文件和接口响应围绕这套工程展开。

第一次接入按这个顺序

步骤	要完成什么	结束时如何确认
1. 创建并跑通主子应用	从空目录创建、安装、配置 appId/entry、启动	无后端也能从基座演示登录打开子应用模板详情
2. 认证、菜单与独立登录	启动可下载的教学 API、配置代理、共享认证和 CSRF	基座真实请求登录；子应用单独打开也能登录并刷新恢复
3. 订单页面与保存返回	复制完整 API/列表/详情文件，同步权限	打开不同订单，保存备注成功后关闭详情并返回列表
4. 构建、部署与验收	配置生产入口、资源 base、网关与 SPA 回退	生产构建、直接刷新、独立入口和权限验收逐项通过

之后再做第二个子应用与跨应用返回。每章都有文件位置、完整示例和预期结果；不要跳过第二章就用第一章的演示身份请求真实业务接口。

先准备： Node.js 22 LTS、npm、三个终端，以及能安装配套版本的 registry。教程与当前仓库模板同步；尚未发布的改动需通过候选包流程验证，不能假定 npm latest 已包含。教学 API 只供本机接入练习，上线需要接自己的服务端。

已跑通后按问题查阅

需求	参考章节
tabId、参数、back、跨应用授权	导航契约
多详情缓存、刷新、浏览器历史恢复	缓存与浏览器
能力调用、事件、Token、认证失效	宿主通信
多语言映射、独立 Token 开发设置、权限工具	认证与公共能力
平台四模块、数量限制、CSRF、CORS、模板迁移	平台适配
应用加载失败、就绪超时、卸载、资源预算	运行时治理
特殊的跨窗口通信	iframe RPC
阅读源码、理解生命周期和优化边界	代码分层与实现解读
完整公开入口与排错索引	API 参考

下面的职责说明用于理解生成项目，首次接入可直接从第一章开始。

一、先明确各层职责

层	提供什么	不提供什么
core	应用注册、页签状态、导航事务、守卫、能力白名单、公开会话	DOM、Vue 页面、业务服务端鉴权
sdk	框架无关类型、取桥、页级调用契约、稳定错误	宿主实例、页面缓存、跨窗口传输
runtime	Wujie 挂载、同 appId 单实例、加载中断和清理	页签 UI、页级缓存、自动重试业务写请求
vue	应用容器、状态订阅、路由连接、页签缓存、页面 SDK 绑定	业务路由定义、草稿持久化
browser	基座地址栏与导航元数据恢复适配	恢复 Vue 实例、恢复表单草稿、替代权限验证
iframe	独立窗口间的受控请求响应	完整 AppBridge 的透明代理、跨窗口页面缓存

正常调用链为：业务页面 → 固定生命周期的 PageSDK → 宿主策略与导航事务 → 宿主状态 → 应用运行时/路由适配 → 目标页面。

通信采用三条不同通路：有响应操作走 callHost，无响应业务通知走事件，导航走页面导航 API。不要用事件模拟有返回值的请求，不要让子应用拿到整个宿主对象。

二、三个必须区分的标识

• appId：决定加载哪个应用。同一 appId 只对应一个运行实例。
• tabId：宿主全局唯一的业务页签标识。例如 order:detail:1001；多个详情必须使用不同标识。
• key：宿主分配的页面生命周期。关闭重开、刷新或同 tabId 更换路由会产生新 key，用于隔离旧 SDK、旧异步任务与旧缓存。

route 是子应用内部绝对路径，例如 /detail?id=1001，不能替代 tabId；activeMenuId 只负责该应用内菜单归属，不能决定应用加载或访问权限。

三、当前支持与明确边界

• 子应用框架不限；Vue 有现成页面缓存适配。其他框架自行实现渲染与页面生命周期，不应导入 /vue。
• Wujie 的同窗口函数桥是工程边界，不是针对恶意代码的安全沙箱。
• 显式跨应用目标通过 page.navigateTo(target) 或 page.back(target) 申请，由宿主 canNavigate 授权；前者保留来源页，后者关闭本页。openTab/operate 不因此获得任意跨应用目标权限。
• 导航结果 committed 表示页签状态已提交，不表示资源下载、子应用挂载、数据请求全部成功。
• 功能页 back(target) 关闭本页并优先去指定目标，back() 返回宿主内存中的来源；跨应用来源须开启 crossAppBack。它不是浏览器后退，也不改变页签栏关闭规则，详见使用方式与参数迁移。
• 缓存停用保留页面实例；关闭、刷新和 LRU 淘汰会真正卸载。离页守卫不拦截浏览器整页刷新或 LRU 淘汰。
• 超时或取消只结束等待并通知协作信号，不撤销已经执行的保存、支付或其他服务端副作用。业务写操作不要盲目自动重试。
• 认证快照不包含 Token；本库没有内置登录服务、自动续期或服务端权限系统。

四、仓库中的可运行参考

位置	用途
packages/fin-micro/src	公开实现，接口以这里和构建声明为准
packages/fin-micro/scaffold/host/src/platform	认证、私有会话、菜单解码与准入策略；旧 platform.ts 保留兼容导出
packages/fin-micro/scaffold/host/src/layout	基座编排、Header、菜单、工作区与页签栏职责拆分
packages/fin-micro/scaffold/vue/src/bootstrap.ts	连接桥、协议协商、路由同步和卸载失效处理
packages/fin-micro/src/vue	公共 MicroRouteView：缓存页面独立路由上下文与加载/错误边界
packages/fin-micro/scaffold/vue/src/views/demo/hooks/useRecordNavigation.ts	业务列表到详情的权限判断与页签导航

CLI 基座默认登记 business，report 为需手动启用的第二应用示例。真实系统中应替换成各自应用的部署地址及权限策略；登记入口不代表用户授权，默认也不授予读取宿主 Token 的能力。