20260916231505

code/fms/.workbuddy-ai/memory/MEMORY.md

@@ -137,3 +137,59 @@
   复合主键用逗号分隔（如 `s_field` 传 `b_module_id,b_field`）。执行顺序 delete → update → insert。
 - 模块元数据（`s_module` / `s_field` / `s_module_schema`）**不由后端接口下发**，
   前端从本地 schema JSON 解析，所以改元数据后无需重启后端。
+
+## 编译 / 测试 fms-api（本机 mvn 入口全是坏的，用这条）
+
+`fms-api/start.cmd` 里的 `JAVA_HOME=D:\devtool\jdk\jdk-21` 与
+`MAVEN_HOME=D:\devtool\maven\apache-maven-3.8.9` **两个路径都不存在**
+（实际是 `D:\devtool\jdk\jdk21`、`D:\devtool\maven`），照抄必失败。
+`/d/devtool/maven/bin/mvn`（shell 脚本）在 Git Bash 下报
+`找不到或无法加载主类 org.codehaus.plexus.classworlds.launcher.Launcher`；
+从 Bash 调 `cmd.exe` 被安全策略拦；另一个 shell 工具的输出不回流（得写文件再读）。
+
+**唯一可行做法：直接用 JDK 拉起 Maven 的 classworlds launcher。**
+
+```bash
+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`**（settings.xml 里改过 localRepository），不是 `~/.m2`。
+- 新依赖要联网首次下载，去掉 `-o` 即可（`repo1.maven.org` 可达）。
+- 中文乱码时输出里加 `grep -a`。
+- `target/` 被 git 跟踪，编译后会有一堆 `.class` / surefire 报告显示为 modified，属正常噪音。
+
+**既有基线失败（不是自己引入的，别去修）**：
+- `OrgDataSourceFactoryTests.databaseConnectionFailureDoesNotRetry`
+  （断言 Druid `getConnectionErrorRetryAttempts()==0`，实测 1）。
+- 前端 `tests/unit/fms-module-list-page.spec.js` 里所有引用 `.filter-drawer` /
+  `.filter-row__*` 的用例 —— 这些类名在 `src/` 里**已不存在**，是高级查询面板改版后没更新的过期断言。
+
+## 导出功能（P0 已落地）
+
+- 入口：`POST /api/export/list`（`ExportController`），**返回文件流**，不是 ApiResponse。
+- 分层：`SqlPermissionService`（动作权限 + 字段白名单 + 数据范围）→ `ExportSchemaService`
+  （按 moduleId 读 s_module + s_field + s_module_schema.view，**与列表同源推导导出列**）→
+  `ExportService`（拼 SQL、SQL 层聚合合计、JDBC 游标 + Fesod 流式写）→
+  `ExportWorkbookWriter`（表头/明细/合计 → xlsx）→ `ExportHeadBuilder`（表头树 → `List<List<String>>`）
+  + `ExportStyleHandler`（三种样式 + 逐列列宽）。
+- 关键约束：**导出列不由前端传**，否则字段权限（`s_user_field_power.b_export`）形同虚设；
+  **所有校验必须在写 `getOutputStream()` 之前完成**，且游标要「先 `executeQuery()` 再设响应头」，
+  否则 SQL 报错时用户拿到的是半截文件而不是 JSON 错误。
+- 依赖：**`org.apache.fesod:fesod-sheet:2.0.2-incubating`**（Apache Fesod Incubating = EasyExcel 的
+  Apache 续作，包名 `org.apache.fesod.sheet.*`，入口类 `FesodSheet`，API 与 EasyExcel 一致，
+  自带 POI 5.5.1，**不要再单独引 POI**）。多级表头合并用 `automaticMergeHead(true)`，
+  各列标题层数可不同（Fesod 底部对齐补空，列名落在最后一行）。
+  **两个 Fesod 行为坑**：① 0 行导出必须仍调用一次 `write`（哪怕传空集合），否则生成的 xlsx
+  **没有任何工作表**；② 合计行是拼出来的数据行，「合计」标签要自己构造（落在第一个无聚合值的列）。
+- 合计行只在 view schema 的列节点带 `summary: sum|count` 时才出现；**目前没有任何模块配了它**，
+  所以线上看不到合计行（多级表头同理，没有模块配 `type:group`）。
+- 前端：`services/exportService.js` + `FmsModuleListPage` 工具栏「导出」按钮；
+  `services/http.js` 的响应拦截器加了 blob 直通分支（下载类响应要能读 headers）。
+- 权限现状：`s_power` 只有 2 行（`s_i18n_type`），`s_user_field_power` / `s_user_data_power`
+  都是空表。非超管走白名单语义会被拒（「没有导出权限」），**g3soft 提权可直接用**。