docs: 更新项目说明并存档开发进度（重装后快速启动）

- 项目说明新增：系统实现现状、目录结构、三端启动指南、模块状态、待办清单、常见坑位
- 新增 AI开发日志/2026-08-23.md 开发进度存档

AI开发日志/2026-08-23.md

@@ -0,0 +1,22 @@
+# 2026-08-23 开发日志
+
+## 本日工作
+- 更新根目录《项目说明》文档：新增「三、系统实现现状」「四、开发进度状态存档」「五、常见坑位与经验」三大章节，补齐技术栈落地、目录结构、本地启动指南（三端命令 + 端口 + 账号）、模块上线状态、待办清单。
+- 目的：用户将重新安装 CodeBuddy 并更换文件夹路径，需要靠根目录文档快速无探索恢复项目上下文、直接启动。
+
+## 项目启动速记（详见《项目说明》3.3）
+- 后端：`cd server && dotnet run --project src/F9MES.Api/F9MES.Api.csproj --launch-profile http`（端口 5136，启动 60-70 秒属正常）
+- 前端：`cd web && npm install && npm run dev`（端口 5173）
+- 打印：`cd openprint && npm install && npm run dev`（端口 5227）
+- 账号：`13800000000 / 123456`
+
+## 四模块开发进度（截止今日，均待补业务服务层）
+- WmsWu（五金）：实体 + 页面 + TABLE_MAP/BILL_MAP 已就绪；缺 `WmsWuService`（库存重算 + Ledger 台账流水）、`DataController.StockLink` 挂接 `WmsWu_InStock/OutStock`。
+- Enms（能耗）：实体 + 页面已就绪；缺 `EnmsService`（抄表 Usage 自动计算 + 按账期/规则分摊写 AllocateResult）、Reading 联动挂接。
+- Sams（销售）：实体 + 页面已就绪；缺 `SamsService`（发货→ContractItem.ShippedQuantity / Contract.ExecutedAmount；回款→PaidAmount）。
+- Fims（成品）：实体 + 页面 + FimsService/StockService 联动已建；仅剩 bill-configs 补 2 张表（Stock/StatusChange）。
+- WmsFu（副产品）：实体 + 页面已就绪；缺库存联动服务。
+- 统一收尾：MetaController 补 CodeRules/RefMap；bill-configs.js 补 8 张表布局；Program.cs 注册新服务。
+
+## 待办下一步
+按《项目说明》3.5 顺序：WmsWuService → EnmsService → SamsService → WmsFu → Meta 补充 → bill-configs 补充 → dotnet build 验证。

项目说明

@@ -5,7 +5,7 @@ F9智慧缫丝设计文档，这是一份系统开发设计文档：
 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风格，高可配置性，数据字典要专业全面，支持的数据类型多一些。
+6.其他要求：界面美观，简洁，专业的Mes风格，高可配置性，数据字典要专业全面，支持的数据类型多一些。
 7.通用约定：表单均需要支持打印功能，要把表单打印作为通用模块，支持自定义设计打印格式，调用打印支持针式打印机和A4打印机，打印组件参考开源项目（https://github.bbitcn.net/fanhongcai/openprint），整体风格要具有风格统一性，操作按钮位置统一性。表单要具有工作流管理（简易工作流）。
 8.设计开放性：可以参考行业中先进的MES功能，命名等，多借鉴过来，遇到代码困难时，可预留后期突破。
 9.开发步骤：先完成PC端，再进行电视大屏端、小程序端，再进行联调内测
@@ -16,3 +16,98 @@ F9智慧缫丝设计文档，这是一份系统开发设计文档：
 产成品的副产品有条吐、下足茧、茧衣等，这些要进行入库，销售，并暂估或者卖出作为收入。
 缫丝不是按订单排产，核心围绕**工艺庄口**组织生产，不是通用离散制造的工单模式。
 本缫丝厂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 二次优化会崩。