🚀 TTD 智能决策引擎资源设计文档
版本：1.0 | 最后更新：TTD 智能决策引擎团队
📌 一、概述
TTD智能决策引擎的资源模型是整个系统的核心基础。引擎通过结构化的资源定义，实现了：
- ✅ 决策流程的可配置化
- ✅ 规则的可编排、复用
- ✅ 特征的批量开发、管理、更新
- ✅ 特征结果可溯源
- ✅ 规则执行可追溯
本文档详细阐述引擎的九大资源类型、资源继承体系、字段设计及应用场景。
🧱 二、资源基础架构
2.1 资源基类（BaseResource）
所有引擎资源均继承自 BaseResource 基类，提供统一的资源元数据管理：
| 字段名 | 类型 | 说明 | 用途 |
|---|---|---|---|
resourceKey |
String | 资源唯一标识键 | 缓存索引、快速检索、资源关联 |
resourceName |
String | 资源名称 | 展示识别、业务语义 |
resourceType |
ResourceTypeEnum | 资源类型枚举 | 资源分类、类型判断 |
version |
String | 资源版本号 | 版本管理、灰度发布、回滚 |
projectId |
Long | 所属项目ID | 项目级隔离、权限控制 |
tenantId |
String | 租户ID | 多租户隔离、数据权限 |
✨ 设计优势
统一的资源标识体系，便于全局索引；版本控制支持热更新和回滚；多租户、多项目架构的天然支持；类型安全的枚举管理。
🧩 三、九大资源类型详解
🔹 3.1 元字段（MetaField）
元字段是引擎的基础数据单元，用于定义和计算基础字段值。
| 字段名 | 类型 | 说明 | 示例 |
|---|---|---|---|
language |
String | 脚本语言类型 | "aviator", "groovy" |
script |
String | 计算脚本 | "user.age >= 18" |
returnType |
ObjectTypeEnum | 返回值类型 | BOOLEAN, STRING, NUMBER |
defaultValue |
String | 默认值 | "0", "unknown" |
exceptionValue |
String | 异常值 | "ERROR", "-1" |
应用场景
vbnet
// 基础数据转换
script: "Math.floor((System.currentTimeMillis() - user.birthday) / 31536000000)"
returnType: NUMBER
// 数据校验
script: "user.phone =~ /^1[3-9]\d{9}$/"
returnType: BOOLEAN💡 设计要点
支持多语言脚本引擎（Aviator、Groovy等）；返回值类型强类型校验；异常处理机制（返回exceptionValue）；默认值兜底。
🔹 3.2 特征配置（FeatureConfig）
特征配置是引擎的核心计算单元，支持时间窗口、聚合计算等高级特性。
| 字段名 | 类型 | 说明 | 示例 |
|---|---|---|---|
featureCode |
String | 特征编码 | "user_login_count_7d" |
conditionScript |
String | 条件脚本 | "event.type == 'LOGIN'" |
mainDimScript |
String | 主维度脚本 | "user.id" |
aggregateMode |
String | 聚合函数 | SUM, COUNT, AVG, MIN, MAX |
timeMode |
String | 时间模式 | TTL, DAY, MONTH, YEAR |
timeWindow |
Integer | 时间窗口大小 | 7 |
聚合模式说明： SUM(求和), COUNT(去重计数), AVG(平均值), MIN(最小值), MAX(最大值)
vbnet
// 用户7天登录次数
featureCode: "user_login_count_7d"
conditionScript: "event.type == 'LOGIN'"
mainDimScript: "user.id"
aggregateMode: "COUNT"
timeMode: "TTL"
timeWindow: 7💡 设计要点
支持多维度计算、灵活的时间窗口配置、丰富的聚合函数、依赖声明（依赖元字段）、双值类型支持（FIX/DYNAMIC）。
🔹 3.3 指标（Factor）
指标是基于元字段和特征配置计算得出的业务指标，支持超时控制和异常处理。
| 字段名 | 类型 | 说明 | 示例 |
|---|---|---|---|
factorType |
String | 指标类型 | META, DERIVATIVE, FEATURE |
returnType |
ObjectTypeEnum | 返回值类型 | NUMBER, STRING, BOOLEAN |
timeout |
Long | 超时时间(毫秒) | 3000 |
💡 设计要点
超时控制防止耗时过长；异常兜底；默认值处理；类型安全。
🔹 3.4 数据集（DataStruct）
数据集定义了结构化数据的Schema，用于规则计算的数据源。
css
dataStructType: "REQUEST"
fields: [
{ fieldCode: "user_id", fieldName: "用户ID", objectType: "STRING" },
{ fieldCode: "order_amount", fieldName: "订单金额", objectType: "NUMBER" }
]🔹 3.5 布尔规则（BooleanRule）
返回布尔值的判断规则。
vbnet
script: "user.age >= 18 && user.credit_score > 600"
language: "aviator"🔹 3.6 行动规则（ActionRule）
继承布尔规则，增加结论和行动码。
vbnet
conclusion: "REJECT"
actions: ["REJECT_ORDER", "ADD_BLACKLIST"]🔹 3.7 规则包（RulePackage）
规则包是行动规则的高级封装，支持多个子规则的合并和优先级排序。
| 字段名 | 说明 | 示例 |
|---|---|---|
mergePriority |
合并优先级映射 | {"REJECT":1, "REVIEW":2, "PASS":3} |
childRules |
子规则列表 | [rule1, rule2] |
defaultConclusion |
默认结论 | "PASS" |
⚖️ 合并优先级：数字越小优先级越高，例如 REJECT(1) > REVIEW(2) > PASS(3)。
🔹 3.8 决策表（DecisionTable）
表格形式的规则定义，适合多维度条件组合。
| 年龄段 | 信用分范围 | 风险等级 |
|---|---|---|
| 18-25 | <600 | HIGH |
| 18-25 | 600-700 | MEDIUM |
| 26-40 | >700 | VERY_LOW |
🔹 3.9 子流程（Decision）
定义了决策执行的流程拓扑结构，通过节点和连线组织规则执行顺序。
vbnet
decisionKey: "credit_decision_v1"
nodes: [START, WORK, BRANCH, END]
lines: [{source:"start", target:"node1", condition:""}]💡 设计要点
可视化流程编排，支持分支、合并，节点类型包括START/END/WORK/BRANCH，支持条件连线。
🌳 四、资源继承体系
scss
BaseResource (资源基类)
├── MetaField (元字段)
├── FeatureConfig (特征配置)
├── Factor (指标)
├── DataStruct (数据集)
├── BooleanRule (布尔规则)
│ └── ActionRule (行动规则)
│ └── RulePackage (规则包)
├── DecisionTable (决策表)
└── Decision (子流程) [独立]📦 五、资源聚合模型（EngineResource）
EngineResource 是部署单元的核心载体，聚合所有类型的资源，便于批量部署和资源关联。
🔗 六、资源依赖关系
部署时基础加载顺序：MetaField → FeatureConfig → Factor →DataStruct
部署时组件加载顺序：BooleanRule → ActionRule → RulePackage → DecisionTable → Decision。
⚠️ 避免循环依赖，使用 resourceKey 建立关联。
🗄️ 七、资源缓存架构
采用单例全局缓存 EngineResourceCache.INSTANCE 和独立不可变缓存类（MetaFieldCache, FeatureConfigCache等），由 Spring 管理的 ResourceCacheManager 提供原子更新和快照获取。
⚠️ 缓存策略，缓存所有资源时需要考虑极端场景，如决策执行过程中资源更新，由于基础资源都是对象引用，如果执行中发生资源变更，这将导致当前正在执行的 实例加载最新资源，从而影响决策执行结果。
♻️ 八、资源生命周期管理
- 创建：后台创建，校验完整性，分配唯一key和版本。
- 部署：打包为 DecisionDeployment，发送事件，缓存构建实例。
- 更新：热更新，新版本生效，旧请求继续使用旧版本。
- 下线：移除缓存，停止新请求，等待旧请求完成。
📐 九、资源设计规范
9.1 命名规范
| 资源类型 | 命名规则 | 示例 |
|---|---|---|
| MetaField | {subject}_{field} | user_age |
| FeatureConfig | {subject}{feature}{window} | user_login_count_7d |
| RulePackage | pkg_{scenario} | pkg_credit_assessment |
📝 九、总结
TTD智能决策引擎的资源模型具有以下核心优势：
- ✅ 类型丰富：9种资源类型覆盖决策场景的全部需求
- ✅ 层次清晰：继承体系明确，资源职责分明
- ✅ 灵活编排：支持流程化编排和规则组合
- ✅ 热更新：支持运行时动态更新，无需重启服务
- ✅ 高性能：全内存缓存，毫秒级资源访问
- ✅ 可扩展：易于扩展新的资源类型和字段
- ✅ 多租户：完善的租户、项目、版本隔离
- ✅ 可观测：完整的日志和监控体系
该资源模型为复杂业务场景下的实时决策提供了强大、灵活、高效的基础支撑。
📅 文档版本：1.0 | 🧑💻 最后更新：TTD 智能决策引擎团队