lunar-mini/web/docs/RETROSPECT.md

开发回顾记录（Retrospect）

会话日期：2026-08-02 ~ 2026-08-03 用途：记录本次会话"做了什么 / 没做什么 / 有疑问的事项"，便于事后回顾与决策。

一、本次完成的工作

1. 文档体系（docs/）

• 新建 docs/：ARCHITECTURE / REQUIREMENTS / PROGRESS / BUGS / CHANGELOG，另加根 README.md
• 修正 AGENTS.md / CLAUDE.md 的过时信息（PWA 状态、页面/Store/API 补全），并持续同步

2. BUG 修复（BUGS.md 均已标记 ✅）

ID	内容
BUG-01	core 包 CJS 导出：tsup 增加 cjs 产物，require() 实测可用
BUG-02	周起始设置生效：settings → useCalendar → getMonthCalendar(weekStart) → WeekDayBar
BUG-03	PWA manifest 对齐（lang=zh-CN、theme_color=#FFFBF5）
BUG-05	配置 ESLint 9 flat config + typescript-eslint，pnpm lint 通过（修复 24 处）
BUG-07	版本号统一 v0.1.0
BUG-08	getMonthCalendar 死分支移除
BUG-09	"回到今天"按钮条件恒 false，改为基于 viewDate 判断
BUG-10	日详情时辰列表重复 React key（早子/晚子均"子"），改用 ganzhi 作 key
TECH-06	(as any)._solarAdjusted → BaziFullResult.solarAdjusted 类型化

3. 功能深化

• 八字流派切换：birthInfoToBazi 新增 ziSect（晚子时算次日/当日），设置页开关
• 出生时间选择器：时/分下拉 + 时辰格可点
• 出生地全国化 + 海外时区：34 省级城市（真太阳时校正）+ 海外 UTC-12~+14 换算北京时间，均支持跨日
• 真太阳时校正开关（设置页，默认开启）
• 宜忌完整显示：根因是首页 slice(0,6)，引擎本有 22 条宜
• 历法信息增强：DayInfo 新增 季节/所处节气/第几天/距下节气/儒略日/佛历年/伊斯兰历（tyme4ts 原生 Hijri）
• 佛教节日：新增 getBuddhistFestival（农历 21 个节日），日详情 🪷 徽章
• 八字神煞：新增 analyzeShensha（22 个常见神煞），八字页"神煞"卡
• 大运/流年生克冲合：新增 analyzeFortuneGanzhi（十神/五行生克/合冲害刑/吉凶）
• 大运→流年→流月→流日交互下钻：新增 getYearMonths（节气月）；八字页交互浏览器，流日可跳日详情

4. 质量

• 单元测试 29 → 50 个（vitest），覆盖历法/八字/运势/梅花/称骨/干支/五行/神煞/流月/流年
• 浏览器 E2E 验证（headless Chrome + CDP 脚本，无新增依赖）：周起始、回到今天、流派、出生地、太阳时开关、宜忌、历法信息、神煞、大运流年交互 全部实测通过

5. 工程清理

• 整理全部文档；删除 node_modules / dist / tsbuildinfo；源码 241M → 764K；打包 164K（/tmp/lunar-source-20260803.tar.gz）

二、未完成 / 待办（详见 PROGRESS.md Backlog）

事项	说明
互卦真算法	梅花易数互卦仍为上下卦互换简化（2-4/3-5 爻法未实现）
死代码清理	useDayDetail/useBazi hooks、AnimatedPanel、CardHeader、CalendarSkeleton/BaziSkeleton、ui store 未用 action、settings 显示开关字段、calendar store weekStart、bookmarks getByDate、utils 未用函数、tailwind-variants 依赖
显示开关字段	settings.showLunar/showSolarTerm/showHoliday/eightCharProvider 已持久化但未消费（其中 eightCharProvider 已被 ziHourSect 替换）
农历周期收藏	bookmarks 的 isLunar 字段已预留，UI 未提供；收藏列表页未做
午时假设	calculateDailyFortune 当日八字固定取午时（TECH-01）
称骨极端值	超出 2两1钱~7两2钱范围的总重仍取"最近值"（TECH-04 残余）
紫微斗数	未做（大工程，用户同意先做神煞）
web 端自动化测试	仅 core 有单测；web 无测试框架
git	项目未初始化 git 仓库，无版本管理与回滚能力

三、有疑问 / 待确认事项

1. 称骨年表存在两套网络变体：本实现采用主流版本（算准网/网易/sunfinelife 三家一致：丙子16钱、戊子15钱等），但另一套变体（丙子19钱、戊子12钱等）也在流通。若用户希望换另一套，改 boneWeight.ts 的 YEAR_WEIGHTS 即可。
2. 天厨贵人查法有版本差异：本实现采用主流版（甲巳、乙午、丙巳、丁午、戊申、己酉、庚亥、辛子、壬寅、癸卯）；传统版（丙寅、丁酉、戊申、己未、庚亥、辛戌、壬卯、癸子）也有出处。代码注释已注明。
3. tyme4ts 十神方向语义：实测 A.getTenStar(B) 返回"B 以 A 为日主"的十神。dailyMatch.ts 中的用法方向（userPillar vs dayPillar 同位置比较）语义上存疑，但未改动（避免影响每日运势结果）；新写的 fortuneLuck 已按正确方向实现。需确认 dailyMatch 是否也要调整。
4. 佛历年：按公历 + 543（泰国惯例）；bmcx 示例 2570 对应的是其他年份。
5. 佛教节日表：21 个为通行版本，个别日期（如腊月廿九华严菩萨圣诞）在不同资料有出入。
6. 默认出生地变化：默认从"120°E 不校正"改为"北京 116.4°E（-14 分钟真太阳校正）"，临界时辰的结果会变。太阳时校正开关默认开启——用户接受度未知，如需要可默认关闭。
7. BUG-04（HomePage InfoCard highlight）：highlight 传布尔但被当作样式类 border-primary/30 处理，语义不清，需确认意图（是要"高亮边框"还是别的）。
8. 起运前年份 UX：大运流年浏览器中，出生当年（起运前）不在任何大运区间，自动落到第一柱大运（如 2026 年出生 → 从 2028 起显示）。是否要显示"起运前"年份待定。
9. pnpm-workspace.yaml allowBuilds：非 pnpm 标准字段（应为 onlyBuiltDependencies），疑似无效但无害，未改。
10. 打包清理：已删除 node_modules/dist，开发前需 pnpm install。

四、验证方式备忘

• E2E 通过 headless Chrome（Playwright 缓存目录的 chromium headless shell）+ CDP 协议 Node 脚本驱动，未引入 Playwright npm 依赖；脚本存于 /tmp/lunar-*.mjs（会话临时文件，未入库）。
• 所有功能均以"单测 + 浏览器实测"双重验证；仅 UI 纯样式类改动（如时间选择器）以 tsc 构建验证为主。