双人文化关系应用如何管理两套资料：输入校验、响应模式与使用边界-编程实验室

双人文化关系应用如何管理两套资料，关键不是完成一次调用，而是让输入口径、处理状态和结果证据可以复核。本文围绕“如何管理双方出生资料、重点方向、同步异步响应和文化娱乐使用边界”给出一套面向真实业务流程的实现方式。

问题与结果

双方资料独立校验和版本化，基础历法数据与文化解读分层，输出明确标注娱乐参考属性。

适用场景

双人关系文化内容产品
互动报告和历史记录
多语言文化内容展示

实现前先确定边界

双方资料必须分别校验，不能用一方默认值补另一方
关注方向必须限制数量并记录版本
同步、异步和 SSE 是交付模式，不改变同一业务结果

可验证工作流

API 编排与职责

步骤	接口	请求方式	用途
生成关系洞察	八字关系合参	POST	校验双方资料并返回关系主题文化解读
查询异步任务	异步任务状态查询	GET	任务模式下查询最终结果

接口地址：

POST https://api.gugudata.com/ai/bazi-relationship-insight

appkey可通过 Query、X-GUGUDATA-APPKEY、Bearer 或 JSON Body 传入。双方资料和focusAreas使用完整 JSON Body，不要将嵌套对象展开成 Query 参数。

最小可运行实现

curl -X POST \ "https://api.gugudata.com/ai/bazi-relationship-insight?appkey=YOUR_APPKEY&responseMode=sync&streaming=false" \ -H "Content-Type: application/json" \ -d '{ "personA": { "gender": "男", "calendarType": "公历", "birthDate": "1990-12-01", "birthTime": "07:30:00", "birthPlace": "浙江杭州", "isLeapMonth": false, "language": "zh-CN" }, "personB": { "gender": "女", "calendarType": "农历", "birthDate": "1992-05-15", "birthTime": "09:20:00", "birthPlace": "江苏苏州", "isLeapMonth": false, "language": "zh-CN" }, "focusAreas": ["沟通方式", "价值观", "长期相处"] }'

服务端可以先构造明确的双人请求：

def build_relationship_payload(person_a: dict, person_b: dict) -> dict: """Build a relationship insight request without mixing profiles.""" return { "personA": dict(person_a), "personB": dict(person_b), "focusAreas": ["沟通方式", "价值观", "长期相处"], }

不要在这个函数里交换、合并或推断双方字段。性别、历法、日期、时间、地点和闰月状态都应保持各自来源。

双方language必须一致；它决定文化解读语言，JSON 字段名保持中文。农历输入必须按实际月份设置isLeapMonth。公历输入设置闰月、不存在的农历闰月、越界日期和非法时间都会返回参数错误，调用方不应自行猜测或降级为公历。若页面还需要展示独立的日期与节气事实，可调用传统历法宜忌参考，但不要把另一接口的结果混入关系洞察原始响应。

三种响应模式怎么选择

模式	参数	适用场景
同步 JSON	`responseMode=sync&streaming=false`	服务端调用、结果较短、需要一次性保存
异步任务	`responseMode=task&streaming=false`	后台生成报告、批量任务、可轮询
SSE 流式	`responseMode=sync&streaming=true`	前台逐步展示内容

任务模式与流式模式不能同时启用。异步模式返回operationId后，应使用创建任务的同一 APPKEY 轮询任务接口；SSE 模式只有收到包含完整结果的done.result才能记为成功。error事件或断流不能沿用上一次结果。

结果怎么组织

结果应分为三层：

层级	内容
基础数据	双方出生资料、历法换算、四柱、八字和关注方向
文化解读	关系摘要、互补特点、沟通建议、长期相处建议和注意事项
使用边界	传统文化研究与娱乐参考说明

基础数据用于确认输入和双方排盘是否正确，文化解读用于内容展示，两者不能混成一个不可追踪的长文本。产品侧不应额外生成无法解释的匹配分数、确定性婚姻结论或新的排盘事实。

失败分类与降级

任何一方缺少gender、calendarType、birthDate或birthTime，都应在调用前提示。农历日期需要正确设置isLeapMonth，不能在接口失败后由前端猜测。

用户修改任一方资料后，旧结果必须标记为过期。任务模式失败时保留必要的失败状态，但不要继续显示上一份结果为“当前结果”。建议按 HTTP 和业务码分开处理：501/400用于参数错误，504/401用于 APPKEY 缺失或无效，901/503用于解读或依赖不可用。

数据契约与留痕

字段	作用
`request_id`	稳定业务标识，用于关联记录和请求追踪
`person_a_version`	输入、规则或产物版本，变更时保留旧版本
`person_b_version`	输入、规则或产物版本，变更时保留旧版本
`focus_topics`	业务数据字段，保存来源、口径和缺失状态
`response_mode`	业务数据字段，保存来源、口径和缺失状态
`result_version`	输入、规则或产物版本，变更时保留旧版本
`generated_at`	带时区的采样或生成时间
`boundary_notice`	业务数据字段，保存来源、口径和缺失状态