98 lines
8.5 KiB
Markdown
98 lines
8.5 KiB
Markdown
# 反馈与消息联动发布清单
|
||
|
||
更新日期：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` 推断目标，也不把正式凭据写入本文。
|
||
|
||
```sh
|
||
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。代码回滚保留迁移后的字段、反馈、回复、审计和通知数据，禁止整表恢复。
|