传统历法日程参考台功能需求文档
所属分类：传统文化/历法日历
产品案例页：https://engineering.gugudata.com/products/fortune/traditional-calendar-guidance-desk/
产品定位与截图范围
传统历法日程参考台面向日历应用、传统文化内容平台和节气栏目，按指定公历日期、时间和时区展示农历、干支、生肖、星座、节气、宜忌、时辰与其他传统历法字段，并提供克制的日程内容参考。
截图覆盖日期与时区设置、公历与农历信息、四柱干支、生肖星座、当前与下一节气、宜忌、十二时辰、方位与传统历法字段、月历、数据完整性、异步状态和复制导出。所有结果用于传统文化研究与娱乐参考，不构成现实决策依据。
目标用户与业务场景
主要用户包括日历产品开发者、节气与传统文化栏目编辑、内容运营人员、多语言文化产品团队和需要历法数据组件的前端开发者。
典型场景包括：
- 日历应用按用户选择日期展示公历、农历、干支和节气；
- 内容团队为节气专题准备当日与下一节气信息；
- 用户选择具体时刻查看对应时柱和时辰参考；
- 运营人员生成一月内容，并检查每一天的字段完整性；
- 后台异步准备日历数据，前台按日期读取已完成结果。
截图可见信息组织
顶部导航包括今日历法、月历视图、时辰参考、节气内容和历史查询。左侧固定展示查询日期、时间、时区、语言和响应模式，并明确当前系统时间与数据更新时间。
中间顶部展示公历、农历、四柱干支、生肖和星座。节气条显示当前节气、下一节气及日期。主体区域分为宜、忌、十二时辰参考、综合矩阵、方位参考和传统历法信息。
底部月历把公历日期、农历日期、节气和传统节日分层展示。右侧包括今日日程参考、数据完整性检查、异步操作状态、复制导出和重要提示。用户自行安排的日程与接口返回内容必须明确区分。
核心功能需求
- 日期查询：
date必填并使用YYYY-MM-DD。 - 时辰查询：
time可选，未传时按 12:00 计算；页面需显示实际使用时间。 - 时区约束：当前固定支持
Asia/Shanghai，不能展示为可随意选择任意时区。 - 基础历法：展示农历年月日、年月至日时干支、生肖、星座和节气。
- 宜忌与扩展字段：展示宜、忌、冲煞、吉神凶煞、彭祖百忌、十二值日、二十八宿、纳音、方位和胎神等返回内容。
- 月历浏览：切换日期后同步更新当前日期所有字段。
- 响应模式：支持同步 JSON、异步任务和 SSE 流式响应。
- 使用边界：日程参考不能自动替用户做现实决策。
主要操作流程
- 用户选择公历日期，按需填写具体时间。
- 系统固定使用
Asia/Shanghai，校验日期和 24 小时制时间。 - 页面调用传统历法宜忌参考接口。
- 基础日期、农历、干支、生肖、星座和节气优先展示。
- 宜忌、时辰、方位和其他传统历法信息按模块加载。
- 用户在月历中切换日期，所有依赖字段同时刷新。
- 用户可以复制或导出数据，也可以自行把参考内容加入日程。
数据与结果展示
基础日期字段必须采用同一查询时间计算。公历日期、农历日期、时柱和当前时辰必须对应，不能在用户修改时间后只更新部分模块。节气区同时展示当前节气和下一个节气的公历时间。
宜与忌使用对称列表，不使用夸大视觉或绝对化文案。十二时辰按两小时区间展示，并标记当前查询时刻。方位、神煞、值日、宿、纳音和胎神等字段应使用可展开信息区，避免首屏信息过载。
日程参考由用户主动采用。页面不得根据宜忌自动批准、拒绝、延迟或触发婚姻、医疗、投资、法律、出行和其他现实事项。
接口调用蓝图
| 业务步骤 | 接口名称 | 接口文档 | 请求地址 | 关键入参 | 关键出参 | 传参关系 |
|---|---|---|---|---|---|---|
| 查询传统历法 | 传统历法宜忌参考 | traditional-calendar-guidance |
POST https://api.gugudata.com/ai/traditional-calendar-guidance |
date*、time、timezone、language、responseMode、streaming |
农历日期、干支、节气、宜、忌及文化解读 | 查询日期与时间共同决定基础历法和时辰结果。 |
| 查询异步任务 | 任务状态查询 | operation 查询接口 | GET https://api.gugudata.com/ai/operations/{operation_id} |
operation_id*、appkey* |
任务状态、结果或失败原因 | 月历预生成任务按日期保存独立 operationId。 |
参数流转说明
date 必须使用 YYYY-MM-DD；time 使用 HH:mm 或 HH:mm:ss，未传时实际计算时间为 12:00。页面应在结果标题中显示最终日期、时间和 Asia/Shanghai，不能只显示用户最初输入。
用户在月历切换日期时，date 改变并触发完整刷新；用户切换时辰时，time 改变，所有依赖时柱与时辰的内容进入待更新状态。批量月历任务按日期分别保存输入和结果，单日失败不影响其他日期。
体验要求与验收标准
桌面端要让用户一眼看清查询日期、时间、时区、农历和节气。信息密度较高的扩展字段应分组，不使用无限长单表。移动端优先展示日期、农历、节气、宜忌和当前时辰，其余字段折叠。
验收时需要确认：日期与时间格式是否正确；时区是否固定为 Asia/Shanghai；未传时间时是否显示 12:00；公历、农历、干支和时辰是否来自同一查询条件；切换日期或时间后是否完整刷新；月历节气是否正确关联；用户日程与文化参考是否分开；免责声明是否持续可见。
截图功能验收清单
- 查询日期、时间和时区始终可见；
- 未填写时间时明确显示服务使用 12:00；
- 公历、农历、干支、生肖、星座和节气条件一致；
- 宜忌、时辰和方位模块可独立展开；
- 当前时辰与查询时间匹配；
- 月历切换会刷新全部依赖字段；
- 导出内容包含查询条件和更新时间；
- 页面不根据文化参考自动执行现实事项；
- 重要提示明确写明不构成现实决策依据。
关于 GuGuData Engineering 产品案例
更多产品案例请访问 GuGuData Engineering 产品案例。
GuGuData Engineering 产品案例页展示基于咕咕数据接口能力构建的数据接入、业务流程和产品原型，帮助团队从真实业务场景出发，快速评估接口组合、调用方式和落地价值。
–EOF–
转载须以超链接形式标明文章原始出处和作者信息
