# 万年历（Lunar Calendar App）

中国农历 / 黄历应用：农历转换、黄历宜忌、八字排盘（大运流年流月流日）、每日运势、神煞、梅花易数、称骨算命、节气、佛教节日。移动端优先，支持 PWA 离线安装。

## 技术栈

- **Monorepo**：pnpm workspaces
- **@lunar/core**：TypeScript + [tyme4ts](https://github.com/6tail/tyme4ts)（历法引擎），零 UI 依赖，ESM+CJS 双产物
- **@lunar/web**：React 19 + Vite 6 + TailwindCSS v4 + Zustand 5 + React Router v7 + Framer Motion + vite-plugin-pwa

## 快速开始

```bash
pnpm install
pnpm dev          # http://localhost:4258
pnpm test         # core 单元测试（vitest，50 例）
pnpm lint         # ESLint
pnpm build        # 构建 core + web（含 PWA）
pnpm preview      # 预览构建产物
```

> 需要 Node ≥ 18、pnpm ≥ 9。

## 文档

详细文档见 `docs/`：

- [ARCHITECTURE.md](docs/ARCHITECTURE.md) — 架构、API、路由、状态管理
- [REQUIREMENTS.md](docs/REQUIREMENTS.md) — 功能点清单与完成状态
- [PROGRESS.md](docs/PROGRESS.md) — 里程碑与待办
- [BUGS.md](docs/BUGS.md) — 已知 BUG、技术债、死代码
- [CHANGELOG.md](docs/CHANGELOG.md) — 变更日志
- [RETROSPECT.md](docs/RETROSPECT.md) — 会话回顾（做了什么/没做什么/疑问）

## 目录结构

```
lunar/
├── docs/                  # 项目文档
├── packages/
│   ├── core/              # @lunar/core —— 纯 TS 计算引擎
│   └── web/               # @lunar/web —— React 应用
├── AGENTS.md / CLAUDE.md  # 开发代理指引
└── eslint.config.js       # ESLint flat config
```

## 核心能力

| 模块 | 说明 |
|---|---|
| 历法 | 公历/农历/干支/节气/季节/儒略日/佛历/伊斯兰历/月相 |
| 黄历 | 宜忌、值神（日/时）、二十八宿、彭祖百忌、胎神、冲煞 |
| 八字 | 四柱、十神、藏干、十二长生、大运、流年、神煞、流派切换 |
| 运势 | 每日运势、流年/流月/流日 vs 日主生克冲合 |
| 占卜 | 梅花易数（64 卦）、袁天罡称骨 |
| 其他 | 佛教节日、节气列表、收藏、PWA |