forge_admin/code-copilot/changes/framework-controller-boundary-hardening/test-spec.md

测试 Spec — Controller 边界与查询规范整改

status: apply created: 2026-07-27

1. 测试原则

• 按模块增量执行，不重跑无关全量 E2E。
• Mapper XML 下沉要验证条件、排序、分页和删除语义，不仅验证编译。
• 不连接真实数据库，不执行流程数据清理。

2. P0 范围

场景	预期
仅 pageNum	三个端点使用该页码
仅旧 page	兼容且页码不变
两者同时传入	旧 page 优先，与 FlowFormController 一致
Controller 业务校验	抛 BusinessException，不存在裸 RuntimeException
Excel 底层异常	日志有堆栈，响应只包含稳定错误文案
AI 默认项切换	清理和设置在单个事务内
流程 Forge 记录清理	2 类逻辑删除，5 类显式物理删除

3. P1 静态合同

• 14 个基线 Controller 不再 import/构造 Query/Update Wrapper，不再调用 Service lambdaQuery/lambdaUpdate。
• Controller 不直接注入 Mapper。
• 自定义查询和更新均有 Mapper XML 对应语句。
• Mapper XML 通过 xmllint --noout。
• rg -n 'throw new RuntimeException' forge-server --glob '*Controller.java' 无输出。

4. 模块验证

批次	必跑
Task 1	System/Flow/Excel 相关模块 compile/package，静态协议检查
Task 2	System Reactor package + 目标测试
Task 3	AI Reactor package + 目标测试
Task 4	Generator Reactor package + 目标测试
Task 5	Data/Message Reactor package + 目标测试
Task 6	Flow Server package + 查询/清理合同测试
Task 7	聚合静态扫描、git diff --check、两阶段审查

5. 跳过项

• 真实 MySQL 的 Mapper SQL 执行：本地不修改真实数据库。
• 真实 Flowable 删除 E2E：属于不可逆管理操作，仅做代码/合同验证。
• 全量前端构建：本变更默认不修改前端；如产生前端差异则升级为必跑。

6. 执行证据

所有命令、结果、警告、跳过原因和服务清理情况追加到 execution-log.md。

7. 本轮增量验证（Task 4）

• Generator 四个目标 Controller 的 Wrapper、lambda* 和 Mapper 直连扫描。
• Generator 四份新增/修改 Mapper XML 的 xmllint 解析。
• Generator Reactor package -DskipTests，覆盖接口、实现和 Mapper 装配的编译合同。
• 真实数据库分页、用途范围筛选和字段重置 SQL 留待集成环境验证。

8. 本轮增量验证（Task 5）

• Data/Message 两个目标 Controller 和对应 Service 的 Wrapper/lambda* 扫描。
• DataDatasetMapper.xml、SysMessageBizTypeMapper.xml 的 xmllint 解析。
• Data/Message Reactor package -DskipTests。
• 真实数据库租户隔离、逻辑删除和分页 SQL 留待集成环境验证。

9. 本轮增量验证（Task 6）

• 三个 Flow 目标 Controller 的 Wrapper 和 Mapper 直连扫描。
• 监控分页、详情、趋势、分布、错误统计和状态更新必须通过 FlowBusinessMapper.xml/FlowErrorLogMapper.xml。
• FlowControllerBoundaryContractTest 固化确认文本、无事务回滚承诺、2 类逻辑删除和 5 类物理删除合同。
• 七份 Flow Mapper XML 执行 xmllint --noout。
• Flow Server 依赖 Reactor package -DskipTests，并单独编译/执行合同测试。
• 真实 MySQL 查询和不可逆 Flowable 清理仍留待受控集成环境验证。

10. 本轮增量验证（Spec Review 修复）

• FlowControllerBoundaryContractTest 增加 page/pageNum 四组合和流程分布首个非空标题合同。
• AsyncExportSecurityContractTest 固化异步任务公开副本、filePath 隐藏和稳定失败文案。
• Flow 子模块受本机 .m2 旧快照限制时，使用当前 Reactor target/classes 作为附加类路径编译并执行目标测试，不把环境失败写成通过。

11. 本轮增量验证（同步 Excel 导入泄露修复）

• ExcelImportSecurityContractTest 覆盖总体导入异常、监听器未知解析异常和内部错误报告路径序列化隐藏。
• SysUserImportSecurityContractTest 固化行级/总体稳定文案和完整异常日志合同。
• 新增安全合同测试不依赖 Mockito inline agent，避免本机 JDK attach 能力影响测试结论。
• Maven 必须启用 enable-tests profile；默认 forge.tests.skip=true 的命令只记录为跳过，不计入通过。

12. 本轮增量验证（Code Quality Review 修复）

• FlowControllerBoundaryContractTest 扩展到 9 条，新增逐实例事务、稳定失败文案和 Flow Service 不依赖 System Service 的合同。
• AiModelProviderConcurrencyContractTest 固化供应商行锁、模型行锁和多供应商确定性锁顺序，不依赖 Mockito inline agent。
• Flow 合同必须确认 Controller 全部系统异常分支不拼接 e.getMessage()；业务拒绝文案保持原有语义。
• 重新执行 Flow+AI 依赖 Reactor package -DskipTests，确认 SPI 适配器和 Mapper 锁查询可聚合装配。

13. 本轮增量验证（第二次 Code Quality Review 修复）

• FlowCleanupTransactionExecutorTest 使用无 Mockito 的记录型事务管理器验证三次执行均为 PROPAGATION_REQUIRES_NEW，成功独立提交、失败独立回滚。
• Flow 合同检查监控用户查询降级保留完整异常日志，且服务不再存在 catch (Exception ignored)。
• AI 并发合同验证更新/删除模型均先锁相关供应商，再锁模型并校验供应商快照。
• AI 并发合同验证供应商删除按“供应商行锁 → 关联模型计数 → 逻辑删除”在同一 Manager 事务中执行，Controller 不再做检查后删除。

14. 本轮增量验证（第三次 Code Quality Review 修复）

• FlowControllerBoundaryContractTest 增加批量清理候选查询稳定错误边界合同，内部日志保留完整堆栈，公开异常不拼接底层消息。
• FlowCleanupTransactionExecutorTest 增加已有外层事务场景，验证 REQUIRES_NEW 独立事务会挂起并恢复外层事务。
• AiModelProviderConcurrencyContractTest 增加默认供应商专用 Manager 路径、全量供应商升序行锁和通用保存忽略 isDefault 的合同。
• AiProviderMapper.xml 执行 xmllint --noout，并重新执行 Flow+AI 依赖 Reactor package -DskipTests。

15. 本轮增量验证（第四次 Code Quality Review 修复）

• FlowControllerBoundaryContractTest 扩展到 12 条，覆盖两个清理端点的专用权限、移除类级租户忽略、V1.0.55 资源合同和不自动授权。
• 清理候选必须由 selectBusinessesForCleanup(tenantId, ...) 返回，禁止再按 modelKey/status 扩大到未满足发起人和时间筛选的 Flowable 实例。
• 单条与逐实例清理均校验 processInstanceId + tenantId 归属；七张 Forge 表的物理/逻辑删除和无实例业务记录删除都显式带 tenant_id。
• AI 默认供应商合同要求 requireTenantId()，并将 tenantId 贯穿全量锁、清默认和设默认 Mapper XML。
• 新增 Flyway 只做静态防重复/权限边界检查；真实 MySQL 和不可逆 Flowable 清理仍为部署门禁。

16. 本轮增量验证（第五次 Code Quality Review 修复）

• FlowControllerBoundaryContractTest 扩展到 14 条，覆盖查询、管理、清理三级强权限，以及流程实例/任务在访问 Flowable 前的当前租户归属守卫。
• 精确截取七份 Mapper XML 的目标 statement，验证表单逻辑清理和业务/表单状态更新均显式使用 tenantId，避免整份 XML 搜索产生假阳性。
• V1.0.55 验证 API 权限标识唯一，已有监控菜单角色只回填查询 API，管理和不可逆清理权限不自动授权。
• 重新执行 FlowCleanupTransactionExecutorTest、七份 Flow Mapper XML 解析和 Flow Server 依赖 Reactor 构建；真实 MySQL/Flyway、权限角色矩阵和不可逆 Flowable 清理仍为部署门禁。

17. 本轮增量验证（第六次 Code Quality Review 修复）

• FlowControllerBoundaryContractTest 最终扩展到 18 条，覆盖错误日志查询/重试/解决的权限与租户边界、监控聚合显式租户参数、管理/清理事务行锁与统一锁顺序、PUT API 权限和迁移碰撞 UPDATE 清除。
• forge-plugin-flow 只执行目标模块编译；FlowBusinessMapper.xml、FlowErrorLogMapper.xml 执行 XML 解析，监控页只执行目标 ESLint。
• 按用户要求不重复运行已通过的全 Reactor 和前端生产构建；真实 MySQL/Flyway、角色矩阵、并发清理和不可逆 Flowable 清理继续作为部署门禁。