feat(deploy): 添加 Gitea 自动部署 Webhook 及配套工具

新增 `/deploy/webhook` 接口，支持 Gitea HMAC 签名校验、指定分支部署、构建并发锁与超时控制
添加前端项目部署脚本 `scripts/deploy_front.sh`，负责拉取代码、安装依赖并执行构建
新增部署相关配置项并更新 `.env.example` 示例配置
更新项目文档说明自动部署的使用约定
补充 `.gitignore` 规则忽略证书和 PEM 格式文件

app/AGENTS.md

@@ -12,6 +12,7 @@
 - `routers/products.py`：商品管理接口，按寺院隔离。
 - `routers/orders.py`：订单管理接口，按寺院隔离。
 - `routers/payments.py`：微信支付接口，按寺院隔离发起 JSAPI 预下单并处理支付通知。
+- `routers/deploy.py`：自动部署 webhook 接口，校验 Gitea 签名或部署 token 后触发前端构建脚本。
 - `routers/rituals.py`：法事管理接口，按寺院隔离。
 - `routers/uploads.py`：图片上传接口，上传到阿里云 OSS。
 - `config.py`：项目运行配置，目前预留阿里云 OSS 配置。
@@ -83,6 +84,14 @@ OSS_ENDPOINT、OSS_BUCKET_NAME、OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET、OSS
 - 配置通过 `.env` 或环境变量提供：`WECHAT_PAY_APPID`、`WECHAT_PAY_MCH_ID`、`WECHAT_PAY_MCH_SERIAL_NO`、`WECHAT_PAY_API_V3_KEY`、`WECHAT_PAY_PRIVATE_KEY_PATH`、`WECHAT_PAY_PUBLIC_KEY_PATH`、`WECHAT_PAY_NOTIFY_URL`。
 - 支付通知需要验签并用 APIv3 密钥解密；生产环境必须配置微信支付公钥或平台证书，不应开启 `WECHAT_PAY_SKIP_NOTIFY_VERIFY`。
 
+## 自动部署约定
+
+- 自动部署接口为 `/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`。
+- 部署脚本为 `scripts/deploy_front.sh`，负责在服务器项目目录执行 `git pull`、进入前端目录安装依赖并执行 `pnpm build`。
+- webhook 密钥不得写入源码或文档；`.env.example` 只能保留占位值。
+
 ## 验证
 
 后端修改后优先执行：
@@ -103,3 +112,4 @@ OSS_ENDPOINT、OSS_BUCKET_NAME、OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET、OSS
 - 2026-07-23：新增登录认证模块，支持服务端动态验证码、bcrypt 密码哈希、失败次数限制、账号临时锁定、HttpOnly/Secure Cookie 会话、退出登录、登录 IP/设备日志和新环境登录标记；`requirements.txt` 新增 `bcrypt`。验证：后端编译通过，运行态登录测试待安装 `bcrypt` 后执行。
 - 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 签名校验测试通过。