imom-framework 框架模块使用指南
imom-framework 是聚合工程（parent 为 imom-dependency，groupId com.sie.mbm.mom），包含 19 个 framework-* 模块。所有模块均通过 Spring Boot 自动装配（META-INF/spring/...AutoConfiguration.imports）生效，业务工程按需引入依赖即可，无需手动 @Import。
| 模块 | 定位 | 是否必引 |
|---|---|---|
| framework-common | 通用基础包（DTO/异常/工具/注解/SPI） | 必引（被所有模块传递依赖） |
| framework-core | 核心自动配置（登录上下文/异常/线程池/HTTP） | 必引（服务入口） |
| framework-cache | Redis 缓存 | 按需 |
| framework-db | 数据访问（mybatis-flex / 华为 iDME） | 按需 |
| framework-mq | Redis Stream 消息队列 | 按需 |
| framework-excel | Excel 导入导出 | 按需 |
| framework-websocket | WebSocket 推送 | 按需 |
| framework-apilog | 接口日志采集 | 按需 |
| framework-sequence | 发号器（号段/雪花） | 按需 |
| framework-swagger | 接口文档 | 按需 |
| framework-compatible | 旧版本兼容层 | 存量工程 |
| framework-idempotent | 幂等/分布式锁 | 按需 |
| framework-language | 多语言 | 按需 |
| framework-license | 授权证书校验 | 私有化部署 |
| framework-oss | 对象存储（MinIO/本地） | 按需 |
| framework-print | 通用打印 | 按需 |
| framework-script | JS 在线脚本引擎 | 按需 |
| framework-seeddata | 种子数据初始化 | 按需 |
| framework-api | 框架远程服务 Feign 客户端 | 随 core 自动启用 |
依赖示例（版本由 imom-dependency BOM 统一管理，无需写版本号）：
<dependency>
<groupId>com.sie.mbm.mom</groupId>
<artifactId>framework-core</artifactId>
</dependency>
framework-common
用途
全局共享的基础包，是全部模块的依赖底座。提供统一返回结构、业务异常体系、基础 DTO、常用注解、线程上下文（TTL）、Jackson 序列化定制与各类静态工具类。
用法
无需配置，引入后直接使用。
- 统一返回：
R、RetOps（链式取值） - 异常与断言：
BusinessException、ErrorCodes、ValidateCodeException、AssertUtils - 基础 DTO：
BaseDTO、BasicDTO、BaseViewDTO、QueryPageVO、QueryPageBaseVO、PageResultVO、LineEditDTO、ExtAttrDTO - 业务注解：
@SIgnore、@SType、@SNeedWrap、@DictParent、@Sensitive、@UniqueKey/@UniqueGroup、@ExcelLine、@DropDownSetField、@ManySheet、@IgnoreTenant、@NotEmpty、@NumberFormat、@SelectType、@ForeignKey、@ViewColumn、@SCodeDescription（枚举多语言描述） - 线程上下文：
ThreadContextHolder（TTL，存UserInfo/BusinessInfo/TransactionInfo），配合线程池透传登录用户 - Handler SPI（由 framework-core 提供默认实现）：
UserHandle、LoginHandle、TenantHandle、UserTokenHandle、DictHandle、ApplicationBizHandle - Jackson 定制：
JavaTimeModule（ZonedDateTime 等）、BigDecimalSerializer、BusinessEnumSerializer - 脱敏：
DesensitizedUtils+@Sensitive+SensitiveSerialize - 工具类：
F（函数式工具）、JsonUtils、StringUtils、CollectionUtils、FileUtils、SpringContextHolder、ThreadPoolUtils（有界线程池）、ZonedDateTimeUtils、RetryUtils、MsgUtils、DiskMultipartFile/ByteMultipartFile - Excel 转换器：
ZonedDateTimeStringConverter、ZonedDateTimeNumberConverter、LocalDateTimeStringConverter等
适用场景
- 所有业务工程的基础依赖，定义实体、DTO、返回值、抛业务异常
- 异步/线程池场景透传用户上下文（ThreadContextHolder）
- 字段级脱敏、唯一键校验、字典标注等声明式需求
framework-api
用途
封装框架平台级远程服务（内核服务 kernel-biz）的 OpenFeign 客户端与传输 DTO，供业务服务查询用户、租户、打印方案、语言包等公共数据。
用法
随 framework-core 引入即可（core 的 @EnableFeignClients(basePackages = "com.sie.mbm.mom.framework.api.feign") 已自动扫描），直接注入使用。
- Feign 客户端：
FrameworkRemoteSysUserService：按 userId/renterId 查用户、创建用户等FrameworkRemoteSysTenantService：租户查询与维护FrameworkRemotePrintSchemeService：打印方案创建与查询RemoteSysLanguageDataService：语言包查询、百度翻译
- DTO：
SysUserViewDTO、SysTenantViewDTO、LanguagePackDTO、BaiduTranslateResultDTO、ApiResolverDTO等
spring:
cloud:
openfeign:
client:
config:
kernel-biz:
url: ${KERNEL_BIZ:http://localhost:8015} # 服务发现关闭时直连地址
适用场景
- 业务服务中查询当前用户/租户信息（登录助手底层亦依赖它）
- 打印模块远程保存/读取打印方案
- 多语言模块远程获取语言包与机器翻译
framework-core
用途
框架核心自动配置模块，应用启动即生效。负责登录上下文注入、MDC TraceId、全局异常处理、线程池与上下文透传、HttpClient 连接池、Feign、多级缓存、字典、Jackson 与 Banner 版本打印等横切能力。
用法
引入即生效，少量配置项可选。
- 自动配置入口：
FrameworkCoreAutoConfiguration（@EnableScheduling/@EnableCaching/@EnableAsync/@EnableFeignClients） - 请求上下文：
ContextHolderFilter（收到请求即维护 MDC TraceId）→LoginContextInterceptor（WebMvcInterceptorConfiguration注册）注入登录用户 - 登录助手：
MbmLoginHelper、AimomLoginHelper（解析 token →UserInfo/SysUser/SysTenant，内置 Caffeine L1 缓存 5/30 分钟 + Redis L2） - 默认实现（可覆盖）：
DefaultLoginHandle、DefaultUserHandle、DefaultTenantHandle、DefaultDictHandle、DefaultApplicationBizHandle - 异常：
GlobalBizExceptionHandler统一兜底业务异常 - 服务基类：
BaseServiceImpl、BasicAtomService - 上下文透传：
TaskExecutorConfigurations+DefaultTaskDecorator（TTL/MDC 跨线程传递） - HTTP：
MomHttpClientConfig（mom.httpclient）连接池化 RestTemplate，HttpPoolLeakDetector定时清理过期连接并监控泄漏；FeignInterceptor透传 token/上下文；DistributedTransactionFilter - 其他：
IgnoreTenantAspect（配合@IgnoreTenant跳过租户过滤）、MultiLevelCacheConfig/MultiLevelCacheHelper（多级缓存）、MomDictConfig、MomApiConfig、MessageSourceConfiguration（i18n 消息源）、LibraryVersionBannerListener（启动打印框架版本）、FieldConvert（NamingStrategy/QueryWrapperFieldConverter查询字段驼峰-下划线转换）
mom:
httpclient:
maxTotal: 200 # 连接池最大连接数
defaultMaxPerRoute: 20 # 单路由最大连接数
connectTimeout: 5000
socketTimeout: 30000
enableConnectionMonitoring: true # 输出连接池状态日志
适用场景
- 所有 Spring Boot 业务服务的统一启动底座（必引）
- 需要获取当前登录用户/租户（LoginHelper、ThreadContextHolder）
- 异步任务、@Async、线程池中保持用户上下文与 TraceId
- 统一异常返回格式与 Feign 调用鉴权头透传
framework-cache
用途
Redis 缓存封装：定制 RedisTemplate 序列化、提供静态缓存门面 CacheHelper（一行代码读写 Redis）、支持 Spring Cache 注解自动缓存与多语言包缓存，支持批量操作与缓存 null 值。
用法
引入后注入或静态调用。
- 静态门面：
CacheHelper.keyIsExist/expire/increment/set/get/...（内部委托ICacheHelper实现RedisHelper） - 直接操作：
RedisHelper、RedisOperator - Spring Cache：
RedisAutoCacheManager+@EnableCache（common 模块注解）开启方法级自动缓存 - 多语言：
I18nCacheHelper（语言包本地缓存，供 framework-language 使用） - 模板定制：
RedisTemplateConfiguration（JSON 序列化；支持spring.redis.log.database将日志类数据写入独立库，默认 7）；DefaultRedisCacheWriter、SmartValueSerializer
CacheHelper.set("key", value, 300); // 写入并 300 秒过期
Long n = CacheHelper.increment("counter", 1); // 原子自增
CacheHelper.hset("map:key", "field", value); // Hash 写入
spring:
data:
redis:
host: 192.168.168.207
port: 32180
database: 0
适用场景
- 热点数据缓存、验证码、Token 存取、分布式计数
- 方法级自动缓存（@EnableCache + Spring Cache 注解）
- 日志/业务数据隔离到不同 Redis database（spring.redis.log.database）
- 多语言包缓存（配合 framework-language）
framework-db
用途
数据访问核心，基于 mybatis-flex（非 mybatis-plus）。提供基础实体与 DbMapper 增强、插入忽略 NULL、selectOne 多条抛异常、逻辑删除、分页工具、SQL 日志、AES 字段自动加解密、租户/工厂/组合隔离，以及华为 iDME(RDM) 委托执行（DmeMapper）与分布式事务、RDM 扩展属性(EXA)模型。
用法
Mapper 继承 DbMapper<T>、实体继承 BasicEntity 即可获得全部增强（BaseEntity 已废弃）。
- 基础实体
BasicEntity：createUser/updateUser/createDate/updateDate/delFlag/tenantId/renterId/siteId DbMapper<T>：继承BaseMapper<T>，新增updateBatch（批量更新，可控制 ignoreNulls），自动过滤 renderId/siteId- 框架默认行为：插入忽略 NULL 字段（让数据库默认值生效）；
selectOne查出多条抛异常；@Table（覆盖 mybatis-flex 同名注解）支持逻辑删除 - 租户/工厂/组合隔离：按模块配置生效，方法/类标
@IgnoreTenant可跳过租户条件 - AES 加密：字段标注后自动加密存储、查询自动解密
- 分页：统一返回 mybatis-flex
Page，配合 common 的QueryPageVO - SQL 日志：输出 SQL（最大 2000 字符），对接 apilog
- iDME 委托（
executeDme包）：DmeMapper、DmeExecute/MbmExecute（工厂创建）、IamAuth（华为 IAM token 管理）、DmeDelegatorService/MbmDelegatorService；@DmeTransactional+DmeTransactionalAspect实现跨 DME/本地库分布式事务 - 扩展属性（
commonBasic包）：ExaDefinition、ExaDefinitionLink、Folder、EntityModel、TypeDefinition的 Repo/Service（RDM 扩展属性定义与管理）
application:
appId: 0fa023ca... # iDME 应用 ID
tenantId: -1
delegate: # iDME(RDM) 连接配置
subAppId: rdm_xxx_app
domain: http://192.168.168.207:30083
userName: siedme02
password: ENC(xxx) # jasypt 加密
endpoint: https://iam.cn-north-4.myhuaweicloud.com
domainName: siedme
regionName: cn-north-4
适用场景
- 常规 MySQL 单表/多表 CRUD（DbMapper + QueryWrapper）
- 多租户 SaaS、工厂维度数据隔离
- 敏感字段（手机号、密码）AES 落库加密
- 华为 iDME/RDM 数据模型读写、本地库与 RDM 混合事务
- RDM 扩展属性(EXA)、文件夹、类型定义管理
framework-mq
用途
基于 Redis Stream 的轻量级消息队列：注解式消费者、重试、竞争消费（消费者组）、广播订阅、手工订阅，发送端默认透传用户/租户/Token 上下文。
用法
发送：注入 MessageSenderService；消费：类实现 MessageHandlerInterface 并标注 @MessageListener。
// 发送（默认携带用户信息）
messageSenderService.send("order-topic", dto);
messageSenderService.send("order-topic", dto, 3, true); // 重试3次, 不带用户信息
// 消费
@MessageListener(value = "order-topic", groupName = "order-biz",
consumeThread = 2, maxRetryCount = 3,
ackAutoDelMessage = true) // 单消费组场景消费成功即删消息
public class OrderMessageHandler implements MessageHandlerInterface {
@Override
public void onMessage(MessageDO message) { ... }
}
mom:
message:
enable: true # 是否启用消息消费
type: redis # 消息类型, 默认 redis
redis: { } # RedisMessageConfigProperties 细项
MessageSubscriptionService：运行期手工订阅 Topic- 广播订阅：同一 Topic 的非竞争消费（各实例都收到）
- 订阅失败默认不抛异常；Redis 组创建失败自动重试
适用场景
- 服务间异步解耦（无需引入 Kafka/RocketMQ）
- 多实例部署下的竞争消费（同 groupName）与广播通知（不同 groupName）
- 失败自动重试、消费成功即释放内存（ackAutoDelMessage）
- 运行期动态订阅消息处理逻辑
framework-excel
用途
基于 EasyExcel 的注解式导入导出：Controller 方法标注注解即可完成下载/上传，支持多 Sheet、动态表头、SpEL 动态文件名、多语言表头、下拉框模板与导入校验。
用法
// 导出：返回值直接写 Excel（文件名支持 SpEL 取方法参数）
@ResponseExcel(name = "用户列表_#{#param.deptName}")
@PostMapping("/export")
public List<UserExportVO> export(@RequestBody QueryVO param) { ... }
// 导入：参数即解析后的行数据列表
@PostMapping("/import")
public R<?> importExcel(@RequestExcel List<UserImportDTO> rows) { ... }
// 多 Sheet
@ManySheetRequestExcel + @Sheet(index = 0, size = 1000)
- 注解：
@ResponseExcel、@RequestExcel、@ManySheetRequestExcel、@DynamicRequestExcel、@Sheet - 监听器：
DefaultAnalysisEventListener、ListAnalysisEventListener、ManySheetAnalysisEventListener、DynamicModelBuildEventListener（动态模型） - 表头：
I18nHeaderCellWriteHandler+HeadGenerator/HeadMeta自定义多语言表头 - 文件名：
DynamicNameAspect+NameSpelExpressionProcessor（SpEL） - 下拉：
ExcelDropDownUtil、DropDownAnnotationUtil、@DropDownSetField（common） - 校验：
Validators、NotEmptyHandler、ExcelValidUtils、ExcelException；错误行回显ErrorMessage - 列宽自适应：
CustomCellWriteWidthConfig；模板路径配置excel.templatePath（默认excel） - ZonedDateTime/LocalDateTime 与字符串互转无需指定转换器（common 的 converters 自动注册）
适用场景
- 列表页导出报表、按查询条件动态命名导出文件
- 批量导入 + 行级校验错误回显（ErrorMessage）
- 一表多 Sheet、模板填充（templatePath）
- 中文/英文多语言表头导出
framework-websocket
用途
内嵌 WebSocket 端点：自动注册握手与处理器、心跳保活、登录用户注入，支持本地与 Redis Pub/Sub 两种集群消息分发模式。
用法
引入即注册端点（默认 /ws/info），业务实现 JsonMessageHandler 处理自定义消息，注入 MessageSender 推送。
// 自定义消息类型
public class NoticeMessage extends AbstractJsonWebSocketMessage {
public NoticeMessage() { super("notice"); }
// payload...
}
@Component
public class NoticeMessageHandler implements JsonMessageHandler<NoticeMessage> { ... }
// 服务端推送
messageSender.send(MessageDO.broadcastMessage(json)); // 全员广播
messageSender.send(new MessageDO().setMessageText(json)); // 单点推送
mom:
websocket:
path: /ws/info # 端点路径, 支持 PathVariable 与 query 参数
allowOrigins: "*"
heartbeat: true # 内置 Ping/Pong 心跳
mapSession: true # session 映射记录
message-distributor: redis # local | redis, 集群部署配 redis
- 会话管理：
WebSocketSessionHolder、MapSessionWebSocketHandlerDecorator、SessionKeyGenerator - 握手：
UserAttributeHandshakeInterceptor（框架负责注入登录用户，业务层无需处理） - 处理器：
CustomWebSocketHandler+JsonMessageHandlerHolder（按 type 分发）、PingJsonMessageHandler - 集群分发：
RedisMessageDistributor+RedisWebsocketMessageListener
适用场景
- 待办/消息通知实时推送
- 任务进度、导入进度反馈
- 实时看板、监控大屏
- 多实例集群下的跨节点推送（message-distributor=redis）
framework-apilog
用途
接口日志采集：切面自动记录 Controller 接口、Feign、RestTemplate 调用的出入参与 SQL，异步写入 Redis 供日志中心消费（对接 ES 链路），含 TraceId、logTime/esLogTime 字段；支持应用内发布订阅扩展处理。
用法
引入即生效（默认全开），可用配置裁剪；自定义落库实现 ApiLogHandler。
- 注解：
@LogController（标注需要记录的 Controller，也可切所有@RestController）、@LogIgnore（忽略方法/参数） - 切面：
LogInterfaceAspect（接口入参出参）、LogRestApiInterceptor（RestTemplate）、LogFeignInterceptor/LogFeignAspect（Feign） - 输出：
RedisAppender写 Redis（key 为${apilog.env}:interface/${apilog.env}:all；apilog.env=loc本地环境不推送；spring.redis.log.database指定日志库，默认 7） - 数据模型：
LogApiInfo/LogApiStrInfo（接口）、LogSqlInfo/LogSqlListInfo（SQL，最长 2000 字符）、LogAllInfo（含 logTime、esLogTime） - 扩展：
LogEvent/LogEventListener应用内发布订阅；ApiLogHandler/DefaultApiLogHandler自定义处理；MdcAwareRunnable异步线程池（有界队列）透传 MDC - appName 识别：
LogConstant按 URL 前缀（/mdm/、/mdm. 等）提取
apilog:
interface-flag: true # 记录接口日志
rest-api-flag: true # 记录 RestTemplate
feign-flag: true # 记录 Feign
response-flag: false # 记录响应体
header-flag: false # 记录请求头
in-flag: false # 入库开关
input-type: list # 写 Redis 结构: list | stream
spring:
redis:
log:
database: 7 # 日志独立库
适用场景
- 接口审计与出入参留痕（等保/追溯）
- 微服务调用链追踪（TraceId 贯通 Feign/线程池）
- SQL 审计与慢 SQL 排查
- 对接日志中心/ES 的统一日志采集
framework-sequence
用途
统一发号器：提供号段模式（Redis 号段区间，高吞吐连续号）与雪花算法（趋势递增分布式 ID）两种 Sequence 实现，业务名（BizName）隔离不同业务的序列。
用法
配置二选一（或自定义 Sequence Bean 覆盖），注入 Sequence 调用 next()。
Long id = sequence.next(); // 纯数字 ID
String no = sequence.next("ORDER"); // 携带业务前缀（DefaultBizName）
mom:
xsequence:
snowflake:
datacenterId: 1 # 数据中心
workerId: 1 # 机器号
redis: # 号段模式(RedisSeqRangeMgr)配置
step: 1000 # 每次取号段长度
db: { } # 数据库号段(SequenceDbProperties)
- 实现：
DefaultRangeSequence（号段）+RedisSeqBuilder/RedisSeqRangeMgr；SnowflakeSequence+SnowflakeSeqBuilder - 装配：
SequenceAutoConfiguration在存在SequenceSnowflakeProperties且无自定义Sequence时默认注册雪花实现 - 业务名：
BizName、DefaultBizName（前缀+日期）、DateBizName
适用场景
- 业务单号生成（订单号、流水号，号段模式保证趋势连续）
- 分布式主键 ID（雪花）
- 多业务线序列隔离（BizName）
framework-swagger
用途
springdoc-openapi 接入：单服务文档开关与分组、网关聚合文档，以及 API 元数据注册服务（供脚本模块等复用）。
用法
启动类标注 @EnableOpenApi（value 填网关路由前缀），配置 swagger.*。
@EnableOpenApi("kernel") // 网关路由前缀
@SpringBootApplication
public class App { }
swagger:
enabled: true
base-package: com.sie.imom
title: MomX Swagger API
gateway: admin-gateway
token-url: http://admin-gateway:9999/auth/oauth/token
services: { } # 服务转发配置(聚合)
@EnableOpenApi：导入OpenAPIDefinitionImportSelector，加载classpath:openapi-config.yaml- 分组：
OpenAPIDefinition（配合 common.yml 的swagger.apis列表做微服务聚合分组） - 属性：
SwaggerProperties（enabled/basePackage/basePath/excludePath/ignoreProviders/title/gateway/tokenUrl/scope/services） - 元数据：
SwaggerRegistryService+ControllerMetadata/RouteMetadata/SchemaMetadata（framework-script 的 JsSwagger 借此为 JS 脚本生成 swagger 文档）
适用场景
- 单服务在线接口文档与调试
- 网关侧多服务文档聚合
- 自研平台读取 API 元数据（脚本接口自动注册 swagger）
framework-compatible
用途
旧版本兼容层：为存量 iMoM/MBM 业务工程提供历史包路径下的通用 DTO、委托接口与断言工具，降低框架升级时的改造量。
用法
仅在迁移存量代码时引入，直接使用其中的历史类型。
com.sie.mbm.mom.framework.common.dto：CommonDTO、CommonViewDTO（旧版通用 DTO）com.sie.mbm.mom.framework.data.base：BaseDelegator<T>（detail/delete/update/create 四个委托方法）、CommonEntitycom.sie.mbm.mom.framework.sentinel.utils：DmeAssert（RDM 场景断言）
适用场景
- 老业务工程升级到新框架后的编译兼容
- 沿用 BaseDelegator 委托模式的存量服务
- RDM 数据校验断言（DmeAssert）
framework-idempotent
用途
基于 Redisson 的注解式幂等控制与分布式锁：防止重复提交、并发互斥，锁支持等待/超时/自动续期/公平锁/联锁（一次锁多个资源），失败行为可定制。
用法
// 幂等: 同一 key 在有效期内只放行一次
@Idempotent(key = "#orderNo", expireTime = 10, delKey = true)
public R<?> submit(String orderNo) { ... }
// 分布式锁: 单资源
@Lock(value = "'stock:' + #skuId", waitTime = 3, leaseTime = 15)
public void deduct(String skuId) { ... }
// 联锁: 同时锁多个资源
@Lock(values = {"'a:' + #id1", "'b:' + #id2"})
public void transfer(Long id1, Long id2) { ... }
@Idempotent：key（SpEL，#参数名/#对象.属性）、expireTime（默认 1s，需大于业务执行时长）、timeUnit、info（重复提示）、delKey（完成后是否删 key）@Lock：value/values（values 开启联锁）、waitTime、leaseTime（默认 15s）、tryLock（默认 true）、fairLock、autoRenew（默认 true 自动续期）、fail（失败回调 Supplier，默认抛异常）、failMessage（默认"您操作的资源已被锁定，请稍后重试"）- 切面：
IdempotentAspect、DistributedLockAspect；实现：IDistributedLock/RedissonDistributedLock；key 解析：KeyResolver/ExpressionResolver
适用场景
- 表单/订单防重复提交（幂等）
- 定时任务、消息消费的并发互斥
- 库存扣减、余额变更等临界资源保护
- 转账/换线等多资源联锁，避免死锁（按序联锁）
framework-language
用途
多语言模块：应用启动时自动扫描业务枚举与异常定义，翻译后统一入库（语言包），并加载到进程内缓存（I18nCacheHelper），运行期按用户语言返回多语言文案；异常消息经 BusinessExceptionHandler 自动翻译。
用法
开启配置 + 扫描范围即可，业务侧无需编码。
language:
enabled: true
modules: mdm,sys # 限定扫描的模块(不配则全量)
LanguageAutoConfiguration：ApplicationReadyEvent触发：扫描 → 翻译入库 →I18nCacheHelper.initLocalCache加载语言包- 扫描器：
BusinessEnumScanner（枚举，配合 common 的@SCodeDescription描述）、BusinessExceptionScanner（异常码） - 翻译入库：
BusinessExceptionHandler（借助RemoteSysLanguageDataService，支持百度翻译BaiduTranslate*DTO） - 运行期：
LanguageUtils按当前语言取文案；I18nCacheHelper（framework-cache）进程内缓存
适用场景
- 面向海外/多语言用户的错误提示翻译
- 枚举字典值的多语言显示
- 语言包集中管理（数据库存储 + 缓存加速）
framework-license
用途
应用授权证书（license）模块：启动时校验证书有效性，并定时（每天 0 点、每 24 小时）复核，证书无效或过期自动关闭应用；支持试用（trial）证书优先；绑定宿主机指纹防拷贝。
用法
配置证书路径即可，校验全自动。
license:
way: LOCAL # 存储方式: LOCAL | MYSQL(待实现) | DME(待实现)
savePath: /data/license/
sysNetAddress: /host/sys/class/net # 容器内网卡信息路径
debug: "0" # 调试日志开关
LsAutoConfiguration：装配LsAutoConfig、LsProperties，扫描 trial 包LsTesterService：启动校验（Windows 开发环境直接跳过；trial 有效则跳过正式校验）+@Scheduled每日 0 点 / 每 24h 定时校验，无效则doAppExit()关闭应用LsHandler：证书加载/解析/校验（LsDTO/LsCheckDTO）- 防伪：
HostMachineUniqueEnum（网卡等机器指纹）、SignUtils/SignClassLoader（签名验签）、ShellUtils（容器内取硬件信息）、YamlConfigUtils
适用场景
- 私有化交付项目的授权期限控制（到期自动停服）
- 防止安装包被复制到未授权机器
- 试用版（trial）与正式版差异化控制
framework-oss
用途
对象存储统一门面：同一套 FileTemplate API 支持 MinIO/S3 协议对象存储与本地磁盘两种实现，含 HTTP 上传端点。
用法
file:
bucket-name: mbm-mom-dev
local: # 本地存储(开发用)
enable: false
base-path: /data/file
oss: # MinIO/S3
type: MINIO
enable: true
endpoint: http://192.168.168.207:31782
path-style-access: true # nginx 反代/S3 用 path-style; 阿里云等用 virtual-hosted-style
access-key: admin
secret-key: xxx
max-connections: 100
- 门面：
FileTemplate（统一上传/下载/删除/URL） - 实现：
OssTemplate（S3 SDK，OssProperties前缀oss）、LocalFileTemplate（LocalFileProperties前缀file.local） - 装配：
FileAutoConfiguration/OssAutoConfiguration/LocalFileAutoConfiguration - 端点：
OssEndpoint（HTTP 上传接口）
适用场景
- 附件/图片/导入导出文件上传下载
- 私有化 MinIO 部署与本地开发环境无缝切换
- 需要替换存储后端而业务代码不动（面向 FileTemplate 编程）
framework-print
用途
通用打印模块：通过注解声明打印计划与打印模型（列定义），框架自动注册元数据并暴露打印预览/取数接口；支持表格（TABLE）与自定义（CUSTOM）两类数据源，打印方案可远程管理。
用法
@PrintScheme(name = "销售订单", code = "sale_order") // 打印模型
public class SaleOrderPrint extends AbstractBillPrintable {
@PrintSchemeColumn(name = "订单号")
private String orderNo;
}
@PrintPlan(name = "销售订单打印", code = "sale_order_plan",
category = PrintPlanCategory.TABLE) // 打印计划
public class SaleOrderPlan { }
- 注解：
@PrintPlan、@PrintScheme、@PrintSchemeColumn - 核心：
FrameworkPrintService（register注册元数据、getPrintData按类别取数：TABLE 走查询/CUSTOM 走自定义）、PrintMetadataInitialization（启动扫描注册） - 接口：
FrameworkPrintController（预览数据PrintPreviewDataDTO、打印数据PrintDataDTO） - 自定义数据源：继承
AbstractBillPrintable（单据）或AbstractSpecifyData（指定数据） - 配置：
PrintConfigProperties（前缀mom.print）；预览策略PreviewDataStrategy - 远程方案管理：framework-api 的
FrameworkRemotePrintSchemeService
适用场景
- 单据打印（订单、出库单等带模板的票据）
- 列表数据打印方案（用户可选列/方案）
- 打印方案集中配置、跨服务共享（配合 kernel-biz）
framework-script
用途
JS 在线脚本引擎（GraalVM Polyglot）：脚本存库、编译缓存、映射为 HTTP 路由对外发布（/_jsapi/**）、在线断点调试（WebSocket）、Gitea 代码版本管理，并可按白名单调用 Spring 服务与内置 Helper（HTTP/Excel/字典/ID/日志/事务等）。是框架内唯一自带单元测试的模块。
用法
开启后脚本管理/调试接口自动可用。
mom:
script:
enable: true
root-path: D:/SieWebApiDev_data # 脚本与资源根目录
code-base-url: /_jsapi/ # 脚本 HTTP 路由前缀
js-debug-session-max-idle-time-minutes: 10
js-enable-gitea: false # Gitea 版本管理
js-gitea-server: http://192.168.168.207:30033/
js-gitea-repo-name: sie-imom-scripts
service-group: # JS 可调用的 Spring 服务白名单
mdm: [ com.sie.imom.mdm ]
sys: [ com.sie.imom.sys ]
- 管理：
Code实体、CodeController/DirController/CodeSearchController - 执行：
JSApiController/KScriptController→JsRoute（JsClass/JsMethod路由缓存）→ 编译执行（CompiledCodeManager、JsSessionManager） - 调试：
DebuggerController+DebugWebSocketHandler+SDebugSession/SBreakpoint（断点、单步、变量查看） - 版本：
GitManager（Gitea 同步、DiffResult） - 脚本可用 API：
SRequest/SResponse/SCookie/UploadedFile；ServiceManager（白名单调用 Spring Bean）；HttpHelper、ExcelHelper、DictHelper、IdHelper、LogHelper、TransactionalHelper、ResourceHelper、YmlConfigReaderHelper；基类SScript - swagger：
JsSwagger+ framework-swagger 的SwaggerRegistryService自动为脚本接口注册文档
适用场景
- 二次开发/低代码：不重启服务新增或修改接口逻辑
- 规则类逻辑（计价、校验、数据转换）在线调整
- 在线断点调试脚本问题
- 脚本代码纳入 Gitea 版本管理、团队协作
framework-seeddata
用途
种子数据初始化模块：应用启动时按 @Order 顺序执行各业务注册的初始化器（基础字典、默认配置、演示数据等），支持配置开关与重复编码检测，自带执行计时日志。
用法
继承 AbstractInitializer 实现 execute()，注册为 Spring Bean 即可。
@Component
@Order(100) // 数值小的先执行
public class DemoDictInitializer extends AbstractInitializer {
@Resource
private DictService dictService;
@Override
public void execute() {
// 幂等初始化种子数据
dictService.initDefault();
}
@Override
public String getCode() { return "demo-dict"; } // 同 code 会告警重复
}
init:
DemoDictInitializer:
enabled: true # 键为 init.{类简单名}.enabled, 默认 true
AbstractInitializer：execute()抽象方法；getName()/getCode()/getType()可覆写；doExecute()模板方法（enabled 检查、StopWatch 计时、异常记录后抛出）InitializerConfig：收集所有初始化器 Bean → 按init.{SimpleName}.enabled过滤 → 按@Order排序执行；启动时检测 code 重复并告警；静态方法getInitializerList()供外部（如管理端点）触发
适用场景
- 新环境部署时自动初始化字典、菜单、角色等基础数据
- 演示/测试数据的按需灌入（配置开关控制）
- 多个初始化任务的顺序编排（@Order）