用传统历法宜忌接口构建节气日历服务

摘要：用一个 JSON 请求获取可核对的历法事实、查询时辰和结构化三语文化内容，并正确处理日期边界、任务与 SSE 响应。

关键词：传统历法 API、农历 API、二十四节气 API、宜忌接口、日历组件、传统文化数据服务

问题背景

日历产品容易把多个来源的数据直接拼在页面上，导致公历日期、农历日期、节气和时辰并不属于同一查询时刻。用户切换时间后，如果只刷新时辰而没有刷新相关干支字段，页面就会出现内部矛盾。

可靠的服务应以明确的 date、time 和 timezone 作为输入，先展示历法基础数据，再展示文化参考内容。基础事实与文化说明必须分区，并持续显示使用边界。

Agent 工作流

传统历法服务流程图

接口编排

步骤 接口 请求方式 用途
查询历法与参考 传统历法宜忌参考 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 不会提前切换到次日。页面应同时显示输入日期、规范化时间和 查询时辰，不要只显示“子时”而隐藏实际日期。

节气结果同时提供兼容的日期字段和精确日期时间。节气日前后的内容应以返回时间为准，不能只比较日期字符串。

基础数据与文化参考分层

基础数据包括：

  • 农历年月日和中文日期；
  • 年、月、日、时干支；
  • 生肖和星座；
  • 当前节气、下一节气及日期；
  • 宜、忌和其他传统历法字段。

文化参考用于组织日程说明。页面应明确它属于传统文化研究与娱乐参考，不应触发自动审批、排期、交易、医疗或其他现实决策。

月历预生成

生成整月内容时，不建议前端同时发起几十个同步请求。可以由后台：

  1. 为目标月份创建每日任务。
  2. 固定时区和默认时刻。
  3. 使用异步任务模式或有界并发，并通过 Header 查询任务状态。
  4. 保存每一天的独立状态。
  5. 只重试失败日期。
  6. 月历读取已完成结果并显示缺失状态。

某一天失败不能让整月任务只返回一个模糊的失败结果。

标准架构拆解

模块 责任
查询入口 接收日期、时间、语言和页面来源
参数校验 校验日期、24 小时制时间和固定时区
历法服务 调用接口并分离基础数据与文化参考
月历任务 有界并发预生成每日内容
组件适配 为日历、节气页和历史查询提供结构化结果
内容边界 展示文化娱乐参考说明

数据流与接口边界

推荐流程：

  1. 用户选择日期和可选时间。
  2. 服务端补齐默认时间并固定 Asia/Shanghai。
  3. 校验请求格式并调用传统历法接口。
  4. 基础数据和文化参考分别展示。
  5. 日历组件读取结构化字段。
  6. 历史查询保留原始查询条件，不重新标记为当前结果。

接口负责历法基础字段与文化参考，应用负责展示层级、任务状态和现实使用边界。

错误处理

日期必须使用 YYYY-MM-DD，时间使用 HH:mm 或 HH:mm:ss。传入其他时区时，当前应直接提示不支持，而不是悄悄改成北京时间。

用户切换时间后，与时柱和时辰相关的旧结果必须失效。批量月历任务发生部分失败时，页面显示缺失日期，并允许后台重试，不能复制相邻日期内容填补。

同步响应在 Data 返回完整结果；任务模式先返回 operationId，成功后由任务查询的 Data.result 返回完整结果；SSE 依次发送 metadata、content 和包含完整结果的 done.result，最后发送结束事件。任务失败、流式断开或业务码 901 都不能当作成功内容保存。

可靠性与观测

指标 用途
calendar_query_success_rate 历法查询成功率
invalid_datetime_count 发现日期时间输入问题
month_prewarm_completion_rate 整月预生成完成率
partial_month_failure_count 发现部分日期失败
query_result_mismatch_count 检测页面条件与结果串位

落地清单

  • 明确记录 date、time 和 timezone。
  • 未传时间时显式使用并展示 12:00。
  • 当前仅允许 Asia/Shanghai。
  • 基础数据与文化参考分层展示。
  • 切换日期或时间后完整刷新依赖字段。
  • 月历预生成使用有界并发和逐日状态。
  • 历史结果保留请求条件与生成时间。
  • 页面不根据文化参考自动执行现实事项。

可扩展方向

传统历法服务可以与天气、空气质量、日出日落和二十四节气内容组合成城市日历组件。组合数据时，应把城市、日期、时区和更新时间作为共同上下文，并明确各数据源的更新时间。

相关接口

posted @ 2026-08-27 13:48  Parry  阅读(17)  评论(0)    收藏  举报