真太阳时修正经验（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”。

抽象问题与防范

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

验证建议

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

后续准则

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