把 Startlux-Decision 接入前，真正容易返工的不是模型本身，而是三件事没说清：同一个决策字段在业务、算法、工程里叫什么，调用时最小输入长什么样，输出里的结论、依据和阈值各自代表什么。只要先统一字段契约和阈值口径，联调时大部分争议都能在日志和配置层面被定位，而不是靠口头解释。判断方向是：字段字典先落地，最小输入契约再固化，输出解释模板和阈值审批收口，最后用少量用例验收。
适用场景：多个系统共同调用 Startlux-Decision，或业务、算法、工程对同一字段理解不一致。操作动作：先建字段映射表，再定最小输入 JSON 契约，然后对齐输出解释字段与阈值，设四类联调用例，最后记录变更与审批。验证方式：用 schema 校验或启动报错检查输入，用联调用例比对输出结论和依据。风险边界：阈值和字段最终要以实际配置、日志和页面行为为准，本文只给通用骨架，不替代具体环境确认。
收集各系统对同一决策字段的叫法
联调时最耗时的往往是“同一个字段在不同系统里叫不同名字”。例如业务侧说“用户等级”，上游接口里可能叫 user_level、member_tier、vip_grade；单位也可能是等级数值、等级名称或区间编号。先把这些叫法拉平，后面传参和取数才不会互相甩锅。
建议用一张字段映射表当唯一口径，至少包含来源字段、含义、类型、单位、缺失规则。缺失规则要明确：是空字符串、null、默认值还是直接拒绝请求。不要用“没传就是没有”这种含糊说法。
- 来源字段：user_level / member_tier / vip_grade
- 含义：用户在业务体系中的等级标签
- 类型：integer
- 单位：等级编号（例如 0 表示未分级）
- 缺失规则：缺失时按未分级处理，或按调用方约定拒绝请求
单位差异要单独标出来。金额字段常见分/元混用，时间字段常见秒和毫秒混用，比率字段常见 0-1 和 0-100 混用。字段映射表里不写清，输入契约再规范也会在联调时出错。缺失值口径建议区分“字段不存在”和“字段存在但值为空”，这两者在后续决策里通常对应不同处理。
定义 Startlux-Decision 的最小输入 JSON 契约
输入契约的目标不是字段越多越好，而是让调用方按同一结构传参，并且能被执行链路校验。建议先定最小输入 JSON 骨架，必填字段只保留决策必须依赖的部分，其余标为可选，避免调用方随便塞字段导致解释困难。
{
"request_id": "string, 必填, 调用方唯一请求标识",
"scene": "string, 必填, 决策场景编码",
"subject": {
"subject_id": "string, 必填, 主体标识",
"subject_type": "string, 必填, 主体类型"
},
"features": {
"user_level": "integer, 可选, 等级编号",
"region_code": "string, 可选, 地区编码",
"amount": "number, 可选, 金额，单位元",
"event_time": "string, 可选, 时间，统一为 ISO 8601 或毫秒时间戳"
},
"options": {
"explain": "boolean, 可选, 是否返回解释字段",
"threshold_profile": "string, 可选, 阈值配置档位"
}
}验证方式可以先用 JSON Schema 做静态校验，字段缺失、类型不符、单位越界都在进入决策逻辑前拦掉；如果服务启动时会加载契约配置，也可以让启动报错暴露契约问题，而不是等运行时才发现。需要结合环境确认的是：schema 放在调用方还是服务端，二者都做校验通常更稳，但会增加维护成本。
对齐输出解释字段与业务阈值
输出不统一，业务和工程就会各看各的。建议把输出拆成结论、依据、置信信息、阈值四类。这里不声称 Startlux-Decision 的官方字段名，不同部署和配置下字段可能不同，以下是通用占位，实际名称以日志和接口返回为准。
- 结论字段：decision_result，表示最终判定或分档结果
- 依据字段：reason_codes，表示命中的规则或因子列表
- 置信信息字段：confidence_info，置信区间、样本量或模型侧参考值占位
- 阈值字段：threshold_used，表示本次决策实际生效的阈值及档位
阈值必须和结论一起返回，业务才能理解“为什么这次是这个结果”。阈值口径要区分业务约定阈值和系统生效阈值，两者不一致时以实际生效值为准，并记录在输出里。置信信息不要被当成保证，它只是辅助判断，业务侧需要结合场景决定是否参考。
设定联调验收用例
不要等全量数据跑通再验收，先用少量可验证样本检查契约是否成立。建议至少覆盖正常、缺失、超范围、多候选四类，每类都写清预期结果，并用日志或接口返回比对。
- 正常用例：必填字段齐全、可选字段合法，预期返回结论和依据，尽量带阈值。
- 缺失用例：缺少可选字段或必填空值，预期按缺失规则处理，或明确拒绝并给出错误码。
- 超范围用例：金额为负、等级超出定义区间、时间格式错误，预期被校验拦下，不进入决策逻辑。
- 多候选用例：多个规则或因子同时命中，预期依据字段能列出命中项，结论可解释。
验收时把 request_id 和日志关联起来，方便定位是输入问题、阈值问题还是解释字段问题。如果同一用例在不同环境结论不同，先检查 threshold_profile 和生效阈值，而不是直接改代码。
记录字段变更和阈值审批方式
上线后随手改字段名或阈值，是联调返工和线上争议的常见来源。建议用变更记录模板收口，至少写清变更内容、原因、影响范围、生效版本和回滚方式。
- 变更记录模板：字段名、旧值、新值、变更原因、影响调用方、生效版本占位、验证方式
- 审批人角色：业务负责人确认口径，算法或规则负责人确认阈值，工程负责人确认兼容性
- 生效版本占位：用配置版本号或发布批次号标识，不要只靠口头通知
- 回滚方式：保留上一版配置或契约，出现问题时按版本回退，并记录回滚原因
阈值审批要特别小心：同一档位的阈值调整，可能让历史结论看起来不一致，所以变更记录里要写清生效时间点和适用范围。字段变更则要评估调用方是否同步，必要时先并行新旧字段，确认无遗漏再下线旧字段。