20260924172548

2026-09-24 17:25:48 +08:00
1 parent 0405cd198a
commit 27e49e2e45
@@ -0,0 +1,29 @@
+# 本机环境坑 + 测试基线
+
+## 环境坑（本机特有）
+
+- **编译/测试 fms-api 唯一可行命令**（`start.cmd` 里的 JDK/Maven 路径都是坏的）：
+  ```
+  cd /d/workspace/code/fms/fms-api && /d/devtool/jdk/jdk21/bin/java \
+    -Dclassworlds.conf="D:/devtool/maven/bin/m2.conf" -Dmaven.home="D:/devtool/maven" \
+    -Dmaven.multiModuleProjectDirectory="D:/workspace/code/fms/fms-api" \
+    -cp "D:/devtool/maven/boot/plexus-classworlds-2.11.0.jar" \
+    org.codehaus.plexus.classworlds.launcher.Launcher -o -Dtest=XxxTests test
+  ```
+  本地仓库是 `D:\data\maven`（不是 ~/.m2）；联网下载去掉 `-o`；`target/` 被 git 跟踪，编译后有噪音。
+- 无 sqlcmd/pyodbc/pymssql：用 `fms-api/tools/migration/RunSqlFile.java` 或一次性 `SqlRunner.java`
+  + JDBC jar（`~/.m2/.../mssql-jdbc-13.4.0.jre11.jar`）+ `/d/devtool/jdk/jdk17/bin/java`。
+  脚本要按行首 `GO` 分批，路径传绝对路径。
+- `vite build` 被 safe-delete 守卫拦（要删 600+ 文件）：用 `--outDir dist-verify --emptyOutDir`；
+  清理用 `find dist-verify -type f -delete` 再 `find dist-verify -type d -empty -delete`。
+- `oxfmt --check` 全仓库都报 format issues（版本漂移），**不是自己引入的**，别顺手格式化整个仓库。
+- 本工作区可能被多会话同时编辑，验证失败项先用 `find <dir> -mmin -N` 确认是否自己引入。
+
+## 测试基线（既有失败，别去修）
+
+- 后端 `OrgDataSourceFactoryTests.databaseConnectionFailureDoesNotRetry`（断言 Druid retry=0，实测 1）。
+- 前端 `tests/unit/fms-module-list-page.spec.js` 里引用 `.filter-drawer`/`.filter-row__*` 的用例
+  （类名已不存在，是高级查询面板改版后的过期断言）—— 另有约 13 个长期失败基线。
+- `tests/helpers/app.js` 的 `mountPage` 用 shallowMount 且默认打桩子组件：给 `Splitter`/`SplitterPanel`
+  打桩时键名要写 **Vue 推断名 `'splitter'`/`'panel'`**（文件名小写），写 `'SplitterPanel'` 打不上桩；
+  自定义组件传 `false` 可强制真实挂载。`global` 会整体覆盖内部 stubs，别在里面再写 stubs。
@@ -0,0 +1,60 @@
+# 主题 / UI 组件库 / i18n / 导出
+
+## 主题
+
+- 唯一真相 `fms-vue/src/theme/tokens.css`：`:root` 浅色 + `.dark` 深色必须同步增删同名变量，
+  `--fms-primary` 由 JS 写入，衍生色用 `color-mix()`。改主题只动这个文件。
+- **侧栏当前是浅色的**（不存在 `--fms-sidebar-*` 变量；若再看到「侧栏是黑的」即为过期信息）。
+  要改侧栏配色就新增 `--fms-sidebar-*` 只给 `AppSidebar.vue`/`NavMenuItem.vue` 用，
+  **别动 `--fms-surface`/`--fms-text` 等全局中性色**（顶栏与所有业务页共用）。
+- 深底 + 主题色高亮必须用「深底 + 白字 + 主色亮描边」：填充 `color-mix(primary 38%, #000)`、
+  描边 `color-mix(primary 40%, #fff)`；「浅底 + 白字」对比度只有 1.4~2.7:1，不可用。
+- Teleport 到 body 的浮层（如 `.fms-team-menu-*`）不在侧栏内，保持全局浅色 token。
+
+## UI 组件库全局配置
+
+- 唯一入口 `fms-vue/src/components/ui/config.js`：`uiConfig`（reactive）+ `setUIConfig(patch)`
+  （按组件维度浅合并）+ `resetUIConfig()`，也从 `@/components/ui` 具名导出。
+  **没有 ConfigProvider、没有 app.use 插件**。
+- 回落顺序固定 **自身 prop > uiConfig > 组件内置默认**；要支持全局覆盖的 prop，`default` 必须写 `undefined`
+  且 validator 要放行 `undefined`（Vue 会拿 default 跑校验）。
+- Form 的 `layout`/`labelAlign`/`labelWidth`/`validateTrigger` 已接入；provide 下发回落后的最终值。
+  语言联动在 `src/App.vue`：中文 `horizontal`、其他语言 `vertical`（判定 `/^zh/i`）。
+- **多列紧凑网格的表单必须显式 `layout="vertical"`**（如自动编码面板 columns=5），
+  否则横排的 88px 标签会把控件压到几十像素。prop 优先于全局配置。
+- `defineModel` 写完**不能立刻回读**：写了只 emit，prop 下一轮才回来；要取刚写入的值就自己先
+  `reactive()` 包一层再赋值，返回其中的代理对象。
+
+## i18n 运行时
+
+- 语言清单 `s_i18n_type`（`b_id` 即语种编码，zh-CN 默认 / en-US）；译文 `s_i18n(b_key, b_locale, b_value)`。
+- store `stores/i18n.js`：`loadLanguages()` 拉清单、**`loadMessages(locale)` 拉译文**（按语种缓存 + 并发去重 +
+  失败静默；只把「当前语种」的译文写进运行时）。**别只看 locale —— 不调 loadMessages 界面不会变。**
+- 合并顺序 **前端内置 < 库表译文**：内置只有 en-US 的 `common.*`（`src/i18n/builtin-messages.js`，
+  代码约定 `t('common.x', '中文兜底')`）；业务文案/字段名/菜单名的译文一律进 `s_i18n` 由实施维护。
+- 现状：`s_i18n` 只登记了 zh-CN（约 134 条），en-US 尚无数据 → 英文界面只有框架按钮/提示是英文，
+  字段名等仍回落中文，需要补录。
+- 顶栏语种下拉取自 `s_i18n_type` 清单，不要硬编码语言编码。
+- 查询区（`FmsQueryToolbar`）已改用 Form/FormItem，因此也跟随该配置；Form 根靠 `display: contents`
+  透明化，让 FormItem 直接参与 `.query-grid`（`minmax(0,200px)`）布局，label 宽局部 72px。
+  高级查询面板（`FmsAdvancedQueryPanel`）仍是自绘 `.filter-*`，**不受**表单布局配置影响。
+
+## 模块管理页的分节布局（2026-09-24）
+
+- 右栏是「卡头（模块名 + 动作）+ 分节导航（`mm-config-nav`，Tabs `nav-only`）+ `.mm-config-stack`」；
+  每个分节是 `.mm-config-pane`（`flex:1; overflow:auto; padding:12px 16px 16px`），**滚动由它负责**。
+- **面板自身不要做「撑满 + 内部滚动」**：需要一页平铺时用 `flex: 1 0 auto`（内容少时填满、内容多时
+  撑高让 `.mm-config-pane` 滚动）。`ModuleQueryConfigPanel` 已按此改造 ——
+  四个分节（更多条件字段 / 工作队列页签 / 关键词字段 / 快捷筛选字段）同页平铺，**不再用内层页签**。
+- **`FmsTable` 必须有确定高度**（根 `.fms-table` 是 `height:100%`，且虚拟滚动要容器尺寸）。
+  平铺多个表格时不能靠 `flex:1` 撑满，要按行数算高度：表头 34 + 行数×30 + 2，
+  clamp 到 140~420px（见 `ModuleQueryConfigPanel.tableHeightOf`），超出上限才在表格内部滚动。
+
+## 导出（P0 已落地）
+
+- `POST /api/export/list` 返回文件流：`SqlPermissionService` → `ExportSchemaService`（列与列表同源推导）
+  → `ExportService`（Fesod 流式写）→ xlsx。**导出列不由前端传**，否则字段权限形同虚设；
+  校验必须在 `getOutputStream()` 前完成。
+- 依赖 `org.apache.fesod:fesod-sheet:2.0.2-incubating`（自带 POI，别再引）。
+- Fesod 坑：0 行也要调一次 `write`，否则无工作表；合计行要自己构造标签。
+- 权限现状：`s_power` 只有 2 行，非超管会被拒，g3soft 可直接用。
@@ -0,0 +1,55 @@
+# 工作流流程设置器（fms-vue/src/views/system/workflow）
+
+## 代码现状 = 原始版本（2026-09-23 重构后已全部回滚）
+
+- 草稿 `schemaVersion:1`（`{definitionId, name, nodes, edges}`），编辑器
+  `WorkflowDesigner` + `WorkflowCanvas`(LogicFlow) + `WorkflowPropertyPanel`，坐标挂 `node.x/y`，
+  条件存单个叶子 `{field, operator, value}`，写入通道未实现（工具栏只有撤销/缩放/查看草稿 JSON）。
+- **别以为仓库里已经有卡片模式/流程树/条件构造器 —— 都被回滚了。**
+- 回滚前的完整实现备份在仓库外 `D:\workspace\code\fms-workflow-refactor-backup-20260923\`
+  （含 `http.js` 的 get/put、`tests/unit/workflow-domain.spec.js`、改过 AST 形状的 mock SQL）。
+
+## 文档是目标，不是现状
+
+- `FMS审批流程设置器交互设计.md`（旧名 `FMS审批流程交互重构设计.md`，已重写为 258 行）：要求改成钉钉式递归流程树，
+  并**明确作废**「线性卡片 + LogicFlow 高级模式」双编辑器方案（§3.2 不再用画布兜底，并行/服务节点等拓扑只读保护）。
+- `FMS审批流程设置器二次重构实施文档.md`：增量执行顺序；§1.1 交互决策已锁定，不必再问。
+- `FMS工作流与审批设计.md`：管表结构与运行语义（其 §19 的画布选型是旧方案）。
+- 参考交互项目 `D:\workspace\code\test\Workflow-Vue3`（只借交互，不复制代码/Element UI/私有字体）。
+
+## 文件与表
+
+- **未进 git**：`design.vue`、`designer/`（除 `index.vue` 外全部）、`sql/fms_workflow_mock.sql` ——
+  改前先备份，`git restore` 救不回来（本地历史里也没有）。
+- **`workflow/index.vue` 被 git 跟踪但工作区版本比 HEAD 新**（新增按钮、表格「设计」行操作均未提交）；
+  直接 `git restore` 会退回 HEAD 的 18 行空壳把按钮冲掉，要恢复就用带按钮的 76 行版本。
+- 表已建：`sql/fms_workflow.sql`(13 表)、`fms_workflow_module.sql`(视图 + s_module 注册)、
+  `fms_workflow_menu.sql`(菜单 `workflow`/`approval*`)、`fms_workflow_mock.sql`
+  (`expense_approval` 样本：7 种节点类型 / 6 种审批方式 / 5 种审批人解析)。
+- **后端 `fms-api/src/main` 目前零工作流代码**：保存/校验/模拟/发布都要走流程服务，
+  接口 404 时必须明确提示「服务未接入」，绝不伪造成功。
+
+## 树形重构踩过的坑
+
+① `b_priority` 是**同一来源节点内**的判断顺序，不是全表序号；
+② 校验只约束**出边**，入边不能锁成 1（分支汇合点天生多条入线）；
+③ 环要单独拦，否则递归不终止；
+④ 默认出口（`condition: null`）必须唯一且固定最后。
+
+## 画布「一键整理」（dagre 自动布局，2026-09-23 已落地）
+
+- 依赖 **`@logicflow/layout@2.1.5`**（peer 正好是 `@logicflow/core ^2.2.5`）。
+  注意 dagre **不在** `@logicflow/extension` 里（那只有一个标注「未完善」的 AutoLayout）。
+- 必须**深路径导入** `import { Dagre } from '@logicflow/layout/es/dagre'`：包入口同时导出 `elkLayout`，
+  从入口引会把 elkjs 打进产物（实测深路径只 +92 kB，走入口 +1MB 以上）。包没有 `exports` 字段，深路径可用。
+- 注册方式：`new LogicFlow({ plugins: [Dagre] })`，调用 `lf.extension.dagre.layout({...})`。
+  插件实例由 `installPlugin` 的「非静态插件」分支创建（`Dagre` 只有 `static pluginName` + `render`，没有 `install`）。
+- **坑**：插件靠 `ToolOverlay` 的 `componentDidMount` → `triggerToolRender` 调用 `render(lf)` 才拿到 `this.lf`；
+  拿不到时 `layout()` 会**直接抛错**（它的 try/catch 只包住 applyDagreLayout）。所以 `autoLayout()` 里先兜底
+  `if (!dagre.lf) dagre.lf = lf`，并用 try/catch + 「坐标是否变化」判断结果 —— 插件失败时只打 console.error。
+- 布局走 `lf.renderRawData()` 整图重渲染：**会丢选中态**，但节点/连线 **id 保留**（`processEdges` 只改路径字段），
+  所以上层按 nodeKey/edgeKey 回填审批人与条件仍然成立。坐标变化由实例的 `history` 自动记录（deepObserve + debounce）。
+- 布局后**必须 `snapshot()`** 把新坐标 emit 给上层，否则草稿里的 x/y 还是旧的。
+- 参数：`rankdir:'TB'`（审批流程纵向）、`align:'UL'`、`nodesep:60`、`ranksep:80`、`isDefaultAnchor:true`（重算连线路径）。
+- 测试 `tests/unit/workflow-canvas-layout.spec.js`（jsdom 挂载画布真跑一次布局；
+  需给 `SVGElement.prototype.getBBox` 打桩，否则 LogicFlow 的 autoWrap 文本测量会挂）。