docs: 更新文档

2026-08-17 12:58:07 +00:00 · 2025-12-17 19:55:39 +08:00
parent 68f6400333
commit a618653e7c
3 changed files with 102 additions and 43 deletions
@@ -0,0 +1,41 @@
+#  telegram Markdown 代码块格式修复记录 2025-12-15
+
+## 问题
+
+排盘完成后发送消息报错：
+```
+❌ 排盘失败: Can't parse entities: can't find end of the entity starting at byte offset 168
+```
+
+## 原因
+
+`bot.py` 中 `header` 消息的 Markdown 代码块格式错误。
+
+原代码使用字符串拼接，在 ``` 后面加了 `\n`，导致 Telegram Markdown 解析器无法正确识别代码块边界：
+
+```python
+# 错误写法
+header = (
+    "```\n"
+    f"{filename}\n"
+    "```\n"
+)
+```
+
+## 修复
+
+改用三引号字符串，确保 ``` 单独成行：
+
+```python
+# 正确写法
+header = f"""报告见附件
+```
+{filename}
+{ai_filename}
+```
+"""
+```
+
+## 修改文件
+
+- `services/telegram-service/src/bot.py` 第 293-308 行
@@ -0,0 +1,32 @@
+# 真太阳时修正经验（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`。