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>
This commit is contained in:
2026-06-11 14:06:31 +08:00
parent b6de637905
commit 6cc7b3fb61
31 changed files with 2400 additions and 153 deletions

View File

@@ -0,0 +1,151 @@
# 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)、本报告

View File

@@ -1,36 +0,0 @@
package com.eip4.platform.auth.stub;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
import com.dsasp.server.common.dataDic.bean.GeneralPOJO;
import com.dsasp.server.common.log.bean.DataLogItem;
import com.dsasp.server.common.log.service.DataOperatorLog;
/**
* WS1 桩:数据操作审计日志。原版写库记录字段级变更,PoC 降级为 slf4j。
*/
@Service("dataOperatorLog")
public class StubDataOperatorLog implements DataOperatorLog {
private static final Logger LOG = LoggerFactory.getLogger("eip3.datalog");
@Override
public DataLogItem insertData(GeneralPOJO po, String dataLogItemId, String mainDataLogItemId) {
LOG.debug("insert {} id={}", po.get_TableName(), po.get_ID());
return null;
}
@Override
public DataLogItem updateData(GeneralPOJO po, String dataLogItemId, String mainDataLogItemId) {
LOG.debug("update {} id={}", po.get_TableName(), po.get_ID());
return null;
}
@Override
public DataLogItem deleteData(GeneralPOJO po, String dataLogItemId, String mainDataLogItemId) {
LOG.debug("delete {} id={}", po.get_TableName(), po.get_ID());
return null;
}
}

View File

@@ -1,72 +0,0 @@
package com.eip4.platform.auth.stub;
import java.io.File;
import java.util.ArrayList;
import java.util.List;
import java.util.Properties;
import org.springframework.stereotype.Service;
import com.dsasp.server.common.dataDic.bean.GeneralPOJO;
import com.dsasp.server.common.file.service.FileService;
/**
* WS1 桩:附件服务。PoC 选定功能不含附件操作,全部 no-op;
* 接口签名原样保留,P2 阶段以 EIP3 真实现替换。
*/
@Service("fileService")
public class StubFileService implements FileService {
@Override
public String save(String tempFile, String fileName, int size, String tableName, String businessKey, Properties ctx) {
return null;
}
@Override
public void saveDoc(String relativePath, String fileName, int size, String tableName, String businessKey, Properties ctx) {
}
@Override
public File getDocFile(String relativePath, String fileName, boolean isZip) {
return null;
}
@Override
public void delete(List<String> fileIds, String userId) {
}
@Override
public void delete(String fileId, String userId) {
}
@Override
public void deleteAttatchmentByBusinessKey(String businessKey, String userId) {
}
@Override
public void deleteAttatchmentByBusinessKey(List<String> businessKeys, String userId) {
}
@Override
public void clearDeletedDocument() {
}
@Override
public void clearDumpFile() {
}
@Override
public List<GeneralPOJO> getDoc(List<String> businessKeys) {
return new ArrayList<>();
}
@Override
public String getPicPath(String tablename, String businesskey) {
return null;
}
@Override
public String saveDecoderBase64File(String base64Code, String userId, String tableName, Properties ctx) throws Exception {
return null;
}
}

View File

@@ -1,44 +0,0 @@
package com.eip4.platform.auth.stub;
import java.util.List;
import org.joda.time.DateTime;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
import com.dsasp.server.common.log.bean.SysLogItem;
import com.dsasp.server.common.log.service.SystemLogManager;
/**
* WS1 桩:系统日志。原版写库(操作日志审计),PoC 阶段降级为 slf4j 输出。
*/
@Service("systemLogManager")
public class StubSystemLogManager implements SystemLogManager {
private static final Logger LOG = LoggerFactory.getLogger("eip3.syslog");
@Override
public void log(LogType logType, String logContent) {
LOG.info("[{}] {}", logType, logContent);
}
@Override
public void deleteAll() {
}
@Override
public void deleteByType(String type) {
}
@Override
public void log(List<SysLogItem> items) {
if (items != null) {
items.forEach(i -> LOG.info("[batch] {}", i));
}
}
@Override
public void deleteByLoginTime(List<String> userIds, DateTime[] loginTimes) {
}
}