From 869d8b2ce85270c95269dba7ff6ca641541b6210 Mon Sep 17 00:00:00 2001
From: Your Name <your.email@example.com>
Date: Wed, 27 May 2026 11:13:02 +0800
Subject: [PATCH] chore: unify quality gate commands

---
 .github/workflows/lint.yml          |  7 +------
 README.md                           |  9 +++++----
 docs/deployment.md                  |  8 ++++++++
 docs/operations.md                  |  9 ++++++---
 package.json                        |  2 ++
 scripts/check-tracked-artifacts.mjs | 24 ++++++++++++++++++++++++
 6 files changed, 46 insertions(+), 13 deletions(-)
 create mode 100644 scripts/check-tracked-artifacts.mjs

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 7e185c7fa..2bb0a9ece 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -40,9 +40,4 @@ jobs:
         run: git diff --check
 
       - name: Check tracked local artifacts
-        shell: bash
-        run: |
-          if git ls-files | grep -E '(^|/)\.DS_Store$|\.swp$|\.env\.local$|^\.claude/|^migration-backup|^tsconfig\.tsbuildinfo$'; then
-            echo "Tracked local artifacts found. Remove them from git tracking before merging."
-            exit 1
-          fi
+        run: pnpm check:artifacts
diff --git a/README.md b/README.md
index 75932a39a..41d724f9d 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,8 @@ http://localhost:3001/settings
 pnpm dev
 pnpm lint
 pnpm check:logs
+pnpm check:artifacts
+pnpm check:quality
 pnpm exec tsc --noEmit --pretty false
 pnpm test
 pnpm db:migrate
@@ -79,10 +81,9 @@ pnpm db:generate
 推荐提交前至少运行：
 
 ```bash
-pnpm lint
-pnpm check:logs
-pnpm exec tsc --noEmit --pretty false
-git diff --check
+pnpm check:quality
+AUTH_TRUST_HOST=true PORT=3001 pnpm dev
+SMOKE_BASE_URL=http://127.0.0.1:3001 pnpm smoke:routes
 ```
 
 ## 目录结构
diff --git a/docs/deployment.md b/docs/deployment.md
index c735f5993..e877476a6 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -77,6 +77,14 @@ NEXT_PUBLIC_ENABLE_CLIENT_LOGS=false
 
 ## 部署后烟测
 
+如果可以从部署机或本地访问目标域名，推荐直接使用脚本：
+
+```bash
+SMOKE_BASE_URL=https://your-domain.com pnpm smoke:routes
+```
+
+也可以手动检查：
+
 ```bash
 curl -I https://your-domain.com/
 curl -I https://your-domain.com/classic
diff --git a/docs/operations.md b/docs/operations.md
index 1c70beaba..4c0b8da61 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -9,20 +9,23 @@ pnpm lint
 pnpm check:logs
 pnpm exec tsc --noEmit --pretty false
 git diff --check
+pnpm check:artifacts
 ```
 
-污染物检查：
+等价的一键质量门禁：
 
 ```bash
-git ls-files | rg '(^|/)\\.DS_Store$|\\.swp$|\\.env\\.local$|^\\.claude/|^migration-backup|^tsconfig\\.tsbuildinfo$' || true
+pnpm check:quality
 ```
 
-预期无输出。
+其中 `pnpm check:artifacts` 会检查 `.DS_Store`、swap 文件、`.env.local`、`.claude/`、migration backup 和 `tsconfig.tsbuildinfo` 等本地污染物是否被 Git 追踪。
 
 ## CI
 
 `.github/workflows/lint.yml` 是基础质量门禁，负责 lint、日志治理、类型检查、diff hygiene 和 tracked 污染物检查。
 
+CI 中的污染物检查复用 `pnpm check:artifacts`，避免本地和远端规则漂移。
+
 Playwright workflow 独立运行，避免 e2e 依赖、浏览器安装和 secrets 影响基础门禁反馈速度。
 
 ## 日志治理
diff --git a/package.json b/package.json
index 39b3f290c..bf57f07b9 100644
--- a/package.json
+++ b/package.json
@@ -12,6 +12,8 @@
     "start": "next start",
     "lint": "npx ultracite@latest check",
     "check:logs": "node scripts/check-log-hygiene.mjs && tsx scripts/check-log-redaction.ts",
+    "check:artifacts": "node scripts/check-tracked-artifacts.mjs",
+    "check:quality": "pnpm lint && pnpm check:logs && pnpm exec tsc --noEmit --pretty false && git diff --check && pnpm check:artifacts",
     "smoke:routes": "node scripts/smoke-routes.mjs",
     "format": "npx ultracite@latest fix",
     "db:generate": "drizzle-kit generate",
diff --git a/scripts/check-tracked-artifacts.mjs b/scripts/check-tracked-artifacts.mjs
new file mode 100644
index 000000000..b21410920
--- /dev/null
+++ b/scripts/check-tracked-artifacts.mjs
@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+
+const forbiddenPattern =
+  /(^|\/)\.DS_Store$|\.swp$|\.env\.local$|^\.claude\/|^migration-backup|^tsconfig\.tsbuildinfo$/;
+
+const trackedFiles = execFileSync("git", ["ls-files"], {
+  encoding: "utf8",
+})
+  .split(/\r?\n/)
+  .filter(Boolean);
+
+const violations = trackedFiles.filter((file) => forbiddenPattern.test(file));
+
+if (violations.length > 0) {
+  console.error("Tracked local artifacts found. Remove them from git tracking:");
+  for (const file of violations) {
+    console.error(`- ${file}`);
+  }
+  process.exit(1);
+}
+
+console.log("Tracked artifact check passed.");