R42: 完成考勤增强首轮交付

2026-03-28 22:13:18 +08:00
@@ -3,10 +3,17 @@ const { Readable } = require("node:stream");
 const ExcelJS = require("exceljs");
 const { z } = require("zod");

+const {
+  HISTORY_STATUS_VALUES,
+  buildPresenceValidationError,
+  buildTeamPresenceHistory,
+  resolvePresenceHistoryRange,
+} = require("../services/presenceHistory");
 const { AppError } = require("../utils/AppError");
 const { buildAuditLogData } = require("../utils/audit");

 const EXPORT_FORMAT_SCHEMA = z.enum(["csv", "xlsx"]);
+const DATE_ONLY_SCHEMA = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);

 const REIMBURSEMENT_STATUS_SCHEMA = z.enum([
  "draft",
@@ -43,8 +50,8 @@ const AUDIT_EXPORT_QUERY_SCHEMA = z.object({

 const DASHBOARD_EXPORT_QUERY_SCHEMA = z.object({
  format: EXPORT_FORMAT_SCHEMA.optional(),
-  dateFrom: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
-  dateTo: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+  dateFrom: DATE_ONLY_SCHEMA.optional(),
+  dateTo: DATE_ONLY_SCHEMA.optional(),
  departmentId: z.string().uuid().optional(),
  limit: z.coerce.number().int().min(1).max(20000).optional(),
 });
@@ -57,6 +64,16 @@ const EMPLOYEE_EXPORT_QUERY_SCHEMA = z.object({
  limit: z.coerce.number().int().min(1).max(20000).optional(),
 });

+const PRESENCE_HISTORY_EXPORT_QUERY_SCHEMA = z.object({
+  format: EXPORT_FORMAT_SCHEMA.optional(),
+  dateFrom: DATE_ONLY_SCHEMA.optional(),
+  dateTo: DATE_ONLY_SCHEMA.optional(),
+  departmentId: z.string().uuid().optional(),
+  employeeId: z.string().uuid().optional(),
+  status: z.enum(HISTORY_STATUS_VALUES).optional(),
+});
+const PRESENCE_HISTORY_EXPORT_LIMIT = 5000;
+
 function csvCell(value) {
  if (value == null) return "";

@@ -801,6 +818,87 @@ async function buildEmployeesXlsx(prisma, where, limit) {
  return workbook.xlsx.writeBuffer();
 }

+function presenceStatusLabel(status) {
+  if (status === "office") return "在岗";
+  if (status === "remote") return "居家";
+  if (status === "out") return "外出";
+  if (status === "travel") return "出差";
+  if (status === "leave") return "请假";
+  return "未更新";
+}
+
+function presenceTimeRangeLabel(timeRange) {
+  if (timeRange === "morning") return "上午";
+  if (timeRange === "afternoon") return "下午";
+  if (timeRange === "full_day") return "全天";
+  return "-";
+}
+
+function presenceSourceLabel(source) {
+  if (source === "manual") return "手工";
+  if (source === "leave_sync") return "审批同步";
+  if (source === "admin_override") return "管理员修正";
+  return "-";
+}
+
+function mapPresenceHistoryExportRow(item) {
+  return [
+    item.date,
+    item.employee.employeeNo,
+    item.employee.name,
+    item.employee.department?.name ?? "",
+    item.employee.title ?? "",
+    presenceStatusLabel(item.presence?.status ?? null),
+    presenceTimeRangeLabel(item.presence?.timeRange),
+    presenceSourceLabel(item.presence?.source),
+    item.presence?.note ?? "-",
+  ];
+}
+
+function buildPresenceHistoryCsv(items) {
+  const rows = [
+    "\ufeff",
+    csvRow(["日期", "工号", "姓名", "部门", "岗位", "状态", "时间段", "来源", "备注"]),
+  ];
+  for (const item of items) {
+    rows.push(csvRow(mapPresenceHistoryExportRow(item)));
+  }
+  return rows.join("");
+}
+
+async function buildPresenceHistoryXlsx(items) {
+  const workbook = new ExcelJS.Workbook();
+  const sheet = workbook.addWorksheet("presence_history");
+
+  sheet.columns = [
+    { header: "日期", key: "date", width: 14 },
+    { header: "工号", key: "employeeNo", width: 14 },
+    { header: "姓名", key: "name", width: 14 },
+    { header: "部门", key: "departmentName", width: 18 },
+    { header: "岗位", key: "title", width: 18 },
+    { header: "状态", key: "status", width: 12 },
+    { header: "时间段", key: "timeRange", width: 12 },
+    { header: "来源", key: "source", width: 14 },
+    { header: "备注", key: "note", width: 32 },
+  ];
+
+  for (const item of items) {
+    sheet.addRow({
+      date: item.date,
+      employeeNo: item.employee.employeeNo,
+      name: item.employee.name,
+      departmentName: item.employee.department?.name ?? "",
+      title: item.employee.title ?? "",
+      status: presenceStatusLabel(item.presence?.status ?? null),
+      timeRange: presenceTimeRangeLabel(item.presence?.timeRange),
+      source: presenceSourceLabel(item.presence?.source),
+      note: item.presence?.note ?? "-",
+    });
+  }
+
+  return workbook.xlsx.writeBuffer();
+}
+
 async function exportsRoutes(fastify) {
  fastify.get(
    "/exports/employees",
@@ -843,6 +941,55 @@ async function exportsRoutes(fastify) {
    },
  );

+  fastify.get(
+    "/exports/presence-history",
+    {
+      preHandler: fastify.requirePermission("system.users"),
+    },
+    async (request, reply) => {
+      const query = parseQuery(PRESENCE_HISTORY_EXPORT_QUERY_SCHEMA, request.query);
+      const format = resolveExportFormat(query);
+      const range = resolvePresenceHistoryRange(query, fastify.config.appTimezone);
+      const history = await buildTeamPresenceHistory(fastify.prisma, {
+        dateStrings: range.dateStrings,
+        departmentId: query.departmentId,
+        employeeId: query.employeeId,
+        status: query.status,
+      });
+
+      if (history.items.length > PRESENCE_HISTORY_EXPORT_LIMIT) {
+        throw buildPresenceValidationError({ export: "too_large" }, 409);
+      }
+
+      await fastify.prisma.auditLog.create({
+        data: buildAuditLogData(request, {
+          actorId: request.employee.id,
+          action: "EXPORT_PRESENCE_HISTORY",
+          targetType: "export",
+          extra: {
+            format,
+            dateFrom: range.dateFrom,
+            dateTo: range.dateTo,
+            departmentId: query.departmentId ?? null,
+            employeeId: query.employeeId ?? null,
+            status: query.status ?? null,
+            matchedTotal: history.items.length,
+          },
+        }),
+      });
+
+      const filename = exportFilename("presence-history", format);
+      setExportHeaders(reply, format, filename);
+
+      if (format === "xlsx") {
+        const buffer = await buildPresenceHistoryXlsx(history.items);
+        return reply.send(Buffer.from(buffer));
+      }
+
+      return reply.send(buildPresenceHistoryCsv(history.items));
+    },
+  );
+
  fastify.get(
    "/exports/reimbursements",
    {
@@ -1,4 +1,8 @@
 const { AppError } = require("../utils/AppError");
+const {
+  buildTeamPresenceSummary,
+  resolvePresenceForEmployee,
+} = require("../services/presenceHistory");
 const { sendData } = require("../utils/reply");
 const { FEATURE_FLAG_KEYS, evaluateFeatureFlag } = require("../services/featureFlags");
 const { getWorkspaceSetting } = require("../services/workspaceSettings");
@@ -78,68 +82,6 @@ function formatPresenceStatus(item) {
  return item.status;
 }

-async function resolvePresenceForEmployee(prisma, employeeId, dateString) {
-  const date = parseDateOnlyString(dateString);
-  const leave = await prisma.leaveRequest.findFirst({
-    where: {
-      owner_id: employeeId,
-      status: "approved",
-      start_date: { lte: date },
-      end_date: { gte: date },
-    },
-    select: { id: true, reason: true },
-  });
-  if (leave) {
-    return { status: "leave", note: leave.reason ?? null, source: "leave_sync" };
-  }
-
-  const travel = await prisma.travelRequest.findFirst({
-    where: {
-      applicant_employee_id: employeeId,
-      status: "approved",
-      start_date: { lte: date },
-      end_date: { gte: date },
-    },
-    select: { id: true, purpose: true },
-  });
-  if (travel) {
-    return { status: "travel", note: travel.purpose ?? null, source: "leave_sync" };
-  }
-
-  const manual = await prisma.employeePresence.findUnique({
-    where: {
-      employee_id_date: {
-        employee_id: employeeId,
-        date,
-      },
-    },
-  });
-  if (!manual) {
-    return null;
-  }
-  return {
-    status: manual.status,
-    note: manual.note ?? null,
-    source: manual.source,
-    timeRange: manual.time_range,
-  };
-}
-
-async function buildTeamPresenceSummary(prisma, dateString) {
-  const employees = await prisma.employee.findMany({ where: { status: "active" }, select: { id: true } });
-  const summary = { office: 0, remote: 0, out: 0, travel: 0, leave: 0, unspecified: 0, total: employees.length };
-  for (const employee of employees) {
-    const item = await resolvePresenceForEmployee(prisma, employee.id, dateString);
-    const status = item?.status;
-    if (!status || !(status in summary)) {
-      summary.unspecified += 1;
-      continue;
-    }
-    summary[status] += 1;
-  }
-  return summary;
-}
-
 function buildQuickLinks({ request, featureEnabled }) {
  const items = [];
  items.push({ key: "team", title: "团队状态", href: "/team" });
@@ -1,40 +1,66 @@
 const { z } = require("zod");

 const { AppError } = require("../utils/AppError");
-const { sendData } = require("../utils/reply");
+const {
+  HISTORY_STATUS_VALUES,
+  PRESENCE_TIME_RANGE_VALUES,
+  PRESENCE_WRITE_STATUS_VALUES,
+  buildMyPresenceHistory,
+  buildPresenceHistoryState,
+  buildPresenceState,
+  buildPresenceSummary,
+  buildPresenceValidationError,
+  buildTeamPresenceHistory,
+  filterHistoryItemsByStatus,
+  mapPresenceRow,
+  listActivePresenceEmployees,
+  resolvePresenceForEmployee,
+  resolvePresenceHistoryRange,
+} = require("../services/presenceHistory");
 const { FEATURE_FLAG_KEYS, evaluateFeatureFlag } = require("../services/featureFlags");
 const { parseDateOnlyString, currentDateString } = require("../utils/date");
+const { sendData } = require("../utils/reply");
+const { buildAuditLogData } = require("../utils/audit");

 const DATE_SCHEMA = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
 const QUERY_SCHEMA = z.object({ date: DATE_SCHEMA.optional() });
 const WRITE_SCHEMA = z
  .object({
    date: DATE_SCHEMA.optional(),
-    status: z.enum(["office", "remote", "out", "travel"]),
-    timeRange: z.enum(["full_day", "morning", "afternoon"]).optional(),
+    status: z.enum(PRESENCE_WRITE_STATUS_VALUES),
+    timeRange: z.enum(PRESENCE_TIME_RANGE_VALUES).optional(),
+    note: z.string().trim().max(300).nullable().optional(),
+  })
+  .strict();
+const HISTORY_QUERY_SCHEMA = z.object({
+  dateFrom: DATE_SCHEMA.optional(),
+  dateTo: DATE_SCHEMA.optional(),
+});
+const TEAM_HISTORY_QUERY_SCHEMA = HISTORY_QUERY_SCHEMA.extend({
+  departmentId: z.string().uuid().optional(),
+  employeeId: z.string().uuid().optional(),
+  status: z.enum(HISTORY_STATUS_VALUES).optional(),
+});
+const TEAM_OVERRIDE_PARAMS_SCHEMA = z.object({
+  employeeId: z.string().uuid(),
+});
+const TEAM_OVERRIDE_BODY_SCHEMA = z
+  .object({
+    date: DATE_SCHEMA,
+    status: z.enum(PRESENCE_WRITE_STATUS_VALUES),
+    timeRange: z.enum(PRESENCE_TIME_RANGE_VALUES).optional(),
    note: z.string().trim().max(300).nullable().optional(),
  })
  .strict();

-function buildValidationError(details, statusCode = 400) {
-  return new AppError({ code: "VALID_001", message: "参数校验失败", statusCode, details });
-}
-
-function parseBody(schema, body) {
-  const parsed = schema.safeParse(body ?? {});
+function parseInput(schema, value) {
+  const parsed = schema.safeParse(value ?? {});
  if (!parsed.success) {
-    throw buildValidationError(parsed.error.flatten());
+    throw buildPresenceValidationError(parsed.error.flatten());
  }
  return parsed.data;
 }

-function formatDateOnly(value) {
-  if (!value) {
-    return null;
-  }
-  return new Date(`${value.toISOString().slice(0, 10)}T00:00:00.000Z`).toISOString().slice(0, 10);
-}
-
 function resolveDateInput(rawDate, timeZone) {
  return rawDate ? rawDate : currentDateString(timeZone ?? "Asia/Shanghai");
 }
@@ -48,188 +74,28 @@ async function ensureFeatureEnabled(fastify, request) {
    strictDepartment: false,
  });
  if (!gate.enabled) {
-    throw buildValidationError({ featureFlag: "presence_board_v1_disabled", reason: gate.reason }, 409);
+    throw buildPresenceValidationError({ featureFlag: "presence_board_v1_disabled", reason: gate.reason }, 409);
  }
 }

-function computeLeaveTimeRange(leave, dateString) {
-  const startDate = formatDateOnly(leave.start_date);
-  const endDate = formatDateOnly(leave.end_date);
-  if (startDate === dateString && endDate === dateString) {
-    if (leave.start_session === "pm" && leave.end_session === "pm") return "afternoon";
-    if (leave.start_session === "am" && leave.end_session === "am") return "morning";
-    return "full_day";
-  }
-  if (startDate === dateString && leave.start_session === "pm") {
-    return "afternoon";
-  }
-  if (endDate === dateString && leave.end_session === "am") {
-    return "morning";
-  }
-  return "full_day";
-}
-
-function mapPresenceRow(row) {
-  if (!row) {
-    return null;
-  }
-  return {
-    id: row.id,
-    employeeId: row.employee_id,
-    date: formatDateOnly(row.date),
-    status: row.status,
-    timeRange: row.time_range,
-    note: row.note ?? null,
-    source: row.source,
-    updatedAt: row.updated_at?.toISOString?.() ?? null,
-  };
-}
-
-async function findLeaveOverlay(prisma, employeeIds, dateString) {
-  if (!employeeIds.length) {
-    return new Map();
-  }
-  const date = parseDateOnlyString(dateString);
-  const rows = await prisma.leaveRequest.findMany({
-    where: {
-      owner_id: { in: employeeIds },
-      status: "approved",
-      start_date: { lte: date },
-      end_date: { gte: date },
-    },
-    select: {
-      id: true,
-      owner_id: true,
-      start_date: true,
-      end_date: true,
-      start_session: true,
-      end_session: true,
-      reason: true,
-    },
-  });
-  const map = new Map();
-  for (const row of rows) {
-    if (!map.has(row.owner_id)) {
-      map.set(row.owner_id, {
-        id: `leave-${row.id}`,
-        employeeId: row.owner_id,
-        date: dateString,
-        status: "leave",
-        timeRange: computeLeaveTimeRange(row, dateString),
-        note: row.reason ?? null,
-        source: "leave_sync",
-        updatedAt: null,
-      });
-    }
-  }
-  return map;
-}
-
-async function findTravelOverlay(prisma, employeeIds, dateString) {
-  if (!employeeIds.length) {
-    return new Map();
-  }
-  const date = parseDateOnlyString(dateString);
-  const rows = await prisma.travelRequest.findMany({
-    where: {
-      applicant_employee_id: { in: employeeIds },
-      status: "approved",
-      start_date: { lte: date },
-      end_date: { gte: date },
-    },
-    select: {
-      id: true,
-      applicant_employee_id: true,
-      purpose: true,
-    },
-  });
-  const map = new Map();
-  for (const row of rows) {
-    if (!map.has(row.applicant_employee_id)) {
-      map.set(row.applicant_employee_id, {
-        id: `travel-${row.id}`,
-        employeeId: row.applicant_employee_id,
-        date: dateString,
-        status: "travel",
-        timeRange: "full_day",
-        note: row.purpose ?? null,
-        source: "leave_sync",
-        updatedAt: null,
-      });
-    }
-  }
-  return map;
-}
-
-async function buildPresenceState(prisma, employeeIds, dateString) {
-  const [manualRows, leaveOverlay, travelOverlay] = await Promise.all([
-    prisma.employeePresence.findMany({
-      where: { employee_id: { in: employeeIds }, date: parseDateOnlyString(dateString) },
-    }),
-    findLeaveOverlay(prisma, employeeIds, dateString),
-    findTravelOverlay(prisma, employeeIds, dateString),
-  ]);
-
-  const manualMap = new Map(manualRows.map((row) => [row.employee_id, mapPresenceRow(row)]));
-  const result = new Map();
-  for (const employeeId of employeeIds) {
-    if (leaveOverlay.has(employeeId)) {
-      result.set(employeeId, leaveOverlay.get(employeeId));
-      continue;
-    }
-    if (travelOverlay.has(employeeId)) {
-      result.set(employeeId, travelOverlay.get(employeeId));
-      continue;
-    }
-    if (manualMap.has(employeeId)) {
-      result.set(employeeId, manualMap.get(employeeId));
-    }
-  }
-  return result;
-}
-
-function buildSummary(items) {
-  const summary = {
-    office: 0,
-    remote: 0,
-    out: 0,
-    travel: 0,
-    leave: 0,
-    unspecified: 0,
-    total: items.length,
-  };
-
-  for (const item of items) {
-    const status = item.presence?.status;
-    if (!status || !(status in summary)) {
-      summary.unspecified += 1;
-      continue;
-    }
-    summary[status] += 1;
-  }
-  return summary;
-}
-
 async function presenceRoutes(fastify) {
  fastify.get("/presence/me", { preHandler: fastify.authenticate }, async (request, reply) => {
    await ensureFeatureEnabled(fastify, request);
-    const parsed = QUERY_SCHEMA.safeParse(request.query ?? {});
-    if (!parsed.success) {
-      throw buildValidationError(parsed.error.flatten());
-    }
-    const dateString = resolveDateInput(parsed.data.date, fastify.config.appTimezone);
+    const query = parseInput(QUERY_SCHEMA, request.query);
+    const dateString = resolveDateInput(query.date, fastify.config.appTimezone);
    const map = await buildPresenceState(fastify.prisma, [request.employee.id], dateString);
    return sendData(reply, request, { item: map.get(request.employee.id) ?? null, date: dateString });
  });

  fastify.put("/presence/me", { preHandler: fastify.authenticate }, async (request, reply) => {
    await ensureFeatureEnabled(fastify, request);
-    const body = parseBody(WRITE_SCHEMA, request.body);
+    const body = parseInput(WRITE_SCHEMA, request.body);
    const dateString = resolveDateInput(body.date, fastify.config.appTimezone);
-    const leaveOverlay = await findLeaveOverlay(fastify.prisma, [request.employee.id], dateString);
-    if (leaveOverlay.has(request.employee.id)) {
-      throw buildValidationError({ date: "covered_by_approved_leave" }, 409);
+    const before = await resolvePresenceForEmployee(fastify.prisma, request.employee.id, dateString);
+    if (before?.source === "leave_sync" && before.status === "leave") {
+      throw buildPresenceValidationError({ date: "covered_by_approved_leave" }, 409);
    }
+
    const record = await fastify.prisma.employeePresence.upsert({
      where: {
        employee_id_date: {
@@ -254,57 +120,146 @@ async function presenceRoutes(fastify) {
        updated_by: request.employee.id,
      },
    });
+
    return sendData(reply, request, { item: mapPresenceRow(record) });
  });

  fastify.get("/presence/team", { preHandler: fastify.authenticate }, async (request, reply) => {
    await ensureFeatureEnabled(fastify, request);
-    const parsed = QUERY_SCHEMA.safeParse(request.query ?? {});
-    if (!parsed.success) {
-      throw buildValidationError(parsed.error.flatten());
-    }
-    const dateString = resolveDateInput(parsed.data.date, fastify.config.appTimezone);
-    const employees = await fastify.prisma.employee.findMany({
-      where: { status: "active" },
-      orderBy: [{ department_id: "asc" }, { employee_no: "asc" }],
-      select: {
-        id: true,
-        employee_no: true,
-        name: true,
-        title: true,
-        employment_status: true,
-        department: { select: { id: true, name: true } },
-      },
-    });
-    const map = await buildPresenceState(fastify.prisma, employees.map((item) => item.id), dateString);
+    const query = parseInput(QUERY_SCHEMA, request.query);
+    const dateString = resolveDateInput(query.date, fastify.config.appTimezone);
+    const employees = await listActivePresenceEmployees(fastify.prisma);
+    const map = await buildPresenceState(
+      fastify.prisma,
+      employees.map((item) => item.id),
+      dateString,
+    );
    const items = employees.map((item) => ({
-      employee: {
-        id: item.id,
-        employeeNo: item.employee_no,
-        name: item.name,
-        title: item.title,
-        employmentStatus: item.employment_status,
-        department: item.department ? { id: item.department.id, name: item.department.name } : null,
-      },
+      employee: item,
      presence: map.get(item.id) ?? null,
    }));
-    return sendData(reply, request, { date: dateString, summary: buildSummary(items), items });
+    return sendData(reply, request, {
+      date: dateString,
+      summary: buildPresenceSummary(items),
+      items,
+    });
  });

+  fastify.get("/presence/me/history", { preHandler: fastify.authenticate }, async (request, reply) => {
+    await ensureFeatureEnabled(fastify, request);
+    const query = parseInput(HISTORY_QUERY_SCHEMA, request.query);
+    const range = resolvePresenceHistoryRange(query, fastify.config.appTimezone);
+    const history = await buildMyPresenceHistory(fastify.prisma, request.employee.id, range.dateStrings);
+    return sendData(reply, request, {
+      dateFrom: range.dateFrom,
+      dateTo: range.dateTo,
+      summary: history.summary,
+      items: history.items,
+    });
+  });
+
+  fastify.get("/presence/team/history", { preHandler: fastify.authenticate }, async (request, reply) => {
+    await ensureFeatureEnabled(fastify, request);
+    const query = parseInput(TEAM_HISTORY_QUERY_SCHEMA, request.query);
+    const range = resolvePresenceHistoryRange(query, fastify.config.appTimezone);
+    const history = await buildTeamPresenceHistory(fastify.prisma, {
+      dateStrings: range.dateStrings,
+      departmentId: query.departmentId,
+      employeeId: query.employeeId,
+      status: query.status,
+    });
+
+    return sendData(reply, request, {
+      dateFrom: range.dateFrom,
+      dateTo: range.dateTo,
+      summary: history.summary,
+      items: history.items,
+    });
+  });
+
+  fastify.put(
+    "/presence/team/:employeeId",
+    {
+      preHandler: fastify.requirePermission("system.users"),
+    },
+    async (request, reply) => {
+      await ensureFeatureEnabled(fastify, request);
+      const params = parseInput(TEAM_OVERRIDE_PARAMS_SCHEMA, request.params);
+      const body = parseInput(TEAM_OVERRIDE_BODY_SCHEMA, request.body);
+
+      const employee = await fastify.prisma.employee.findUnique({
+        where: { id: params.employeeId },
+        select: { id: true, status: true },
+      });
+      if (!employee || employee.status !== "active") {
+        throw new AppError({ code: "SYS_404", message: "Not Found", statusCode: 404 });
+      }
+
+      const before = await resolvePresenceForEmployee(fastify.prisma, params.employeeId, body.date);
+      const record = await fastify.prisma.employeePresence.upsert({
+        where: {
+          employee_id_date: {
+            employee_id: params.employeeId,
+            date: parseDateOnlyString(body.date),
+          },
+        },
+        update: {
+          status: body.status,
+          time_range: body.timeRange ?? "full_day",
+          note: body.note ?? null,
+          source: "admin_override",
+          updated_by: request.employee.id,
+        },
+        create: {
+          employee_id: params.employeeId,
+          date: parseDateOnlyString(body.date),
+          status: body.status,
+          time_range: body.timeRange ?? "full_day",
+          note: body.note ?? null,
+          source: "admin_override",
+          updated_by: request.employee.id,
+        },
+      });
+
+      const after = mapPresenceRow(record);
+      await fastify.prisma.auditLog.create({
+        data: buildAuditLogData(request, {
+          actorId: request.employee.id,
+          action: "PRESENCE_ADMIN_CORRECTED",
+          targetType: "employee_presence",
+          targetId: params.employeeId,
+          extra: {
+            employeeId: params.employeeId,
+            date: body.date,
+            before,
+            after,
+          },
+        }),
+      });
+
+      return sendData(reply, request, { item: after });
+    },
+  );
+
  fastify.get("/presence/summary", { preHandler: fastify.authenticate }, async (request, reply) => {
    await ensureFeatureEnabled(fastify, request);
-    const parsed = QUERY_SCHEMA.safeParse(request.query ?? {});
-    if (!parsed.success) {
-      throw buildValidationError(parsed.error.flatten());
-    }
-    const dateString = resolveDateInput(parsed.data.date, fastify.config.appTimezone);
-    const employeeIds = (
-      await fastify.prisma.employee.findMany({ where: { status: "active" }, select: { id: true } })
-    ).map((item) => item.id);
+    const query = parseInput(QUERY_SCHEMA, request.query);
+    const dateString = resolveDateInput(query.date, fastify.config.appTimezone);
+    const employeeIds = (await listActivePresenceEmployees(fastify.prisma)).map((item) => item.id);
    const map = await buildPresenceState(fastify.prisma, employeeIds, dateString);
    const items = employeeIds.map((employeeId) => ({ employeeId, presence: map.get(employeeId) ?? null }));
-    return sendData(reply, request, { date: dateString, summary: buildSummary(items) });
+    return sendData(reply, request, {
+      date: dateString,
+      summary: buildPresenceSummary(items),
+    });
  });
 }

+presenceRoutes.__testables = {
+  buildPresenceHistoryState,
+  filterHistoryItemsByStatus,
+  listActivePresenceEmployees,
+  resolveHistoryRange: resolvePresenceHistoryRange,
+};
+
 module.exports = presenceRoutes;
@@ -0,0 +1,402 @@
+const { AppError } = require("../utils/AppError");
+const { currentDateString, parseDateOnlyString } = require("../utils/date");
+
+const HISTORY_STATUS_VALUES = ["office", "remote", "out", "travel", "leave", "unspecified"];
+const PRESENCE_WRITE_STATUS_VALUES = ["office", "remote", "out", "travel"];
+const PRESENCE_TIME_RANGE_VALUES = ["full_day", "morning", "afternoon"];
+const HISTORY_DEFAULT_DAYS = 7;
+const HISTORY_MAX_DAYS = 31;
+
+function buildPresenceValidationError(details, statusCode = 400) {
+  return new AppError({
+    code: "VALID_001",
+    message: "参数校验失败",
+    statusCode,
+    details,
+  });
+}
+
+function formatDateOnly(value) {
+  if (!value) {
+    return null;
+  }
+  return new Date(`${value.toISOString().slice(0, 10)}T00:00:00.000Z`).toISOString().slice(0, 10);
+}
+
+function addUtcDays(date, days) {
+  const next = new Date(date.getTime());
+  next.setUTCDate(next.getUTCDate() + days);
+  return next;
+}
+
+function buildDateStrings(dateFrom, dateTo) {
+  const items = [];
+  for (let current = new Date(dateFrom.getTime()); current <= dateTo; current = addUtcDays(current, 1)) {
+    items.push(formatDateOnly(current));
+  }
+  return items;
+}
+
+function resolvePresenceHistoryRange(query, timeZone) {
+  const todayString = currentDateString(timeZone ?? "Asia/Shanghai");
+  let dateFrom = query.dateFrom ?? null;
+  let dateTo = query.dateTo ?? null;
+
+  if (!dateFrom && !dateTo) {
+    dateTo = todayString;
+    dateFrom = formatDateOnly(addUtcDays(parseDateOnlyString(dateTo), -(HISTORY_DEFAULT_DAYS - 1)));
+  } else if (!dateFrom && dateTo) {
+    dateFrom = formatDateOnly(addUtcDays(parseDateOnlyString(dateTo), -(HISTORY_DEFAULT_DAYS - 1)));
+  } else if (dateFrom && !dateTo) {
+    dateTo = todayString;
+  }
+
+  const start = parseDateOnlyString(dateFrom);
+  const end = parseDateOnlyString(dateTo);
+  if (start > end) {
+    throw buildPresenceValidationError({ dateTo: "must_be_after_or_equal_dateFrom" });
+  }
+
+  const totalDays = Math.floor((end.getTime() - start.getTime()) / 86400000) + 1;
+  if (totalDays > HISTORY_MAX_DAYS) {
+    throw buildPresenceValidationError({ dateRange: "too_large" });
+  }
+
+  return {
+    dateFrom,
+    dateTo,
+    dateStrings: buildDateStrings(start, end),
+  };
+}
+
+function computeLeaveTimeRange(leave, dateString) {
+  const startDate = formatDateOnly(leave.start_date);
+  const endDate = formatDateOnly(leave.end_date);
+  if (startDate === dateString && endDate === dateString) {
+    if (leave.start_session === "pm" && leave.end_session === "pm") return "afternoon";
+    if (leave.start_session === "am" && leave.end_session === "am") return "morning";
+    return "full_day";
+  }
+  if (startDate === dateString && leave.start_session === "pm") {
+    return "afternoon";
+  }
+  if (endDate === dateString && leave.end_session === "am") {
+    return "morning";
+  }
+  return "full_day";
+}
+
+function mapPresenceRow(row) {
+  if (!row) {
+    return null;
+  }
+  return {
+    id: row.id,
+    employeeId: row.employee_id,
+    date: formatDateOnly(row.date),
+    status: row.status,
+    timeRange: row.time_range,
+    note: row.note ?? null,
+    source: row.source,
+    updatedAt: row.updated_at?.toISOString?.() ?? null,
+  };
+}
+
+function mapPresenceEmployee(row) {
+  return {
+    id: row.id,
+    employeeNo: row.employee_no,
+    name: row.name,
+    title: row.title,
+    employmentStatus: row.employment_status,
+    department: row.department ? { id: row.department.id, name: row.department.name } : null,
+  };
+}
+
+function comparePresenceEmployees(left, right) {
+  const departmentCompare = (left.department?.name ?? "").localeCompare(right.department?.name ?? "", "zh-CN");
+  if (departmentCompare !== 0) {
+    return departmentCompare;
+  }
+  return left.employeeNo.localeCompare(right.employeeNo, "en");
+}
+
+function buildHistoryKey(employeeId, dateString) {
+  return `${employeeId}:${dateString}`;
+}
+
+function buildTravelPresence(row, dateString) {
+  return {
+    id: `travel-${row.id}`,
+    employeeId: row.applicant_employee_id,
+    date: dateString,
+    status: "travel",
+    timeRange: "full_day",
+    note: row.purpose ?? null,
+    source: "leave_sync",
+    updatedAt: null,
+  };
+}
+
+function buildLeavePresence(row, dateString) {
+  return {
+    id: `leave-${row.id}`,
+    employeeId: row.owner_id,
+    date: dateString,
+    status: "leave",
+    timeRange: computeLeaveTimeRange(row, dateString),
+    note: row.reason ?? null,
+    source: "leave_sync",
+    updatedAt: null,
+  };
+}
+
+async function buildPresenceHistoryState(prisma, employeeIds, dateStrings) {
+  if (!employeeIds.length || !dateStrings.length) {
+    return new Map();
+  }
+
+  const dateFrom = dateStrings[0];
+  const dateTo = dateStrings[dateStrings.length - 1];
+  const [presenceRows, leaveRows, travelRows] = await Promise.all([
+    prisma.employeePresence.findMany({
+      where: {
+        employee_id: { in: employeeIds },
+        date: {
+          gte: parseDateOnlyString(dateFrom),
+          lte: parseDateOnlyString(dateTo),
+        },
+      },
+    }),
+    prisma.leaveRequest.findMany({
+      where: {
+        owner_id: { in: employeeIds },
+        status: "approved",
+        start_date: { lte: parseDateOnlyString(dateTo) },
+        end_date: { gte: parseDateOnlyString(dateFrom) },
+      },
+      select: {
+        id: true,
+        owner_id: true,
+        start_date: true,
+        end_date: true,
+        start_session: true,
+        end_session: true,
+        reason: true,
+      },
+    }),
+    prisma.travelRequest.findMany({
+      where: {
+        applicant_employee_id: { in: employeeIds },
+        status: "approved",
+        start_date: { lte: parseDateOnlyString(dateTo) },
+        end_date: { gte: parseDateOnlyString(dateFrom) },
+      },
+      select: {
+        id: true,
+        applicant_employee_id: true,
+        start_date: true,
+        end_date: true,
+        purpose: true,
+      },
+    }),
+  ]);
+
+  const result = new Map();
+  const adminOverrideMap = new Map();
+  for (const row of presenceRows) {
+    const key = buildHistoryKey(row.employee_id, formatDateOnly(row.date));
+    const mapped = mapPresenceRow(row);
+    if (row.source === "admin_override") {
+      adminOverrideMap.set(key, mapped);
+    } else {
+      result.set(key, mapped);
+    }
+  }
+
+  for (const row of travelRows) {
+    const startDate = formatDateOnly(row.start_date);
+    const endDate = formatDateOnly(row.end_date);
+    for (const dateString of dateStrings) {
+      if (dateString < startDate || dateString > endDate) {
+        continue;
+      }
+      const key = buildHistoryKey(row.applicant_employee_id, dateString);
+      if (!result.has(key) || result.get(key)?.source !== "leave_sync") {
+        result.set(key, buildTravelPresence(row, dateString));
+      }
+    }
+  }
+
+  for (const row of leaveRows) {
+    const startDate = formatDateOnly(row.start_date);
+    const endDate = formatDateOnly(row.end_date);
+    for (const dateString of dateStrings) {
+      if (dateString < startDate || dateString > endDate) {
+        continue;
+      }
+      const key = buildHistoryKey(row.owner_id, dateString);
+      result.set(key, buildLeavePresence(row, dateString));
+    }
+  }
+
+  for (const [key, value] of adminOverrideMap.entries()) {
+    result.set(key, value);
+  }
+
+  return result;
+}
+
+async function buildPresenceState(prisma, employeeIds, dateString) {
+  const historyMap = await buildPresenceHistoryState(prisma, employeeIds, [dateString]);
+  const result = new Map();
+  for (const employeeId of employeeIds) {
+    const key = buildHistoryKey(employeeId, dateString);
+    if (historyMap.has(key)) {
+      result.set(employeeId, historyMap.get(key));
+    }
+  }
+  return result;
+}
+
+async function resolvePresenceForEmployee(prisma, employeeId, dateString) {
+  const map = await buildPresenceState(prisma, [employeeId], dateString);
+  return map.get(employeeId) ?? null;
+}
+
+function buildPresenceSummary(items) {
+  const summary = {
+    office: 0,
+    remote: 0,
+    out: 0,
+    travel: 0,
+    leave: 0,
+    unspecified: 0,
+    total: items.length,
+  };
+
+  for (const item of items) {
+    const status = item.presence?.status;
+    if (!status || !(status in summary)) {
+      summary.unspecified += 1;
+      continue;
+    }
+    summary[status] += 1;
+  }
+
+  return summary;
+}
+
+function filterHistoryItemsByStatus(items, status) {
+  if (!status) {
+    return items;
+  }
+  if (status === "unspecified") {
+    return items.filter((item) => !item.presence);
+  }
+  return items.filter((item) => item.presence?.status === status);
+}
+
+async function listActivePresenceEmployees(prisma, filters = {}) {
+  const employees = await prisma.employee.findMany({
+    where: {
+      status: "active",
+      ...(filters.departmentId ? { department_id: filters.departmentId } : {}),
+      ...(filters.employeeId ? { id: filters.employeeId } : {}),
+    },
+    select: {
+      id: true,
+      employee_no: true,
+      name: true,
+      title: true,
+      employment_status: true,
+      department: { select: { id: true, name: true } },
+    },
+  });
+
+  return employees.map(mapPresenceEmployee).sort(comparePresenceEmployees);
+}
+
+function buildTeamHistoryItems(employees, dateStrings, historyMap) {
+  return [...dateStrings]
+    .reverse()
+    .flatMap((date) =>
+      employees.map((employee) => ({
+        date,
+        employee,
+        presence: historyMap.get(buildHistoryKey(employee.id, date)) ?? null,
+      })),
+    );
+}
+
+async function buildMyPresenceHistory(prisma, employeeId, dateStrings) {
+  const historyMap = await buildPresenceHistoryState(prisma, [employeeId], dateStrings);
+  const items = [...dateStrings].reverse().map((date) => ({
+    date,
+    presence: historyMap.get(buildHistoryKey(employeeId, date)) ?? null,
+  }));
+  return {
+    items,
+    summary: buildPresenceSummary(items),
+  };
+}
+
+async function buildTeamPresenceHistory(prisma, options) {
+  const employees = await listActivePresenceEmployees(prisma, {
+    departmentId: options.departmentId,
+    employeeId: options.employeeId,
+  });
+  const historyMap = await buildPresenceHistoryState(
+    prisma,
+    employees.map((item) => item.id),
+    options.dateStrings,
+  );
+  const items = filterHistoryItemsByStatus(
+    buildTeamHistoryItems(employees, options.dateStrings, historyMap),
+    options.status,
+  );
+
+  return {
+    employees,
+    items,
+    summary: buildPresenceSummary(items),
+  };
+}
+
+async function buildTeamPresenceSummary(prisma, dateString) {
+  const employees = await listActivePresenceEmployees(prisma);
+  const map = await buildPresenceState(
+    prisma,
+    employees.map((item) => item.id),
+    dateString,
+  );
+  const items = employees.map((employee) => ({
+    employee,
+    presence: map.get(employee.id) ?? null,
+  }));
+  return buildPresenceSummary(items);
+}
+
+module.exports = {
+  HISTORY_DEFAULT_DAYS,
+  HISTORY_MAX_DAYS,
+  HISTORY_STATUS_VALUES,
+  PRESENCE_TIME_RANGE_VALUES,
+  PRESENCE_WRITE_STATUS_VALUES,
+  addUtcDays,
+  buildHistoryKey,
+  buildMyPresenceHistory,
+  buildPresenceHistoryState,
+  buildPresenceState,
+  buildPresenceSummary,
+  buildPresenceValidationError,
+  buildTeamPresenceHistory,
+  buildTeamPresenceSummary,
+  filterHistoryItemsByStatus,
+  formatDateOnly,
+  listActivePresenceEmployees,
+  mapPresenceEmployee,
+  mapPresenceRow,
+  resolvePresenceForEmployee,
+  resolvePresenceHistoryRange,
+};