# framework-foundation 规范

## 目的

定义 TvT.js 作为框架的稳定身份边界：项目本质是什么、核心技术栈是什么、哪些仓库级约定应被视为框架规则，而不是某个插件自己的实现细节。

## 职责边界

### 本规范覆盖

- 项目作为“三维可视化快速落地框架”的定位，而不是单一业务应用
- 以代码为准的框架级技术栈选择与版本锚点
- 会影响全部能力的仓库级目录约定
- 影响所有下游能力的全局构建与运行入口
- 哪些文件应被视为代码优先的事实来源

### 本规范不覆盖

- 插件页面路由细节
- 插件元数据字段规范
- 预览中心菜单行为
- 插件打包与安装流程
- `qiankun`、`uni-app`、`zone3Deditor`、`GoView` 的集成细节

## 主要代码依据

- `package.json`
- `.fes.js`
- `src/app.jsx`
- `README.md`
- `README_zh.md`

## 要求

### Requirement: 框架身份保持

仓库 SHALL 保持 TvT.js 作为“三维可视化快速落地框架”的定位。维护者在做结构调整时 SHALL 优先维护框架能力边界，而不是把仓库收缩为单一项目案例。

#### Scenario: 进行大规模结构调整

- GIVEN 维护者计划重构仓库结构
- WHEN 调整会影响多个插件、运行模式或集成能力
- THEN 调整 SHALL 以框架能力维持为前提
- AND 相关边界应先写入规范再实施

### Requirement: 代码优先事实源

当代码实现与说明文档出现冲突时，框架级事实 SHALL 默认以代码为准；文档应被视为解释层，而不是覆盖代码行为的更高来源。

#### Scenario: 文档与代码对 Node 基线不一致

- GIVEN `package.json` 与 README 中的 Node.js 版本要求不一致
- WHEN 维护者需要确定项目当前基线
- THEN SHALL 以 `package.json` 中的约束作为当前正式基线
- AND README 中的差异应被视为待同步文档问题，而不是覆盖代码事实

### Requirement: 核心技术栈锚点

TvT.js 的仓库级技术栈 SHALL 以 `package.json` 与 `.fes.js` 中声明的组合为正式锚点：Vue 3、Fes.js 4、Tres.js 5、three.js 0.180.x，以及基于 Vite 的构建链路。维护者在升级这些基础依赖时 SHALL 把它视为框架级变更，而不是单个插件内部实现调整。

#### Scenario: 升级框架主依赖

- GIVEN 维护者计划升级 `vue`、`three`、`@tresjs/*` 或 `@fesjs/*` 等仓库级主依赖
- WHEN 该升级会影响插件运行、构建或集成边界
- THEN 维护者 SHALL 先以 `package.json` 与 `.fes.js` 为事实源确认新基线
- AND 相关 spec SHALL 同步检查并更新，而不是只修改单个插件代码

### Requirement: Node.js 基线

TvT.js 当前的 Node.js 基线 SHALL 以 `package.json` 中的 `engines.node` 为准。后续若要提升 Node.js 基线，应先改代码和包管理约束，再同步文档说明。

#### Scenario: 维护者更新运行环境要求

- GIVEN 维护者计划提高最低 Node.js 版本
- WHEN 该调整成为项目正式要求
- THEN SHALL 先修改 `package.json`
- AND 之后再同步 README 与其他说明文档