FMS 项目长期约定

目录 / 文档 / 库

后端 fms-api（Spring Boot + JDK21，JDBC+Druid 无 ORM）；前端 fms-vue（Vue 3.5 + Vite 8 + Pinia，纯 JS）。 fms-vue-old1/old2 仅供历史参考，不要改。
根目录设计文档：FMS新系统核心表结构设计.md（权威表结构）、FMS业务表设计.md、开发规范.md（AI 规范）、 Fms旧系统表结构.md（旧库 G3HY2025，只有表无视图）、FMS删除规则引擎设计.md。
建库/模块注册脚本在 sql/（fms_core.sql、fms_business_*.sql、fms_module_*.sql）。
SQL Server 118.89.70.199:1433：旧库 G3HY2025，新库 FMS（新系统一律用 FMS，生产库，写前先确认）。
机构→库映射在 fms-api/config/dbconfigs/{ORG_ID}.properties（gitignore）：G3HD.properties → FMS， G3HY2025.properties → G3HY2025。没有 FMS.properties。
后端 8088（context-path /api），前端 dev 5082（/api → 127.0.0.1:8088）。直连接口需先 /auth/login。

元数据核心表（真实列名，已连库核对，别再猜）

s_module：PK b_id（无 b_module_code；无 b_route，那是 s_menu 的）；本身是树： b_parent_id/b_depth/b_path；另有 b_module_type(module/data/virtual)、b_view_table、b_save_table、 b_key_field、b_order_sql、b_query_sql、b_config_json、b_canuse、b_xh、b_bz、b_name、b_i18n。
s_field：PK (b_module_id, b_field)，无 b_id；b_type 实测 input/number/checkbox/datetime/date。
s_module_schema：PK (b_module_id, b_schema_type∈view|edit|query)，b_schema_json。
s_menu：b_id/b_parent_id/b_depth/b_path/b_menu_type(directory|page)/b_route/b_icon；s_menu_module 绑菜单与模块。
权限靠 b_id：permissionStore 的 moduleCodes 即 s_module.b_id，页面 MODULE_CODE 必须等于它；还要在 s_menu_module 里绑菜单，否则非超管看不到授权入口。
列表模块编码统一 v_+表名（v_b_othercompany），b_view_table→视图，b_save_table→真实表。
schema JSON 形状：view{columns:[{field,width}|{type:group,title,children}]}、 edit{children:[{field,span,required,readonly,defaultValue}|group]}、query{groups:[{conditions}],quick}。
路由守卫只看 meta.moduleId/meta.adminOnly；views/module/** 是 adminOnly（仅 g3soft）。

树结构规范（模块/菜单/部门/分类树通用）

b_parent_id 是权威关系，b_depth（根=0）、b_path（/cn/east/）是派生字段，移动节点要同事务更新全部后代；不一致时以 b_parent_id 为准。工具在 src/utils/tree.js（buildSortedTree/computeTreeMove/collectDescendantIds/ applyTreePosition/filterTreeByText/findTreeNode），展示层用 components/fms-tree/FmsTree.vue（自管虚拟根）。

后端通用接口（前端业务数据只走这几个）

POST /auth/login：字段是小写 orgid/userid/password；orgid=G3HD。
/data/loaddata：view_name/search_condition/可选 order_by/search_columns（真 JSON 数组）。
/data/page：order_by 必填（DbUtils.buildPageOrderBy 会报「order_by 不能为空」），分页参数名是 page_no/page_size（不是 pageindex/pagesize）。
/data/saveobjt：body 是数组，每项 {table, key_field, deletes, updates, inserts}，key_field 必填 （复合主键逗号分隔），顺序 delete→update→insert。
模块元数据不由接口下发，前端读本地 schema JSON，改元数据无需重启后端。
DbUtils 是 SQL 唯一出口：标识符加 []，validateReadOnlySql() 只允许查询。

环境坑（本机特有）

编译/测试 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。

主题约定

配色唯一真相 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-*，不受表单布局配置影响。

导出（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 可直接用。

9.5 KiB Raw Blame History Unescape Escape