From ea975214e257218fcb378af4b5ba1a4a3e963ebc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=B5=85=E5=BF=B5?= Date: Tue, 29 Sep 2026 16:19:00 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=83=A8=E7=BD=B2spec=E5=90=B8?= =?UTF-8?q?=E6=94=B6=E5=AE=A1=E6=9F=A5=E5=BB=BA=E8=AE=AE=E2=80=94=E2=80=94?= =?UTF-8?q?tar=E7=9C=9F=E5=AE=9E=E8=B7=AF=E5=BE=84=E7=9B=B4=E8=90=BD?= =?UTF-8?q?=E6=8C=82=E8=BD=BD=E7=82=B9/=E5=8D=95=E7=9B=AE=E6=A0=87?= =?UTF-8?q?=E8=AF=AD=E4=B9=89=E8=A1=A8/CLAUDE.md=E5=AE=9E=E9=99=85?= =?UTF-8?q?=E4=B8=8D=E5=AD=98=E5=9C=A8=E6=94=B9=E4=B8=BA=E6=96=B0=E5=BB=BA?= =?UTF-8?q?/logs-gitignore=E5=89=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Code --- ...-09-29-git-and-deploy-automation-design.md | 28 +++++++++++++------ 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/docs/superpowers/specs/2026-09-29-git-and-deploy-automation-design.md b/docs/superpowers/specs/2026-09-29-git-and-deploy-automation-design.md index ec9b0c4..8feaa2c 100644 --- a/docs/superpowers/specs/2026-09-29-git-and-deploy-automation-design.md +++ b/docs/superpowers/specs/2026-09-29-git-and-deploy-automation-design.md @@ -21,7 +21,9 @@ - 被代码引用的资产（如 LoginLeftView 引用的图片）→ 提交入库 - 设计文档/设计稿（assets/design 等）→ 提交入库（团队知识） - 临时验证产物（根目录截图、测试页 html、.playwright-mcp/、.tmp-*）→ .gitignore + - **.gitignore 必须在本期初始提交中即包含 `deploy/logs/`**——否则首次部署产生的日志污染工作区，下一次部署被自身的"工作区干净"前置门禁拦住 - 敏感文件扫描：确认无 .env/私钥/明文密码入库（.env.example 除外）；deploy/.env 不存在于本机（仅服务器有） + - 首次 push 到 http 远程会弹凭证（Windows Git Credential Manager 交互一次后缓存）——一次性用户侧操作，AI 执行 push 前需用户确认凭证已配好 3. 推送 `m1` 与 `main` 两分支（m1 为当前功能分支）。 4. 后续提交按既有节奏正常 push（不做 push 即部署——见"明确不做"）。 @@ -53,10 +55,18 @@ SITE_URL=https://tracker.12418113.xyz | 1 前置 | git 工作区干净（`--allow-dirty` 逃生舱）；跳板 SSH 可达 | 部署未提交状态 | | 2 测试门禁 | server: pytest tracker/tests（188 基线）；sdk: vitest run + tsc；admin: vue-tsc（build 内含） | 带病上线 | | 3 构建 | admin: `NODE_OPTIONS=--max-old-space-size=6144 pnpm build`；sdk: build + gzip 字节数记录 | 本机 OOM | -| 4 传输 | tar（排除 __pycache__/db.sqlite3/.pytest_cache）→ scp 经跳板 → /tmp | — | -| 5 服务器侧 | 解压到 $REMOTE_DIR；**cp -rf dist/* admin/dist/、cp dist/v1.js sdk/dist/**（后清理误解压的 dist/）；server: `docker compose up -d --build web`（Dockerfile 内自动 migrate） | 错误挂载点目录（×2 历史） | -| 6 验证 | tracker-web 容器 Up；站点 curl 200；admin 线上 index.html 哈希 === 本机产物哈希；sdk 线上 v1.js 含新 build_id | 部署无效/缓存误判 | -| 7 记录 | deploy/logs/deploy-<时间戳>.log：git 哈希/部署目标/版本标识/验证结果/耗时（logs 目录 gitignore） | 无部署历史可追溯 | +| 4 打包与传输 | **tar 按真实路径打包**（非暂存 dist/ 方案）：admin/sdk 目标打 `admin/dist sdk/dist`；server 目标打 `server/`（排除 __pycache__/db.sqlite3/.pytest_cache；**绝不打包 node_modules/.git/docs**）→ scp 经跳板 → /tmp | 根目录 tar 连 node_modules 一起传 | +| 5 服务器侧 | 在 $REMOTE_DIR 解压——**tar 真实路径直接落位挂载点**（admin/dist、sdk/dist 原地合并覆盖，无 cp、无暂存、无清理步骤——彻底消灭"解压到错误目录"路径）；server: `docker compose up -d --build web`（Dockerfile 内自动 migrate） | 错误挂载点目录（×2 历史） | +| 6 验证 | tracker-web 容器 Up；`curl -f $SITE_URL` → 200；admin：`sha256(curl $SITE_URL 的 index.html) === sha256(本机 admin/dist/index.html)`；sdk：`curl $SITE_URL/sdk/v1.js` 含新 build_id | 部署无效/缓存误判 | +| 7 记录 | deploy/logs/deploy-<时间戳>.log：git 哈希/部署目标/版本标识/验证结果/耗时（logs 目录 gitignore，已在 Part 1 落地） | 无部署历史可追溯 | + +### 单目标语义（每个目标都完整走：前置检查 + 自己的测试 + 自己的验证） + +| 目标 | 子集 | +|---|---| +| server | pytest → tar server/ → 解压 $REMOTE_DIR → docker compose up -d --build web → 容器 Up + `curl -f $SITE_URL` 200（无 dist 传输） | +| admin | vue-tsc/build → tar admin/dist → 解压落位 → index.html sha256 线上比对（无 docker、无 pytest） | +| sdk | vitest + tsc → build → tar sdk/dist → 解压落位 → 线上 v1.js 含 build_id（无 docker） | ### 失败语义 @@ -67,11 +77,13 @@ SITE_URL=https://tracker.12418113.xyz - 脚本为 bash（开发机 Git Bash 执行；服务器侧命令经 ssh 执行，无 Windows 依赖） - 服务器现有 1Panel/OpenResty 等其他项目**严格不触碰**（既有红线） -## Part 3：使用约定（更新 CLAUDE.md 部署策略段） +## Part 3：使用约定（新建 CLAUDE.md + 更新会话背景与记忆） -- 用户说"部署到线上" → AI 执行 `bash deploy/deploy.sh all`（或按改动范围选目标）并汇报验证结果与版本标识 -- 任务完成后的标准部署 = 同一条命令；原"tar→scp→…"手工步骤描述作废，指向本脚本 -- 部署日志位于 deploy/logs/ 供追溯 +现状核实：仓库与用户级**均无 CLAUDE.md**——部署约定目前活在用户每会话粘贴的"项目背景"块与 AI 自动记忆中。落地： + +1. **新建仓库 CLAUDE.md**（部署约定段）：用户说"部署到线上" → AI 执行 `bash deploy/deploy.sh all`（或按改动范围选单目标）并汇报验证结果与版本标识；任务完成后的标准部署 = 同一条命令；部署日志位于 deploy/logs/。 +2. **用户侧**：其后会话粘贴的"项目背景"块中"部署策略"段改为指向本脚本（由用户自行更新其模板，spec 不代写）。 +3. **AI 自动记忆**：更新既有"前端部署目标目录"记忆条目——手工链描述作废，指向 deploy/deploy.sh（历史陷阱教训保留）。 ## 明确不做（本期）