P4-6: platform-flow-gateway 待办→业务页映射(tablename→templateId→pageUrl)

- 侦察口径:sys_entity+view_templateentity+view_template 两步映射;
  多模板优先级 type=7(表单)>1(列表)>其余升序,同 type 按 templateid 字典序取首个
- 新建 PageTemplateService:findTemplateId() 查只读客户库,
  @Cacheable("pageTemplateByTable") Caffeine TTL=10min/maxSize=2000
- FlowGatewayConfig 启用 @EnableCaching + flowGatewayCacheManager(Caffeine)
- TodoItem 增加 pageTemplateId/pageUrl/pageUrlReason;
  查不到映射时 pageUrl=null+reason,前端据此禁用跳转(优雅降级)
- TodoAggregator 注入 PageTemplateService,aggregate 逐条 fillPageTemplate
- PageTemplateMappingTest 10 单测;TodoAggregatorTest 补 @Mock PageTemplateService
- 验证:真实用户(829cdcca)3 条待办带出 templateId=7042cb37(PM_SAFE_CLARIFICATION/安全技术交底),
  与客户库直查一致;全反应堆 31+ArchUnit 绿

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-06-11 16:52:50 +08:00
parent f563b472e6
commit ba6e7559fa
8 changed files with 498 additions and 4 deletions

View File

@@ -0,0 +1,111 @@
package com.eip4.platform.flowgateway.aggregate;
import java.util.Optional;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.cache.annotation.Cacheable;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Service;
/**
* 业务表名 → 前端页面模板 ID 映射服务。
*
* <p><b>映射口径(侦察客户库 view_templateentity + view_template + sys_entity 得出)</b>:
* <ol>
* <li>{@code tablename} → {@code sys_entity.sys_entity_id}(entityid)</li>
* <li>{@code entityid} → {@code view_templateentity.templateid}(经 {@code view_template.type} 优先级筛选)</li>
* </ol>
*
* <p><b>多模板优先级规则</b>(由 TemplateType 枚举语义 + 待办填写场景决定):
* <ul>
* <li>type=7(EDITFORM 表单模板)优先 —— 待办详情对应的填写/审批页面;</li>
* <li>type=1(GRID 列表模板)次之 —— 无专属表单时退回列表页;</li>
* <li>其余 type 按升序兜底(type=3/4/6 等功能模板);</li>
* <li>type=100(SELECTDIALOG)和 type=200(REPORT)语义与待办无关,但不排除(有表单/列表时自然被压后);</li>
* <li>同 type 有多条时按 templateid 字典序取首个(稳定可重复)。</li>
* </ul>
*
* <p><b>缓存</b>:模板关联是低频变更配置数据(设计时确定),用 Caffeine 缓存 {@code tablename→templateId}
* 映射结果,避免每次待办渲染都查只读客户库两张关联表。
* 缓存命名 {@code "pageTemplateByTable"},配置见 {@code FlowGatewayConfig}。
*
* <p><b>优雅降级</b>:任何数据库异常或找不到映射时返回 {@link Optional#empty()},不抛出,由调用方决定降级策略。
*
* <p><b>数据源只读</b>:全程只查 {@code sys_entity} + {@code view_templateentity} + {@code view_template},
* 不写任何表,对齐客户库只读约定。
*/
@Service
public class PageTemplateService {
private static final Logger log = LoggerFactory.getLogger(PageTemplateService.class);
/**
* 优先级映射:type → 排序权重(越小越优先)。
* type=7 (EDITFORM) 最优先;type=1 (GRID) 次之;其余按 type 值本身升序。
* 未在此表中的 type 用 {@code type + 1000} 作兜底权重。
*/
private static final String BEST_TEMPLATE_SQL = """
SELECT vte.templateid
FROM sys_entity se
JOIN view_templateentity vte ON vte.entityid = se.sys_entity_id
JOIN view_template vt ON vt.view_template_id = vte.templateid
WHERE UPPER(se.tablename) = UPPER(?)
ORDER BY
CASE vt.type
WHEN 7 THEN 0
WHEN 1 THEN 1
WHEN 3 THEN 2
WHEN 4 THEN 3
WHEN 6 THEN 4
WHEN 5 THEN 5
WHEN 100 THEN 6
WHEN 101 THEN 7
WHEN 200 THEN 8
ELSE vt.type + 1000
END,
vte.templateid
LIMIT 1
""";
private final JdbcTemplate jdbcTemplate;
public PageTemplateService(JdbcTemplate jdbcTemplate) {
this.jdbcTemplate = jdbcTemplate;
}
/**
* 按业务表名查对应的最优前端模板 ID。
*
* <p>结果被 Caffeine 缓存(key = tableName 原始值,不区分大小写 —— SQL 内已 UPPER 归一)。
* 缓存未命中时查只读客户库,任何异常返回 {@link Optional#empty()}。
*
* @param tableName 业务表名(如 {@code PM_PAYMENTAPPLY}),不区分大小写
* @return 最优 templateId;找不到或异常时为 {@link Optional#empty()}
*/
@Cacheable(cacheNames = "pageTemplateByTable", unless = "#result.isEmpty()")
public Optional<String> findTemplateId(String tableName) {
if (tableName == null || tableName.isBlank()) {
return Optional.empty();
}
try {
String id = jdbcTemplate.query(BEST_TEMPLATE_SQL,
rs -> rs.next() ? rs.getString(1) : null,
tableName);
return Optional.ofNullable(id);
} catch (RuntimeException e) {
log.debug("pageTemplate 映射查询降级(tableName={}): {}", tableName, e.getMessage());
return Optional.empty();
}
}
/**
* 按 templateId 构造前端页面 URL(路由形态 {@code /page/{templateId}})。
*
* @param templateId 非空 templateId
* @return {@code /page/<templateId>}
*/
public static String buildPageUrl(String templateId) {
return "/page/" + templateId;
}
}

View File

@@ -2,6 +2,7 @@ package com.eip4.platform.flowgateway.aggregate;
import java.util.ArrayList;
import java.util.List;
import java.util.Optional;
import org.springframework.stereotype.Service;
@@ -15,21 +16,26 @@ import com.eip4.platform.flowgateway.client.FlowableClient;
* <ul>
* <li>当前用户待办——按 assignee + 候选组(JWT roles)聚合;</li>
* <li>逐条经 {@link BusinessSummaryService} 拼业务摘要(businessKey → 业务表标题字段);</li>
* <li>拼不到摘要时优雅降级为仅流程字段(由 BusinessSummaryService 内部兜底)。</li>
* <li>逐条经 {@link PageTemplateService} 填充前端页面模板(businessTable → templateId → pageUrl);</li>
* <li>拼不到摘要/模板时优雅降级(pageUrl=null + pageUrlReason 说明原因),不拖垮整张列表。</li>
* </ul>
*
* <p>引擎不可达由 {@link FlowableClient} 抛 {@code FlowServiceUnavailableException}(→ 503),
* 本层不吞;但业务摘要侧缺数据一律降级,不影响流程字段返回。
* 本层不吞;但业务摘要/模板侧缺数据一律降级,不影响流程字段返回。
*/
@Service
public class TodoAggregator {
private final FlowableClient flowableClient;
private final BusinessSummaryService businessSummaryService;
private final PageTemplateService pageTemplateService;
public TodoAggregator(FlowableClient flowableClient, BusinessSummaryService businessSummaryService) {
public TodoAggregator(FlowableClient flowableClient,
BusinessSummaryService businessSummaryService,
PageTemplateService pageTemplateService) {
this.flowableClient = flowableClient;
this.businessSummaryService = businessSummaryService;
this.pageTemplateService = pageTemplateService;
}
/**
@@ -49,7 +55,7 @@ public class TodoAggregator {
return aggregate(tasks);
}
/** 逐条拼业务摘要(摘要侧异常已在 BusinessSummaryService 内降级,不在此抛出)。 */
/** 逐条拼业务摘要 + 页面模板(异常已在各 Service 内降级,不在此抛出)。 */
private List<TodoItem> aggregate(List<FlowTaskDto> tasks) {
List<TodoItem> items = new ArrayList<>(tasks == null ? 0 : tasks.size());
if (tasks == null) {
@@ -60,8 +66,28 @@ public class TodoAggregator {
BusinessSummaryService.Summary summary = businessSummaryService.summarize(t.businessKey);
item.businessTable = summary.tableName();
item.businessSummary = summary.fields();
fillPageTemplate(item);
items.add(item);
}
return items;
}
/**
* 填充 pageTemplateId / pageUrl / pageUrlReason。
* 依赖链:businessTable(已由业务摘要层填充) → templateId → pageUrl。
* 任何环节缺失时 pageUrl=null 并写入 reason,前端据此禁用跳转。
*/
private void fillPageTemplate(TodoItem item) {
if (item.businessTable == null) {
item.pageUrlReason = "businessTable 未映射,无法定位模板";
return;
}
Optional<String> templateId = pageTemplateService.findTemplateId(item.businessTable);
if (templateId.isEmpty()) {
item.pageUrlReason = "sys_entity/view_templateentity 中找不到表 " + item.businessTable + " 对应的模板";
return;
}
item.pageTemplateId = templateId.get();
item.pageUrl = PageTemplateService.buildPageUrl(item.pageTemplateId);
}
}

View File

@@ -34,6 +34,22 @@ public class TodoItem {
/** 业务摘要标题字段(loadPOJO 只读取的标题类字段)。拼不到时为空 Map(降级)。 */
public Map<String, Object> businessSummary = Map.of();
/**
* 前端页面模板 ID(经 sys_entity + view_templateentity + view_template 映射,type=7 表单优先)。
* 查不到映射时为 null(前端根据 pageUrlReason 决定是否禁用跳转)。
*/
public String pageTemplateId;
/**
* 前端页面 URL,形态 {@code /page/{templateId}}。
* 查不到时为 null,前端应禁用跳转按钮。
*/
public String pageUrl;
/**
* 当 {@code pageUrl} 为 null 时,说明查不到映射的原因(优雅降级辅助信息)。
* pageUrl 不为 null 时此字段为 null。
*/
public String pageUrlReason;
static TodoItem fromTask(FlowTaskDto t) {
TodoItem item = new TodoItem();
item.taskId = t.id;

View File

@@ -1,23 +1,34 @@
package com.eip4.platform.flowgateway.client;
import java.time.Duration;
import java.util.List;
import java.util.concurrent.TimeUnit;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.boot.web.client.ClientHttpRequestFactories;
import org.springframework.boot.web.client.ClientHttpRequestFactorySettings;
import org.springframework.cache.CacheManager;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.cache.caffeine.CaffeineCacheManager;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.ClientHttpRequestFactory;
import org.springframework.web.client.RestClient;
import com.github.benmanes.caffeine.cache.Caffeine;
/**
* 流程网关客户端装配:把 {@link FlowGatewayProperties} 的基址/超时落到一个专用 {@code RestClient}。
*
* <p>用专属 bean 名 {@code flowRestClient},不与应用里可能存在的其他 {@code RestClient} 冲突;
* 超时经 {@link ClientHttpRequestFactorySettings} 落到请求工厂(JDK {@code SimpleClientHttpRequestFactory}),
* 引擎卡死时按 {@code read-timeout} 抛 {@code SocketTimeoutException} → {@code FlowableClient} 走熔断降级。
*
* <p>同时启用 {@link EnableCaching} 并注册 Caffeine 缓存管理器,供
* {@code PageTemplateService} 缓存 tablename→templateId 映射结果(模板关联低频变更,10 分钟 TTL)。
*/
@Configuration
@EnableCaching
@EnableConfigurationProperties(FlowGatewayProperties.class)
public class FlowGatewayConfig {
@@ -36,4 +47,18 @@ public class FlowGatewayConfig {
.requestFactory(flowRequestFactory)
.build();
}
/**
* Caffeine 缓存管理器:{@code pageTemplateByTable} 缓存 tablename→templateId 映射。
* TTL 10 分钟(模板关联是设计时低频配置,无需实时刷新);最大 2000 条(实体总量约 1500,留余量)。
*/
@Bean
CacheManager flowGatewayCacheManager() {
CaffeineCacheManager mgr = new CaffeineCacheManager();
mgr.setCacheNames(List.of("pageTemplateByTable"));
mgr.setCaffeine(Caffeine.newBuilder()
.expireAfterWrite(10, TimeUnit.MINUTES)
.maximumSize(2000));
return mgr;
}
}