City-Lifeline-Cockpit/openspec/specs/runtime-modes/spec.md

# runtime-modes 规范

目的

定义 TvT.js 在普通项目模式、预览模式、单插件模式之间的切换方式，包括每种模式由哪些环境变量控制，以及这些变量如何影响路由和启动行为。

职责边界

本规范覆盖

• 通过 .env、.env.predev、.env.predev.one 进行模式切换
• FES_APP_PLUGINS 控制的行为
• FES_APP_PREINDEX 控制的行为
• FES_APP_PLSNAME 控制的行为
• src/app.jsx 如何根据不同模式修改路由与启动逻辑
• package.json 中模式脚本的职责边界
• .fes.js、.fes.predev.js、.fes.predev.one.js 的项目约定映射
• 预览相关远程菜单数据的加载条件

本规范不覆盖

• 单个插件内部如何组织实现
• 预览卡片字段设计
• ZIP 打包格式细节
• qiankun 或 uni-app 容器中的专属集成约束

主要代码依据

• .env
• .env.predev
• .env.predev.one
• package.json
• src/app.jsx
• src/common/utils.js
• src/plugins/preview.vue
• .fes.js
• .fes.predev.js
• .fes.predev.one.js

要求

Requirement: 模式预设与脚本映射

TvT.js 仓库 SHALL 通过环境变量预设与 package.json 脚本来定义运行模式，而不是通过临时修改业务代码切换模式。普通项目模式、预览模式、单插件模式 SHALL 分别由稳定的脚本入口与环境文件组合驱动。

Scenario: 普通项目模式脚本

• GIVEN 维护者执行 yarn dev 或 yarn build
• WHEN 未显式切换到 predev 或 predev.one
• THEN 系统 SHALL 进入普通项目模式
• AND 其默认行为应以 .env 与 .fes.js 为基础

Scenario: 预览模式脚本

• GIVEN 维护者执行 yarn pre.dev 或 yarn pre.build
• WHEN FES_ENV=predev
• THEN 系统 SHALL 进入预览模式
• AND 其行为应以 .env.predev 与 .fes.predev.js 为基础

Scenario: 单插件模式脚本

• GIVEN 维护者执行 yarn pre.dev.one 或 yarn pre.build.one
• WHEN FES_ENV=predev.one
• THEN 系统 SHALL 进入单插件模式
• AND 其行为应以 .env.predev.one 与 .fes.predev.one.js 为基础

Requirement: FES_ENV 与配置文件约定

TvT.js 项目 SHALL 将不同 FES_ENV 与配置文件的对应关系视为项目级运行约定：默认环境对应 .fes.js，predev 对应 .fes.predev.js，predev.one 对应 .fes.predev.one.js。维护者在调整脚本或环境配置时 SHALL 保持这组映射稳定。

Scenario: 维护脚本时保持映射稳定

• GIVEN 维护者调整 package.json 中的运行脚本
• WHEN 这些脚本继续代表普通、预览、单插件三种模式
• THEN 其 FES_ENV 与配置文件的对应关系 SHALL 保持不变

Requirement: 普通项目模式行为

当 FES_APP_PLUGINS=false 时，系统 SHALL 将当前运行视为普通项目模式。在该模式下，系统 SHALL 不自动为 src/plugins/**/pages/**/*.vue 注册插件路由，并 SHALL 保持普通项目首页语义，不以预览中心替换默认首页。

Scenario: 普通项目模式不注入插件路由

• GIVEN 当前环境中 FES_APP_PLUGINS=false
• WHEN src/app.jsx 执行 patchRoutes
• THEN 系统 SHALL 不自动追加 /plugins/... 路由集合

Scenario: 普通项目模式不替换为预览首页

• GIVEN 当前环境中 FES_APP_PLUGINS=false
• WHEN src/app.jsx 执行 modifyRoute
• THEN 系统 SHALL 不以 src/plugins/preview.vue 替换根路由首页
• AND 应保持普通项目模式下的默认首页语义

Requirement: 预览模式行为

当 FES_APP_PLUGINS=true 时，系统 SHALL 启用插件路由发现；当同时 FES_APP_PREINDEX=true 时，系统 SHALL 使用预览中心作为根首页。预览模式的目标是面向插件与案例展示，而不是普通业务项目首页。

Scenario: 预览模式发现插件页面

• GIVEN 当前环境中 FES_APP_PLUGINS=true
• WHEN src/app.jsx 扫描 ./plugins/**/pages/**/*.vue
• THEN 系统 SHALL 根据受支持的页面层级注册 /plugins/<plugin>/... 路由

Scenario: 预览模式替换根首页

• GIVEN 当前环境中 FES_APP_PREINDEX=true
• WHEN src/app.jsx 执行 modifyRoute
• THEN 根路径 / 的首页组件 SHALL 被替换为 src/plugins/preview.vue
• AND 该首页的路由元信息 SHALL 标识为预览中心语义

Requirement: 单插件模式过滤

当设置 FES_APP_PLSNAME 时，系统 SHALL 将当前运行限定为指定插件的单插件模式。该模式下，插件页面发现、插件配置发现以及单插件构建输出 SHALL 共同围绕目标插件及其显式声明依赖进行过滤。

Scenario: 单插件模式过滤页面路由

• GIVEN 当前环境中 FES_APP_PLSNAME='qiankunTvt'
• WHEN src/app.jsx 进行页面扫描
• THEN 系统 SHALL 仅保留 ./plugins/qiankunTvt/pages/ 下的页面参与路由注册

Scenario: 单插件模式过滤插件配置

• GIVEN 当前环境中 FES_APP_PLSNAME='qiankunTvt'
• WHEN src/common/utils.js 读取 PLS/*/config.js
• THEN 系统 SHALL 仅保留 qiankunTvt 的插件配置进入当前配置集合

Scenario: 单插件模式过滤公共资源

• GIVEN 当前环境中 FES_APP_PLSNAME='qiankunTvt'
• AND qiankunTvt 在 config.require 中声明了依赖插件
• WHEN 执行 yarn pre.build.one
• THEN 构建流程 SHALL 仅复制目标插件及其声明依赖所需的公共资源目录

Requirement: 预览标签菜单设置加载条件

预览标签与徽标相关的 menuSetup 远程数据 SHALL 由 src/app.jsx 的启动前逻辑控制：当 FES_APP_PLUGINS=true 且处于开发环境时，或显式开启 FES_APP_ONLINE_API 时，系统 SHALL 调用 getMenu() 加载这类数据。该条件独立于是否处于单插件模式。

Scenario: 本地预览模式加载 menuSetup

• GIVEN 当前处于开发环境
• AND FES_APP_PLUGINS=true
• WHEN 应用执行启动前初始化
• THEN 系统 SHALL 调用 getMenu() 加载预览标签与徽标设置

Scenario: 普通项目模式不主动加载 menuSetup

• GIVEN 当前环境中 FES_APP_PLUGINS=false
• AND 未开启 FES_APP_ONLINE_API
• WHEN 应用执行启动前初始化
• THEN 系统 SHALL 不因预览机制而主动加载 menuSetup 远程数据

Requirement: 线上插件菜单补充加载条件

预览中心中的 getOnlinePluginConfig() 线上插件菜单补充 SHALL 由 src/plugins/preview.vue 单独控制：仅当 NODE_ENV='development' 且未设置 FES_APP_PLSNAME 时，或显式开启 FES_APP_ONLINE_API 时，系统才 SHALL 拉取线上发布菜单并与本地配置合并。

Scenario: 本地多插件预览模式补充线上菜单

• GIVEN 当前处于开发环境
• AND 未设置 FES_APP_PLSNAME
• WHEN 预览中心初始化插件配置
• THEN 系统 SHALL 允许拉取线上发布菜单作为本地配置补充

Scenario: 单插件模式默认不做线上插件菜单补充

• GIVEN 当前处于本地单插件模式
• AND FES_APP_PLSNAME 已设置
• AND 未开启 FES_APP_ONLINE_API
• WHEN 预览中心决定是否拉取线上插件菜单补充
• THEN 系统 SHALL 默认跳过该线上补充逻辑

Scenario: 线上 API 开关覆盖默认条件

• GIVEN 当前已显式开启 FES_APP_ONLINE_API
• WHEN 应用进行预览初始化
• THEN menuSetup 加载与线上插件菜单补充 SHALL 都允许执行
• AND 不再受本地是否单插件模式的默认限制