迁移首批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]>
2026-09-25 21:16:55 +08:00
@@ -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)]));
@@ -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({
-      code: "VALID_001",
-      message: "参数校验失败",
-      statusCode: 409,
-      details: { featureFlag: "payment_batch_v1_disabled", reason: gate.reason },
-    });
+    throw buildBusinessValidationError(
+      "ap_operations.feature_disabled",
+      { featureFlag: "payment_batch_v1_disabled", reason: gate.reason },
+      409,
+    );
  }
 }

@@ -208,12 +208,7 @@ async function apOperationsRoutes(fastify) {

    const parsed = FINANCE_LEDGER_QUERY_SCHEMA.safeParse(request.query ?? {});
    if (!parsed.success) {
-      throw new AppError({
-        code: "VALID_001",
-        message: "参数校验失败",
-        statusCode: 400,
-        details: parsed.error.flatten(),
-      });
+      throw buildBusinessValidationError("ap_operations.query_invalid", parsed.error.flatten(), 400);
    }

    const ledger = await listFinanceLedger(fastify.prisma, parsed.data);
@@ -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({
-      code: "VALID_001",
-      message: "参数校验失败",
-      statusCode: 409,
-      details: { featureFlag: "portal_home_v1_disabled", reason: gate.reason },
-    });
+    throw buildBusinessValidationError(
+      "portal.feature_disabled",
+      { featureFlag: "portal_home_v1_disabled", reason: gate.reason },
+      409,
+    );
  }
 }

@@ -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,
+    );
  }
 }

@@ -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": "工作台暂未开放，请联系管理员确认处理方式。"
 }
@@ -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();
+    }
+  });
 });
@@ -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();
+  });
 });
@@ -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();
+    }
+  });
+});