# snippets-collection

**Repository Path**: mpbug/snippets-collection

## Basic Information

- **Project Name**: snippets-collection
- **Description**: 面向 Three.js、CesiumJS、CSS、JavaScript 和 GLSL 的创意代码与素材工作台
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-08-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SnippetsCollection

面向 Three.js、CesiumJS、CSS、JavaScript 和 GLSL 的创意代码与素材工作台。

## 开发

```powershell
corepack enable
pnpm install --frozen-lockfile
pnpm dev
```

需要 Node.js 22.13 或更高版本（项目使用内置 `node:sqlite`）。浏览器打开 `http://127.0.0.1:4173`。`pnpm dev` 会在服务端文件变化时自动重启；不需要监听时使用 `pnpm start`。

默认端口被占用时可运行 `node server.js --port=4174`。容器或局域网部署时通过 `HOST=0.0.0.0` 开放监听地址。

## 测试与构建

```powershell
pnpm test
pnpm build
```

`pnpm test` 执行 JavaScript 语法检查、UTF-8/Base64 编解码与完整性测试，并在隔离端口验证 SQLite API 和关键浏览器资源。

`pnpm build` 会清理并重新生成 `dist`，复制应用代码、初始数据以及浏览器实际使用的 Monaco 和 Prettier 资源。构建随后从 `dist` 独立启动服务，校验资源、健康检查和所有文件的 SHA-256。产物无需携带 `node_modules`，也无需再次安装依赖：

```powershell
node dist/server.js
```

`dist/build-manifest.json` 记录版本、前端依赖版本、文件大小和校验和。运行期的 `data/*.sqlite3*` 不会进入构建产物；`dist/data/data.json` 只用于首次初始化和只读回退。

常用流水线命令：

| 命令 | 用途 |
| --- | --- |
| `pnpm dev` | 开发服务与服务端热重启 |
| `pnpm test` | 源码检查和回归测试 |
| `pnpm build` | 生成并独立验证 `dist` |
| `pnpm ci` | CI 中依次执行测试和构建 |
| `pnpm clean` | 删除 `dist` |
| `pnpm release` | 测试、构建并生成发布压缩包 |

## 部署与发布

直接部署时只需复制整个 `dist` 到 Node.js 22.13+ 环境，然后运行 `node server.js`。生产环境应把数据库指向持久化目录：

```powershell
$env:HOST = "0.0.0.0"
$env:PORT = "4173"
$env:FRAMEBASE_DB_PATH = "D:\snippets-data\snippetsCollection.sqlite3"
node dist/server.js
```

容器部署会使用多阶段构建，最终镜像只包含 Node 运行时和 `dist`，SQLite 保存在命名卷中：

```powershell
docker compose up --build -d
docker compose ps
```

服务健康检查地址为 `/api/health`。可配置项包括 `HOST`、`PORT`、`FRAMEBASE_DB_PATH` 和 `FRAMEBASE_DATA_PATH`。

正式发布执行：

```powershell
pnpm release
```

发布前会完整测试并重新构建，归档输出到 `release/snippets-collection-<version>.tgz`，并生成对应的 `.sha256` 校验文件。解压后进入包目录直接运行 `node server.js`；压缩包已包含所有浏览器依赖、资源和第三方许可证。

## 当前能力

### 代码工作台

- Three.js、CesiumJS、CSS、Canvas、JavaScript 和原生 WebGL/GLSL 模板。
- Monaco Editor、语法着色、自动补全及 HTML/CSS/JavaScript 诊断。
- Prettier 格式化、自动运行、隔离 iframe、控制台转发和响应式视口。
- 运行性能指标：FPS、加载耗时、资源数量和 WebGL 版本。
- 动态分类、标签检索、收藏、复制、回收站和 JSON 导入导出。
- 保存时自动快照、逐行差异对比和历史版本恢复。
- 片段预览缺失或图片加载失败时，使用由名称确定的纯色背景和名称文字回退。

### 运行配置

- 片段级 CDN 依赖列表、精确版本、加载顺序和启用状态。
- 工作区环境变量通过 `FRAMEBASE_ENV` 注入预览沙箱。
- 素材通过 `FRAMEBASE_ASSETS` 提供稳定 ID、URL 和内嵌内容。
- 敏感环境变量保存在本地，但导出工作区时会自动清空值。

### 素材中心

- 文本、着色器、图片、音频、视频和 GIS 数据的新增、编辑、删除和恢复。
- 本地小文件内嵌、外部 URL、仓库路径及直接文本内容。
- SHA-256 内容指纹和重复素材阻止。
- 图片尺寸、音视频时长、文本行数和 GeoJSON 要素/包围盒提取。
- 图片、音视频、文本、GLSL 和 GeoJSON 可视化检查器。
- 素材到片段的双向引用查询。

## 数据与安全边界

当前版本使用本地 SQLite 数据库 `data/snippetsCollection.sqlite3` 固化工作区。SQLite 尚无工作区记录时，会优先迁移旧版 `localStorage` 工作区；没有旧版数据时读取 `data/data.json`，并将初始工作区写入 SQLite。迁移成功后会清理浏览器副本。1.5 MB 以内文件可内嵌；大文件仅保存元数据和路径。

SQLite 初始化或读取失败时，浏览器会立即请求 `./data/data.json` 并导入其中的工作区；该请求、JSON 解析或工作区校验失败时，界面改为显示内置默认内容。

工作区先序列化为 UTF-8 JSON，再以标准 Base64 文本存入 SQLite；同一记录保存原始字节数和 SHA-256。读取时会依次校验 Base64 规范性、字节数、SHA-256 及 UTF-8 反转码一致性，任一环节不一致都会拒绝加载。SQLite 启用 WAL 和 `synchronous=FULL`，单条 UPSERT 保证工作区替换的原子性。

数据库目录已从静态文件服务中隔离。静态服务只开放回退文件 `/data/data.json`，SQLite 数据库仍只能通过 `/api/workspace` 读写经过校验的工作区对象。

用户代码运行在 `sandbox="allow-scripts allow-modals"` iframe 中，没有同源权限。CDN 依赖和环境变量仍会进入浏览器运行环境，因此生产版必须进一步提供：

- 独立预览域名和严格 CSP。
- 依赖域名白名单、SRI 校验和供应链扫描。
- 服务端密钥代理，避免浏览器接触长期凭据。
- CPU、内存、网络和最长运行时间限制。
- 对象存储配额、MIME 校验和文件安全扫描。

## 推荐生产架构

```text
Web IDE / Explorer / Asset Center
              |
        Workspace API
       /      |       \
   SQLite   Assets   Preview runtime
 workspace  inline    isolated iframe
       \      |       /
     Search index + Dependency graph
```

当前单机版由 SQLite 承担工作区固化；扩展到多用户生产环境时，核心实体建议拆为 `Workspace`、`Snippet`、`SnippetVersion`、`Asset`、`AssetVersion`、`Dependency`、`EnvironmentVariable`、`Run` 和 `AuditEvent`，并迁移到 PostgreSQL 与对象存储。所有引用使用稳定 ID，不直接依赖可变文件名。

## 后续阶段

1. 工作区后端、账号体系、对象存储和细粒度权限。
2. Git 同步、分支、评论评审和多人实时协作。
3. Cesium 3D Tiles、GeoTIFF、KML 等 GIS 专用解析与地图图层控制。
4. 图片缩略图流水线、音视频转码和大文件分片上传。
5. 可复现预览容器、截图基线、性能预算与运行记录对比。
6. 发布链接、嵌入代码、模板市场和团队审计。