feat: initialize manufacturing progress dashboard

2026-07-13 18:07:59 +08:00
commit 658a23b630
87 changed files with 19195 additions and 0 deletions
@@ -0,0 +1,103 @@
+# 东方水利制造进度驾驶舱
+
+工业制造订单进度大屏，前端采用 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
+```