Lunar Calendar App (万年历)

Chinese almanac/perpetual calendar app with Bazi calculation, daily fortune, divination tools, and beautiful UI.

Documentation

Detailed docs live in docs/ — read them before starting any task:

docs/ARCHITECTURE.md — tech stack, layered design, API surface, routes, stores
docs/REQUIREMENTS.md — full feature inventory with completion status
docs/PROGRESS.md — milestones, current state, prioritized backlog
docs/BUGS.md — known bugs, algorithmic approximations, dead code
docs/CHANGELOG.md — version history

Tech Stack

Monorepo: pnpm workspaces
Core: TypeScript + tyme4ts (calendar engine)
Web: React 19 + Vite + TailwindCSS v4 + Framer Motion + Zustand + React Router v7
PWA: vite-plugin-pwa (configured and built — autoUpdate + Workbox)

Project Structure

lunar/
├── docs/                  # Architecture / Requirements / Progress / Bugs / Changelog
├── packages/
│   ├── core/              # @lunar/core — Pure TS, no UI deps
│   │   └── src/
│   │       ├── types/          # calendar.ts, bazi.ts, almanac.ts, fortune.ts
│   │       ├── transformers/   # tyme4ts → plain objects (day.ts, bazi.ts, almanac.ts)
│   │       └── calculators/    # dailyMatch.ts, relationship.ts, elementStrength.ts, plumBlossom.ts, boneWeight.ts
│   └── web/               # @lunar/web — React app
│       └── src/
│           ├── stores/         # Zustand: calendar, user, settings, ui, bookmarks
│           ├── hooks/          # useCalendar, useDayDetail, useBazi, useDailyFortune
│           ├── components/     # calendar/, layout/, ui/
│           └── pages/          # Home, Calendar, DayDetail, Bazi, DailyFortune, Settings, Divination, SolarTerms

Key Architecture Principles

tyme4ts objects never enter React — all transformed to plain JS objects in @lunar/core
@lunar/core has zero UI deps — works in any JS runtime (web, Node, RN, mini-program)
Mobile-first responsive — phone first, desktop sidebar layout
Dark mode via CSS custom properties — theme toggle with system preference detection

Commands

pnpm dev — Start Vite dev server (port 4258)
pnpm build — Build core (ESM+CJS) + web
pnpm --filter @lunar/core build — Build core only (tsup)
pnpm --filter @lunar/web dev — Start web dev server
pnpm preview — Preview production build
pnpm test — Run core unit tests (vitest)
pnpm lint — Run ESLint on all packages

Core API (from @lunar/core)

getDayInfo(year, month, day) → DayInfo
getTodayInfo() → DayInfo
getMonthCalendar(year, month, weekStart?) → DayInfo[][]
getAlmanacInfo(year, month, day) → AlmanacInfo
birthInfoToBazi(params) → BaziFullResult
calculateDailyFortune(userBazi, date) → DailyFortuneResult
analyzeElementBalance(bazi) → ElementProfile
calculatePlumBlossom(y, m, d, hour?) → PlumBlossomResult
calculateBoneWeight(...) → BoneWeightResult
getBranchRelationship(a, b) / getTenStarRelationship(s, o) / checkStemCombine / checkStemOpposite
getBuddhistFestival(lunarMonth, lunarDay) → string | null
analyzeShensha(bazi) → ShenshaInfo[]（22 个常见神煞）
analyzeFortuneGanzhi(ganzhi, dayStem, dayBranch) → FortuneLuck（大运/流年 vs 日主生克冲合）
getYearMonths(year) → YearMonthInfo[]（按节气月）

Known Issues

See docs/BUGS.md for the current list. Resolved: core CJS export, week-start setting, PWA manifest metadata, tests (50), lint, 称骨 data tables, 八字流派 switching, shensha, 大运流年 explorer. Remaining: simplified 互卦 algorithm, dead code cleanup.

3.7 KiB Raw Blame History Unescape Escape