# Shadowline-front

**Repository Path**: kingzha/shadowline-front

## Basic Information

- **Project Name**: Shadowline-front
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-29
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Shadowline 前端

AI 数字孪生工作空间前端，使用 Vue 3、TypeScript、Vite 与 Three.js。包含场景搭建、模型导入、运行台、实验室、数据接入和只读大屏。

## 工作区结构

每个工程拥有独立 Git 仓库，建议将前后端并列放置：

```text
2_workspace/
├── shadowline-front/       # 当前仓库
└── shadowline-backend/     # FastAPI、SQL、联调脚本及业务文档
```

后端仓库：https://gitee.com/kingzha/shadowline-backend

## 安装与启动

要求 Node.js 20.19+，本机已验证 Node.js 22.14.0。在本仓库根目录执行：

```powershell
npm.cmd ci
npm.cmd run dev
```

访问 http://127.0.0.1:3053。Vite 将 `/api` 代理到 http://127.0.0.1:3051，后端需要另行配置并启动；具体步骤见后端 README。Windows 下可使用后端 `scripts/start.ps1`、`scripts/stop.ps1` 同时管理两个工程。

```powershell
npm.cmd run build
npm.cmd run preview
```

构建命令先执行 Vue/TypeScript 类型检查，再生成 `dist/`。预览同样使用 3053 端口及后端 API 代理。正式部署需为 SPA 路由配置回退至 `index.html`，并反向代理 `/api` 至后端。

## 目录

| 路径 | 内容 |
|---|---|
| `src/pages/` | 业务页面 |
| `src/components/` | 通用组件与 3D 视口 |
| `src/api.ts`、`src/types.ts` | API 适配与基础类型 |
| `src/store.ts` | 当前场景和编辑状态 |
| `src/studio-drafts.ts` | 按对象及属性/绑定/动作分别保留编辑草稿 |
| `src/history.ts` | 按字段时间重建历史状态，隔离数据来源 |
| `tests/` | Vitest 回归与离线浏览器验证 |
| `public/engine/` | 3D 渲染及模型导入 |
| `public/vendor/` | 离线 Three.js 依赖，许可证见 `THREE-LICENSE.txt` |
| `public/samples/` | 演示模型，属于源码资源，随仓库提交 |

浏览器不保存服务端密钥。数据库账号、AI API key 等配置在后端 `config.local.json`。`node_modules/`、`dist/`、本地环境文件、日志和测试产物由 `.gitignore` 排除；`package-lock.json` 随仓库提交。

当前版本的业务规则、运行范围及联调脚本见后端 `doc/` 和 README。

## 回归验证

```powershell
npm.cmd test
npm.cmd run build
```

回归覆盖局部保存、对象切换、保存期间继续编辑、JSON 字段顺序，以及历史乱序、时间未知、清空、快照/epoch 和来源隔离。

另开终端运行 `npm.cmd run dev` 后，可用安装了 Python Playwright 的环境和本机 Chrome 执行页面回归：

```powershell
../shadowline-backend/.venv/Scripts/python.exe -X utf8 tests/browser-regressions.py
```

该脚本拦截全部 API 并使用本地夹具，不要求启动后端，也不写数据库。截图、请求记录和结果按 runId 写入 `test-results/draft-history-*/`；失败记录同样保留，产物不提交。