一、升级总览

模块	升级内容	状态
后端修复	附件删除根因修复（路径基准 + 引用防误删）	✅ 已完成，用户确认
后台管理	移动端抽屉导航、站点设置拆 4 菜单、表格适配	✅ 已完成（上传服务器生效）
正文渲染	文本段 / 图片段拆分，rich-text + image 混合渲染，样式完整保留	✅ 已过集成测试
主题系统	白天 / 黑夜主题、右下角切换浮窗、后台默认方案实时下发	✅ 已完成
底部菜单	抽成全局组件 + 后台上移 / 下移排序 + 显示数量可配	✅ 已完成
公众号引导	关注引导组件（入口条 + 自动弹窗），后台整板块配置	✅ 已完成
登录 / 冷启动	5 次渐进重试、登录就绪队列、401 自动重登、朋友圈单页模式	✅ 已完成
首页翻页	无限滚动改显式翻页，每页条数后台可配（5-50）	✅ 已完成
封面图	正文首图自动提取作封面（懒迁移回写）	✅ 已完成
数据库	自动迁移体系，结构版本升至 V10	✅ 已完成
发布物料	发布文章（飞书文档）+ 3 张科技风配图	✅ 已交付

---

二、2026-09-07・发布物料与基础代码

1. 发布文章（营销侧，未改程序逻辑）

• 为小程序撰写发布文章，交付为飞书文档，含：简介、8 大功能、对比、适用人群、备选标题与内容验真。
• 配置 3 张「深空蓝铂金科技风」配图（公众号头图 2.35:1 / 竖版宣传图 9:16 / 功能流程图 16:9），存放于 D:\桌面\图文小程序\小程序发布配图\。

2. 基础代码新增

• 新增 server/api/auth_token.php：统一 token 校验中间件，解析 X-Token 头换取 openid；无令牌时以 guest 游客身份放行只读接口（为朋友圈单页模式铺路）。
• 新增 miniprogram/utils/request.js：统一请求封装，401 自动重新登录并重放原请求（最多重试一次），解决刷新 / 轮询偶现 “缺少访问令牌 / 登录已失效”。
• 新增 miniprogram/components/follow-mp/：引导关注公众号组件骨架。

---

三、2026-09-08・后端修复与数据库

1. 附件删除根因修复（server/auth.php）⭐

• 路径基准修正：删除文件统一以 __DIR__（即 server/ 目录）为基准拼接，修正此前 dirname(__DIR__) 造成的路径偏差 —— 上传保存与删除路径首次统一。
• 引用检查防误删：删除前依次检查该图片是否仍被以下内容引用，仍被引用则自动跳过：
• 文章封面（images JSON 数组）
• 文章自动提取封面（cover 字段，兼容完整网址 / 相对路径）
• 文章正文富文本（content 中的 <img src>）
• 幻灯片（banners）、自定义广告（ads）
• 公众号二维码（settings.mp_qrcode）
• 调用约定：调用方先删自身记录、再调删除函数，引用检查才准确；admin/api.php 删除文章、编辑保存、删除幻灯片 / 广告均已接入。

2. 数据库自动迁移体系完善（server/db.php / server/schema.php / server/upgrade.php）

• SCHEMA_VERSION 提升至 10，.schema_version 标记文件 + 幂等执行：代码升级后首次请求自动补齐新表 / 新字段，无需手工建表。
• 本次新增字段：

表	字段	版本	说明
articles	cover	V10	封面图；未单独上传图片时自动取正文第一张图
notices	direction / color	V5	公告滚动方向（左右 / 上下）、文字颜色
banners	miniapp_id / miniapp_path	V7	幻灯片跳转其它小程序
tabs	miniapp_id / miniapp_path	V8	底部菜单跳转其它小程序
categories	home_show	V9	1 = 主页显示 0 = 仅栏目内查看

• 空库自动初始化：默认分类 “默认”、默认底部菜单 “首页”、站点设置默认键值（含新增的 list_page_size、tab_count、theme_default、image_threshold_mb、image_target_kb 等）。
• upgrade.php 保留手动触发入口（删除标记文件→强制完整迁移），迁移完成后应删除该文件。

3. 封面图自动提取（懒迁移）

• extract_first_image()：从正文 HTML 提取第一张图（兼容 wangEditor 任意属性顺序与单双引号）。
• list.php / detail.php：images 为空且 cover 为空的历史文章，按页懒提取正文首图并回写数据库，一次写库永久生效。
• 列表 / 详情展示优先级：单独上传的图片（images[0]）＞ 正文首图（cover）。

---

四、2026-09-08・后台管理升级（server/admin/）

1. 移动端适配大改版（index.html）

• 抽屉导航：手机 / 平板下侧边栏收起，汉堡按钮 + 左侧滑出抽屉 + 遮罩点击关闭，切换视图后自动收起。
• 表格适配：单行省略号防撑破、操作列 sticky 固定、横向滚动。
• 桌面端样式不变，原有菜单 id 全部保留。

2. 站点设置拆 4 个菜单，分板块提交 ⭐

• 「站点设置」拆为独立菜单：

1. 站点信息：站点标题、SEO 关键词 / 描述、备案号
2. 图片处理：自动压缩开关、最大宽度、质量、强制压缩阈值（超过 X MB 压到 Y KB 以内）
3. 前台与主题：列表每页条数（5-50）、列表显示封面开关、底部菜单显示数量（1-5）、小程序默认主题方案（白天 / 黑夜 / 跟随系统）
4. 公众号引导：二维码、公众号名称、简介、引导文案、自动弹窗开关

• 提交方式改为 saveSettings(part) 分板块提交，互不覆盖。

3. 底部菜单管理增强（api.php）

• 新增 tab_move 动作：底部菜单上移 / 下移排序（重新连续编号 sort，越靠前越大）。
• 菜单列表显示顺序编号；最多显示数量由「站点设置 → 底部菜单显示数量」控制（1-5）。

4. 分类管理

• 新增主页显示开关（home_show）：可控制某个栏目是否出现在小程序主页，设为 “仅栏目内查看” 后主页列表自动过滤（list.php 首页模式过滤 home_show=1 的分类，未分类文章始终显示）。

5. 公告管理

• 新增滚动方向（左右跑马灯 / 上下纵向切换）与文字颜色选择器（可勾选 “使用默认色”）。

6. 图片上传与压缩

• 封面图支持一次多选（单次上限 20 张）逐张上传；富文本编辑器插入图片同样支持多选依次插入。
• 强制压缩策略：超过阈值（默认 1MB）自动逐步降质量 / 尺寸至目标大小（默认 500KB），二分法找最优质量，尽量保留画质。

---

五、2026-09-08・小程序端升级（miniprogram/）

1. 正文渲染重构（核心）⭐

背景：小程序 rich-text 内的图片无法长按保存 / 预览；纯原生 view/text 嵌套又触发渲染层 diff 异常。

最终方案（已过集成测试）：

• 后端 detail.php 把正文按原文顺序拆分为 “文本段 / 图片段”（blocks 数组）：
• 图片段：独立 <img> 标签逐张拆出，URL 转绝对地址；
• 附件上传的封面图作为图片段置于开头，与正文重复的图自动去重（同一张图不出现两次）；
• 同时从 content 中移除 <img>，兼容旧版前端。
• 前端 detail.js（buildRenderBlocks）：
• 图片段 → image 组件：支持长按保存 / 预览 / 扫码；
• 文本段 → 样式增强 HTML 交给 rich-text 渲染（原生组件节点树自管，规避多层 view/text 嵌套的 diff 异常）。
• 样式增强（ensureRichHtml）：
• 完整保留后台发布的对齐 / 字号 / 颜色 / 粗斜体 / 引用 / 标题 / 列表内联样式；
• 未显式设色的文字跟随主题（白天 #333 / 黑夜 rgba(255,255,255,.88)），theme-dark 时重算；
• 给无 margin 的块级标签（p/div/h1-6）补默认段距，rich-text 渲染更接近后台排版。
• 排查过程留档：初版用原生 view/text + 解析器渲染，遇渲染层 diff 异常 → 复查 wx:key 确认非根因 → 改为 rich-text 兜底 + 渲染节点 id 全局自增保证唯一 → 移除 text space=”nbsp”、&nbsp;/<br> 改普通空格、空 style 注入 font-weight:normal。
• 遗留：微信开发者工具 3.16.2 模拟器存在已知渲染 bug，若复测仍报，需真机预览验证。

2. 主题系统（全新）⭐

• 优先级：用户手动选择（storage theme_mode）＞ 后台默认方案（theme_default：light/dark/system）＞ 跟随系统。
• 后台「前台与主题」改 theme_default 后，小程序轮询实时应用（未手动选过时）。
• 右下角太阳 / 月亮切换浮窗（theme-switch 组件）：点击白天↔黑夜；页面滚动时浮标自动隐藏，停止滚动 300ms 后恢复（onPageScroll 驱动）。
• 页面 / 组件通过 app.onThemeChange() 订阅主题变化，注销回调自动清理；tabbar 组件直接使用色值自管理，不依赖页面变量继承。

3. 底部菜单全局化（tabbar 组件）

• 底部菜单抽成全局组件，首页、文章详情页等所有页面统一显示（app.json 注册 + 各页挂载）。
• 首页内点击通过事件原地切换分类；其它页面点击 reLaunch 回首页并定位对应菜单（?tab=<菜单ID>）。
• 支持类型：首页 / 分类列表 / 网页（webview）/ 其它小程序（navigateToMiniProgram）。
• 轮询周期自动刷新组件数据：后台改菜单内容 / 数量后数秒内实时生效。

4. 公众号引导（follow-mp 组件）

• 首页轮播下方点击引导入口条（仅首页 showEntry 显示）；自动弹窗：延迟 1.5s 弹出一次，当天关闭后不再自动弹（storage 记录日期）。
• 后台「公众号引导」整板块配置：二维码、名称、简介、引导文案、自动弹窗开关；未配置二维码则整组件不显示。
• 单页模式（朋友圈）不自动弹，保留入口条点击。

5. 登录与冷启动增强（app.js / request.js / auth_token.php）⭐

• 5 次渐进式重试：wx.login 失败 / 未返回 code / 服务器业务错误 / 网络失败，均按 800/1600/2400/3200/4000 毫秒渐进重试，修复体验版从朋友圈、分享链接冷启动时 “微信登录失败”。
• 登录就绪队列（ensureReady）：已有 token 立即执行；登录中则排队等待；失败回调具体原因。修复分享链接冷启动 “缺少令牌”。
• 401 自动重登防并发（relogin）：多个请求同时 401 只触发一次登录，完成后统一重放请求，避免互相覆盖 token。
• 朋友圈单页模式（场景 1154）：wx.login 不可用，检测后以游客（guest）身份访问只读接口（列表 / 详情预览），页面引导 “前往小程序”，不再卡死加载中。
• 失败展示优化：列表页 / 详情页显示失败原因 + 「重试」按钮，替代永久 “加载中”。

6. 首页显式翻页

• 无限滚动改为显式翻页：上一页 / 页码 / 下一页，翻页自动回顶。
• 每页条数由后台「站点设置 → 列表每页显示条数」控制（5-50，服务端强制区间）。
• 轮询检测到新增 / 修改文章后静默刷新当前页（不打断浏览位置），并同步首页配置（幻灯片 / 菜单 / 开关实时生效）。

7. 公告组件（notice）

• 公告升级为全局组件，首页、详情页等所有页面顶部统一显示；左右 / 上下滚动 + 文字颜色由后台配置。
• 拉取公告等登录完成后再请求（ensureReady），修复冷启动无 token 拉取失败。

---

六、后台配置实时生效清单

以下配置在小程序轮询时自动检测变化并刷新，无需重新发布小程序：

配置	生效效果
站点标题	状态栏标题 + 分享标题实时更新
默认主题方案	未手动选过主题的用户立即应用新主题
列表显示封面开关	变化立即刷新列表（关闭时不下发图片数据，省流量）
分类主页显示	变化立即刷新列表
底部菜单内容 / 数量	组件数据刷新，数秒内生效

---

七、数据库自动迁移说明

• 覆盖上传新版 server/ 后无需手动建表：首次请求自动补齐新表与新字段，版本标记在 .schema_version。
• 也可访问 https://你的域名/upgrade.php 手动触发一次并查看结果，完成后删除 upgrade.php。
• 迁移幂等、可重复执行；失败不阻断请求，问题在具体接口中暴露（如数据库账号无 ALTER 权限）。

---

八、涉及文件清单

后端（server/）

文件	改动
auth.php	附件删除根因修复（__DIR__ 基准 + 引用检查防误删）
db.php	自动迁移体系，SCHEMA_VERSION=10，封面懒提取函数
schema.php	统一建表定义（含 cover /direction/color /miniapp/home_show）
upgrade.php	手动升级入口（强制完整迁移）
api/auth_token.php	【新增】token 校验中间件，游客 guest 放行只读接口
api/home.php	首页配置下发（tab_count 数量控制、theme_default 等）
api/list.php	显式翻页 + 每页条数可配 + 封面懒迁移 + home_show 过滤
api/detail.php	正文拆 blocks（文本段 / 图片段）、封面懒提取
admin/index.html	移动端抽屉、表格适配、站点设置拆 4 菜单
admin/api.php	tab_move 排序、home_show、多图上传、公告颜色 / 方向、附件清理接入
admin/ads_api.php	广告位接口配套更新

小程序端（miniprogram/）

文件	改动
app.js	主题体系、登录重试、ensureReady /relogin、单页模式
utils/request.js	【新增】统一请求封装 + 401 自动重登重放
pages/index/	显式翻页、轮询刷新、主题、封面开关、分类签名
pages/detail/	正文分段渲染（rich-text + image）、主题重算、错误重试
components/tabbar/	【新增】全局底部菜单组件
components/theme-switch/	【新增】主题切换浮窗（滚动隐藏）
components/notice/	全局公告组件（方向 / 颜色）
components/follow-mp/	【新增】公众号引导（弹窗 + 入口条）
app.wxss / 各页 wxss	主题样式、组件样式

---

九、部署与验证状态

项	状态
server/auth.php 附件删除修复	✅ 已完成，用户确认
server/admin/（index.html / api.php）	✅ 已迭代完成，待上传服务器生效
正文渲染（detail.php + detail.js）	✅ 已过集成测试（PHP/JS 语法、字段一致性）
小程序端编译	⏳ 待重新编译验证（开发者工具）
数据库迁移	⏳ 上传 server/ 后首次请求自动完成（或手动运行 upgrade.php）

建议上线步骤：

1. 覆盖上传新版 server/ 到服务器；
2. 访问一次首页接口（或 /upgrade.php）触发数据库自动迁移，确认后删除 upgrade.php；
3. 微信开发者工具重新编译小程序，验证：正文样式与图片长按保存、主题切换、底部菜单、翻页、冷启动登录；
4. 若模拟器正文仍报渲染错误，用真机预览验证（3.16.2 模拟器已知渲染 bug）。

遗留事项：

• 开发者工具模拟器正文渲染异常：已确认 wx:key 非根因，最终方案为 rich-text 兜底，需真机复测确认。