# 真太阳时修正经验（2025-12-16）

## 背景
- 新疆用户反馈：报告中“阳历先减2小时，真太阳时再减2小时”，四柱/神煞与对照工具不一致。
- 根因：出生时间先在调用方计算了一次真太阳时，然后 `BaziCalculator` 内部再次计算，形成“双重扣减”。

## 现行策略（已上线）
- **唯一修正点**：所有真太阳时只在 `BaziCalculator` 内部执行一次。
- **时间基线**：入口出生时间一律视为北京时间（Asia/Shanghai），用 `ensure_cn` 赋予时区后再做真太阳时修正。
- **计算时间**：核心与扩展模块全部基于 `calc_dt`（真太阳时或用户禁用时的原始北京时），保持一致性。
- **展示时间**：UI/进度/日志/队列/Help 统一用北京时间；报告字段 `trueSolarTime` 展示经度修正后的时间。

## 涉及改动（要点）
- `utils/timezone.py`: `now_cn/ensure_cn/fmt_cn` 固定 Asia/Shanghai。
- `bot.py`: 去掉外层 `calc_true_solar_time`；时间显示用 `fmt_cn(now_cn())`；队列时间戳用北京时间。
- `main.py`: API 不再预先修正；`trueSolarTime` 取自 `BaziCalculator` 内部结果。
- `bazi_calculator.py`: 新增 `use_true_solar_time`，统一 `calc_dt`；扩展模块/命卦/小运等改用 `calc_dt`；元数据时间用北京时间。
- `liuyao.py`, `qimen.py`, `system_optimization.py`: 时间戳统一北京时间。
- 文档：`AGENTS.md` 记录“时区统一 Asia/Shanghai”。

## 抽象问题与防范
1. **时区假设不一致**：Naive datetime 若按本地解析会漂移；统一假设“输入即北京时”，先补时区再计算。
2. **重复校正**：真太阳时公式只允许出现一次；调用链上严禁二次修正。
3. **基准混用**：展示用北京时，计算用真太阳时（单次修正）。若新增模块，必须复用 `calc_dt`，不得自算。

## 验证建议
- 用新疆样例（乌鲁木齐 87E，08:00）跑一次：阳历应保持 08:00，北京时显示 08:00，真太阳时约 05:4x，仅扣一次。
- 比对“测测”等对照工具的四柱/神煞，应一致。

## 后续准则
- 如需对外提供 UTC/其他时区，先转为北京时，再按经度做真太阳时，仍然只修正一次。
- 新增集成模块时，禁止各自重复计算真太阳时；统一接受 `calc_dt`。