TaskFlow

Appearance

本地提交前检查（对齐 GitHub Actions） ​

CI 工作流见仓库 .github/workflows/ci.yml，与本地 pnpm run check 一致。

每次改完建议执行 ​

在仓库根目录：

bash
pnpm run check

约 2～5 分钟（视机器而定），依次执行：

步骤命令内容
1check:backendESLint → 路由 registry → 权限 Jest → Nest 全量 build
2check:frontendvue-tsc → Vite build
3check:miniappESLint → vue-tsc → uni H5 build
—check:miniapp:weixinme-sub 路径校验 → 微信构建 → 主包 < 2048KB（CI 独立 job，发版前建议本地也跑）
—check:permission-codesbackend ↔ shared 写权限码一致（已并入 check:backend:fast）
—check:preset-roles预置角色权限绑定（需本地 DB；已并入 check:staging）
4check:docsVitePress 文档 build

推送 / 提 PR 前 跑通一次，可避免 Actions 里 check job 失败。

为什么 push 一次会跑多个 Actions？ ​

仓库里有多份工作流，推到 main / master 时通常会同时触发：

工作流文件何时跑作用
CI.github/workflows/ci.yml每次 push / PRpnpm run check（与本地一致）+ check:miniapp:weixin（微信构建与主包体积）
Prerelease gates.github/workflows/prerelease-gates.yml每次 push / PR预发权限、check:env-pack、可选月结
Release acceptance.github/workflows/release-acceptance.yml仅手动 Run workflow发版前完整 prerelease（需配 DATABASE_URL Secret）

另：E2E Readonly Stack 一般为手动触发，不会在每次 push 自动跑。

因此 push 后常见 2～3 条记录（CI + Prerelease gates；若你手动点了 Release acceptance 会再多一条）。不是重复部署，是不同门禁。

推送前推荐（2 分钟 + 可选 5 分钟） ​

bash
# 必做：对齐 CI 的 check job
pnpm run check

# 可选：与 Prerelease gates 前半一致（无数据库）
pnpm run check:staging && pnpm run check:env-pack

若只改了后端/前端/小程序，可只跑对应的 pnpm run check:backend 等（见下文「只改了某一端」）。

注意：GitHub Actions 的 step if 不能用 secrets 做非空判断（会报 Invalid workflow）。应改为在 run 里用 shell 判断环境变量，例如：

bash
if [ -z "${DATABASE_URL}" ]; then echo "跳过"; exit 0; fi

Prerelease gates 里的 check:preset-roles 需要连库；CI 未配 DATABASE_URL Secret 时会 自动跳过（不失败）。本地发版前请在 backend/.env 配置 DATABASE_URL 后执行 pnpm run check:staging 做完整校验。

打 tag / 候选发版前（权限或 env 有改动时）：

bash
pnpm run check:release-candidate   # = check + check:staging

清单见 release-window-checklist.md。

发版前可选（安全） ​

bash
pnpm run check:audit          # 仅 backend + frontend prod，high+ 失败（现网部署范围）
pnpm run check:audit:miniapp  # 仅 miniapp prod，定期查看，不阻塞后端发版
pnpm run check:audit:all      # 全 monorepo prod（参考）

均走 scripts/check-audit.mjs → registry.npmjs.org（与 .npmrc 镜像无关）。pnpm 无法按 workspace filter audit，脚本按依赖路径根包（backend / frontend / miniapp）过滤。

体积与分包（Web / 小程序） ​

  • Web 管理端：vite.config.ts 的 manualChunks（naive-ui / echarts / vicons / vue 系）+ 路由懒加载；勿仅靠调大 chunkSizeWarningLimit。
  • 微信小程序：在 miniapp/src/pages.json 的 subPackages 按业务拆包；主包仅首页、登录、tabBar。CI：pnpm run check:miniapp:weixin（主包 < 2048KB）。

详见 bundle-size-strategy.md。

只改了某一端时 ​

bash
pnpm run check:backend    # 后端 / 权限 / zenstack
pnpm run check:frontend   # Web 管理端
pnpm run check:miniapp    # 小程序
pnpm run check:miniapp:weixin   # 微信包体积（较慢，发版前）
pnpm run check:docs       # 文档站

开发中快速反馈（不替代提交前 check） ​

仅后端、且不想等 Nest build：

bash
pnpm --filter taskflow-backend run lint:check
pnpm --filter taskflow-backend run test:permission

改 docs/**/*.md 时勿链到 docs/ 外路径（见 .cursor/rules/docs-vitepress-links.mdc），提交前：

bash
pnpm run check:docs

改 schema.zmodel 后先：

bash
pnpm run zen:generate

再跑 check:backend 或全量 check。

格式化（避免 Prettier 在 CI 失败） ​

后端 ESLint 含 Prettier 规则，提交前可：

bash
pnpm --filter taskflow-backend run lint        # 自动修复
pnpm --filter taskflow-backend run lint:check  # 仅检查（与 CI 相同）

小程序：

bash
pnpm --filter taskflow-miniapp run lint:check
pnpm --filter taskflow-miniapp run type-check

常见失败与处理 ​

CI 现象原因处理
prettier/prettier未按项目格式保存pnpm --filter taskflow-backend run lint
Cannot find module '@prisma/client'误用 Prisma 类型；本项目 ORM 为 ZenStack改用 @zenstack/input 的 *WhereInput 等，勿引 @prisma/client
check:route-registry新 POST 未登记补 acc-route-permission-registry.ts / sys-route-permission-registry.ts
test:permission 失败权限逻辑回归本地 pnpm --filter taskflow-backend run test:permission 排查
frontend/miniapp vue-tsc类型错误对应包下 run type-check

预发权限严格模式 ​

bash
pnpm run check:staging

校验路由 registry、权限测试，并对 deploy/docker/env.staging.example 检查 ACC_ROUTE_GUARD_STRICT / SYS_ROUTE_GUARD_STRICT。将 env.staging.example 合并进实际 .env.pack 后，在服务器重启 gateway/sys/acc。

合并 deploy/docker/snippets/permission-strict.env.snippet 进 deploy/docker/.env.pack 后：

bash
pnpm run check:env-pack

部署脚本默认校验包内 .env 权限项；push-and-deploy.config 建议 REQUIRE_PERMISSION_STRICT=1（未开 strict 时部署会失败）。

发版验收（M4 手工表 + 月结 + STRICT）：acc-release-acceptance.md。
手工验收与 §4.2 签字：permission-staging-checklist.md。

bash
pnpm run check:release-acceptance   # 预发权限 strict + 月结 SQL（须 backend/.env DATABASE_URL）

前端 ESLint ​

bash
pnpm --filter frontend run lint:check

已并入 frontend 的 verify，根目录 pnpm run check 会执行。

可选：Docker 镜像构建（与发版一致） ​

bash
pnpm run check:docker

在仓库根构建 Dockerfile.backend / Dockerfile.frontend（含 docs/、shared/），避免「本地 pnpm 过、镜像 vue-tsc 挂」。CI 工作流 docker-images job 同样执行。

可选：月结巡检与预置角色（运维） ​

bash
pnpm --filter taskflow-backend run check:preset-roles
pnpm --filter taskflow-backend run check:month-close
# 单站点：node backend/scripts/check-acc-month-close-integrity.mjs --site-id=<uuid>

check:month-close 发现库存与流水不一致、出库超产量等会 exit 1；预发前可与 db:sync-roles-perms 联用。

Web ADMIN 可在侧栏「运维巡检」（/acc/ops，静态路由、不入权限种子）执行同等 API（POST /acc/ops/month-close-integrity、POST /acc/ops/preset-roles-check），无需连库跑脚本。

可选：Web E2E（Playwright） ​

需先启动 Web（pnpm run dev:web，默认 http://127.0.0.1:5000），首次安装浏览器：

bash
pnpm install
pnpm run test:e2e:install
pnpm run test:e2e

未起前端时对应用例会 skip（不会导致 CI 失败，除非流水线显式起服务并设 E2E_BASE_URL）。

只读权限用例（需网关 + Sys + Acc，且账号绑定 ACC_PC_LITE 或仅有 MINI_RECORDER_READ 的 PC 用户）：

bash
E2E_ACCOUNT_READONLY=readonly_user E2E_PASSWORD_READONLY=*** \
E2E_API_BASE_URL=http://127.0.0.1:3000 \
E2E_SITE_ID=<站点UUID> \
pnpm run test:e2e

未配置 E2E_ACCOUNT_READONLY / E2E_PASSWORD_READONLY 时只读过账用例自动 skip（e2e/acc-readonly-posting.spec.ts）。CI e2e-smoke job 可配置同名 Secrets + E2E_API_BASE_URL（仍须可达网关，否则登录失败会 skip）。

可选：Git 提交前自动跑（husky） ​

若团队需要 hook，可在根目录自行安装 husky 并将 pre-push 设为 pnpm run check（全量较慢，按需启用）。

默认不强制 hook，以文档约定 「提交前手动 pnpm run check」 为主。

TaskFlow 内部文档 Released under the MIT License.

Copyright © 2026-present QiHang Qiu