R38: 完成员工管理筛选与部门树试跑

server/src/routes/employees.js

@@ -281,7 +281,7 @@ async function buildEmployeeProfile(prisma, employeeId) {
 }
 
 async function employeesRoutes(fastify) {
-  await usersRoutes(fastify, { basePath: "/employees" });
+  await usersRoutes(fastify, { basePath: "/employees", allowDepartmentFilter: true });
 
   fastify.get("/employees/:id/profile", { preHandler: fastify.authenticate }, async (request, reply) => {
     await ensureFeatureEnabled(fastify, request);

server/src/routes/users.js

@@ -32,6 +32,9 @@ const listQuerySchema = z.object({
   status: z.enum(["active", "archived"]).optional(),
   q: z.string().max(100).optional(),
 });
+const listQueryWithDepartmentSchema = listQuerySchema.extend({
+  departmentId: z.string().uuid().optional(),
+});
 
 const createBodySchema = z.object({
   employeeNo: z.string().min(1).max(50),
@@ -86,8 +89,10 @@ function parseUserId(params) {
   return parsed.data;
 }
 
-function parseListQuery(query) {
-  const parsed = listQuerySchema.safeParse(query ?? {});
+function parseListQuery(query, options = {}) {
+  const allowDepartmentFilter = options.allowDepartmentFilter === true;
+  const schema = allowDepartmentFilter ? listQueryWithDepartmentSchema : listQuerySchema;
+  const parsed = schema.safeParse(query ?? {});
   if (!parsed.success) {
     throw new AppError({
       code: "VALID_001",
@@ -102,6 +107,7 @@ function parseListQuery(query) {
     pageSize: parsed.data.pageSize ?? 20,
     status: parsed.data.status,
     q: parsed.data.q?.trim() ?? "",
+    departmentId: allowDepartmentFilter ? parsed.data.departmentId : undefined,
   };
 }
 
@@ -232,6 +238,7 @@ async function usersRoutes(fastify, opts = {}) {
     typeof opts.basePath === "string" && opts.basePath.trim() ? opts.basePath.trim() : "/users";
   const basePath = basePathRaw.startsWith("/") ? basePathRaw : `/${basePathRaw}`;
   const routeBasePath = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+  const allowDepartmentFilter = opts.allowDepartmentFilter === true;
 
   fastify.get(
     routeBasePath,
@@ -239,12 +246,13 @@ async function usersRoutes(fastify, opts = {}) {
       preHandler: fastify.requirePermission("system.users"),
     },
     async (request, reply) => {
-      const query = parseListQuery(request.query);
+      const query = parseListQuery(request.query, { allowDepartmentFilter });
       const skip = (query.page - 1) * query.pageSize;
 
       const q = query.q;
       const where = {
         ...(query.status ? { status: query.status } : {}),
+        ...(query.departmentId ? { department_id: query.departmentId } : {}),
         ...(q
           ? {
               OR: [

server/tests/unit/routes/users.list.test.js

@@ -0,0 +1,129 @@
+const Fastify = require("fastify");
+
+const usersRoutes = require("../../../src/routes/users");
+
+function buildEmployeeRow(overrides = {}) {
+  const now = new Date("2026-03-28T10:00:00.000Z");
+  return {
+    id: "11111111-1111-4111-8111-111111111111",
+    employee_no: "E001",
+    name: "Alice",
+    phone: "13800000000",
+    email: "[email protected]",
+    status: "active",
+    department_id: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+    title: "员工",
+    created_at: now,
+    updated_at: now,
+    roles: [{ role_code: "employee" }],
+    ...overrides,
+  };
+}
+
+async function buildApp(routeOptions = {}) {
+  const app = Fastify();
+  const findMany = vi.fn().mockResolvedValue([buildEmployeeRow()]);
+  const count = vi.fn().mockResolvedValue(1);
+
+  app.decorate("prisma", {
+    employee: {
+      findMany,
+      count,
+    },
+  });
+  app.decorate("requirePermission", () => async (request) => {
+    request.employee = {
+      id: "actor-1",
+      department_id: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+      permissionCodes: ["system.users"],
+    };
+  });
+  app.decorate("authenticate", async (request) => {
+    request.employee = {
+      id: "actor-1",
+      department_id: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+      permissionCodes: ["system.users"],
+    };
+  });
+  app.decorate("hasPermission", () => true);
+  app.decorate("config", {});
+
+  await app.register(usersRoutes, { prefix: "/api", ...routeOptions });
+  return { app, findMany, count };
+}
+
+describe("usersRoutes list query", () => {
+  it("supports departmentId filter for /employees when enabled", async () => {
+    const departmentId = "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb";
+    const { app, findMany, count } = await buildApp({
+      basePath: "/employees",
+      allowDepartmentFilter: true,
+    });
+
+    const response = await app.inject({
+      method: "GET",
+      url: `/api/employees?page=1&pageSize=20&departmentId=${departmentId}`,
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(findMany).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: expect.objectContaining({
+          department_id: departmentId,
+        }),
+      }),
+    );
+    expect(count).toHaveBeenCalledWith({
+      where: expect.objectContaining({
+        department_id: departmentId,
+      }),
+    });
+
+    await app.close();
+  });
+
+  it("combines q + status + departmentId for /employees", async () => {
+    const departmentId = "cccccccc-cccc-4ccc-8ccc-cccccccccccc";
+    const { app, findMany } = await buildApp({
+      basePath: "/employees",
+      allowDepartmentFilter: true,
+    });
+
+    const response = await app.inject({
+      method: "GET",
+      url: `/api/employees?status=active&q=alice&departmentId=${departmentId}`,
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(findMany).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: expect.objectContaining({
+          status: "active",
+          department_id: departmentId,
+          OR: expect.arrayContaining([
+            expect.objectContaining({ name: expect.any(Object) }),
+            expect.objectContaining({ employee_no: expect.any(Object) }),
+          ]),
+        }),
+      }),
+    );
+
+    await app.close();
+  });
+
+  it("does not apply departmentId filter for /users", async () => {
+    const departmentId = "dddddddd-dddd-4ddd-8ddd-dddddddddddd";
+    const { app, findMany } = await buildApp();
+
+    const response = await app.inject({
+      method: "GET",
+      url: `/api/users?departmentId=${departmentId}`,
+    });
+
+    expect(response.statusCode).toBe(200);
+    const where = findMany.mock.calls[0][0].where;
+    expect(where.department_id).toBeUndefined();
+
+    await app.close();
+  });
+});