# 发布就绪清单

更新时间：2026-06-16

## 当前完成口径

本清单用于区分“已经可验证的生产底座”和“仍需专项验收的上线阻断项”。每次发布前按本文件更新状态，避免凭感觉上线。

## 本轮生产收口硬门槛

- 真实配置基线来自 `handoff/server-secrets-upload/.env.production`，已同步为本机根目录 `.env.production`；密钥包目录已加入 `.gitignore` / `.dockerignore`。
- 生产开关必须保持关闭：`ENABLE_DEV_AUTH_CODE=false`、`ENABLE_DEV_ADMIN_TOKEN=false`、`ENABLE_DEV_PAYMENT=false`。
- 生产配置必须通过 `node backend/scripts/production-env-audit.mjs .env.production`，该脚本只输出 set/empty/placeholder，不输出密钥值。
- 生产源码必须通过 `node scripts/audit-production-sentinels.mjs`，禁止用户可见 mock、自动填 demoCode、历史种子账号文案和“待上传”占位残留。
- 品牌 logo 使用固定公共文件记录 `/api/files/d1b1d1b1-2026-4000-9000-000000000001`，部署迁移后必须执行 `backend npm run files:ensure-brand-logo` 或通过 `db:migrate:lite` 自动补齐对象存储文件。
- Caddy 公网必须阻断 `/api/metrics`；Prometheus 仍从内网 `backend:4000/api/metrics` 抓取。
- 登录、onboarding、login-required、员工工作台 redirect 只允许内部路径，拒绝外链、`//` 和协议型跳转。
- 真实短信、小程序微信登录、PC 扫码登录、微信支付、S3/MinIO 上传、核销扫码、数据服务交付文件必须完成试运行验收。

## 当前工作区基线

- 当前工作区变更总数：270
- 修改文件：133
- 未跟踪文件/目录：115
- 删除文件：22
- macOS 元数据：0
- QA 产物：`qa-artifacts/` 已加入 `.gitignore`，不进入发布提交
- 分组提交边界见 [docs/RELEASE_BASELINE_GROUPS.md](docs/RELEASE_BASELINE_GROUPS.md)

## 已落地

- 手机号验证码账号收口：超级管理员手机号初始化、员工/管理员验证码登录、已知密码入口禁用。
- 小程序微信注册与 PC 小程序码登录链路：小程序微信身份、手机号绑定、资料 onboarding、PC 扫码会话。
- 微信支付基础链路：小程序 JSAPI、PC Native、微信回调验签解密、支付状态查询、本地 dev 支付隔离。
- Web 全局错误体验：`error.tsx`、`loading.tsx`、`not-found.tsx`，避免全站白屏。
- 生产部署骨架：Docker Compose、Backend/Web Dockerfile、Caddy 反代、生产环境样例、Makefile。
- CI 骨架：后端迁移/类型检查/单元测试/业务闭环、Web lint/build/Playwright smoke、小程序 typecheck/build、Compose 配置检查。
- 健康检查：`/api/health`、`/api/health/deep`，对象存储会做真实 put/get/delete 探测。
- 监控基础：`/api/metrics`、结构化请求日志、Sentry DSN 轻量上报、Prometheus/Grafana/Alertmanager Compose 配置。
- 后台异常处理中心：`/admin/exceptions`，支持查看、处理中、记录重试、解决、忽略。
- 系统状态页面：`/admin/system`。
- 对象存储迁移脚本：`backend npm run files:migrate:s3`。
- 品牌 logo 已从 Web/小程序本地打包引用收口到后端公共文件接口；生产使用 S3/MinIO 时由 `backend npm run files:ensure-brand-logo` 写入对象存储。
- Prisma 第二批低风险迁移继续推进：用户 session、上传文件记录、发票申请主链路已切到 Prisma repository；`business-pg.mjs` 中 SQL 使用量降至 `queryJson 228 / executeSql 87 / sqlLiteral 1046`。
- 文件权限收口：新上传的商品/站点资产默认公开；发票、数据服务交付、专家材料、用户附件默认私有并按 owner 鉴权；文件对象缺失会写入异常中心。
- 异常中心事件补强：支付超时、支付成功但订单未同步、订单已支付但权益缺失、发票长期待处理/失败、权益发放失败会自动入库。
- 第二波开发收口继续推进：前台商品读取、会员/智能体/课程/活动/数据目录读取、用户/后台订单读取、支付状态与后台支付读取、发票导出行查询已迁到 Prisma 参数化 repository。
- `business-pg.mjs` 旧 SQL 使用量继续下降至 `queryJson 207 / executeSql 86 / sqlLiteral 992`。
- 文件治理补强：上传接口支持受控 owner 类型；公共资产和私有材料按白名单分流；数据服务交付文件绑定 request owner；异常中心会扫描本地/S3 文件对象缺失。
- 对象存储健康探测失败会写入 `file.storage.probe_failed`，下载或扫描缺失文件会写入 `file.object.missing`。
- 第三波交易核心收口：`createOrder` 写入、`createPaymentOrder` 创建/初始化、`markPaymentSucceeded` 支付成功、权益发放、优惠券核销、会员订阅、专家结算已迁入 Prisma 参数化事务 repository；微信外部请求仍保持在事务外。
- 支付成功幂等补强：支付单和订单行在事务中锁定；重复 dev 支付成功/微信回调不会重复发权益、重复核销优惠券或重复生成结算记录。
- `business-pg.mjs` 旧 SQL 使用量继续下降至 `queryJson 197 / executeSql 69 / sqlLiteral 880`，业务闭环回归已覆盖会员支付重复成功路径。

## 开发机与生产 QA 分工

- 当前开发机不再强制跑完整 Docker Compose 生产模拟。原因：本机系统盘空间不足，Docker/Colima 在构建 backend 镜像时反复出现 BuildKit/containerd `input/output error`，属于本机容器存储环境问题，不是项目代码错误。
- 开发机本地门禁保留：Prisma validate、Prisma generate、backend typecheck/unit/business-closure、web lint/build/e2e、miniapp typecheck/build、`docker compose config`。
- 完整 Docker 启动、HTTPS、微信真支付、回调、MinIO 持久化、Grafana/Alertmanager/Sentry、备份恢复演练交给生产服务器内 QA Agent 执行。

## 上线阻断项

- 本机 `.env.production` 已按 handoff 真实配置同步；服务器部署前仍需确认同源配置已落地，且密钥未进入 Git、镜像或日志。
- 生产服务器尚未完成 Docker Compose 实机启动、HTTPS 证书签发、域名解析、微信支付回调公网验收。
- 小程序真机全流程还未完成：微信登录、绑定手机号、onboarding、JSAPI 支付、PC 扫码确认。
- 微信支付至少需要完成 1 笔小额真实支付，并确认回调后订单与权益状态正确。
- 文件仍有本地上传兼容路径，MinIO/S3 写入已有主动探测和迁移脚本，但所有业务文件场景仍需实机逐项验收。
- 后端业务 SQL 仍大量在 `business-pg.mjs` 通过旧 helper 执行，Prisma 全面迁移尚未完成；下一批应迁后台财务/对账、会员运营、专家/数据服务复杂工作流和剩余 checkout 前置校验。
- 交易核心已完成第三波参数化事务收口，但仍需在生产服务器用真实微信回调、小程序 JSAPI、PC Native 支付做全链路 QA。
- 监控告警配置已进 Compose，但生产 webhook token、Grafana 密码、Sentry DSN 和告警触发演练尚未在服务器完成。
- 备份恢复演练脚本/文档已有，仍需要在 staging 或临时 Compose 项目实跑一次。
- 当前 Git 工作区已完成第一波分组基线盘点，但发布前仍需按 [docs/RELEASE_BASELINE_GROUPS.md](docs/RELEASE_BASELINE_GROUPS.md) 分组 staging/提交，并逐组确认删除项。

## 发布前命令

```bash
make clean-macos
node backend/scripts/production-env-audit.mjs .env.production
node scripts/audit-production-sentinels.mjs
cd backend && npm run typecheck && npm run prisma:validate && npm run test:unit && npm run test:business-closure
cd ../web && npm run lint && npm run build && npm run test:e2e
cd ../miniapp && npm run typecheck && npm run build:weapp
docker compose --env-file .env.production config --quiet
make backup
```

完整生产 QA 任务见 [docs/PRODUCTION_QA_AGENT_CHECKLIST.md](docs/PRODUCTION_QA_AGENT_CHECKLIST.md)。

## 生产试运行验收

- 访问 `https://bigdata.dtacloud.cn` 首页、登录页、结算页、后台页。
- 访问 `https://bigdata.dtacloud.cn/api/health` 返回 `ok`。
- 访问 `https://bigdata.dtacloud.cn/api/health/deep`，数据库、短信、微信支付配置为 `ok`。
- 访问 `https://bigdata.dtacloud.cn/api/files/d1b1d1b1-2026-4000-9000-000000000001?v=original-logo` 能返回品牌 logo。
- 访问 `https://bigdata.dtacloud.cn/api/metrics` 经公网返回 404；Prometheus 内网仍能抓取。
- 新手机号在小程序完成微信登录、绑定手机号、资料填写。
- PC 端扫码登录能完成确认并自动进入用户态。
- PC Native 支付二维码能被微信识别。
- 小程序 JSAPI 支付能调起微信支付。
- 微信支付回调成功后，订单为 `paid`，支付单为 `succeeded`，权益只发放一次。
- 上传文件后重启 backend/web/minio，文件仍可访问。
- 人为访问不存在页面和触发错误页，无白屏、无布局重叠。

## 上线后 24 小时观察

- 5xx 错误数。
- 支付回调失败数。
- 支付单超过 10 分钟未确认数。
- 短信失败率和限流命中数。
- 数据库连接与慢查询。
- 磁盘空间和备份任务状态。
- 小程序真机用户反馈。
