TaskFlow

Appearance

权限改造 — 预发 / 上线检查清单 ​

与 permission-matrix.md、permission-api-unification.md 配套。在开启路由 Guard 严格模式 前按序执行。

发版阶段总览：release-phase-plan.md（P0 签字 → C/B 产品线 → E2E/链路）。

在制业务话术与双路径说明见 miniapp-wip-labor-paths.md。

1. 自动化（本地 / CI） ​

bash
pnpm run check
pnpm run check:release-acceptance   # staging + 月结 SQL；见 acc-release-acceptance.md

分项：

bash
pnpm run check:staging
pnpm --filter taskflow-backend run check:preset-roles
# 或指定 env：node backend/scripts/check-staging-permission-env.mjs deploy/docker/.env.pack
pnpm --filter taskflow-frontend exec vue-tsc --noEmit
pnpm run check:docker

verify 已包含 check:route-registry 与 test:permission（57+ 用例，含 query/partners 门面委托、入库/出库/结算集成语义）。产品语义见 permission-code-conventions.md。

可选 Web 冒烟（需本地已起 pnpm run dev:web，默认 http://127.0.0.1:5000）：

bash
pnpm run test:e2e:install   # 首次安装 Chromium
pnpm run test:e2e
# 或指定：E2E_BASE_URL=http://127.0.0.1:5000 pnpm run test:e2e

1.1 预发 / 线上 .env.pack（external-dbs） ​

操作步骤见 env-pack-strict-and-e2e.md。

  1. 合并 strict：pnpm run merge:env-pack-strict 或 ./deploy/scripts/merge-env-pack-strict.sh（须已有 .env.pack）。
  2. 校验：pnpm run check:env-pack（须 exit 0）。
  3. 部署并重启 gateway / sys / acc 后，按 §4 表 在 STRICT 开启状态下 复测。
  4. 填写 §4.2 签字表并存档（工单 / 发布记录）。

2. 环境变量 ​

2.1 网关 Redis 会话（默认开启） ​

ini
# 省略或 true：JWT 有效且 Redis 存在 token:{userId}:web|miniapp 才转发 Acc/Sys
GATEWAY_SESSION_CHECK=true

首次启用后，仅有 JWT、无 Redis 会话键的用户会 401 须重登一次。排障或灰度可临时 GATEWAY_SESSION_CHECK=false（仍实时加载 claims）。鉴权声明默认 Redis 短缓存（GATEWAY_CLAIMS_CACHE）；改权限后会 bumpGatewayClaimsCacheVersion，最长等待 GATEWAY_CLAIMS_CACHE_TTL 秒自动刷新。

2.2 路由 Guard 严格模式 ​

在 backend/.env 或 deploy/docker/.env 中（登记完整且预发验证通过后再开）：

ini
ACC_ROUTE_GUARD_STRICT=true
SYS_ROUTE_GUARD_STRICT=true

未登记路由将直接 403（PERMISSION_DENIED）；/auth/* 仍由 Sys registry 隐式 skip。

3. 角色与数据准备 ​

  1. 执行 pnpm --filter taskflow-backend run db:sync-roles-perms（或等价 seed）。
  2. 按 permission-role-templates.md 绑定预置角色（推荐，减少手勾遗漏）：
    • 记录员只读 → MINI_RECORDER_READ
    • 记录员过账 → MINI_RECORDER_POST
    • 工人（须 Web 绑定工人档案）→ MINI_WORKER
    • PC 全功能 → ACC_PC_OPERATOR
  3. 或手工准备测试账号（换角色后 重新登录）：
    • 仅菜单：例如只有 menu_acc_inbound，无 btn_acc_inbound_write
    • 完整会计：ACC_PC_OPERATOR 或等价勾选
    • 无 Acc 菜单：仅有站点、无 menu_acc_*
  4. 测试账号须绑定至少一个 站点（JWT siteIds）。

4. 手工验收（对照 permission-matrix 自检用例） ​

#操作期望
1仅入库菜单，Web 打开入库列表列表 OK
2同上，点「过账」或调 POST /acc/inbound/post403，requiredPermissions 含 btn_acc_inbound_write
3勾选写按钮后过账成功
4仅 menu_acc_production，WIP 开单/报工/关账403（btn_acc_production_write）
5无 menu_acc_customers，删客户403
6无结算菜单，settlement/page403
6b仅有结算菜单无 btn_acc_settlement_write，settlement/post / mark-paid403
7无记工查看码，labor-records/site-page403
8PC 未授权路由 URL跳转 /no-permission
9小程序记录员无写权限码，新建入库页加载供应商Toast 含权限说明
10非 ADMIN，角色分配 assignments/save403
11小程序无 btn_acc_inbound_write 直开 inbound-createToast + 回首页（useMiniappPageGate）
12小程序无 mobile_recorder_labour_view 直开记工明细同上
13经理无 mobile_manager_settlement 直开结算列表同上
14经理有结算读权限无 btn_acc_settlement_write，小程序「发放工资」页无「上传凭证并标记已发放」按钮；调 API 403
15账号绑 MINI_WORKER，Web/小程序绑定工人档案，打开 payslip仅本人 settled/paid；草稿不可见；详情非本人 403
16账号绑 MINI_MANAGER（含 btn_acc_settlement_write），进 settlement-create 保存成功；无写权限无 FAB/门禁拦截

预发数据：pnpm --filter taskflow-backend run db:sync-roles-perms 后，在管理端为用户勾选 MINI_WORKER / MINI_MANAGER（或等价权限并集），重新登录 再测。

可在浏览器 Network 查看响应体 code / requiredPermissions；小程序与 Web 均已接 getApiErrorMessage / getMiniappApiErrorMessage。

4.1 上线签字（运维） ​

一键预检：pnpm run check:release-acceptance + 全量 pnpm run check。完整步骤与 M4 表：acc-release-acceptance.md。

项通过
pnpm run check + check:release-acceptance□
GATEWAY_SESSION_CHECK / GATEWAY_CLAIMS_CACHE□
ACC_ROUTE_GUARD_STRICT + SYS_ROUTE_GUARD_STRICT（§4.2 已签）□
上表 1–13 手工用例（STRICT 开启后）□
Web E2E pnpm run test:e2e（见 local-ci-check.md）□
月结：脚本 / Web /acc/ops / 小程序报表 Tab 三选一已验□
升级后 db:sync-roles-perms 且业务角色已勾选□

说明：管理员改角色绑定后，Acc/Sys API 立即按库内权限生效（网关 loadUserGatewayClaims）。PC 按钮经 refreshAuthClaims 更新；小程序经 useAccPermissions + App.onShow。在后台执行 角色绑定权限、权限树保存/删除、用户角色/站点同步、重置密码/改状态、 账号合并 或 角色成员分配 后，相关用户 Redis 会话会被清除，须重新登录（新 JWT 与按钮态一致）。

4.2 预发 STRICT 模式签字（上线前必填） ​

在 §2.2 两项均为 true 且本清单 §1、§4 自动化与手工项通过后，由运维 / 业务负责人共同签字存档（可复制到工单或发布记录）。

运维逐步手册：strict-signoff-ops-runbook.md（合并 env、重启、db:sync-roles-perms、验收顺序、存档位置）。

检查项通过备注
ACC_ROUTE_GUARD_STRICT=true 已写入预发 .env 并重启 gateway/acc□未登记路由 → 403
SYS_ROUTE_GUARD_STRICT=true 同上□/auth/* 仍 skip
§4 表 1–13 在 STRICT 开启后 复测通过□含生产 WIP 写权限 #4
miniapp-m3-wip-acceptance.md L3/L4 + 关账/现场报工路径□与 miniapp-wip-scope.md 一致
production-wip 开单/关账/报工 API 403 语义与矩阵一致□无 500 误放行
字段填写
预发环境 / 版本
STRICT 开启日期（UTC+8）
运维负责人
业务验收负责人
签字日期

5. 回滚（严格模式） ​

严格模式异常时，去掉 *_ROUTE_GUARD_STRICT 或设为 false，重启 gateway/sys/acc 进程即可；Service 层 assertAcc* 仍生效。

TaskFlow 内部文档 Released under the MIT License.

Copyright © 2026-present QiHang Qiu