docs: 归档生产部署任务 #299

docs/task/299-admin部署pdd反查与ai颜色建议版本到生产.md

@@ -0,0 +1,90 @@
+# 299 Admin：部署 PDD 反查与 AI 颜色建议版本到生产
+
+- 类型：部署
+- 父级大工单：#14
+- 所属 MVP / 版本：#291 / 蝦皮与 PDD 商品级颜色映射
+- 状态：已完成，待用户验收
+- 日期：2026-08-24
+- Gitea 工单：https://git.ilapage.cn/OPC/cmautobuy/issues/299
+
+## 背景与目标
+
+生产原来运行 `7d5f4e9`，尚未包含 #297 的 PDD 商品 ID 反查和 #298 的 AI 颜色建议
+人工确认。本任务把已提交并推送的固定提交 `96d9e30` 发布到生产，不修改数据库结构、
+生产配置、AI 密钥或业务数据。
+
+## 最终方案
+
+- 从固定提交 `96d9e30a580e07c05d397762f9b9b7f166b13cfd` 的 Git 归档构建，未带入
+  当前工作区未提交的 Client 文件、本地 `config.yaml`、环境文件或密钥。
+- 第一份只导出 `admin/` 的隔离源码缺少根目录 `testdata/contracts`，契约测试因此找不到
+  测试向量；随后改为导出同一提交的完整仓库并重新执行全部验证，未修改代码或测试。
+- 使用 Go 1.23.0 完成 build、test、vet，再以 Linux amd64、`CGO_ENABLED=0`、
+  `-trimpath -ldflags="-s -w"` 生成静态发布物。发布物大小为 28,319,896 字节，
+  本地、上传、release 和生产 SHA-256 均为
+  `a89b9929a0c58b1b6f703b7b2845a9f320bad32aaa9db370b3a93a7915498d1d`。
+- 切换前确认 schema 为 v30，顺运宝同步、商品目录导入、AI 批量匹配和档口入库码后台
+  活动任务均为 0。
+- 使用 `mysqldump --no-defaults --no-tablespaces --single-transaction` 创建 gzip
+  逻辑备份，验证 gzip、0600 权限、文件大小、SHA-256 和 34 个建表段。
+- 发布到 `/opt/cmautobuy/releases/96d9e30/`，其中 `config.yaml` 和 `data` 分别链接
+  到稳定 `/opt/cmautobuy/config.yaml` 与 `/opt/cmautobuy/data`，没有复制或替换配置、
+  AI 密钥和数据目录。
+- 在空闲端口 18083 以生产账号和生产环境变量完成启动预检。最初两次命令兼容性检查因
+  服务器旧版 `setpriv` 参数和二进制字符串检查方式不适用而在切换前停止；第三次发现
+  AI POST 路由受 CSRF 保护返回 403 而不是预期 303，也在切换前停止。改用服务器支持
+  的参数和真实 HTTP 状态语义后预检通过，期间没有触发 AI 调用或业务写入。
+- 原子切换稳定二进制链接并重启 systemd。首次切换脚本在服务已健康后，因服务器旧版
+  `systemctl` 不支持 `show --value` 而提前退出；随后使用兼容命令完成全部不变量检查，
+  稳定链接和实际进程均确认指向新 release，因此无需回退。
+- 上一 release `7d5f4e9` 保留，可直接进行二进制回退。本版本没有数据库迁移，schema
+  始终保持 v30。
+
+## 改了哪些
+
+- `/opt/cmautobuy/releases/96d9e30/cmautobuy-admin`：新增并启用生产二进制，权限
+  0750，属主 `cmautobuy:cmautobuy`。
+- `/opt/cmautobuy/releases/96d9e30/config.yaml`、`data`：分别链接到稳定配置文件和
+  数据目录。
+- `/opt/cmautobuy/cmautobuy-admin`：稳定链接从 `7d5f4e9` 原子切换到 `96d9e30`。
+- `/opt/cmautobuy/backups/autobuy-before-299-20260824T083950Z-notablespaces.sql.gz`：
+  部署前逻辑备份，83,499,647 字节、权限 0600、34 个建表段，SHA-256 为
+  `a04341b7c0b0cf2f126f682e55ea40edc7b038d5ca6abf4ef279c7eeb08bcac0`。
+- 生产 MySQL：未执行迁移，`schema_migrations` 保持 v30，业务数据未主动改动。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 发布物来自固定提交，本地、上传、release 和生产 SHA-256 一致 | 通过 |
+| Go 1.23.0 build、test、vet 全部通过 | 通过 |
+| 切换前后台活动任务为空，schema 保持 v30 | 通过 |
+| 部署前备份通过 gzip、权限、大小和建表段检查 | 通过 |
+| 独立端口预检通过，配置、数据目录和 AI 密钥未替换 | 通过 |
+| systemd active/enabled，进程和稳定链接均指向 `96d9e30` | 通过 |
+| 18080、Nginx、本机及公网 HTTPS 检查正常 | 通过 |
+| PDD 反查代码与 AI 建议路由、静态脚本已随新版本上线 | 通过 |
+| 上一 release `7d5f4e9` 保留，可进行二进制回退 | 通过 |
+| 未触发同步、AI 调用、采集、采购、下单或付款 | 通过 |
+
+## 测试
+
+- 执行的命令：在固定提交的完整隔离源码 `admin/` 下以 Go 1.23.0 执行
+  `go build ./...`、`go test ./... -count=1`、`go vet ./...`，再以
+  `GOOS=linux GOARCH=amd64 CGO_ENABLED=0` 构建发布物；服务器执行 SHA-256、
+  `mysqldump`、`gzip -t`、schema 与活动任务查询、18083 独立端口预检、`systemctl`、
+  `ss`、`nginx -t` 和日志检查；本机执行公网 HTTPS 检查。
+- 结果：生产稳定链接和实际进程均指向 `96d9e30`；schema 为 v30；systemd
+  active/enabled；本机与公网根路径、登录页、颜色匹配路由和颜色脚本为
+  303/200/303/200；AI 建议 POST 在未登录且无 CSRF 时为 403，未知 POST 路由为 404；
+  启动日志没有 fatal、panic、迁移失败或 schema 自检失败；发布后四类后台任务仍为 0。
+- **没验证到的部分**：未使用生产账号登录后视觉验收 PDD 商品 ID 反查和 AI 建议按钮；
+  未实际调用生产 AI 模型、保存颜色映射或进入后续 SYB 采购链路；未实际执行二进制回退
+  或数据库备份恢复。
+
+## 相关提交
+
+- `2f76ff1` feat: 支持按 PDD 商品 ID 反查蝦皮商品 (#297)
+- `fb9a6a1` docs: 归档任务 #297
+- `943dbdb` feat: 增加 AI 颜色建议人工确认 (#298)
+- `96d9e30` docs: 归档任务 #298（本次固定发布基线）