节气日历服务如何统一日期口径关键不是完成一次调用而是让输入口径、处理状态和结果证据可以复核。本文围绕“如何处理日期、时间、时区和节气边界并把历法事实与文化参考分开返回”给出一套面向真实业务流程的实现方式。问题与结果先计算可核对的日期与节气事实再生成文化参考两类数据拥有不同字段、版本和使用边界。适用场景节气和传统日历组件文化内容服务结合天气与日出日落的日程提示实现前先确定边界请求时间必须带时区默认时间也要显式记录午夜、子时和跨日边界使用统一规则版本天气与空气质量按独立采样时间展示可验证工作流API 编排与职责步骤接口请求方式用途查询历法与参考传统历法宜忌参考POST返回农历、干支、生肖、星座、节气、宜忌和文化参考查询异步任务异步任务状态查询GET月历预生成或后台批量任务接口地址POST https://api.gugudata.com/ai/traditional-calendar-guidance当前timezone固定支持Asia/Shanghai。date范围为 1901-01-01 至 2100-12-31time可选未传时按 12:00 计算。最小可运行实现curl -X POST \ https://api.gugudata.com/ai/traditional-calendar-guidance \ -H X-GUGUDATA-APPKEY: YOUR_APPKEY \ -H Content-Type: application/json \ -d { date: 2026-07-18, time: 12:00, timezone: Asia/Shanghai, language: zh-CN }应用侧应显式保存最终查询条件from dataclasses import dataclass dataclass(frozenTrue) class CalendarQuery: date: str time: str 12:00 timezone: str Asia/Shanghai language: str zh-CN def build_calendar_payload(query: CalendarQuery) - dict: Build an explicit traditional calendar request. return { date: query.date, time: query.time, timezone: query.timezone, language: query.language, }即使用户没有填写时间也建议应用侧把默认值 12:00 写入请求避免之后无法解释时柱为何如此。午夜与子时边界接口按北京时间民用日处理日期00:00 才切换公历、农历和日柱。23:00 至 00:59 都属于子时但 23:00 至 23:59 不会提前切换到次日。页面应同时显示输入日期、规范化时间和查询时辰不要只显示“子时”而隐藏实际日期。节气结果同时提供兼容的日期字段和精确日期时间。节气日前后的内容应以返回时间为准不能只比较日期字符串。基础数据与文化参考分层基础数据包括农历年月日和中文日期年、月、日、时干支生肖和星座当前节气、下一节气及日期宜、忌和其他传统历法字段。文化参考用于组织日程说明。页面应明确它属于传统文化研究与娱乐参考不应触发自动审批、排期、交易、医疗或其他现实决策。月历预生成生成整月内容时不建议前端同时发起几十个同步请求。可以由后台为目标月份创建每日任务。固定时区和默认时刻。使用异步任务模式或有界并发并通过 Header 查询任务状态。保存每一天的独立状态。只重试失败日期。月历读取已完成结果并显示缺失状态。某一天失败不能让整月任务只返回一个模糊的失败结果。失败分类与降级日期必须使用YYYY-MM-DD时间使用HH:mm或HH:mm:ss。传入其他时区时当前应直接提示不支持而不是悄悄改成北京时间。用户切换时间后与时柱和时辰相关的旧结果必须失效。批量月历任务发生部分失败时页面显示缺失日期并允许后台重试不能复制相邻日期内容填补。同步响应在Data返回完整结果任务模式先返回operationId成功后由任务查询的Data.result返回完整结果SSE 依次发送metadata、content和包含完整结果的done.result最后发送结束事件。任务失败、流式断开或业务码 901 都不能当作成功内容保存。数据契约与留痕字段作用calendar_date带时区的采样或生成时间local_time带时区的采样或生成时间timezone业务数据字段保存来源、口径和缺失状态rule_version输入、规则或产物版本变更时保留旧版本calendar_facts业务数据字段保存来源、口径和缺失状态cultural_reference业务数据字段保存来源、口径和缺失状态cache_key业务数据字段保存来源、口径和缺失状态generated_at带时区的采样或生成时间重试应新增尝试记录不覆盖最后一次失败。派生结果必须关联输入版本、生成时间和业务状态。验收清单同一输入和规则版本可稳定复用节气事实与文化描述在结构上分离环境数据缺失时不会影响历法事实返回能力边界文化宜忌只作传统文化参考环境信息应分别读取 天气预报、空气质量 与 日出日落并保留各自采样时间不能用历法结果替代。示例中的YOUR_APPKEY仅为占位符。真实密钥只能放在服务端环境变量或密钥管理系统中。