Initial commit: Lunar calendar converter project

- Add lunar calendar astronomical calculation engine (lunar_calendar.py)
- Add converter utilities for solar/lunar date conversion
- Add historical era name conversions (chrono_converter.py, converter_with_eras.py)
- Add FastAPI REST API for date conversion services
- Add age calculator using lunar calendar
- Add batch generation script for lunar calendar JSON data
- Add project documentation (CLAUDE.md, pyproject.toml)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Lunar_Calendar_Converter_README

@@ -0,0 +1,123 @@
+Lunar Calendar Converter 農曆轉換工具
+
+一套使用 Python 3.13+ 與 Skyfield 天文資料庫實作的農曆轉換工具，支援西曆↔農曆、閏月查詢，並提供 CLI 與 API（FastAPI）。
+
+需求
+
+- Python >= 3.13（可用 uv 安裝）
+- 套件：
+  - skyfield
+  - jplephem
+  - numpy
+  - fastapi、uvicorn（僅在使用 API 時）
+- Skyfield 天文資料檔（本庫已附）：
+  - de422.bsp（程式目前預設使用）
+  - de440s.bsp、de421.bsp（可替代）
+
+安裝與環境（使用 uv）
+
+初始化與安裝依賴（如已存在可略過 init）
+uv init lunar-converter
+cd lunar-converter
+uv add skyfield jplephem numpy flask
+uv lock
+uv sync
+
+uv 會自動建立 .venv/ 虛擬環境，無需手動啟動。
+
+專案結構（重點檔案）
+
+.
+├── converter.py                  # 西曆↔農曆轉換核心與閏月查詢（供程式/API 使用）
+├── converter_with_eras.py        # 指令列工具：solar2lunar / lunar2solar / era
+├── api.py                        # FastAPI 服務
+├── generate_lunar_calendar_json.py # 批次產生 JSON（可自訂年份範圍）
+├── lunar_calendar.py             # 天文計算與 JSON 產生
+├── lunar_json/                   # 每年一檔的農曆 JSON（執行產生器後）
+
+產生農曆資料（JSON）
+
+預設腳本為 `generate_lunar_calendar_json.py`，內含可調整的年份範圍。
+
+uv run python generate_lunar_calendar_json.py
+
+會輸出到 `lunar_json/`，例如：`lunar_json/2025.json`。
+
+若只想產生 1900–2100，可修改腳本內的 years 範圍：
+
+# generate_lunar_calendar_json.py
+# years = range(1900, 2101)
+
+指令列（CLI）使用
+
+CLI 功能位於 `converter_with_eras.py`：
+
+uv run python converter_with_eras.py solar2lunar 2025-10-12
+uv run python converter_with_eras.py lunar2solar 1977-08-30 --leap   # 閏月請加上 --leap
+uv run python converter_with_eras.py era 1906-02-07                  # 歷代年號 / 日本元號查詢
+
+範例輸出（solar2lunar）
+
+{
+  "西曆": "2025-10-12",
+  "農曆": "8月21日",
+  "干支": "乙巳",
+  "生肖": "蛇",
+  "節氣": ""
+}
+
+啟用 API（FastAPI）
+
+uv run python api.py
+
+程式會自動尋找可用埠（預設從 5000 開始）。可瀏覽 `/docs` 或 `/redoc` 查看互動式文件。
+或直接用 Uvicorn 啟動：
+
+uv run uvicorn api:app --host 0.0.0.0 --port 5000
+
+API 範例
+
+# 查詢一個存在的日期
+curl "http://127.0.0.1:5001/solar2lunar?date=2025-10-06" | jq
+
+# 不提供 date 參數
+curl "http://127.0.0.1:5001/solar2lunar" | jq
+
+# 查詢一個沒有閏月的日期
+curl "http://127.0.0.1:5001/lunar2solar?date=1977-08-30" | jq
+
+# 查詢一個有閏月的日期
+curl "http://127.0.0.1:5001/lunar2solar?date=1976-08-25" | jq
+
+# 查詢一個不存在的日期（會得到 404）
+curl -i "http://127.0.0.1:5001/lunar2solar?date=2025-08-30"
+
+# 查詢 2023 年（該年有閏二月）
+curl "http://127.0.0.1:5001/leap-info?year=2023" | jq
+
+# 查詢 1977 年
+curl "http://127.0.0.1:5001/leap-info?year=1977" | jq
+
+# 提供一個非數字的年份
+curl "http://127.0.0.1:5001/leap-info?year=abc" | jq
+
+備註
+
+- 干支與生肖依據「農曆年」切換。
+- 使用 Skyfield 計算節氣與朔望月，精度高於傳統對照表。
+- 目前 `lunar_calendar.py` 預設載入 `de422.bsp`。欲改用 `de440s.bsp` 或 `de421.bsp`，請修改：
+  self.eph = load('de422.bsp')
+- 若缺少某年 JSON 檔，查詢會提示錯誤，請先執行產生器產生對應年份。
+
+作者
+
+由 Timmy（羅楊竣）開發。
+
+MIT License
+
+開發小工具（直接使用 uv 指令）
+
+- `uv run --group dev black .`：使用 Black 格式化專案
+- `uv run --group dev ruff format .`：使用 Ruff 內建 formatter 格式化
+- `uv run --group dev ruff check .`：Ruff 檢查
+- `uv run --group dev ruff check --fix .`：Ruff 自動修正