📜 版本历史

🔧 Hotfix：连续起课时间不刷新

• 修复 连续多次点击「起课抽牌」时起课时间不刷新：handleSubmit 开头未清除 currentReading 和 storedDivTime，导致时间优先链捡到上一次起课的旧时间
• 技术 handleSubmit 开头加 currentReading = null; setStoredDivTime(null)，确保每次新起课时间优先链落到底部 getDivinationTime() 取实时

🔧 Hotfix：起课时间还原取当前时间而非原始时间

• 修复 起课时间还原时显示当前时间而非原始时间：renderReading/completeCrossReading 直接 getDivinationTime() 取实时，不读已存值
• 修复 IIFE 还原时间在 render 之后执行，render 已用当前时间覆盖 — 改为 render 之前 setStoredDivTime，render 自然捡到原始时间
• 技术 getDivinationTime() 替换为优先链：currentReading?.divinationTime || getStoredDivTime() || getDivinationTime()

🎯 太极居中 · 起课时间 · AI去Markdown

• 新功能 太极阵单牌居中：CSS taiji-spread flex + text-align center，牌面图片和文字在容器内居中，不靠左
• 新功能 起课时间模块：起课时自动取公历 + 干支时间（🕐 2026.06.06 18:07 📅 丙午年 甲午月 辛亥日 丁酉时），显示在牌阵上方首个元素，支持保存、还原、AI 输入
• 新功能 干支算法：年干支 (y-4)%60、月干支从年干推算、日干支 2024-01-01=甲子基准、时干支从日干推算，纯前端 JS 实现
• 修复 AI 断语中 Markdown 加粗符号（**文字**）影响阅读，renderPlainText 统一 strip **
• 后端 readings 表新增 divination_time TEXT 列，SaveReadingReq 支持 divination_time 字段，admin 详情返回时间
• 注入 renderReading / completeCrossReading / renderWeeklyReading 三处统一注入时间；resetReading 清时间；IIFE 还原恢复时间
• 缓存 app.js ?v=4.3.0，styles.css ?v=4.3.0
• 全栈 前端 4 文件（app.js / styles.css / index.html / changelog.html）+ 后端 3 文件（models.py / readings.py / admin.py），6/6 MD5 校验一致

🏷️ 周运小卡干支五行角标（绝对定位版）

• Hotfix v4.2.2 当时 meta-row 撑破周运牌阵 layout 导致牌阵消失，v4.2.3 改用 CSS 绝对定位 重新实现：左下角暗红底白字显示干支（甲子），右下角深棕底白字显示五行（水）
• 技术 position: absolute + pointer-events: none + z-index: 2，完全不撑卡片高度，不影响弹层点击
• 样式 新增 .weekly-badge / .weekly-badge-stem / .weekly-badge-element 三个类，仅作用于 .weekly-arc-card，不影响其他牌阵
• 缓存 app.js 缓存版本号 ?v=4.2.2 → ?v=4.2.3

🃏 周运牌阵显示增强 + 每日地支关系 + 体用生克

• 新功能 周运小卡显示天干地支 + 地支五行属性（如 甲子 + 水 标签），弹层之前就有，现在小卡本身也常驻显示
• 新功能 周运每日解读追加地支关系行：周运总牌地支 与 今日地支 → 六合/六冲/六害/三合/三刑/无特殊关系
• 新功能 周运每日解读追加体用生克行：周运总牌（体）· 今日（用）→ 5 级断语（用生体大吉 / 体克用小吉 / 体用平平和 / 体生用小凶 / 用克体大凶）
• 复用 全部复用 v3.4+ 已有的 analyzeBranchRelation() 与 tiYongJudgement() 函数，不重复造轮子
• 样式 干支用浅色描边小标签（card-stem-branch），五行用半透明背景小标签（card-element），保留古风调性

🐛 还原起课时备注不显示修复

• 修复 从个人中心还原带备注的起课记录到首页牌阵，备注 textarea 不显示备注内容
• 根因 渲染备注依赖 currentReading._remark 跨函数桥，但 IIFE 还原路径只设 weeklyState/crossState/调 render 函数，从不在 currentReading 上写 _remark
• 修法 去掉跨函数桥，IIFE 末尾直接 DOM 写入 #remarkInput.value + #remarkCount.textContent，覆盖 5 种牌阵（太极/两仪/三才/周运/十字）
• 附带 修 renderReading 末尾 currentReading._remark 引用未做 null 保护的潜在报错（currentReading = null 时不再抛错）

📍 起课记录位置标注 + 备注笔记 + 幂等保存

• 新功能 后台管理 admin.html 起课记录卡片化：每张牌明确标注对应位置（太极/主位(体)/客位(用)/天位(过去)/人位(现在)/地位(未来)/周运总牌+周日~周六/守护神/人牌/气运/天牌/地牌）
• 新功能 管理员后台可编辑保存每条起课的备注，调 PUT /api/admin/users/{uid}/readings/{rid}/remark
• 新功能 管理员后台单条起课详情接口 GET /api/admin/users/{uid}/readings/{rid}：返回完整 cards/positions/relation_summary/weekly_summary/ai_answer
• 新功能 管理员后台起课记录支持 AI 解读折叠展开（<details>）+ 总断徽章 + 周运周序号标签
• 新功能 主页/用户中心起课记录详情加备注编辑区（≤5000字，含实时字数计数与保存按钮）
• 修复 用户中心详情页 position 标签只对十字法阵显示的 bug：改为用后端存的 positions 数组，所有牌阵都标注位置
• 架构 session_id 幂等键：每次起课生成唯一会话 ID（同卦的所有保存/AI 解读都更新同一条记录，不会重复创建）
• 数据库 readings 表加 session_id 列 + 联合唯一索引 (user_id, session_id)；旧数据 session_id 为 NULL 不受影响
• 后端 POST /api/readings 改 upsert：按 (user_id, session_id) 查重，命中则更新，否则新建；返回 {updated: bool}
• 后端 /api/wenxin 接收 session_id 字段：首次 AI 解读时无 reading_id，靠 session_id 找到同一条记录更新
• 校验 remark 字段统一 max_length=5000（Pydantic Field），前后端双重校验
• 后端 管理员后台起课记录补全 positions/remark/ai_answer/total/cards_summary/week_label/week_range/session_id 等字段
• 后端 后台响应新增 display_positions 字段：按瑞局口语映射好的紧凑标签（与前端 positionLabels 保持一致）

按钮样式 + 还原弹窗修复

• 修复 个人中心按钮不可见：:root 未定义 --bronze 变量，按钮背景透明致白字不可见
• 修复 十字法阵还原时多余「是否保存」弹窗：还原记录无需再保存

报数/线下模式自动卦解

• 修复 十字法阵报数/线下模式提交后未自动生成解卦内容，需额外点击「起课成卦」

十字五牌阵（三才问事法阵）

• 新增 三才问事法阵 · 十字五牌：随机/报数/线下三种模式，固定抽牌顺序（守护神→人牌→气运牌→天牌→地牌）
• 新增 十字法阵独立筛选分类「法阵」，与周运并列
• 新增 牌面缩略图显示 + 天干地支名 + 五行属性完整展示
• 新增 三才核心（人牌·天牌·地牌）视觉分组，守护神/气运牌为纯信息牌不参与生克
• 修复 十字法阵报数/线下模式选择器错位（crossField→numberSelects/offlineSelects）
• 修复 抽牌进度文本逐张更新
• 变更 抽取中间牌时牌阵区渐显，非等全部抽完才显示

🆕 管理员后台 + 权限控制

• 新功能 新增管理后台页面 admin.html，管理员专用入口
• 新功能 数据概览：用户总数、起课数、周运用户、7 日新增
• 新功能 用户搜索（按手机号或 ID）、详情查看、起课记录
• 新功能 重置密码（随机密码 / 自定义密码）、封禁/解封
• 新功能 管理员可为用户设置昵称、自定义密码
• 新功能 用户个人中心自助修改昵称、修改密码
• 权限 个人中心「管理后台」入口仅 admin 角色可见
• 权限 admin.html 校验 JWT 中的 admin 角色，非管理员自动拦截
• 权限 版本历史页 changelog.html 仅管理员可查看，非管理员显示锁定提示
• 权限 首页「版本」链接移除，管理员通过「管理」导航或后台内链访问

🐛 周序号修复

• 修复 周序号算法：去掉 +2 偏移，改为按 Sun-Sat 周习惯（W1 = 该年第一个周日）计算
• 修复 之前偏差约 2 周，例 2026-06-07 从显示 W25 修正为 W23
• 部署 v4.0.4+v4.0.5 前端静态文件补上线，线上同步到 v4.0.6

🆕 周运目标周显示

• 新功能 周运牌阵显示年周与日期范围，例如 26-W25 · 2026.6.7-2026.6.13
• 新功能 weekly_summary 保存 weekInfo，历史还原优先使用保存时的目标周
• 新功能 起课历史列表的周运记录显示对应年周和日期范围

🔧 全栈验收修复

• 修复 主页面、用户页、版本页静态资源缓存版本统一到 v4.0.4
• 修复 AI 解读与起课详情改为安全文本渲染，避免历史内容注入 HTML
• 修复 手动保存起课改为等待接口结果后提示，不再提前提示已保存
• 修复 /api/wenxin 自动保存补充周运服务端限频，防止绕过 /api/readings 重复保存本周周运

🆕 周运拦截 + 筛选搜索

• 新功能 周运抽牌前置检查，本周已有记录则禁止重抽
• 新功能 起课列表分类筛选：全部 / 周运 / 太极 / 两仪 / 三才
• 新功能 关键词搜索（搜问题/牌类/AI解读）
• 新功能 日期范围筛选
• 后端 readings.py +q / +date_from / +date_to

🆕 周运保存 + 还原修复

• 新功能 周运抽完最后一日弹出保存确认
• 修复 保存完整度升级：全量牌数据 + topicKey + 牌组模式 + 周运摘要
• 修复 周运还原样式：重建 weeklyState → 弧形牌阵
• 修复 三才分离模式 saveReadingIfLoggedIn 未定义 bug

🆕 删除 + 还原到牌阵

• 新功能 起课记录删除（列表 + 详情页，确认弹窗）
• 新功能 起课记录还原到牌阵（详情页 → 首页完整渲染）
• 新功能 保存确认弹窗 + 两个手动保存按钮

🆕 用户系统

• 新功能 手机号 + 密码注册 / 登录
• 新功能 个人中心（用户信息 · 起课列表 · 详情还原）
• 新功能 起课自动保存（登录后调 AI 自动存）
• 新功能 周运限频（登录用户每周一次，周日清零）
• 新功能 管理员后台（查用户 · 重置密码 · 封禁 · 统计）

🔧 技术变更

• 后端 拆文件：models.py / auth.py / readings.py / admin.py（1317 行）
• 数据库 SQLite（wenxin.db），3 表
• 鉴权 JWT（access 15min + refresh 30d cookie）

🆕 周运牌阵

• 新功能 1 张总运 + 7 张日运，不重复，吉平凶评分
• 新功能 半圆布局 + 点击放大读象弹层
• 新功能 两仪紧凑一行布局（用在左体在右）
• 新功能 周运入口移到问事类型

🔧 配置

• 修复 M3→M2.7-hs（解决 3+ 张牌超时）
• 修复 nginx 180s 封顶链路
• 调参 max_tokens 10000 · timeout 180s

🆕 逐图牌义库

• 新功能 card-details.js（60 张牌逐图详解）
• 新功能 后端 Prompt 改版（固定解读顺序 · 应期条件语气）
• 新功能 读象/上中下层次按牌名匹配（速查表 + 课堂笔记双轨）

🆕 关系工具子系统

• 新功能 五行/地支/牌面三种查询模式
• 新功能 体用行动建议生成器
• 新功能 三合完成度检测

🆕 体用五级断语

• 新功能 3 级（吉/平/凶）升级到 5 级（大吉~大凶）
• 新功能 tiYongJudgement 函数统一处理
• 修复 地支五行替代天干作为生克计算基准

🆕 三才双牌组 + 抽牌简化

• 新功能 三才阵双牌组（统一 60 张 / 三套独立 12 张）
• 新功能 13 个问事类型（1 综合 + 12 单类）
• 优化 移除毫秒分组逻辑

🔧 五行重构

• 新功能 element 字段由天干定五行改为地支定五行
• 新功能 element-tag 展示地支单字
• 修复 两仪/三才生克同步用地支五行

• 初版上线（60 张文字牌 · 太极/两仪牌阵）
• LLM 接入（MiniMax→M3）
• HMAC token 自签鉴权 · 速率限制
• 三才阵 · 线下抽牌 · 牌库密码墙
• Fallback 机制（opencode-go deepseek-v4-flash）