114 lines
12 KiB
Plaintext
114 lines
12 KiB
Plaintext
F9智慧缫丝设计文档，这是一份系统开发设计文档：
|
||
# 一、系统描述
|
||
1.这是一款应用于缫丝厂生产管理的MES系统，包含PC网页端、电视大屏端、小程序端三个平台。
|
||
2.技术要求：网页版：后端采用 .Net10，前端采用Vue最新版，数据库采用云MySQL数据库（地址：116.198.221.105 库名：f9web 用户名：f9web 密码：t~QMq5u6j5 ）ORM框架用Freesql（最新版v3.5.311），本地涉及缓存库的话，采用sqlite最新版；小程序版采用微信的原生开发架构；电视大屏端采用VUE。代码要人性化，必要的地方加上注释，要确保离开AI能够进行人工维护。
|
||
3.数据库设计：表名前面要带模块，例如CRM_Customer等，表中默认要有id字段，flag（标记数据有效状态，0为删除，>0为有效数据，<0为无效数据，其中-1为作废），addtime（数据添加日期），adder（数据添加人，用户uid），updatetime（添加人），updater（修改人），memo（备注）建字段要加字段描述，该建的索引要建索引。
|
||
4.第三方接口：文件图片存储放在阿里云（ "BucketName": "bbit-f9-web", "EndPoint": "oss-cn-chengdu.aliyuncs.com", "STSEndPoint": "sts.cn-chengdu.aliyuncs.com", "AccessKeyId": "LTAI5tSnK8HCPruXm3ZCRZDQ", "AccessKeySecret": "lHcL75fV809SJYZ3IJtMWlPM7qYUXK"），天气预报采用 Open-Meteo，其他需要时再提供。
|
||
5.项目要求：项目文件架构要求，类文件命名要求前面加模块名称，例如CRM_CustomerList,每个模块的类放在各自文件夹，公共模块的类放在Common文件夹。
|
||
6.其他要求：界面美观，简洁，专业的Mes风格，高可配置性，数据字典要专业全面，支持的数据类型多一些。
|
||
7.通用约定：表单均需要支持打印功能，要把表单打印作为通用模块，支持自定义设计打印格式，调用打印支持针式打印机和A4打印机，打印组件参考开源项目（https://github.bbitcn.net/fanhongcai/openprint），整体风格要具有风格统一性，操作按钮位置统一性。表单要具有工作流管理（简易工作流）。
|
||
8.设计开放性：可以参考行业中先进的MES功能，命名等，多借鉴过来，遇到代码困难时，可预留后期突破。
|
||
9.开发步骤：先完成PC端，再进行电视大屏端、小程序端，再进行联调内测
|
||
# 二、缫丝厂的业务流程说明
|
||
缫丝厂基本流程：干茧（也有可能是鲜茧）原料出库后，依次经过选茧工序筛选出上车茧，送入前缫车间开展煮茧作业，经煮茧膨润丝胶后进入自动缫丝机完成索绪、理绪、缫丝落丝，产出小䈅丝片；小䈅丝片流转至后缫工段，完成给湿、复摇返丝、编丝整理，同步开展黑板、纤度、公量等理化检验，按批次完成生丝组批定级，检验合格后入库形成成品生丝，各工序同步产出各类下脚副产品单独归集入库。
|
||
庄口指原料蚕茧的批次化管理，原料庄口指的是A地某年某季的原料蚕茧，工艺庄口指根据生产工艺组合的生产用庄口，开始生产后，全局采用该工艺庄口作为贯穿系统的线索，即产生的成本、产量、排工等均已该线索为依据。
|
||
缫丝生产主要的原料就是蚕茧，辅料有一些，能源主要有电力、燃气、煤、水等，产成品主要是生丝，生丝要称重，检验后打柄入库。
|
||
产成品的副产品有条吐、下足茧、茧衣等，这些要进行入库，销售，并暂估或者卖出作为收入。
|
||
缫丝不是按订单排产，核心围绕**工艺庄口**组织生产，不是通用离散制造的工单模式。
|
||
本缫丝厂MES系统旨在解决缫丝环节中的各项信息化的问题。
|
||
|
||
---
|
||
|
||
# 三、系统实现现状（截至 2026-08-23）
|
||
|
||
## 3.1 技术栈落地情况
|
||
- 后端：`.NET 10` Web API（`server/src/F9MES.Api`，启动项目），ORM 用 FreeSql v3.5.x，JWT 认证（`Jwt` 配置节，Secret 在 appsettings.json）。
|
||
- 数据库：云 MySQL（`116.198.221.105:3306` 库名 `f9web`，用户 `f9web`），实体自动建表（`Flag/AddTime/Adder/UpdateTime/Updater/Memo` 系统字段规范落地，软删除 `Flag=0`）。SQLite 本地缓存库 `f9mes_cache.db`（暂无实际使用）。
|
||
- 前端：`web/`（Vue 3.5 + Element Plus + Pinia + Vue Router 4 + Vite 6 + ECharts），dev 端口 5173，`/api` 代理到后端 5136。
|
||
- 打印设计器：`openprint/`（Vue3 + TS + Vite + Fabric.js + CodeMirror + tiptap），dev 端口 5227，参考开源 openprint 项目；单据模板渲染 + 打印数据接口由后端 `PrintApiController` 提供。
|
||
- 移动端（小程序）、电视大屏端（BoardCenter）设计文档已规划，尚未开发。
|
||
|
||
## 3.2 目录结构速览
|
||
```
|
||
server/src/F9MES.Domain 各模块实体（xxx_Entities.cs，按模块文件夹）
|
||
server/src/F9MES.Application Biz/ 业务服务（StockService/FimsService/ProductionService），Init/ 初始化（账号/菜单/字典）
|
||
server/src/F9MES.Api 控制器（DataController 动态CRUD + 联动、MetaController 元数据、PrintApiController 打印数据、BaseSysController）
|
||
web/src/views/<模块> 页面视图
|
||
web/src/components CrudPage（通用列表页）/ BillPage（通用单据页）
|
||
web/src/config/table-map.js TABLE_MAP（页面→表）/ BILL_MAP（表→单据页路由）/ PRINT_MAP
|
||
web/src/config/bill-configs.js 通用单据页布局配置（42 张表）
|
||
openprint/src 打印模板设计器 + 渲染服务
|
||
```
|
||
|
||
## 3.3 本地启动指南（更换路径后无需改配置）
|
||
依赖：.NET 10 SDK、Node（openprint 要求 ^22.18 || >=24.12）、npm。
|
||
```powershell
|
||
# 1. 后端（启动约 60-70 秒，远程 MySQL 初始化 + SyncStructure，期间端口不监听属正常）
|
||
cd server
|
||
dotnet run --project src/F9MES.Api/F9MES.Api.csproj --launch-profile http
|
||
# → http://localhost:5136 （Swagger: /swagger）
|
||
# 注意：若直接运行 F9MES.Api.exe 不会读 launchSettings.json，默认监听 5000，须用 dotnet run --launch-profile http
|
||
|
||
# 2. 前端（另开终端）
|
||
cd web
|
||
npm install # 首次或依赖变更时
|
||
npm run dev # → http://localhost:5173 （已配置 /api → 5136 代理）
|
||
|
||
# 3. 打印设计器（另开终端，打印模板/单据预览依赖它）
|
||
cd openprint
|
||
npm install # 首次或依赖变更时（node_modules 已存在则跳过）
|
||
npm run dev # → http://localhost:5227
|
||
```
|
||
- 默认管理员账号：`13800000000 / 123456`（InitDataService 自动初始化，幂等）。
|
||
- 后端日志输出到终端；也可用 `dotnet run --launch-profile http > api-run.log 2>&1` 重定向。
|
||
- 数据库连接串在 `server/src/F9MES.Api/appsettings.json` 的 `ConnectionStrings:MySQL`。
|
||
|
||
## 3.4 已上线功能模块（与《功能清单》对照）
|
||
- 系统管理 BaseSys：菜单 / 组织 / 角色权限 / 用户（已实现）。
|
||
- 基础数据 BaseCommon：物资目录 / 生丝规格 / 定级标准 / 业务账期 / 工种 / 往来单位 / 注册表（已实现）。
|
||
- 工作台 WorkBench：首页聚合看板（待办 / 预警 / 看板 / 快捷操作，已实现基础版）。
|
||
- 原料管理 RawMaterial：采购 / 供应商 / 原料庄口 / 入库（磅码单）/ 翻包 / 出库 / 库存 / 原料检验 / 原料仓库 / 仓储环境（已实现，全链路联动）。
|
||
- 生技工艺 Process：样茧试缫 / 工艺庄口 / 工艺指标 / 工艺单（已实现）。
|
||
- 生产计划 ProPlan / 选茧 ProXuan / 前缫 ProQian / 后缫 ProHou / 检验 Lims / 质量 Qums：实体与页面已建，报表联动待深化。
|
||
- 成品 Fims：批次 / 包件 / 入库 / 出库 / 库存 / 状态管理（实体 + 页面 + FimsService 联动已建，bill-configs 尚有 2 张表待补）。
|
||
- 五金 WmsWu：入库 / 出库 / 库存 / 采购计划 / 领料申请 / 采购报销 / 台账（实体 + 页面已建，**出入库→库存重算 + 台账流水服务未建**）。
|
||
- 销售 Sams：客户 / 合同 / 发货计划 / 回款 / 发票（实体 + 页面已建，**合同执行 / 回款 / 开票汇总联动服务未建**）。
|
||
- 能耗 Enms：计量表 / 抄表读数 / 分摊规则 / 分摊结果（实体 + 页面已建，**用量自动计算 + 分摊执行服务未建**）。
|
||
- 副产品 WmsFu：入库 / 出库 / 库存（实体 + 页面已建，库存联动服务未建）。
|
||
- 打印 / 报表 / 看板设计器：openprint 已可用，42 张核心业务表接通用单据页（BillPage），单据打印已打通（含三等分原料出库单）。
|
||
|
||
## 3.5 待办（后续开发方向）
|
||
1. **WmsWu**：新建 `WmsWuService`（参考 `StockService.RecalcFimsAsync`），出入库 Status=1 时按 MaterialId 重算 `WmsWu_Stock` 并全量重建 `WmsWu_Ledger` 流水；`DataController.StockLink` 加 `WmsWu_InStock/OutStock` 条目。
|
||
2. **Enms**：新建 `EnmsService`：①抄表保存自动 `Usage = max(0, Reading-LastReading)` 并回写 `Enms_Meter.CurrentReading`；②按账期 + AllocateBasis（产量/人数/工时/固定/表读数）执行分摊写 `Enms_AllocateResult`；DataController 挂接 Reading 联动。
|
||
3. **Sams**：新建 `SamsService`：发货计划 Status=1 回写 `ContractItem.ShippedQuantity` 并汇总 `Contract.ExecutedAmount`；回款增删回写 `Contract.PaidAmount`。
|
||
4. **WmsFu**：副产品出入库→库存联动（可并入 WmsWuService 或单独服务）。
|
||
5. MetaController 补 `CodeRules`（Sams/WmsWu/Enms 自动编号）与 `RefMap`（PeriodId/MeterId/ContractItemId 等）。
|
||
6. bill-configs.js 补缺 8 张表布局（Enms_Meter/AllocateRule/AllocateResult、WmsWu_Stock/Ledger/Reimburse、Fims_Stock/StatusChange、Sams_ContractItem）。
|
||
7. 移动端小程序、电视大屏端（后期）。
|
||
|
||
# 四、开发进度状态存档（2026-08-23）
|
||
| 阶段 | 状态 |
|
||
|---|---|
|
||
| 后端框架 / 动态CRUD / 元数据 / 认证 / 初始化 | ✅ 完成 |
|
||
| 原料全链路（入库→翻包→出库→检验→仓库→库存重算） | ✅ 完成（含打印） |
|
||
| 全系统单据页化（BillPage 配置驱动 42 表）+ 窗体风格规范 | ✅ 完成 |
|
||
| 单据打印链路（openprint 模板 + 打印数据接口） | ✅ 完成（含出库单空白修复） |
|
||
| 即时通讯浮窗 / 简易工作流 / 打印模块 | ✅ 完成 |
|
||
| 成品 Fims 实体+页面+核心联动 | 🟡 基本完成（补 2 表 bill-configs） |
|
||
| 五金 WmsWu 实体+页面 | 🟡 待补库存重算/台账服务 |
|
||
| 销售 Sams 实体+页面 | 🟡 待补合同联动服务 |
|
||
| 能耗 Enms 实体+页面 | 🟡 待补用量计算/分摊服务 |
|
||
| 副产品 WmsFu 实体+页面 | 🔴 待补库存联动服务 |
|
||
| 移动端小程序 / 电视大屏端 | 🔴 未开始 |
|
||
|
||
# 五、常见坑位与经验（重要）
|
||
- **后端启动慢是正常的**：远程 MySQL + SyncStructure 初始化约 60-70 秒，别误判为失败。
|
||
- **必须用 `dotnet run --launch-profile http`**：直接跑 exe 会监听 5000 而非 5136。
|
||
- **前端 DateTime 提交格式**：已全局兼容空格 `YYYY-MM-DD HH:mm:ss`（FlexibleDateTimeConverter），但旧数据/接口可能仍用 ISO 格式。
|
||
- **自动编号（Code）**：由前端 `gencode` 生成（add 接口返回 Code 为空属正常）。
|
||
- **菜单不自动补**：`InitMenusAsync` 仅空表时全量插入，已部署库新增菜单需手动 `POST /api/data/BaseSys_Menu/add`。
|
||
- **PowerShell 中文乱码**：命令行内联中文（git commit / node -e）易转码，写文件用工具 write_to_file 或 UTF-8 临时文件，`Remove-Item` 会触发 IDE safe-delete 守卫，删临时文件用 delete_file 工具。
|
||
- **打印预览空白**：openprint iframe 打印需 `@media screen` 隐藏 + `@media print` 显示并等待 `document.fonts.ready`（已修复，勿回退到 `left:-9999px`）。
|
||
- **服务注册**：新业务服务需在 `Program.cs` 登记 `AddScoped`；`DataController` 的 `StockLink/ProductionLink` 是增删改联动挂接点。
|
||
- **Openprint 依赖**：CodeMirror 6 与 tiptap 子包需在 vite `dedupe/optimizeDeps.include` 中列明，否则 dev server 二次优化会崩。
|