# 需求文档（Requirements & 功能清单）

> 最后更新：2026-08-02
> 状态说明：✅ 已完成 · 🟡 部分完成 / 有已知问题 · ⬜ 规划中

## 1. 需求总览

| 模块 | 状态 | 说明 |
|---|---|---|
| 历法核心引擎（@lunar/core） | ✅ | 农历/干支/黄历/八字/运势算法 |
| 万年历（首页 + 日历 + 日详情） | ✅ | 功能齐全（周起始设置已修复） |
| 八字排盘 | 🟡 | 功能齐全，含一个非类型安全补丁 |
| 每日运势 | ✅ | 依赖用户档案 |
| 占卜工具（梅花易数 / 称骨） | 🟡 | 算法为简化实现（见备注） |
| 节气 | ✅ | 24 节气列表 |
| 用户档案 + 设置 | 🟡 | 部分设置字段未生效 |
| 收藏 | 🟡 | 仅支持公历单日收藏 |
| PWA | ✅ | 已构建，manifest 有瑕疵 |

## 2. 功能点清单

### 2.1 历法核心（@lunar/core）

| # | 功能点 | 描述 | 状态 |
|---|---|---|---|
| C1 | 日期转换 | tyme4ts → DayInfo（公历/农历/干支/星座/生肖/节日/假日/月相） | ✅ |
| C2 | 月历生成 | `getMonthCalendar` 周×天网格，含相邻月补位 | ✅ |
| C3 | 黄历信息 | 宜忌、值神（日/时）、十二/廿八/九/六曜星、彭祖百忌、胎神、冲煞、纳音、三合/六合 | ✅ |
| C4 | 时辰黄历 | 12 时辰逐时黄历（buildHourlyAlmanac） | ✅ |
| C5 | 八字排盘 | 四柱、十神、藏干、十二长生、胎元/胎息、命宫/身宫、空亡、起运 | ✅ |
| C6 | 大运/流年 | 10 大运 + 10 流年 | ✅ |
| C7 | 干支关系 | 六合/三合/六冲/六害/相刑/三合局/天干合冲 | ✅ |
| C8 | 五行分析 | 五行力量统计（藏干 0.5 权重）、旺衰、平衡度 | ✅ |
| C9 | 每日运势 | 四柱逐柱 vs 当日干支打分（日 40%/月 25%/年 20%/时 15%），输出评分、宜忌、幸运色/数/方位、分项（感情/事业/财运/健康） | 🟡 当日八字固定取午时 |
| C10 | 梅花易数 | 时间起卦、变卦、互卦（简化）、体用关系、64 卦辞 | 🟡 互卦简化为上下互换（卦库 64/64 完整，已有测试） |
| C11 | 称骨算命 | 年/月/日/时称骨表 + 52 首解诗（2两1钱~7两2钱完整） | ✅ 数据表已按主流版本修正，歌诀补全（极端值仍取最近） |
| C12 | 历法信息 | 季节、所处节气/第几天/距下节气、儒略日、佛历年、伊斯兰历（Hijri） | ✅ |
| C13 | 佛教节日 | 农历 21 个重大佛教节日（`getBuddhistFestival`） | ✅ 日详情页 🪷 徽章展示 |
| C14 | 八字神煞 | 22 个常见神煞（`analyzeShensha`） | ✅ 八字页"神煞"卡片 |
| C15 | 大运/流年 vs 日主生克冲合 | 十神、五行生克、天干合冲、地支关系、吉凶（`analyzeFortuneGanzhi`） | ✅ |
| C16 | 流年·流月·流日分析 | 任意日期年/月/日干支 vs 日主（`getYearMonths` 按节气月） | ✅ 八字页交互浏览器 |

### 2.2 首页 HomePage（`/`）

| # | 功能点 | 状态 |
|---|---|---|
| H1 | 今日概览：日期、农历、干支、宜忌摘要 | ✅ |
| H2 | 运势预览（需档案） | ✅ |
| H3 | 快捷导航（占卜、节气） | ✅ |
| H4 | 值神/彭祖/胎神展示 | ✅ |

### 2.3 日历 CalendarPage（`/calendar`）

| # | 功能点 | 状态 |
|---|---|---|
| K1 | 月视图/周视图切换 | ✅ |
| K2 | 年/月切换（MonthYearPicker） | ✅ |
| K3 | 格子显示：节日/节气缩写、农历、周末/今日高亮、收藏星标、运势点 | ✅ |
| K4 | 点击日期 → 日详情页 | ✅ |
| K5 | 手势滑动切换月份 | ✅ |
| K6 | 周起始（周一/周日）设置生效 | ✅ 已修复（BUG-02） |
| K7 | 非本月时显示"回到今天"浮动按钮，点击返回当月 | ✅ 已修复（BUG-09） |

### 2.4 日详情 DayDetailPage（`/calendar/:date`）

| # | 功能点 | 状态 |
|---|---|---|
| D1 | 四柱、纳音、值星展示 | ✅ |
| D2 | 冲合害煞、宜忌列表 | ✅ |
| D3 | 值神、彭祖百忌、胎神 | ✅ |
| D4 | 12 时辰逐时黄历 | ✅ |
| D5 | 收藏按钮 | ✅ 仅公历收藏 |

### 2.5 八字 BaziPage（`/bazi`）

| # | 功能点 | 状态 |
|---|---|---|
| B1 | 出生档案管理（最多 3 个，持久化） | ✅ |
| B2 | 排盘：四柱 + 十神 + 藏干 | ✅ |
| B3 | 五行力量 / 十二长生展示 | ✅ |
| B4 | 起运 / 大运 / 流年 | ✅ |
| B5 | 称骨集成 | ✅ 使用出生年干支（占卜页已同步修正） |
| B6 | 日柱类型安全 | ✅ `solarAdjusted` 字段替代 `(as any)` 补丁 |
| B7 | 八字流派切换（晚子时换日 23点 / 0点换日） | ✅ 设置页可切换，排盘实时生效 |
| B8 | 出生地：全国 34 省级城市真太阳时校正 | ✅ 含跨日处理，受"真太阳时校正"开关控制 |
| B9 | 出生地：海外时区 → 北京时间（UTC+8）换算排盘 | ✅ 含跨日处理 |
| B10 | 神煞展示（22 个常见神煞，吉/凶/中性分组） | ✅ |
| B11 | 大运全量 10 条 + 流年（小运）10 条，均附生克冲合 | ✅ |
| B12 | 大运→流年→流月→流日交互下钻（按年度切换） | ✅ 点选日期跳转日详情 |

### 2.6 每日运势 DailyFortunePage（`/daily-fortune`）

| # | 功能点 | 状态 |
|---|---|---|
| F1 | 日期导航查看任意日运势 | ✅ |
| F2 | 无档案时引导创建 | ✅ |
| F3 | 评分等级、宜忌、幸运信息、分项得分 | ✅ |

### 2.7 占卜 DivinationPage（`/divination`）

| # | 功能点 | 状态 |
|---|---|---|
| P1 | 今日梅花易数卦象 + 体用分析 | 🟡 算法简化 |
| P2 | 称骨算命输入与结果 | 🟡 年索引用日干支近似 |

### 2.8 节气 SolarTermsPage（`/solar-terms`）

| # | 功能点 | 状态 |
|---|---|---|
| S1 | 全年 24 节气列表 | ✅ |

### 2.9 设置 SettingsPage（`/settings`）

| # | 功能点 | 状态 |
|---|---|---|
| T1 | 档案管理入口 | ✅ |
| T2 | 农历日期查询（阴阳历转换） | ✅ |
| T3 | 今日天干地支/纳音 | ✅ |
| T4 | 主题切换（亮/暗/跟随系统） | ✅ |
| T5 | 周起始设置 | ✅ 已修复（BUG-02） |
| T6 | 显示开关（农历/节气/假日）、八字来源 | 🟡 字段已持久化但未消费 |
| T7 | 关于：版本号 | ✅ 已统一为 0.1.0（BUG-07） |
| T8 | 真太阳时校正开关（默认开启） | ✅ 关闭后按北京时间排盘 |

### 2.10 收藏 Bookmarks

| # | 功能点 | 状态 |
|---|---|---|
| M1 | 收藏/取消收藏日期，日历格星标 | ✅ |
| M2 | 农历周期收藏（每年/月循环） | ⬜ 字段已预留，UI 未提供 |
| M3 | 收藏列表页 | ⬜ 规划中 |

### 2.11 非功能需求

| # | 需求 | 状态 |
|---|---|---|
| N1 | PWA 可安装、离线可用 | ✅ 已构建 |
| N2 | 移动端优先响应式 | ✅ |
| N3 | 暗色模式（跟随系统） | ✅ |
| N4 | 页面懒加载 + 骨架屏 + 错误边界 | ✅ |
| N5 | 自动化测试 | ✅ 2026-08-02 引入 vitest，29 个用例（历法/八字/运势/梅花/称骨/干支） |
| N6 | Lint / 代码规范 | ✅ 2026-08-02 配置 ESLint 9 flat config + typescript-eslint，`pnpm lint` 通过 |