update

app/AGENTS.md

@@ -88,8 +88,8 @@ OSS_ENDPOINT、OSS_BUCKET_NAME、OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET、OSS
 
 - 自动部署接口为 `/deploy/webhook`，生产环境通常通过 Nginx 映射为 `/api/deploy/webhook` 给 Gitea 调用。
 - Gitea Webhook 应配置 `Secret`，后端会按原始请求体校验 `X-Gitea-Signature` 的 HMAC-SHA256 签名；也兼容 `X-Hub-Signature-256`。
-- 部署配置通过 `.env` 或环境变量提供：`DEPLOY_WEBHOOK_SECRET`、`DEPLOY_PROJECT_DIR`、`DEPLOY_FRONT_DIR`、`DEPLOY_BRANCH`、`DEPLOY_SCRIPT_PATH`、`DEPLOY_COMMAND_TIMEOUT`、`DEPLOY_LOCK_PATH`；如 webhook 进程拿到旧 Node，可设置 `DEPLOY_NODE_BIN_DIR` 指向新 Node 所在目录。
-- 部署脚本为 `scripts/deploy_front.sh`，负责在服务器项目目录执行 `git pull`、进入前端目录安装依赖并执行 `pnpm build`。
+- 部署配置通过 `.env` 或环境变量提供：`DEPLOY_WEBHOOK_SECRET`、`DEPLOY_PROJECT_DIR`、`DEPLOY_FRONT_DIR`、`DEPLOY_BRANCH`、`DEPLOY_SCRIPT_PATH`、`DEPLOY_COMMAND_TIMEOUT`、`DEPLOY_LOCK_PATH`、`DEPLOY_LOG_PATH`；如 webhook 进程拿到旧 Node，可设置 `DEPLOY_NODE_BIN_DIR` 指向新 Node 所在目录。
+- 部署脚本为 `scripts/deploy_front.sh`，负责在服务器项目目录执行 `git pull`、进入前端目录安装依赖并执行 `pnpm build`；webhook 接口只投递后台任务并立即返回 `202 accepted`，构建结果查看 `DEPLOY_LOG_PATH`。
 - webhook 密钥不得写入源码或文档；`.env.example` 只能保留占位值。
 
 ## 验证
@@ -113,3 +113,4 @@ OSS_ENDPOINT、OSS_BUCKET_NAME、OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET、OSS
 - 2026-07-23：商品模型新增 `description` 商品描述字段，后端补充 `products.description` 轻量迁移、Pydantic 模型和 `/products` CRUD 读写。验证：后端编译通过，运行态接口测试待安装 `bcrypt` 后执行。
 - 2026-07-23：新增微信支付 JSAPI 预下单和支付通知处理，增加 `payment_transactions` 支付流水表、微信支付 API v3 签名/通知验签/回调解密工具和配置占位；`requirements.txt` 新增 `cryptography`。验证：后端编译通过，真实预下单和通知验签待填写微信商户配置后联调。
 - 2026-07-27：新增自动部署 webhook 模块，`/deploy/webhook` 支持 Gitea HMAC 签名校验、部署分支过滤、并发锁和构建脚本超时控制，`scripts/deploy_front.sh` 负责拉取代码并构建前端。验证：后端编译通过，webhook 密钥与 Gitea 签名校验测试通过。
+- 2026-07-27：自动部署 webhook 改为后台执行构建，接口在签名校验、分支检查和加锁后立即返回 `202 accepted`，后台任务将构建结果写入部署日志，避免 Gitea Delivery 因等待响应超时。验证：后端编译通过，webhook 后台任务触发测试通过。