# 东方水利制造进度驾驶舱

工业制造订单进度大屏，前端采用 React + Vite + TypeScript，后端采用 ASP.NET Core 8 + EF Core + SQL Server + SignalR。

## 目录

- `src/`：驾驶舱前端。
- `server/DongfangHydro.Dashboard.Api/`：REST API、SignalR Hub、EF Core 数据模型与迁移。
- `server/DongfangHydro.Dashboard.Tests/`：聚合规则与 API 集成测试。
- `server/docker-compose.yml`：本地 SQL Server 2022 开发实例。

## 数据库连接

正式连接串通过环境变量提供，不需要修改源码：

```powershell
$env:ConnectionStrings__DashboardDb='Server=YOUR_SERVER;Database=YOUR_DATABASE;User Id=YOUR_USER;Password=YOUR_PASSWORD;TrustServerCertificate=True'
$env:Database__AutoMigrate='true'
$env:Database__Seed='true'
```

首次连接正式库时，建议先保留 `Database__Seed=false`，确认迁移成功后再决定是否写入演示数据。已有业务数据库也可以只使用本项目表，不会修改其他表。

当前 `InitialCreate` 是在尚未接入任何正式 SQL Server 实例时生成的首次迁移。如果目标库已由其他版本创建过同名表，请先核对迁移历史，不要直接开启自动迁移。

本地也可以启动 Docker SQL Server：

```powershell
docker compose -f .\server\docker-compose.yml up -d
```

启动前先设置强密码：`$env:MSSQL_SA_PASSWORD='YOUR_STRONG_LOCAL_PASSWORD'`。使用 Docker 数据库时，再把 `ConnectionStrings__DashboardDb` 设置为 `Server=localhost,1433;...` 的连接串；端口仅绑定本机回环地址。

## 启动后端

本机未全局安装 .NET 时，可使用本项目开发时安装的用户级 SDK：

```powershell
& "$env:USERPROFILE\.dotnet\dotnet.exe" tool restore
& "$env:USERPROFILE\.dotnet\dotnet.exe" run --project .\server\DongfangHydro.Dashboard.Api --urls http://localhost:5080
```

后端默认地址：`http://localhost:5080`，健康检查：`GET /health`，SignalR：`/hubs/dashboard`。

## 导入 Excel BOM

先将 `ConnectionStrings:DashboardDb` 配置在环境变量或 .NET User Secrets 中。只读校验不会连接数据库：

```powershell
& "$env:USERPROFILE\.dotnet\dotnet.exe" run --project .\server\DongfangHydro.Dashboard.Api -- import-bom --file "C:\path\bom.xlsx" --validate-only
```

校验通过后执行正式导入：

```powershell
& "$env:USERPROFILE\.dotnet\dotnet.exe" run --project .\server\DongfangHydro.Dashboard.Api -- import-bom --file "C:\path\bom.xlsx" --purge-demo
```

导入以定额编号识别同一订单，在一个 SQL 事务中替换原订单及其 BOM、材料定额、趋势和风险数据。`--purge-demo` 只删除标记为 `demo` 的订单，不影响其他真实订单。重复导入同一文件不会累积重复节点。

同一定额编号且文件哈希未变化时，命令默认跳过替换，以免清空后续报工进度。只有确认需要重建时才追加 `--force`；强制导入会重置该订单的进度、趋势和风险数据。

解析器保留来源工作表、行号、原序号、规格、材质、数量、单重、总重和备注。负数量与 `/`、`95L`、`21件` 等源表文本通过“原文 + 可计算数值”双字段保存，不会被静默改写。

## 启动前端

```powershell
npm install
npm run dev
```

如后端不是 `http://localhost:5080`，在本地 `.env` 中设置：

```dotenv
VITE_DASHBOARD_API_URL=http://your-api-host:port
```

后端不可用时，前端保留最后一次订单快照；成功连接后会通过 REST 获取完整数据，并通过 SignalR 接收增量更新。

## 主要接口

- `GET /api/dashboard/overview`
- `GET /api/orders?keyword=&status=&lineId=&page=1&pageSize=20`
- `GET /api/orders/{orderId}`
- `GET /api/orders/{orderId}/tree`
- `GET /api/orders/{orderId}/trend`
- `GET /api/orders/{orderId}/material-quotas?category=&keyword=&page=1&pageSize=50`
- `GET /api/risk-events`
- `GET /api/delay-top`
- `PATCH /api/nodes/{nodeId}/progress`

更新进度时应携带节点返回的 `version` 作为 `expectedVersion`；并发修改冲突会返回 `409 Conflict`，调用方重新获取节点后再提交。

第一版按既定范围不包含登录和权限模块。正式部署前应放在受控内网或带鉴权的反向代理之后，写接口不要直接暴露到公网。

## 验证

```powershell
npm test
npm run lint
npm run build
& "$env:USERPROFILE\.dotnet\dotnet.exe" test .\server\DongfangHydro.Dashboard.Tests\DongfangHydro.Dashboard.Tests.csproj
```