# Shadowline-backend

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

## Basic Information

- **Project Name**: Shadowline-backend
- **Description**: No description available
- **Primary Language**: Python
- **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 数字孪生工作空间后端，使用 FastAPI、PostgreSQL、只读 MQTT 接入与离散事件求解器。数据库名称固定为 **shadowline**。

## 工程结构

参照独立工程工作区组织方式，前后端分别对应一个 Git 仓库：

```text
2_workspace/
├── shadowline-front/       # Vue 3 + TypeScript + Vite
└── shadowline-backend/     # 当前仓库
    ├── app/               # API、领域逻辑、求解器及存储适配
    ├── database/          # 按编号执行的 SQL 迁移
    ├── doc/               # 业务规则、表结构及代码映射
    ├── scripts/           # 迁移、启动/停止及联调验证
    ├── tests/             # 离线单元和适配器测试
    ├── config.example.json
    └── requirements.txt
```

前端仓库：https://gitee.com/kingzha/shadowline-front

## 安装与配置

要求 Python **3.11+** 和可访问的 PostgreSQL。联合启动脚本用于 Windows；联合启动还要求 Node.js **20.19+** 与已安装依赖的同级 `shadowline-front` 工程。以下命令均在本仓库根目录执行：

```powershell
python -m venv .venv
.venv/Scripts/python.exe -m pip install -r requirements.txt
Copy-Item config.example.json config.local.json
```

已有 `config.local.json` 时保留现有文件。填写 `database` 连接信息，并确保 `shadowline` 数据库已创建且账号有建表权限。`config.local.json` 不提交；也可通过 `SHADOWLINE_CONFIG` 环境变量指定外部配置文件。

AI 配置入口为 `config.local.json` 的 `ai.api_key`、`base_url` 和 `model`。`mode=auto` 时空 key 使用明确标记的本地规则，填写 key 后调用兼容 `/chat/completions` 的模型服务；`mode=service` 强制要求 key，`mode=rules` 强制规则模式。修改配置后重启后端。浏览器无法读取 key。

```powershell
# 仅显式迁移时执行 DDL；重复执行校验 SQL 版本和校验和。
.venv/Scripts/python.exe scripts/migrate.py
# 单独启动后端
.venv/Scripts/python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 3051
```

SQL `001_init.sql`、`002_seed.sql` 保持原内容；后续变更新增编号 SQL，勿改写已经执行的迁移文件。

## 前后端联合启动

先在同级 `shadowline-front` 执行 `npm.cmd ci`，然后回到本仓库运行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/start.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/stop.ps1
```

启动脚本检查 3051/3053 端口占用，记录 PID 和进程创建时间；停止脚本校验身份后停止本次启动的进程。后端可独立克隆并启动；联合启动和模型上传联调验证默认使用同级前端目录。

- 前端：http://127.0.0.1:3053
- 后端健康：http://127.0.0.1:3051/api/health
- API 文档：http://127.0.0.1:3051/docs
- 联合启动日志：本仓库 `logs/`

## 主要流程

1. 工作空间选择机器人单元或三工位产线，进入孪生工作室。
2. 拖入24类组件，调整属性、连接、顺序动作和设备字段映射；或导入GLB/glTF/OBJ/STL，校核单位/向上轴、按模型节点建立语义。
3. AI协作先生成命令预览，再应用；修改与人工操作共用校验、revision与事务。撤销/重做同样保存到数据库。
4. 运行台播放同一服务端事件流的资源、工件、产出与WIP。现场映射与历史回放独立选择；只读大屏适合展示。
5. 实验室运行缓冲1/2/4 × 并行装配1/2，设置重复次数、扰动和预算。按产出与成本选择方案，下载JSON复现数据或HTML报告。
6. 数据接入配置演示数据或MQTT TCP/TLS/WebSocket Broker，验证消息质量；项目设置维护知识、版本、差异、恢复和场景包迁移。

场景、版本、AI任务、实验、消息、知识和审计保存PostgreSQL；模型原始文件保存 `storage/`。浏览器仅保存最近选择的场景。**备份必须同时备份数据库和storage。** 场景ZIP包含模型源文件，但不包含遥测历史或密钥。

## 运行范围

- 当前求解器为明确限定的三工位离散事件模型：上料10s → 装配16s+动作时间 → 检测20s，服务后阻塞、空线启动、无限原料、无故障/不良品；默认产出148件/小时，缓冲扩至4仍148，装配并行2为178。
- 布局、导入模型、顺序动作尚未自动编译成任意生产调度；故障按钮只演示暂停。关节姿态为示意，导入模型尚无关节标定与驱动。
- 实验分析页使用引用当前批次结果的确定性证据摘要；AI协作的分析角色在配置模型后可调用模型服务。知识目前为文本上下文，不是向量检索。
- 现场快照保存来源摘要，实验仍为空线启动；历史回放取最近1000条消息，不恢复在制任务。MQTT只读，不下发生产指令。
- 当前为**本机开发版**：尚无真实登录、组织权限、多人协作、生产审批、专业碰撞/动力学、CAD/FBX转换或高负载生产验收。页面“设计覆盖与边界”列出完整范围。

## 验证与资料

```powershell
# 离线测试：使用 mock，不连接数据库或调用真实 AI。
.venv/Scripts/python.exe -m pytest tests -q --junitxml=test-results/unit.xml
# 前端类型检查与构建（在同级前端工程运行）
npm.cmd --prefix ../shadowline-front run build
# 以下需已启动服务；API 验证会创建并保留“验收专用”数据。
.venv/Scripts/python.exe -X utf8 scripts/verify_api.py
.venv/Scripts/python.exe -X utf8 scripts/verify_browser.py
.venv/Scripts/python.exe -X utf8 scripts/verify_mqtt.py
```

浏览器验证额外需要在当前 Python 环境安装 `playwright`，并安装本机 Chrome。`verify_layout_fixture.py` 使用本地接口夹具验证页面，不依赖远程数据库，需启动前端。MQTT 验证使用随机本机端口协议夹具并恢复原连接配置，不代表工厂 Broker 验收。截图和测试输出写入本仓库 `test-results/`，不提交。

业务/API：[doc/business.md](doc/business.md)；字段真源：[doc/service-schema.md](doc/service-schema.md)；代码映射：[doc/System-Model-Code-Map.md](doc/System-Model-Code-Map.md)。原始设计文档和页面原型在本地工作区上级 `../../0_doc`、`../../1_原型` 对应的项目资料目录中，不属于运行时依赖。

## 本地文件与版本管理

`.gitignore` 排除本机配置、`.venv/`、缓存、`storage/` 上传内容、`logs/`、`test-results/` 和编辑器配置。`config.example.json`、SQL、测试源码、业务文档与依赖清单随仓库提交。

整理前的本机配置、模型上传文件、日志和历史测试产物均保留在对应本地目录。一次性参考环境配置与历史验收汇总脚本保存在 `scripts/local/`，仅用于本机存档，已排除提交。移动过的虚拟环境如需使用 `pip.exe` 等控制台入口，应重新创建；安装和测试命令统一通过 `python.exe -m` 执行。