73 lines
3.7 KiB
Markdown
73 lines
3.7 KiB
Markdown
# 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
|
||
1. **tyme4ts objects never enter React** — all transformed to plain JS objects in @lunar/core
|
||
2. **@lunar/core has zero UI deps** — works in any JS runtime (web, Node, RN, mini-program)
|
||
3. **Mobile-first responsive** — phone first, desktop sidebar layout
|
||
4. **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.
|