From cd01e4bf28282aed55800dc5107aa583daf66430 Mon Sep 17 00:00:00 2001 From: shunli Date: Fri, 25 Sep 2026 21:16:55 +0800 Subject: [PATCH] =?UTF-8?q?=E8=BF=81=E7=A7=BB=E9=A6=96=E6=89=B94=E4=B8=AA?= =?UTF-8?q?=E9=94=99=E8=AF=AF=E7=A0=81=EF=BC=9AAP=E5=8F=B0=E8=B4=A6/?= =?UTF-8?q?=E6=9F=A5=E8=AF=A2=E3=80=81=E5=BE=85=E5=8A=9E=E3=80=81=E5=B7=A5?= =?UTF-8?q?=E4=BD=9C=E5=8F=B0=E5=8A=9F=E8=83=BD=E5=BC=80=E5=85=B3=20[09-05?= =?UTF-8?q?-error-explainability-payment-readiness]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- client/src/api/errorReasons.ts | 4 + scripts/qa/error-reason-legacy-baseline.json | 4 - server/src/constants/errorReasons.js | 4 + server/src/routes/apOperations.js | 19 ++--- server/src/routes/portal.js | 12 +-- server/src/routes/todos.js | 7 +- .../unit/fixtures/error-reason-messages.json | 6 +- .../routes/apOperations.permissions.test.js | 43 ++++++++++- server/tests/unit/routes/portal.test.js | 23 ++++++ server/tests/unit/routes/todos.test.js | 77 +++++++++++++++++++ 10 files changed, 172 insertions(+), 27 deletions(-) create mode 100644 server/tests/unit/routes/todos.test.js diff --git a/client/src/api/errorReasons.ts b/client/src/api/errorReasons.ts index 02278871..835c018b 100644 --- a/client/src/api/errorReasons.ts +++ b/client/src/api/errorReasons.ts @@ -228,6 +228,10 @@ export const ERROR_REASON_MESSAGES: Record = { "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 = "操作未完成，请核对页面提示；如仍无法继续，请联系管理员协助处理。"; diff --git a/scripts/qa/error-reason-legacy-baseline.json b/scripts/qa/error-reason-legacy-baseline.json index 43ccf58f..7a82ff76 100644 --- a/scripts/qa/error-reason-legacy-baseline.json +++ b/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"}, diff --git a/server/src/constants/errorReasons.js b/server/src/constants/errorReasons.js index 087f373e..269d1306 100644 --- a/server/src/constants/errorReasons.js +++ b/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)])); diff --git a/server/src/routes/apOperations.js b/server/src/routes/apOperations.js index 19d34958..6948bcf3 100644 --- a/server/src/routes/apOperations.js +++ b/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({ - 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); diff --git a/server/src/routes/portal.js b/server/src/routes/portal.js index f9c762bd..3d803b8d 100644 --- a/server/src/routes/portal.js +++ b/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({ - 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, + ); } } diff --git a/server/src/routes/todos.js b/server/src/routes/todos.js index 6cbd2f03..34d832ab 100644 --- a/server/src/routes/todos.js +++ b/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, + ); } } diff --git a/server/tests/unit/fixtures/error-reason-messages.json b/server/tests/unit/fixtures/error-reason-messages.json index 2979b58f..56935e24 100644 --- a/server/tests/unit/fixtures/error-reason-messages.json +++ b/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": "工作台暂未开放，请联系管理员确认处理方式。" } diff --git a/server/tests/unit/routes/apOperations.permissions.test.js b/server/tests/unit/routes/apOperations.permissions.test.js index 5b362825..ccffe68f 100644 --- a/server/tests/unit/routes/apOperations.permissions.test.js +++ b/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(); + } + }); }); diff --git a/server/tests/unit/routes/portal.test.js b/server/tests/unit/routes/portal.test.js index e6077274..cb40fbae 100644 --- a/server/tests/unit/routes/portal.test.js +++ b/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(); + }); }); diff --git a/server/tests/unit/routes/todos.test.js b/server/tests/unit/routes/todos.test.js new file mode 100644 index 00000000..a77320a6 --- /dev/null +++ b/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(); + } + }); +});