airz-uniapp/docs/反馈消息发布清单.md

反馈与消息联动发布清单

更新日期：2026-10-05。本文记录0.57—0.59反馈闭环源码的发布范围、迁移、验收和回滚边界。本轮已完成后端生产发布；小程序端由用户自行发行。目标后端为 https://airz.hqling.cloud，生产目录为 /www/wwwroot/xctai.cn。

1. 发布范围

本次配套范围包括：

• 0.57后台反馈并发保护、CSRF、版本冲突和事务审计。
• 0.58会员反馈 requestId 回执、未知提交恢复和原键确认。
• 0.59反馈回复触发本人站内消息、消息目标跳转、通知去重及账户切换守卫。

本地发布包应只从下列清单取文件。前端与后端必须作为同一兼容批次安排；后端先发布并完成回执检查后，才能发行依赖 requestId 和反馈目标的前端。

明确排除：积分规则及积分表迁移、首页及内容功能的其他未提交改动、Home.php/HomeCatalog.php、首页测试、FAQ种子导入、私有附件、短信/数据/人工客服供应商接入，以及本仓库中与本批次无关的 Playwright 产物和 output/。不把当前工作树的其他改动带入发布包。

2. 精确文件清单

前端仓库 D:\WorkSpace\cyun\ai融资

文件	作用
packages/account/login/login.uvue	反馈目标登录白名单和登录后回跳
packages/account/messages/messages.uvue	分类消息、已读和反馈目标入口
packages/content/help/help.uvue	反馈列表、详情读取、原键确认和回复展示
packages/content/services/feedback.uts	requestId 回执、待确认持久化和反馈接口解析
services/cache-lifecycle.uts	账户切换、401 和退出时的缓存生命周期
services/messages.uts	消息分页、详情目标和反馈白名单路由

后端仓库 D:\AAdesk\202609\airz

文件	作用
application/admin/controller/Feedback.php	后台反馈表单的 CSRF、版本和安全投影
application/admin/library/FeedbackEditor.php	并发保护、权限复核、反馈/审计/通知事务
application/admin/model/AdminLog.php	安全审计字段及白名单日志投影
application/admin/view/feedback/edit.html	版本快照、CSRF 字段和冲突表单
application/common/library/FeedbackRecords.php	会员反馈 requestId 回执和本人读取
application/common/library/UserMessages.php	反馈回复通知及反馈目标归属校验
public/assets/js/backend/feedback.js	后台冲突提示、草稿保留和重试交互

迁移脚本 database/migrate_feedback.php 与 database/migrate_user_messages.php 仅用于目标结构预检或另行授权的增量迁移，不因出现在仓库中而自动随代码发布执行。

3. 数据库预检与迁移前置

发布前在明确的目标环境执行只读预检，命令中的 .env、主机、端口和库名必须由本轮维护记录明确填写；不从本机默认 .env 推断目标，也不把正式凭据写入本文。

php database/migrate_feedback.php \
  --env <explicit-env> --target <host:port/database>

php database/migrate_user_messages.php \
  --env <explicit-env> --target <host:port/database>

fa_feedback 需要确认 request_id、reply、handled_by、handled_at 四列，以及唯一索引 uk_user_feedback_request(user_id,request_id)；历史 request_id IS NULL 必须保留。fa_user_message 需要确认 uk_user_message_event(user_id,business_type,business_id)，并确认没有重复事件组。两项预检还应记录 MySQL 版本、InnoDB/字符集、重复组数量、当前行数和活动任务状态。

若字段或索引缺失：先阻断写入、停空闲 worker、确认无 processing/pending/streaming 任务，完成完整表结构和数据备份，再单独取得迁移授权。迁移只能使用脚本的显式 --apply --backup-dir，迁移后重跑预检并确认 changeCount=0；本轮准备工作不执行 --apply，也不自动修复重复键、错误索引或结构漂移。

4. 推荐发布顺序

1. 维护窗口开始后阻断后台写入，核对 airz-analysis、PHP-FPM、Redis/队列和错误日志；记录进程状态、队列计数、数据库目标和备份位置。
2. 完成上节两个只读预检。缺字段/索引时暂停代码发布，按授权单独迁移并复检。
3. 备份本批后端旧文件、fa_feedback/fa_user_message 结构和必要行摘要；保存新文件 SHA-256。备份不能替代迁移脚本的结构核对。
4. 先发布后端精确清单，刷新 PHP-FPM/OPcache，确认旧接口仍能鉴权和读取，随后验证新的反馈回执及消息接口。
5. 做后端冒烟：新反馈返回相同 requestId；同键重放返回原记录当前状态；旧后台页面缺 CSRF/版本时拒绝保存；版本冲突不覆盖草稿；有效回复只产生一条本人通知；重复保存、修订和后续关闭不重复通知；消息目标只能打开本人的反馈。
6. 后端冒烟通过后，重新编译前端并更新 H5/小程序体验版本。前端发行必须包含本清单的全部六个文件，不能只更新消息页或帮助页。
7. 做前端冒烟：消息分类分页、已读水位、通知跳转、第一页之外反馈读取、登录回跳、账户切换、退出/401、迟到响应、原键确认和反馈列表局部重试；再检查控制台错误、页面横溢和关键截图。
8. 恢复 worker 与入口，观察队列、PHP-FPM、通知错误和 FEEDBACK_*/MESSAGE_* 业务码；维护窗口结束后记录实际版本、证据和剩余风险。

5. 兼容性矩阵

后端	前端	结果
旧0.55	旧前端	既有流程保持；不含本批新能力
旧0.55	新0.58/0.59前端	新反馈成功可能已入库但缺 requestId 回执，页面会持续待确认；禁止发行
新0.57—0.59	旧前端	旧会员请求没有 requestId，新接口会拒绝；旧后台页面缺 CSRF/expectedVersion 不能继续保存
新后端	新前端完整批次	目标组合；仍需完成迁移预检、后端冒烟和前端发行检查
新后端仅后台文件	新会员前端缺消息/反馈文件	回复通知可以落库，但用户不能可靠跳转或确认；禁止拆开发行

数据库结构未确认前，不把“源码无新增 DDL”当作线上已兼容。反馈四列和消息唯一索引是本批接口行为的前置条件。

6. 回滚边界

代码故障时先阻断写入并恢复本批前的后端文件，刷新 PHP-FPM/OPcache，再按旧前端版本回退 H5/小程序；保留新增反馈、回复、审计和通知行，避免用户已看到的业务结果消失。回退后仍需检查旧接口不会误读新目标字段。

不得整表覆盖 fa_feedback 或 fa_user_message，不得用旧备份覆盖发布后的新写入，不得因为代码回退而删除通知、已读时间或反馈处理记录。新增字段和唯一索引默认保留；只有单独审查迁移备份、确认旧代码和数据均不再依赖后，才可讨论 DDL 回退，本文不默认执行 DROP INDEX 或删列。

前端发行回退不等于数据库回退。回退记录必须包含实际代码版本、前端版本、迁移状态、备份位置、已保留业务数据和复验结果。

7. 当前状态

2026-10-05 已在维护窗口内通过宝塔 Playwright 完成明确生产目标 111.230.144.231:3306/airz 的迁移与后端发布。完整私密备份为 /root/airz-feedback-release-20261005-114514；fa_feedback 四列及唯一索引已补齐，fa_user_message 唯一索引保持存在，迁移后预检为 missingFields=[]、indexExists=true、duplicateGroups=0、changeCount=0。迁移行摘要备份为 /root/airz-feedback-release-20261005-114514/migration/feedback-20261005-115239-3e7a68c4.json。

已按精确清单发布 7 个后端文件，发布包 SHA-256 为 597A2BC55D8877FCA5EFC205C1B0761D14B0B1E614196DD7C1C1FF7B8775D4B3；线上文件哈希与发布包一致，PHP 7.4 lint 通过，权限为 644 root:root。php-fpm-74、redis、airz-analysis 已恢复 active，Redis 认证后分析队列为0，worker 发布后无 warning/error 日志。

只读烟测通过：/api/v1/home=200；匿名 /api/v1/messages、/api/v1/products、/api/v1/points 均为401；后台反馈入口返回登录页；/.env=404。未创建真实反馈或回复；临时发布包、迁移脚本、临时 env、解压目录和烟测响应已清理。小程序端由用户自行发行，本轮未提交、未推送、未创建 PR。代码回滚保留迁移后的字段、反馈、回复、审计和通知数据，禁止整表恢复。