节气日历服务如何统一日期口径：时区、历法事实与文化参考分层

节气日历服务如何统一日期口径，关键不是完成一次调用，而是让输入口径、处理状态和结果证据可以复核。本文围绕“如何处理日期、时间、时区和节气边界，并把历法事实与文化参考分开返回”给出一套面向真实业务流程的实现方式。

问题与结果

先计算可核对的日期与节气事实，再生成文化参考；两类数据拥有不同字段、版本和使用边界。

适用场景

节气和传统日历组件
文化内容服务
结合天气与日出日落的日程提示

实现前先确定边界

请求时间必须带时区，默认时间也要显式记录
午夜、子时和跨日边界使用统一规则版本
天气与空气质量按独立采样时间展示

可验证工作流

API 编排与职责

步骤	接口	请求方式	用途
查询历法与参考	传统历法宜忌参考	POST	返回农历、干支、生肖、星座、节气、宜忌和文化参考
查询异步任务	异步任务状态查询	GET	月历预生成或后台批量任务

接口地址：

POST https://api.gugudata.com/ai/traditional-calendar-guidance

当前 timezone 固定支持 Asia/Shanghai。date 范围为 1901-01-01 至 2100-12-31；time 可选，未传时按 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(frozen=True)
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 仅为占位符。真实密钥只能放在服务端环境变量或密钥管理系统中。