迁移首批4个错误码：AP台账/查询、待办、工作台功能开关 [09-05-error-explainability-payment-readiness]

10-05 到期例外清单里已设计好的首批 4 个具体调用，现予落码（原方案见
implement.md §14「首批具体分支与验证要求」）：

- ap_operations.feature_disabled（409）：AP 台账/明细查询功能关闭
- ap_operations.query_invalid（400）：AP 台账查询参数校验失败
- todo.feature_disabled（409）：待办功能关闭
- portal.feature_disabled（409）：工作台首页功能关闭

四处均改为调用 buildBusinessValidationError(reasonCode, details, statusCode)，
保留原 HTTP 状态码、featureFlag/reason 等既有 details 字段不变，仅新增精确
reasonCode；不改功能开关判断逻辑、不改权限校验顺序。

- server/src/constants/errorReasons.js + client/src/api/errorReasons.ts：
  注册 4 条原因码及中文文案，服务端/客户端逐字一致。
- scripts/qa/error-reason-legacy-baseline.json：移除这 4 条已迁移的旧例外
  记录（591 → 587），check-error-reason-contract.mjs 主检查与 self-test
  均 PASS，无 new_legacy/stale_exception/unregistered_reason。
- apOperations.permissions.test.js：扩展"功能关闭"断言校验 reasonCode 与
  原 details 字段共存；新增"查询参数非法（功能开启）"400 用例，断言零
  台账业务查询；新增"合法查询仍 200"用例。
- portal.test.js：新增工作台关闭时 409+reasonCode+零业务查询断言（此前
  完全没有覆盖这条路径）。
- todos.test.js：新建（此前 todos 路由零测试覆盖），聚焦 ensureFeatureEnabled
  网关：关闭时 GET/POST 均 409+reasonCode+零 todoItem 查询；开启时正常放行。

验证：server 5 个相关测试文件 286/286 通过；client typecheck/build 通过；
check-ui-design-rules.mjs --strict、check-trellis-governance.mjs、
git diff --check 通过。routes/ 全量回归 872/874（2 个失败为 paymentBatches
BIFF8 导出的既有环境问题，已用 git stash 验证在改动前的 HEAD 上同样失败，
与本次改动无关，不在本次范围内处理）。

剩余 669 条例外记录不变，尚未处理；B/C 两档 57 文件仍需逐模块确认迁移或
提出延期理由，本次不扩大范围。

Co-Authored-By: Claude Sonnet 5 <[email protected]>

client/src/api/errorReasons.ts

@@ -228,6 +228,10 @@ export const ERROR_REASON_MESSAGES: Record<string, string> = {
   "payment_batch.payment_account_unavailable": "公司付款账户暂不可用，请联系管理员检查账户配置后重试。",
   "payment_batch.active_batch_exists": "所选单据已进入其他付款安排，请刷新列表并查看已有批次。",
   "payment_batch.reviewer_required": "当前没有可复核的经理或负责人，制单人不能复核自己的批次，请联系管理员安排独立复核人。",
+  "ap_operations.feature_disabled": "应付账款暂未开放，请联系管理员确认处理方式。",
+  "ap_operations.query_invalid": "查询条件不符合要求，请检查筛选条件后重试。",
+  "todo.feature_disabled": "待办功能暂未开放，请联系管理员确认处理方式。",
+  "portal.feature_disabled": "工作台暂未开放，请联系管理员确认处理方式。",
 };
 
 export const UNKNOWN_VALIDATION_MESSAGE = "操作未完成，请核对页面提示；如仍无法继续，请联系管理员协助处理。";

scripts/qa/error-reason-legacy-baseline.json

@@ -12,8 +12,6 @@
     {"file":"server/src/routes/announcements.js","fingerprint":"16e3a77398374a9da0ba54d34380f16866000cd809d649d13c68a262437cecb8","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"/announcements/:id"},
     {"file":"server/src/routes/announcements.js","fingerprint":"b489caa88f9c4b0f9cbdd4ddaa317a550973dc746fe11c44f556d6b0be5c5c58","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"/announcements/:id/acknowledge"},
     {"file":"server/src/routes/announcements.js","fingerprint":"6f2ecb599e0390bc141c7c6a8874a4a0b04b55c3f9c9f249432829ef2aa4c21f","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"/announcements/:id/acknowledge"},
-    {"file":"server/src/routes/apOperations.js","fingerprint":"48951ae2ad49593089e10d00afd95a5f18e10c2cbcb87f7956eb47a59d60cfa0","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:ensureFeatureEnabled"},
-    {"file":"server/src/routes/apOperations.js","fingerprint":"4673e0a3f7e965475ce8a75bc2dd25a14481692a28acdad66e22e8f66d5b2910","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"/ap-operations/reimbursement-ledger"},
     {"file":"server/src/routes/approvalRules.js","fingerprint":"4673e0a3f7e965475ce8a75bc2dd25a14481692a28acdad66e22e8f66d5b2910","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:parseBody"},
     {"file":"server/src/routes/approvalRules.js","fingerprint":"eafa3d7b708b3d3b0052c67493ee3cf3f1ee62121cdbc3612f6d0c16b057eddc","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:parseApprovalRuleId"},
     {"file":"server/src/routes/approvalRules.js","fingerprint":"cd6c77086d44835903ad40dc099ee6640c1ddfb1323f346af4ba86ed8a0ea323","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:ensureAmountRangeValid"},
@@ -335,7 +333,6 @@
     {"file":"server/src/routes/performance.js","fingerprint":"f45ef4d4efbe70b8b8d9986fbfa81ab17ec19b4be5d49a05c50e4113870bf090","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"/performance/cycles/:cycleId"},
     {"file":"server/src/routes/performance.js","fingerprint":"b2271cd4b603af5a201ffeacd3f23408030b50cb56e9f7380996a3a90cfe241d","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:performanceRoutes"},
     {"file":"server/src/routes/performance.js","fingerprint":"a36e4a2edab739bdd3595d96a3d8ac1c1e6dd814915bfa5b0a189c17da335abe","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:performanceRoutes"},
-    {"file":"server/src/routes/portal.js","fingerprint":"de0048472baa2ade9251177868ca94a4e86e149b88bb49f48d8cc7d10549767b","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:ensureFeatureEnabled"},
     {"file":"server/src/routes/portal.js","fingerprint":"1ccd0d7139b90bcb4360218527df65fcbec8936865ee49a7abf1f8eb175deabf","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:buildValidationError"},
     {"file":"server/src/routes/presence.js","fingerprint":"8082c82f99fcf677784600a080881baa1d83e621985e6c5945f8c90cd05d4297","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:parseInput"},
     {"file":"server/src/routes/presence.js","fingerprint":"2adc3ff7dd515743a159e4289f5872beaed9785c8fb49532b3c37485d6053cf1","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:ensureFeatureEnabled"},
@@ -415,7 +412,6 @@
     {"file":"server/src/routes/todos.js","fingerprint":"1ccd0d7139b90bcb4360218527df65fcbec8936865ee49a7abf1f8eb175deabf","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:buildValidationError"},
     {"file":"server/src/routes/todos.js","fingerprint":"278003b27036a26a6c6c2bac8e175081f3d2f7f950a5d3c2ed2c8e71f604bfdd","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:parseBody"},
     {"file":"server/src/routes/todos.js","fingerprint":"6c58fb0c0b2fb699a6a013d4d40a2b87c072068b06e766e74b0e092cc7a335d5","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:parseUuid"},
-    {"file":"server/src/routes/todos.js","fingerprint":"309a572d3996ecefcf2cd76ff4d999f27066193832e45339137025bd0444a326","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:ensureFeatureEnabled"},
     {"file":"server/src/routes/todos.js","fingerprint":"278003b27036a26a6c6c2bac8e175081f3d2f7f950a5d3c2ed2c8e71f604bfdd","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"/todos"},
     {"file":"server/src/routes/travelAuthorizations.js","fingerprint":"1ccd0d7139b90bcb4360218527df65fcbec8936865ee49a7abf1f8eb175deabf","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:buildValidationError"},
     {"file":"server/src/routes/travelAuthorizations.js","fingerprint":"278003b27036a26a6c6c2bac8e175081f3d2f7f950a5d3c2ed2c8e71f604bfdd","count":1,"owner":"shunli","reason":"非首批迁移域；修改此调用时须完成原因码注册、客户端映射和具体内容断言","expiresOn":"2026-10-05","operation":"function:parseListQuery"},

server/src/constants/errorReasons.js

@@ -228,6 +228,10 @@ const ERROR_REASONS = [
   { code: "payment_batch.payment_account_unavailable", domain: "payment_batch", audience: "user", defaultMessage: "公司付款账户暂不可用，请联系管理员检查账户配置后重试。", recovery: "contact_admin" },
   { code: "payment_batch.active_batch_exists", domain: "payment_batch", audience: "user", defaultMessage: "所选单据已进入其他付款安排，请刷新列表并查看已有批次。", recovery: "refresh" },
   { code: "payment_batch.reviewer_required", domain: "payment_batch", audience: "user", defaultMessage: "当前没有可复核的经理或负责人，制单人不能复核自己的批次，请联系管理员安排独立复核人。", recovery: "contact_admin" },
+  { code: "ap_operations.feature_disabled", domain: "ap_operations", audience: "user", defaultMessage: "应付账款暂未开放，请联系管理员确认处理方式。", recovery: "contact_admin" },
+  { code: "ap_operations.query_invalid", domain: "ap_operations", audience: "user", defaultMessage: "查询条件不符合要求，请检查筛选条件后重试。", recovery: "follow_guidance" },
+  { code: "todo.feature_disabled", domain: "todo", audience: "user", defaultMessage: "待办功能暂未开放，请联系管理员确认处理方式。", recovery: "contact_admin" },
+  { code: "portal.feature_disabled", domain: "portal", audience: "user", defaultMessage: "工作台暂未开放，请联系管理员确认处理方式。", recovery: "contact_admin" },
 ];
 
 const reasonsByCode = new Map(ERROR_REASONS.map((reason) => [reason.code, Object.freeze(reason)]));

server/src/routes/apOperations.js

@@ -1,4 +1,5 @@
 const { AppError } = require("../utils/AppError");
+const { buildBusinessValidationError } = require("../utils/businessValidationError");
 const { sendData } = require("../utils/reply");
 const { FEATURE_FLAG_KEYS, evaluateFeatureFlag } = require("../services/featureFlags");
 const { BUDGET_RISK_CODES, buildPersistedRiskFlag, toMoneyNumber, toMoneyString } = require("../services/feeControl");
@@ -39,12 +40,11 @@ async function ensureFeatureEnabled(fastify) {
     strictDepartment: false,
   });
   if (!gate.enabled) {
-    throw new AppError({
+    throw buildBusinessValidationError(
-      code: "VALID_001",
+      "ap_operations.feature_disabled",
-      message: "参数校验失败",
+      { featureFlag: "payment_batch_v1_disabled", reason: gate.reason },
-      statusCode: 409,
+      409,
-      details: { featureFlag: "payment_batch_v1_disabled", reason: gate.reason },
+    );
-    });
   }
 }
 
@@ -208,12 +208,7 @@ async function apOperationsRoutes(fastify) {
 
     const parsed = FINANCE_LEDGER_QUERY_SCHEMA.safeParse(request.query ?? {});
     if (!parsed.success) {
-      throw new AppError({
+      throw buildBusinessValidationError("ap_operations.query_invalid", parsed.error.flatten(), 400);
-        code: "VALID_001",
-        message: "参数校验失败",
-        statusCode: 400,
-        details: parsed.error.flatten(),
-      });
     }
 
     const ledger = await listFinanceLedger(fastify.prisma, parsed.data);

server/src/routes/portal.js

@@ -1,4 +1,5 @@
 const { AppError } = require("../utils/AppError");
+const { buildBusinessValidationError } = require("../utils/businessValidationError");
 const {
   buildTeamPresenceSummary,
   resolvePresenceForEmployee,
@@ -76,12 +77,11 @@ async function ensureFeatureEnabled(fastify, request) {
     strictDepartment: false,
   });
   if (!gate.enabled) {
-    throw new AppError({
+    throw buildBusinessValidationError(
-      code: "VALID_001",
+      "portal.feature_disabled",
-      message: "参数校验失败",
+      { featureFlag: "portal_home_v1_disabled", reason: gate.reason },
-      statusCode: 409,
+      409,
-      details: { featureFlag: "portal_home_v1_disabled", reason: gate.reason },
+    );
-    });
   }
 }
 

server/src/routes/todos.js

@@ -1,6 +1,7 @@
 const { z } = require("zod");
 
 const { AppError } = require("../utils/AppError");
+const { buildBusinessValidationError } = require("../utils/businessValidationError");
 const { sendData } = require("../utils/reply");
 const { createNotifications } = require("../services/notifications");
 const { FEATURE_FLAG_KEYS, evaluateFeatureFlag } = require("../services/featureFlags");
@@ -81,7 +82,11 @@ async function ensureFeatureEnabled(fastify, request) {
     strictDepartment: false,
   });
   if (!gate.enabled) {
-    throw buildValidationError({ featureFlag: "todo_board_v1_disabled", reason: gate.reason }, 409);
+    throw buildBusinessValidationError(
+      "todo.feature_disabled",
+      { featureFlag: "todo_board_v1_disabled", reason: gate.reason },
+      409,
+    );
   }
 }
 

server/tests/unit/fixtures/error-reason-messages.json

@@ -227,5 +227,9 @@
   "payment_batch.payment_account_required": "所属公司尚无可用的建行付款账户，请联系账户管理员维护后重试。",
   "payment_batch.payment_account_unavailable": "公司付款账户暂不可用，请联系管理员检查账户配置后重试。",
   "payment_batch.active_batch_exists": "所选单据已进入其他付款安排，请刷新列表并查看已有批次。",
-  "payment_batch.reviewer_required": "当前没有可复核的经理或负责人，制单人不能复核自己的批次，请联系管理员安排独立复核人。"
+  "payment_batch.reviewer_required": "当前没有可复核的经理或负责人，制单人不能复核自己的批次，请联系管理员安排独立复核人。",
+  "ap_operations.feature_disabled": "应付账款暂未开放，请联系管理员确认处理方式。",
+  "ap_operations.query_invalid": "查询条件不符合要求，请检查筛选条件后重试。",
+  "todo.feature_disabled": "待办功能暂未开放，请联系管理员确认处理方式。",
+  "portal.feature_disabled": "工作台暂未开放，请联系管理员确认处理方式。"
 }

server/tests/unit/routes/apOperations.permissions.test.js

@@ -35,7 +35,7 @@ async function buildApp(permissionCodes, enabled = true) {
   });
   app.decorate("hasPermission", (employee, permission) => hasPermission(employee.permissionCodes, permission));
   app.setErrorHandler((error, request, reply) => {
-    reply.code(error.statusCode ?? 500).send({ error: { code: error.code } });
+    reply.code(error.statusCode ?? 500).send({ error: { code: error.code, details: error.details ?? {} } });
   });
   await app.register(apOperationsRoutes, { prefix: "/api" });
   return { app, queries };
@@ -52,7 +52,7 @@ describe("AP full-ledger permission boundary", () => {
         const response = await app.inject({ method: "GET", url });
         expect(response.statusCode).toBe(allowed ? 200 : 403);
         if (!allowed) {
-          expect(response.json()).toEqual({ error: { code: "PERM_001" } });
+          expect(response.json()).toEqual({ error: { code: "PERM_001", details: {} } });
           for (const query of queries) expect(query).not.toHaveBeenCalled();
         }
       }
@@ -88,10 +88,47 @@ describe("AP full-ledger permission boundary", () => {
   it("preserves feature-off refusal without querying financial data", async () => {
     const { app, queries } = await buildApp(["finance.ledger.view"], false);
     try {
-      for (const url of paths) expect((await app.inject({ method: "GET", url })).statusCode).toBe(409);
+      for (const url of paths) {
+        const response = await app.inject({ method: "GET", url });
+        expect(response.statusCode).toBe(409);
+        expect(response.json()).toEqual({
+          error: {
+            code: "VALID_001",
+            details: { featureFlag: "payment_batch_v1_disabled", reason: "flag_force_off", reasonCode: "ap_operations.feature_disabled" },
+          },
+        });
+      }
       for (const query of queries) expect(query).not.toHaveBeenCalled();
     } finally {
       await app.close();
     }
   });
+
+  it("rejects invalid ledger query params with a precise reasonCode and no ledger read", async () => {
+    const { app, queries } = await buildApp(["finance.ledger.view"], true);
+    try {
+      const response = await app.inject({
+        method: "GET",
+        url: "/api/ap-operations/reimbursement-ledger?pageSize=999",
+      });
+      expect(response.statusCode).toBe(400);
+      const body = response.json();
+      expect(body.error.code).toBe("VALID_001");
+      expect(body.error.details.reasonCode).toBe("ap_operations.query_invalid");
+      expect(body.error.details.fieldErrors).toHaveProperty("pageSize");
+      for (const query of queries) expect(query).not.toHaveBeenCalled();
+    } finally {
+      await app.close();
+    }
+  });
+
+  it("still returns 200 for a legitimate ledger query when the feature is on", async () => {
+    const { app } = await buildApp(["finance.ledger.view"], true);
+    try {
+      const response = await app.inject({ method: "GET", url: "/api/ap-operations/reimbursement-ledger" });
+      expect(response.statusCode).toBe(200);
+    } finally {
+      await app.close();
+    }
+  });
 });

server/tests/unit/routes/portal.test.js

@@ -559,4 +559,27 @@ describe("portal routes", () => {
 
     await app.close();
   });
+
+  it("returns a precise reasonCode and skips business queries when portal home is disabled", async () => {
+    featureFlagState.portalHome = false;
+    const { app, prisma } = await buildApp({});
+
+    const response = await app.inject({
+      method: "GET",
+      url: "/api/portal/home",
+      headers: { authorization: "Bearer test" },
+    });
+
+    expect(response.statusCode).toBe(409);
+    expect(response.json()).toMatchObject({
+      error: {
+        code: "VALID_001",
+        details: { featureFlag: "portal_home_v1_disabled", reason: "env_hard_off", reasonCode: "portal.feature_disabled" },
+      },
+    });
+    expect(prisma.reimbursementForm.count).not.toHaveBeenCalled();
+    expect(prisma.workflowTask.count).not.toHaveBeenCalled();
+
+    await app.close();
+  });
 });

server/tests/unit/routes/todos.test.js

@@ -0,0 +1,77 @@
+const Fastify = require("fastify");
+const todosRoutes = require("../../../src/routes/todos");
+const { AppError } = require("../../../src/utils/AppError");
+
+async function buildApp({ featureEnabled = true } = {}) {
+  const app = Fastify();
+  const prisma = {
+    featureFlag: {
+      findUnique: vi.fn(async () => ({
+        flag_key: "todo_board_v1",
+        override_mode: featureEnabled ? "force_on" : "force_off",
+        rollout_type: "global",
+        department_ids: [],
+      })),
+    },
+    todoItem: {
+      findMany: vi.fn(async () => []),
+      create: vi.fn(),
+      findUnique: vi.fn(),
+      update: vi.fn(),
+    },
+  };
+  app.decorate("prisma", prisma);
+  app.decorate("config", { todoBoardEnabled: true });
+  app.decorate("authenticate", async (request) => {
+    request.employee = { id: "employee-1", department_id: "department-1", permissionCodes: [] };
+  });
+  app.decorate("hasPermission", () => false);
+  app.setErrorHandler((error, request, reply) => {
+    if (error instanceof AppError) {
+      return reply.code(error.statusCode).send({ error: { code: error.code, details: error.details ?? {} } });
+    }
+    return reply.code(500).send({ error: { code: "SYS_001" } });
+  });
+  await app.register(todosRoutes, { prefix: "/api" });
+  return { app, prisma };
+}
+
+describe("todos feature gate", () => {
+  it("returns a precise reasonCode and skips todo reads when the board is disabled", async () => {
+    const { app, prisma } = await buildApp({ featureEnabled: false });
+    try {
+      const getResponse = await app.inject({ method: "GET", url: "/api/todos" });
+      expect(getResponse.statusCode).toBe(409);
+      expect(getResponse.json()).toEqual({
+        error: {
+          code: "VALID_001",
+          details: { featureFlag: "todo_board_v1_disabled", reason: "flag_force_off", reasonCode: "todo.feature_disabled" },
+        },
+      });
+      expect(prisma.todoItem.findMany).not.toHaveBeenCalled();
+
+      const postResponse = await app.inject({
+        method: "POST",
+        url: "/api/todos",
+        payload: { title: "合成待办" },
+      });
+      expect(postResponse.statusCode).toBe(409);
+      expect(postResponse.json().error.details.reasonCode).toBe("todo.feature_disabled");
+      expect(prisma.todoItem.create).not.toHaveBeenCalled();
+    } finally {
+      await app.close();
+    }
+  });
+
+  it("lists todos normally without leaking a reasonCode when the board is enabled", async () => {
+    const { app, prisma } = await buildApp({ featureEnabled: true });
+    try {
+      const response = await app.inject({ method: "GET", url: "/api/todos" });
+      expect(response.statusCode).toBe(200);
+      expect(response.json().data).toEqual({ items: [] });
+      expect(prisma.todoItem.findMany).toHaveBeenCalledTimes(1);
+    } finally {
+      await app.close();
+    }
+  });
+});