Files
eip4-platform/platform-auth/P2横切服务实测报告.md
zhengwr 6cc7b3fb61 P2-3: 横切服务桩换 framework 真实现(文件/日志/消息)
保真层原样移植三块横切服务,删除对应桩,bean 名/包名/签名不动:

- 文件 com.dsasp.server.file.*:FileServiceImpl(bean fileService)真实现,
  存储后端经替换类 FTPClientTemplate(保包名/类名/签名,FTP→本地盘,
  根目录 eip4.file.root 配置化默认 ./data/files,resolveSafe 防 ../ 逃逸);
  BASE64Decoder→java.util.Base64、ant zip→java.util.zip、commons-codec→MessageDigest。
- 日志 com.dsasp.server.log.*:SystemLogManagerImpl/DataOperatorLogger/
  DataLogRecorderImpl + 异步调度(DataLogManager/ProcessLogThread/ProcessSysLogThread)
  原样移植,落 SYS_LOG/SYS_DATA_LOG/SYS_DATA_LOGITEM(后者 insert-only 无审计列,§5.1)。
- 消息 com.dsasp.server.mail.*:SystemEmailServiceImpl + SystemEmail/SystemEmailService
  移植;SMTP 配置缺省时降级 no-op + WARN,不阻塞启动(§5.38)。

装配/配置/自举/验证:
- LegacyXmlWiring 等价补齐三处 jdbcTemplate setter + MainApp.destPath 注入(§4.1);
- application.yml 加 eip4.file.root;bootstrap-xservice.sql 自举四张横切表 + LOGLEVEL;
- 删除 StubFileService/StubSystemLogManager/StubDataOperatorLog(StubProjectSwitchService
  属 viewframework 域非本任务范畴,保留);
- 单测 12 + 本地 DB 集成 4,全模块 mvn clean test 绿(含 ArchUnit);8087 启动验证毕已 kill。

报告:platform-auth/P2横切服务实测报告.md;坑入 docs/迁移手册.md §3.1/§3.2/§5.36-5.38。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 14:06:31 +08:00

11 KiB

P2-3 横切服务真实现实测报告(文件 / 日志 / 消息)

任务:用 framework 真实现替换横切服务桩(文件/日志/消息) 工程:/Users/zhengwr/workspace/eip3/eip4-platform 日期:2026-06-11 必读对照:docs/迁移手册.md(§3.1 替换类、§3.2 横切桩、§4.1 XML 等价装配、§5.1/§5.36/§5.37/§5.38、§5 引擎契约)


一、结论速览

维度 结果
移植主源文件 18 个(文件 7 + 日志 7 + 消息 3 + MainApp 1),约 1,611 行
删除的桩 3 个(StubFileService / StubSystemLogManager / StubDataOperatorLog)
保留的桩 1 个(StubProjectSwitchService —— viewframework 域,非本任务范畴,见 §四)
替换类登记 FTPClientTemplate(FTP 后端 → 本地盘,保包名/类名/签名),已登记入 §3.1
新增替换实现 bean fileService / systemLogManager / dataOperatorLog / dataLogRecorder / systemEmailService
单元 + 集成测试 16 个(单测 12 + 本地 DB 集成 4),全绿
全模块 mvn clean test BUILD SUCCESS(8 模块全绿,含 ArchUnit)
端口 8087 启动 正常(0.98s 起;无异常;mail 降级 bean 不阻塞);验证毕已 kill
8084 / 8085 未触碰(8084 为并行代理进程,全程保留)

二、移植面与替换类登记

2.1 文件服务(com.dsasp.server.file.* → platform-legacy-core)

文件 性质 与原版差异
service/FileServiceImpl.java 真实现,bean fileService sun.misc.BASE64Decoder→java.util.Base64;存储后端经替换类 FTPClientTemplate 走本地盘;其余原样
upload/FTPClientTemplate.java 替换类(§3.1) FTP 后端 → 本地盘;保包名/类名/对外签名 uploadFileAndZip/downloadFile/delete/fileExists;根目录 MainApp.destPath;resolveSafe 防 ../ 逃逸
util/ZipUtil.java 移植(瘦身) 仅保留 ZipFileToDest(原 ant zip 重载无调用方,不移植)
util/FileUtil.java 移植(瘦身) 去 javax.swing.FileSystemView 依赖的 getFileType/sortFiles(无调用方)
util/HashCalc.java 移植 commons-codec DigestUtils → JDK MessageDigest,十六进制摘要逐字节一致
util/HashEnum.java / util/SysUtil.java 原样移植 ——
common/util/MainApp.java 配置持有者 原版写死 Windows 路径 → 跨平台默认 ./data/files + setter(现代层注入)

替换类策略落地(§3.1「旧代码零感知」):FileServiceImpl / ZipUtil 对 FTPClientTemplate 的调用一行未改,仅 FTPClientTemplate 内部从 commons-net FTP 客户端换成本地盘读写。本地盘根目录经 eip4.file.root(application.yml,env EIP4_FILE_ROOT 覆盖,默认 ./data/files)由 LegacyXmlWiring 单向写入 MainApp.destPath——保真层不反向依赖现代层(ArchUnit 约束)。

2.2 日志服务(com.dsasp.server.log.* + common/log/service/DataLogRecorder → platform-legacy-core)

原样移植 6 个 impl/调度 + 补 1 个接口:SystemLogManagerImpl(bean systemLogManager)、DataOperatorLogger(bean dataOperatorLog)、DataLogRecorderImpl(bean dataLogRecorder)、DataLogManager(异步调度,Timer 1s/30s)、ProcessLogThread、ProcessSysLogThread、DataLogRecorder(接口)。

落库语义与老系统一致:

  • SYS_LOG:SYS_LOG_ID,TYPE,CONTENT,createtime(joda 毫秒),createby=操作人,updatetime,updateby,isactive=1,version=0。
  • SYS_DATA_LOG:sys_data_log_id,tablename,recordid,mainrecordid,type,updatetime,updateby。
  • SYS_DATA_LOGITEM:sys_data_logitem_id,sys_datalogid,oldvalue,newvalue,columnname —— insert-only,无 UPDATETIME 列(§5.1),实现只走纯 INSERT,符合。

2.3 消息服务(com.dsasp.server.mail.* + common/email/* → platform-legacy-core)

SystemEmailService(接口)+ SystemEmail(bean)原样移植;SystemEmailServiceImpl(bean systemEmailService)降级装配:SMTP 发件人配置(SysConfig 键 com.dsasp.server.mail.admin_mail)缺省时仅打 WARN 后 no-op,不抛、不阻塞启动。原版深度依赖 javax.mail + freemarker + OSGi ConfigUtil + 活的 SMTP,真实投递留口待 JavaMailSender 装配后接通(详见 §5.38)。ClientMailService(POP3/IMAP 全客户端)非「横切消息」范畴且无调用方,本次不移植。

2.4 XML 等价装配补齐(§4.1)

platform-app/.../config/LegacyXmlWiring.java 新增三处 setter 注入(等价原 framework service.xml <property>):

fileService.setJdbcTemplate(jdbcTemplate);
systemLogManagerImpl.setJdbcTemplate(jdbcTemplate);
dataLogRecorder.setJdbcTemplate(jdbcTemplate);
MainApp.setDestPath(fileRoot);   // eip4.file.root 注入

三、实测证据

3.1 文件:上传 → 下载字节一致 → 删除(本地盘)

LocalFileStorageTest + XServiceLocalIT#file_upload_download_roundtrip(经容器内真实替换类 FTPClientTemplate):

  • 写入二进制载荷 → uploadFileAndZip 落 destPath/SYS_DOC/0/itest.zip → fileExists=true;
  • downloadFile 解压回字节 → assertArrayEquals(原始, 下载) 通过(byte 一致);
  • delete → fileExists=false。
  • 路径安全:fileExists("../../etc/passwd") / downloadFile("/a/../../../escape.zip",…) → 抛 IOException + WARN「拒绝越界附件路径(疑似 ../ 逃逸)」(运行日志已见)。

3.2 日志:CRUD → SYS_LOG / 数据日志表落行,字段语义对

XServiceLocalIT(local profile,本地 eip4m0,经容器内真实 bean):

  • systemLogManager.log(List) → SYS_LOG 落行,断言 type='Info'、content 原值、createby/updateby='tester-001'(操作人)、isactive=1、version=0、createtime>0(joda 毫秒)→ 通过;
  • dataLogRecorder.recorderLogs(List) → SYS_DATA_LOG + SYS_DATA_LOGITEM 落行,断言主表 tablename/recordid/type/updateby、明细 columnname='NAME'/newvalue='集成测试客户'/oldvalue=null → 通过。
  • 实库残留行(运行后 psql 直查):
    sys_data_log:      EIP4PT_CUSTOMER | rec-itest | type=1 | tester-002
    sys_data_logitem:  NAME | 集成测试客户
    

3.3 消息:配置缺省降级路径(启动无异常、调用打 WARN 不抛)

  • 8087 启动日志:Started Eip4PlatformApplication in 0.981 seconds,无任何 mail 相关异常(降级 bean 装配成功,满足「不阻塞启动」);
  • SystemEmailServiceImplTest + XServiceLocalIT#mail_degrades_without_config:sendEmail 在无配置时打 WARN 后 no-op,assertDoesNotThrow 通过;运行日志见: WARN ... 邮件服务未配置发件人(com.dsasp.server.mail.admin_mail),降级为 no-op:主题=[...] 收件人=[...]。

3.4 自举脚本

新增 platform-parity/src/main/resources/bootstrap/bootstrap-xservice.sql:幂等建 SYS_DOC / SYS_LOG / SYS_DATA_LOG / SYS_DATA_LOGITEM(后者 insert-only 无审计列)+ 种 LOGLEVEL='Errors,Info,Debug,Warnings'。

3.5 单测清单(16,全绿)

测试类 数 覆盖
LocalFileStorageTest 4 上传下载字节一致 / ../ 逃逸防护 / 删除 / 缺失下载抛错
HashAndFileUtilTest 3 MD5 标准向量 / 文件名扩展名解析 / 路径分隔归一
SystemLogManagerImplTest 2 SYS_LOG 列绑定语义(mock JdbcTemplate)/ deleteByType
DataLogRecorderImplTest 1 SYS_DATA_LOG + LOGITEM 列绑定 + insert-only(无 updatetime)
SystemEmailServiceImplTest 2 降级 no-op 不抛 / null 安全
XServiceLocalIT(集成,本地 DB) 4 系统日志落库 / 数据日志落库 / 附件本地盘往返 / 邮件降级

3.6 全模块测试 + ArchUnit

mvn -o clean test → BUILD SUCCESS,8 模块全绿;ArchitectureRulesTest(com.dsasp.. 不得依赖 com.eip4..)通过——三块真实现仅引 com.dsasp + JDK + spring + slf4j,无反向依赖。

备注:一次非 clean 增量 reactor 运行曾出现 ArchUnit 瞬时 FAILURE,经隔离重跑 + clean test 确认为陈旧编译产物(install -DskipTests 先于 parity 新 SQL 上 classpath)所致,非真实违例;clean 全量稳定绿。


四、StubProjectSwitchService 侦察结论(保留,不接管)

StubProjectSwitchService implements com.dsasp.server.common.viewframework.service.ProjectSwitchService,属 viewframework 域(项目上下文切换),不在本任务「文件/日志/消息」范畴。侦察 framework 未见对应的独立横切 impl bundle(file/log/mail 三 bundle 均不含),其真实现归属 viewFramework 域;P2-3 计划未列此项。故按任务约定保留该桩,待 viewFramework 域专项移植时接管。已在 docs/迁移手册.md §3.2 标注。


五、坑列表(已入 docs/迁移手册.md)

编号 坑
§5.36 附件 FileService 原版后端=FTP(非本地盘);本地盘默认须经替换类落地;旧依赖 sun.misc.BASE64Decoder/ant zip/swing 在 JDK17 不可用
§5.37 系统/数据日志为异步队列+定时批量落库;bean 名 systemLogManager/dataOperatorLog/dataLogRecorder 三件齐;jdbcTemplate 须 XML 等价 setter 补齐;LOGLEVEL 未配置=整链静默;数据日志仅 ischangelog=1 实体才记
§5.38 邮件 SystemEmailServiceImpl 深度依赖外部 SMTP(javax.mail+freemarker+OSGi ConfigUtil),按「配置缺省降级 no-op + WARN」装配,不阻塞启动;ClientMailService(POP3/IMAP)非横切范畴不移植
§3.1 新增行 FTPClientTemplate 替换类(FTP 后端→本地盘)登记

六、变更文件清单

保真层(platform-legacy-core,com.dsasp. 原样移植)*:

  • com/dsasp/server/common/util/MainApp.java
  • com/dsasp/server/file/service/FileServiceImpl.java、file/upload/FTPClientTemplate.java、file/util/{ZipUtil,FileUtil,HashCalc,HashEnum,SysUtil}.java
  • com/dsasp/server/common/log/service/DataLogRecorder.java
  • com/dsasp/server/log/service/{SystemLogManagerImpl,DataOperatorLogger,DataLogManager,DataLogRecorderImpl,ProcessLogThread,ProcessSysLogThread}.java
  • com/dsasp/server/common/email/bean/SystemEmail.java、common/email/service/SystemEmailService.java、mail/service/SystemEmailServiceImpl.java
  • 测试:file/{LocalFileStorageTest,HashAndFileUtilTest}.java、log/{SystemLogManagerImplTest,DataLogRecorderImplTest}.java、mail/SystemEmailServiceImplTest.java

现代层 / 配置 / 自举:

  • platform-app/.../config/LegacyXmlWiring.java(新增三处 setter + 文件根注入)
  • platform-app/src/main/resources/application.yml(eip4.file.root)
  • platform-app/.../app/XServiceLocalIT.java(本地 DB 集成测试)
  • platform-parity/src/main/resources/bootstrap/bootstrap-xservice.sql(横切表自举)

删除:platform-auth/.../stub/{StubFileService,StubSystemLogManager,StubDataOperatorLog}.java

文档:docs/迁移手册.md(§3.1 / §3.2 / §5.36-5.38)、本报告