104 lines
4.4 KiB
Markdown
104 lines
4.4 KiB
Markdown
# 东方水利制造进度驾驶舱
|
||
|
||
工业制造订单进度大屏，前端采用 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
|
||
```
|