feat: settle course attendance automatically

2026-07-13 10:26:38 +08:00
parent b9b295c997
commit 1c8bd08be4
11 changed files with 730 additions and 87 deletions
--- a/apps/admin/src/pages/Attendance/attendance-workspace.integration.test.ts
+++ b/apps/admin/src/pages/Attendance/attendance-workspace.integration.test.ts
@@ -4,6 +4,7 @@ import {
  getAttendanceExperience,
  getSchedulePhase,
  summarizeAttendance,
+  summarizeLessonCheckins,
 } from './attendance-workspace';

 describe('attendance role experience', () => {
@@ -51,3 +52,16 @@ describe('attendance summary', () => {
    ).toEqual({ total: 4, present: 2, late: 1, absent: 1, leave: 0, pending: 0 });
  });
 });
+
+describe('lesson check-in summary', () => {
+  it('counts late punches as checked in and missing punches as not checked in', () => {
+    expect(
+      summarizeLessonCheckins([
+        { status: 'present' },
+        { status: 'late' },
+        { status: 'pending' },
+        { status: 'absent' },
+      ]),
+    ).toEqual({ total: 4, checkedIn: 2, notCheckedIn: 2 });
+  });
+});
--- a/apps/admin/src/pages/Attendance/attendance-workspace.ts
+++ b/apps/admin/src/pages/Attendance/attendance-workspace.ts
@@ -63,3 +63,22 @@ export function summarizeAttendance(records: readonly { status: string }[]): Att
  }
  return summary;
 }
+
+export interface LessonCheckinSummary {
+  total: number;
+  checkedIn: number;
+  notCheckedIn: number;
+}
+
+export function summarizeLessonCheckins(
+  records: readonly { status: string }[],
+): LessonCheckinSummary {
+  const checkedIn = records.filter(
+    (record) => record.status === 'present' || record.status === 'late',
+  ).length;
+  return {
+    total: records.length,
+    checkedIn,
+    notCheckedIn: records.length - checkedIn,
+  };
+}
--- a/apps/admin/src/pages/Attendance/index.tsx
+++ b/apps/admin/src/pages/Attendance/index.tsx
@@ -42,7 +42,7 @@ import {
  canPullAttendance,
  getAttendanceExperience,
  getSchedulePhase,
-  summarizeAttendance,
+  summarizeLessonCheckins,
  type AttendanceSummary,
  type SchedulePhase,
 } from './attendance-workspace';
@@ -215,6 +215,27 @@ function SummaryStrip({ summary }: { summary: AttendanceSummary }) {
  );
 }

+function LessonCheckinSummaryStrip({ records }: { records: readonly AttendanceRecordItem[] }) {
+  const summary = summarizeLessonCheckins(records);
+  const rate = summary.total > 0 ? Math.round((summary.checkedIn / summary.total) * 100) : 0;
+  return (
+    <div className="attendance-summary-strip">
+      <div className="attendance-rate">
+        <Progress type="circle" percent={rate} size={64} strokeWidth={9} />
+        <div><span>打卡率</span><strong>{summary.total} 人</strong></div>
+      </div>
+      <div className="attendance-summary-cell">
+        <span className="attendance-summary-icon is-present">勤</span>
+        <div><strong>{summary.checkedIn}</strong><span>已打卡</span></div>
+      </div>
+      <div className="attendance-summary-cell">
+        <span className="attendance-summary-icon is-absent">缺</span>
+        <div><strong>{summary.notCheckedIn}</strong><span>未打卡</span></div>
+      </div>
+    </div>
+  );
+}
+
 const AttendancePage: React.FC = () => {
  const { permissions, hasPermission } = usePermission();
  const roles = useMemo(readCurrentRoles, []);
@@ -235,7 +256,6 @@ const TeacherAttendanceWorkspace: React.FC = () => {
  const [lessonRecords, setLessonRecords] = useState<AttendanceRecordItem[]>([]);
  const [recordLoading, setRecordLoading] = useState(false);
  const [drawerOpen, setDrawerOpen] = useState(false);
-  const [finishing, setFinishing] = useState(false);

  const loadWorkspace = useCallback(async () => {
    setLoading(true);
@@ -257,15 +277,6 @@ const TeacherAttendanceWorkspace: React.FC = () => {
    [workspace],
  );

-  const loadLessonAttendance = useCallback(async (schedule: TodaySchedule) => {
-    const today = dayjs().format('YYYY-MM-DD');
-    const data = await api.get<LessonAttendanceResponse>(
-      `/attendance-lessons/schedules/${schedule.id}`,
-      { params: { date: today } },
-    );
-    setLessonSession(data.session);
-    setLessonRecords(data.records);
-  }, []);

  const openAttendance = useCallback(async (schedule: TodaySchedule) => {
    setSelectedSchedule(schedule);
@@ -279,7 +290,7 @@ const TeacherAttendanceWorkspace: React.FC = () => {
      );
      setLessonSession(data.session);
      setLessonRecords(data.records);
-      message.success('钉钉考勤已更新，请核对待确认和异常记录');
+      message.success('钉钉打卡已更新；课程截止后系统将自动结算');
    } catch (error: unknown) {
      setLessonSession(null);
      setLessonRecords([]);
@@ -307,23 +318,6 @@ const TeacherAttendanceWorkspace: React.FC = () => {
    [],
  );

-  const completeAttendance = useCallback(async () => {
-    if (!lessonSession || !selectedSchedule) return;
-    setFinishing(true);
-    try {
-      const result = await api.post<LessonAttendanceResponse>(
-        `/attendance-lessons/${lessonSession.id}/complete`,
-      );
-      setLessonSession(result.session);
-      setLessonRecords(result.records);
-      message.success('考勤核对已完成');
-      await loadLessonAttendance(selectedSchedule);
-    } catch (error: unknown) {
-      message.error((error as { message?: string })?.message || '完成点名失败');
-    } finally {
-      setFinishing(false);
-    }
-  }, [lessonSession, selectedSchedule, loadLessonAttendance]);

  const now = new Date();
  const schedules = workspace?.todaySchedules ?? [];
@@ -333,7 +327,6 @@ const TeacherAttendanceWorkspace: React.FC = () => {
  const nextSchedule = schedules.find(
    (item) => getSchedulePhase(item.startTime, item.endTime, now) !== 'ended',
  );
-  const drawerSummary = summarizeAttendance(lessonRecords);
  const isAttendanceCompleted = lessonSession?.status === 'completed';

  return (
@@ -342,7 +335,7 @@ const TeacherAttendanceWorkspace: React.FC = () => {
        <div>
          <span className="attendance-eyebrow">TEACHING DAY · {dayjs().format('MM月DD日 dddd')}</span>
          <h1>今天，从课程开始</h1>
-          <p>课表先同步到钉钉考勤；课程开始后，老师可随时拉取该节课的最新打卡结果并核对异常。</p>
+          <p>课程开始后可查看最新打卡结果；课程截止时系统自动拉取并结算缺勤。</p>
        </div>
        <Button icon={<ReloadOutlined />} onClick={() => void loadWorkspace()}>
          刷新
@@ -403,18 +396,11 @@ const TeacherAttendanceWorkspace: React.FC = () => {
          <Alert
            type={isAttendanceCompleted ? 'success' : 'info'}
            showIcon
-            title={isAttendanceCompleted ? '本节课考勤已核对完成；如有错误仍可直接修正' : '钉钉考勤已拉取，请核对待确认和异常学生'}
+            title={isAttendanceCompleted ? '本节课考勤已结算' : '当前打卡结果；课程截止后将自动做最终结算'}
            style={{ marginBottom: 16 }}
-            action={
-              !isAttendanceCompleted ? (
-                <Button type="primary" loading={finishing} onClick={() => void completeAttendance()}>
-                  完成核对
-                </Button>
-              ) : undefined
-            }
          />
        )}
-        <SummaryStrip summary={drawerSummary} />
+        <LessonCheckinSummaryStrip records={lessonRecords} />
        <Table<AttendanceRecordItem>
          rowKey="id"
          loading={recordLoading}
@@ -427,24 +413,31 @@ const TeacherAttendanceWorkspace: React.FC = () => {
              render: (name: string) => <div className="student-cell"><Avatar size={32}>{name?.slice(0, 1)}</Avatar><strong>{name || '-'}</strong></div>,
            },
            {
-              title: '考勤结果', dataIndex: 'status', width: 310,
-              render: (value: string, record: AttendanceRecordItem) => (
-                <div className="attendance-marking-actions">
-                  {STATUS_OPTIONS.map((option) => (
+              title: '考勤结果', dataIndex: 'status', width: 230,
+              render: (value: string, record: AttendanceRecordItem) => {
+                const checkedIn = value === 'present' || value === 'late';
+                return (
+                  <div className="attendance-marking-actions">
                    <Button
-                      key={option.value}
                      size="small"
-                      type={value === option.value ? 'primary' : 'default'}
-                      danger={value === option.value && option.value === 'absent'}
-                      onClick={() => void updateLessonRecord(record, option.value)}
+                      type={checkedIn ? 'primary' : 'default'}
+                      onClick={() => void updateLessonRecord(record, 'present')}
                    >
-                      {option.label}
+                      已打卡
                    </Button>
-                  ))}
-                </div>
-              ),
+                    <Button
+                      size="small"
+                      type={!checkedIn ? 'primary' : 'default'}
+                      danger={!checkedIn}
+                      onClick={() => void updateLessonRecord(record, 'absent')}
+                    >
+                      未打卡
+                    </Button>
+                  </div>
+                );
+              },
            },
-            { title: '当前状态', dataIndex: 'status', width: 105, render: (value: string) => <AttendanceStatusTag status={value} /> },
+            { title: '当前状态', dataIndex: 'status', width: 105, render: (value: string) => <AttendanceStatusTag status={value === 'present' || value === 'late' ? 'present' : 'absent'} /> },
            { title: '备注', dataIndex: 'remark', render: (value: string | null) => value || <span className="muted-text">—</span> },
          ]}
        />
--- a/apps/server/src/app.module.ts
+++ b/apps/server/src/app.module.ts
@@ -4,6 +4,7 @@ import { ConfigModule, ConfigService } from '@nestjs/config';
 import { EventEmitterModule } from '@nestjs/event-emitter';
 import { TypeOrmModule, type TypeOrmModuleOptions } from '@nestjs/typeorm';
 import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';
+import { ScheduleModule } from '@nestjs/schedule';
 import {
  Student,
  Room,
@@ -88,6 +89,7 @@ import { IntegrationConfigModule } from './integration/config/config.module';
      },
    ]),
    EventEmitterModule.forRoot(),
+    ScheduleModule.forRoot(),
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
--- a/apps/server/src/attendance/attendance-settlement.service.spec.ts
+++ b/apps/server/src/attendance/attendance-settlement.service.spec.ts
@@ -0,0 +1,205 @@
+import { AttendanceSettlementService } from './attendance-settlement.service';
+
+const schedule = {
+  id: 2,
+  classId: 8,
+  teacherId: 21,
+  weekDay: 1,
+  startTime: '09:00',
+  endTime: '10:00',
+  startDate: '2026-07-01',
+  endDate: '2026-07-31',
+  scheduleType: 'INTERNAL',
+  status: 'active',
+};
+
+const createService = () => {
+  const scheduleRepo = { find: jest.fn() };
+  const sessionRepo = {
+    find: jest.fn(),
+    update: jest.fn().mockResolvedValue({ affected: 1 }),
+  };
+  const attendanceService = {
+    getTeacherClassDingUserIds: jest.fn().mockResolvedValue(['ding-1']),
+    createLessonAttendanceFromDingTalk: jest.fn().mockImplementation(
+      async (_scheduleId: number, lessonDate: string, userId: number, finalize: boolean) => ({
+        session: { id: 90, lessonDate, startedBy: userId, status: finalize ? 'completed' : 'in_progress' },
+      }),
+    ),
+  };
+  const importService = {
+    importFromDingTalk: jest.fn().mockResolvedValue({ success: true, errors: [] }),
+  };
+  const service = new AttendanceSettlementService(
+    scheduleRepo as never,
+    sessionRepo as never,
+    attendanceService as never,
+    importService as never,
+  );
+  return { service, scheduleRepo, sessionRepo, attendanceService, importService };
+};
+
+describe('AttendanceSettlementService', () => {
+  it('pulls and finalizes an ended lesson once', async () => {
+    const { service, scheduleRepo, sessionRepo, attendanceService, importService } = createService();
+    scheduleRepo.find.mockResolvedValue([schedule]);
+    sessionRepo.find.mockResolvedValue([]);
+
+    await service.settleEndedLessons(new Date('2026-07-13T10:01:00+08:00'));
+
+    expect(importService.importFromDingTalk).toHaveBeenCalledWith({
+      startDate: '2026-07-13',
+      endDate: '2026-07-13',
+      userIds: ['ding-1'],
+      autoMatch: true,
+      userId: 21,
+    });
+    expect(attendanceService.createLessonAttendanceFromDingTalk).toHaveBeenNthCalledWith(
+      1, 2, '2026-07-13', 21, false,
+    );
+    expect(attendanceService.createLessonAttendanceFromDingTalk).toHaveBeenNthCalledWith(
+      2, 2, '2026-07-13', 21, true,
+    );
+  });
+
+  it('does not settle a lesson before its end time', async () => {
+    const { service, scheduleRepo, sessionRepo, attendanceService } = createService();
+    scheduleRepo.find.mockResolvedValue([schedule]);
+    sessionRepo.find.mockResolvedValue([]);
+
+    await service.settleEndedLessons(new Date('2026-07-13T09:30:00+08:00'));
+
+    expect(attendanceService.createLessonAttendanceFromDingTalk).not.toHaveBeenCalled();
+  });
+
+  it('continues with the next lesson when one settlement fails', async () => {
+    const { service, scheduleRepo, sessionRepo, attendanceService, importService } = createService();
+    scheduleRepo.find.mockResolvedValue([schedule, { ...schedule, id: 3 }]);
+    sessionRepo.find.mockResolvedValue([]);
+    importService.importFromDingTalk
+      .mockRejectedValueOnce(new Error('DingTalk unavailable'))
+      .mockResolvedValueOnce({ success: true, errors: [] });
+
+    await service.settleEndedLessons(new Date('2026-07-13T10:01:00+08:00'));
+
+    expect(attendanceService.createLessonAttendanceFromDingTalk).toHaveBeenNthCalledWith(
+      2,
+      3,
+      '2026-07-13',
+      21,
+      false,
+    );
+    expect(attendanceService.createLessonAttendanceFromDingTalk).toHaveBeenLastCalledWith(
+      3,
+      '2026-07-13',
+      21,
+      true,
+    );
+  });
+
+  it('does not finalize when an import reports partial errors', async () => {
+    const { service, scheduleRepo, sessionRepo, attendanceService, importService } = createService();
+    scheduleRepo.find.mockResolvedValue([schedule]);
+    sessionRepo.find.mockResolvedValue([]);
+    importService.importFromDingTalk.mockResolvedValue({
+      success: true,
+      errors: ['one batch failed'],
+    });
+
+    await service.settleEndedLessons(new Date('2026-07-13T10:01:00+08:00'));
+
+    expect(attendanceService.createLessonAttendanceFromDingTalk).not.toHaveBeenCalledWith(
+      2, '2026-07-13', 21, true,
+    );
+  });
+
+  it('retries an uncompleted daytime lesson on a later day', async () => {
+    const { service, scheduleRepo, sessionRepo, attendanceService } = createService();
+    scheduleRepo.find.mockResolvedValue([]);
+    sessionRepo.find.mockResolvedValue([
+      {
+        scheduleId: 2,
+        lessonDate: '2026-07-13',
+        status: 'in_progress',
+        schedule,
+      },
+    ]);
+
+    await service.settleEndedLessons(new Date('2026-07-15T10:01:00+08:00'));
+
+    expect(attendanceService.createLessonAttendanceFromDingTalk).toHaveBeenCalledWith(
+      2,
+      '2026-07-13',
+      21,
+      true,
+    );
+  });
+
+  it('skips final pull when another worker already claimed the session', async () => {
+    const { service, scheduleRepo, sessionRepo, attendanceService, importService } = createService();
+    scheduleRepo.find.mockResolvedValue([]);
+    sessionRepo.find.mockResolvedValue([
+      {
+        id: 90,
+        scheduleId: 2,
+        lessonDate: '2026-07-13',
+        status: 'in_progress',
+        schedule,
+      },
+    ]);
+    sessionRepo.update.mockResolvedValue({ affected: 0 });
+
+    await service.settleEndedLessons(new Date('2026-07-13T10:01:00+08:00'));
+
+    expect(importService.importFromDingTalk).not.toHaveBeenCalled();
+    expect(attendanceService.createLessonAttendanceFromDingTalk).not.toHaveBeenCalled();
+  });
+
+  it('settles an overnight lesson after its next-day end time', async () => {
+    const { service, scheduleRepo, sessionRepo, attendanceService } = createService();
+    scheduleRepo.find.mockResolvedValue([
+      { ...schedule, id: 4, weekDay: 7, startTime: '22:00', endTime: '01:00' },
+    ]);
+    sessionRepo.find.mockResolvedValue([]);
+
+    await service.settleEndedLessons(new Date('2026-07-13T01:01:00+08:00'));
+
+    expect(attendanceService.createLessonAttendanceFromDingTalk).toHaveBeenCalledWith(
+      4,
+      '2026-07-12',
+      21,
+      true,
+    );
+  });
+
+  it('pulls an overnight lesson through its next calendar date', async () => {
+    const { service, scheduleRepo, sessionRepo, importService } = createService();
+    scheduleRepo.find.mockResolvedValue([
+      { ...schedule, id: 4, weekDay: 7, startTime: '22:00', endTime: '01:00' },
+    ]);
+    sessionRepo.find.mockResolvedValue([]);
+
+    await service.settleEndedLessons(new Date('2026-07-13T01:01:00+08:00'));
+
+    expect(importService.importFromDingTalk).toHaveBeenCalledWith(
+      expect.objectContaining({ startDate: '2026-07-12', endDate: '2026-07-13' }),
+    );
+  });
+});
+
+describe('attendance settlement timezone', () => {
+  it('uses Asia/Shanghai course time when the server runs in UTC', async () => {
+    const { service, scheduleRepo, sessionRepo, attendanceService } = createService();
+    scheduleRepo.find.mockResolvedValue([schedule]);
+    sessionRepo.find.mockResolvedValue([]);
+
+    await service.settleEndedLessons(new Date('2026-07-13T02:01:00.000Z'));
+
+    expect(attendanceService.createLessonAttendanceFromDingTalk).toHaveBeenCalledWith(
+      2,
+      '2026-07-13',
+      21,
+      true,
+    );
+  });
+});
--- a/apps/server/src/attendance/attendance-settlement.service.ts
+++ b/apps/server/src/attendance/attendance-settlement.service.ts
@@ -0,0 +1,193 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Cron } from '@nestjs/schedule';
+import { InjectRepository } from '@nestjs/typeorm';
+import { In, LessThan, LessThanOrEqual, MoreThanOrEqual, Repository } from 'typeorm';
+import { AttendanceSession, ClassSchedule, ScheduleType } from '../entities';
+import { AttendanceImportService } from './attendance-import.service';
+import { AttendanceService } from './attendance.service';
+
+@Injectable()
+export class AttendanceSettlementService {
+  private readonly logger = new Logger(AttendanceSettlementService.name);
+  private readonly courseTimeZone = 'Asia/Shanghai';
+  private running = false;
+
+  constructor(
+    @InjectRepository(ClassSchedule)
+    private readonly scheduleRepo: Repository<ClassSchedule>,
+    @InjectRepository(AttendanceSession)
+    private readonly sessionRepo: Repository<AttendanceSession>,
+    private readonly attendanceService: AttendanceService,
+    private readonly importService: AttendanceImportService,
+  ) {}
+
+  @Cron('* * * * *')
+  async settleEndedLessons(now = new Date()): Promise<void> {
+    if (this.running) return;
+    this.running = true;
+    try {
+      const clock = this.getCourseClock(now);
+      const staleClaimBefore = new Date(now.getTime() - 35 * 60 * 1000);
+      await this.sessionRepo.update(
+        { status: 'settling', updatedAt: LessThan(staleClaimBefore) },
+        { status: 'in_progress' },
+      );
+      const today = clock.date;
+      const yesterday = this.shiftDate(today, -1);
+      const [schedules, sessions] = await Promise.all([
+        this.scheduleRepo.find({
+          where: {
+            scheduleType: ScheduleType.INTERNAL,
+            status: 'active',
+            startDate: LessThanOrEqual(today),
+            endDate: MoreThanOrEqual(yesterday),
+          },
+        }),
+        this.sessionRepo.find({
+          where: { status: In(['in_progress', 'settling']) },
+          relations: ['schedule'],
+        }),
+      ]);
+      const sessionByKey = new Map(
+        sessions.map((session) => [`${session.scheduleId}|${session.lessonDate}`, session]),
+      );
+      const candidates = new Map<string, { schedule: ClassSchedule; lessonDate: string; session?: AttendanceSession }>();
+
+      for (const schedule of schedules) {
+        const lessonDate = this.getEndedOccurrenceDate(schedule, clock, today, yesterday);
+        if (lessonDate) {
+          const key = `${schedule.id}|${lessonDate}`;
+          candidates.set(key, { schedule, lessonDate, session: sessionByKey.get(key) });
+        }
+      }
+      for (const session of sessions) {
+        if (session.status === 'in_progress' && session.schedule) {
+          candidates.set(`${session.scheduleId}|${session.lessonDate}`, {
+            schedule: session.schedule,
+            lessonDate: session.lessonDate,
+            session,
+          });
+        }
+      }
+
+      for (const candidate of candidates.values()) {
+        await this.settleCandidate(candidate);
+      }
+    } finally {
+      this.running = false;
+    }
+  }
+
+  private async settleCandidate(candidate: {
+    schedule: ClassSchedule;
+    lessonDate: string;
+    session?: AttendanceSession;
+  }): Promise<void> {
+    const { schedule, lessonDate } = candidate;
+    if (schedule.classId == null || schedule.teacherId == null) {
+      this.logger.error(`课程${schedule.id} ${lessonDate}缺少班级或教师，无法自动结算`);
+      return;
+    }
+
+    let session = candidate.session;
+    try {
+      if (!session) {
+        const created = await this.attendanceService.createLessonAttendanceFromDingTalk(
+          schedule.id,
+          lessonDate,
+          schedule.teacherId,
+          false,
+        );
+        session = created.session;
+      }
+      const claimed = await this.sessionRepo.update(
+        { id: session.id, status: 'in_progress' },
+        { status: 'settling' },
+      );
+      if (claimed.affected !== 1) return;
+
+      const userIds = await this.attendanceService.getTeacherClassDingUserIds(
+        schedule.teacherId,
+        schedule.classId,
+      );
+      const imported = await this.importService.importFromDingTalk({
+        startDate: lessonDate,
+        endDate: this.isOvernight(schedule) ? this.shiftDate(lessonDate, 1) : lessonDate,
+        userIds,
+        autoMatch: true,
+        userId: schedule.teacherId,
+      });
+      if (!imported.success || imported.errors.length > 0) {
+        throw new Error(imported.errors.join('; ') || '钉钉考勤拉取失败');
+      }
+      await this.attendanceService.createLessonAttendanceFromDingTalk(
+        schedule.id,
+        lessonDate,
+        schedule.teacherId,
+        true,
+      );
+    } catch (error: unknown) {
+      if (session) await this.sessionRepo.update({ id: session.id, status: 'settling' }, { status: 'in_progress' });
+      this.logger.error(
+        `课程${schedule.id} ${lessonDate}自动结算失败: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  private getEndedOccurrenceDate(
+    schedule: ClassSchedule,
+    clock: { weekDay: number; minutes: number },
+    today: string,
+    yesterday: string,
+  ): string | null {
+    const endMinutes = this.toMinutes(schedule.endTime);
+    const overnight = this.isOvernight(schedule);
+    const yesterdayWeekDay = clock.weekDay === 1 ? 7 : clock.weekDay - 1;
+    if (
+      !overnight &&
+      schedule.weekDay === clock.weekDay &&
+      clock.minutes >= endMinutes &&
+      today >= schedule.startDate &&
+      today <= schedule.endDate
+    ) return today;
+    if (
+      overnight &&
+      schedule.weekDay === yesterdayWeekDay &&
+      clock.minutes >= endMinutes &&
+      yesterday >= schedule.startDate &&
+      yesterday <= schedule.endDate
+    ) return yesterday;
+    return null;
+  }
+
+  private isOvernight(schedule: ClassSchedule): boolean {
+    return this.toMinutes(schedule.endTime) <= this.toMinutes(schedule.startTime);
+  }
+
+  private toMinutes(time: string): number {
+    const [hour, minute] = time.split(':').map(Number);
+    return hour * 60 + minute;
+  }
+
+  private getCourseClock(date: Date): { date: string; weekDay: number; minutes: number } {
+    const parts = Object.fromEntries(
+      new Intl.DateTimeFormat('en-CA', {
+        timeZone: this.courseTimeZone,
+        year: 'numeric', month: '2-digit', day: '2-digit', weekday: 'short',
+        hour: '2-digit', minute: '2-digit', hourCycle: 'h23',
+      }).formatToParts(date).filter((part) => part.type !== 'literal').map((part) => [part.type, part.value]),
+    );
+    const weekDays: Record<string, number> = { Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6, Sun: 7 };
+    return {
+      date: `${parts.year}-${parts.month}-${parts.day}`,
+      weekDay: weekDays[parts.weekday],
+      minutes: Number(parts.hour) * 60 + Number(parts.minute),
+    };
+  }
+
+  private shiftDate(date: string, days: number): string {
+    const shifted = new Date(`${date}T00:00:00.000Z`);
+    shifted.setUTCDate(shifted.getUTCDate() + days);
+    return shifted.toISOString().slice(0, 10);
+  }
+}
--- a/apps/server/src/attendance/attendance.lesson-session.spec.ts
+++ b/apps/server/src/attendance/attendance.lesson-session.spec.ts
@@ -74,8 +74,18 @@ describe('AttendanceService \u2014 DingTalk course attendance', () => {
      { studentId: 4, student: { id: 4, name: '\u8D75\u516D' } },
    ]);
    dingRawRepo.find.mockResolvedValue([
-      { matchedStudentId: 1, attendanceType: 'OnDuty', timeResult: 'Normal' },
-      { matchedStudentId: 2, attendanceType: 'OnDuty', timeResult: 'Late' },
+      {
+        matchedStudentId: 1,
+        attendanceType: 'OnDuty',
+        timeResult: 'Normal',
+        checkInTime: new Date('2026-07-11T08:55:00+08:00'),
+      },
+      {
+        matchedStudentId: 2,
+        attendanceType: 'OnDuty',
+        timeResult: 'Late',
+        checkInTime: new Date('2026-07-11T09:05:00+08:00'),
+      },
      { matchedStudentId: 3, attendanceType: 'OnDuty', timeResult: 'NotSigned' },
    ]);

@@ -91,13 +101,34 @@ describe('AttendanceService \u2014 DingTalk course attendance', () => {
    );
    expect(attendanceRepo.save).toHaveBeenCalledWith([
      expect.objectContaining({ studentId: 1, status: 'present', source: 'dingtalk' }),
-      expect.objectContaining({ studentId: 2, status: 'late', source: 'dingtalk' }),
-      expect.objectContaining({ studentId: 3, status: 'absent', source: 'dingtalk' }),
+      expect.objectContaining({ studentId: 2, status: 'present', source: 'dingtalk' }),
+      expect.objectContaining({ studentId: 3, status: 'pending', source: 'dingtalk' }),
      expect.objectContaining({ studentId: 4, status: 'pending', source: 'dingtalk' }),
    ]);
    expect(result.records).toHaveLength(4);
  });

+  it('finalizes missing punches as absent and completes the session', async () => {
+    const { service, attendanceRepo, dingRawRepo, scheduleRepo, classStudentRepo, sessionRepo } =
+      createService();
+    scheduleRepo.findOne.mockResolvedValue(endedSchedule);
+    sessionRepo.findOne.mockResolvedValue(null);
+    classStudentRepo.find.mockResolvedValue([
+      { studentId: 1, student: { id: 1, name: '张三' } },
+    ]);
+    dingRawRepo.find.mockResolvedValue([]);
+
+    const result = await service.createLessonAttendanceFromDingTalk(4, '2026-07-11', 21, true);
+
+    expect(attendanceRepo.save).toHaveBeenCalledWith([
+      expect.objectContaining({ studentId: 1, status: 'absent' }),
+    ]);
+    expect(sessionRepo.save).toHaveBeenLastCalledWith(
+      expect.objectContaining({ status: 'completed', completedBy: 21 }),
+    );
+    expect(result.session.status).toBe('completed');
+  });
+
  it('returns student relations after the first pull', async () => {
    const { service, attendanceRepo, dingRawRepo, scheduleRepo, classStudentRepo, sessionRepo } =
      createService();
@@ -211,8 +242,8 @@ describe('AttendanceService \u2014 DingTalk course attendance', () => {
      { studentId: 2, student: { id: 2, name: '\u674E\u56DB' } },
    ]);
    dingRawRepo.find.mockResolvedValue([
-      { matchedStudentId: 1, attendanceType: 'OnDuty', timeResult: 'Normal' },
-      { matchedStudentId: 2, attendanceType: 'OnDuty', timeResult: 'Late' },
+      { matchedStudentId: 1, attendanceType: 'OnDuty', timeResult: 'Normal', checkInTime: new Date('2026-07-11T08:55:00+08:00') },
+      { matchedStudentId: 2, attendanceType: 'OnDuty', timeResult: 'Late', checkInTime: new Date('2026-07-11T09:05:00+08:00') },
    ]);

    const result = await service.createLessonAttendanceFromDingTalk(4, '2026-07-11', 21);
@@ -225,7 +256,7 @@ describe('AttendanceService \u2014 DingTalk course attendance', () => {
    expect(savedRecords).toEqual(
      expect.arrayContaining([
        expect.objectContaining({ studentId: 1, status: 'present' }),
-        expect.objectContaining({ studentId: 2, status: 'late' }),
+        expect.objectContaining({ studentId: 2, status: 'present' }),
      ]),
    );
    expect(result.records).toHaveLength(2);
@@ -278,8 +309,8 @@ describe('AttendanceService \u2014 DingTalk course attendance', () => {
      { studentId: 2, student: { id: 2, name: '\u674E\u56DB' } },
    ]);
    dingRawRepo.find.mockResolvedValue([
-      { matchedStudentId: 1, attendanceType: 'OnDuty', timeResult: 'Late' },
-      { matchedStudentId: 2, attendanceType: 'OnDuty', timeResult: 'Late' },
+      { matchedStudentId: 1, attendanceType: 'OnDuty', timeResult: 'Late', checkInTime: new Date('2026-07-11T09:05:00+08:00') },
+      { matchedStudentId: 2, attendanceType: 'OnDuty', timeResult: 'Late', checkInTime: new Date('2026-07-11T09:05:00+08:00') },
    ]);

    const result = await service.createLessonAttendanceFromDingTalk(4, '2026-07-11', 21);
@@ -289,12 +320,38 @@ describe('AttendanceService \u2014 DingTalk course attendance', () => {
    expect(savedRecords).toEqual(
      expect.arrayContaining([
        expect.objectContaining({ studentId: 1, status: 'leave' }),
-        expect.objectContaining({ studentId: 2, status: 'late' }),
+        expect.objectContaining({ studentId: 2, status: 'present' }),
      ]),
    );
    expect(result.records).toHaveLength(2);
  });

+  it('final settlement overrides interim manual status using the final punch result', async () => {
+    const { service, attendanceRepo, dingRawRepo, scheduleRepo, classStudentRepo, sessionRepo } =
+      createService();
+    scheduleRepo.findOne.mockResolvedValue(endedSchedule);
+    sessionRepo.findOne.mockResolvedValue({
+      id: 90,
+      scheduleId: 4,
+      classId: 8,
+      lessonDate: '2026-07-11',
+      status: 'in_progress',
+    });
+    attendanceRepo.find.mockResolvedValue([
+      { id: 101, studentId: 1, attendanceSessionId: 90, status: 'present', source: 'manual' },
+    ]);
+    classStudentRepo.find.mockResolvedValue([
+      { studentId: 1, student: { id: 1, name: '张三' } },
+    ]);
+    dingRawRepo.find.mockResolvedValue([]);
+
+    await service.createLessonAttendanceFromDingTalk(4, '2026-07-11', 21, true);
+
+    expect(attendanceRepo.save).toHaveBeenCalledWith([
+      expect.objectContaining({ studentId: 1, status: 'absent' }),
+    ]);
+  });
+
  it('rejects completion when pending records exist', async () => {
    const { service, sessionRepo, attendanceRepo } = createService();
    sessionRepo.findOne.mockResolvedValue({
@@ -368,8 +425,8 @@ describe('AttendanceService \u2014 DingTalk course attendance', () => {
      { studentId: 2, student: { id: 2, name: '李四' } },
    ]);
    dingRawRepo.find.mockResolvedValue([
-      { matchedStudentId: 1, attendanceType: 'OnDuty', timeResult: 'Normal' },
-      { matchedStudentId: 2, attendanceType: 'OnDuty', timeResult: 'Normal' },
+      { matchedStudentId: 1, attendanceType: 'OnDuty', timeResult: 'Normal', checkInTime: new Date('2026-07-11T08:55:00+08:00') },
+      { matchedStudentId: 2, attendanceType: 'OnDuty', timeResult: 'Normal', checkInTime: new Date('2026-07-11T08:55:00+08:00') },
    ]);

    // Step 1: update the record to absent via generic update()
--- a/apps/server/src/attendance/attendance.module.ts
+++ b/apps/server/src/attendance/attendance.module.ts
@@ -3,6 +3,7 @@ import { TypeOrmModule } from '@nestjs/typeorm';
 import { AttendanceRecord, AttendanceSession, DingAttendanceRaw, Student, Class, ClassSchedule, ClassStudent, ClassTeacher, StudentDingMapping } from '../entities';
 import { AttendanceService } from './attendance.service';
 import { AttendanceImportService } from './attendance-import.service';
+import { AttendanceSettlementService } from './attendance-settlement.service';
 import { AttendanceController } from './attendance.controller';
 import { OperationLogsModule } from '../operation-logs/operation-logs.module';
 import { IntegrationModule } from '../integration/integration.module';
@@ -14,7 +15,7 @@ import { IntegrationModule } from '../integration/integration.module';
    IntegrationModule,
  ],
  controllers: [AttendanceController],
-  providers: [AttendanceService, AttendanceImportService],
+  providers: [AttendanceService, AttendanceImportService, AttendanceSettlementService],
  exports: [AttendanceService, AttendanceImportService],
 })
 export class AttendanceModule {}
--- a/apps/server/src/attendance/attendance.service.ts
+++ b/apps/server/src/attendance/attendance.service.ts
@@ -195,24 +195,16 @@ export class AttendanceService {
    return timed.length > 0 ? timed : records.filter((record) => !record.checkInTime && !record.checkOutTime);
  }

-  private mapDingTalkStatus(records: DingAttendanceRaw[]): string {
-    const results = new Set(records.map((record) => record.timeResult?.toLowerCase()));
-    if (results.has('late') || results.has('seriouslate')) return 'late';
-    if (
-      results.has('notsigned') ||
-      results.has('absenteeism') ||
-      results.has('absent')
-    ) {
-      return 'absent';
-    }
-    if (results.has('leave') || results.has('vacation')) return 'leave';
-    if (results.has('normal')) return 'present';
-    return 'pending';
+  private mapDingTalkStatus(records: DingAttendanceRaw[], finalize = false): string {
+    const hasPunch = records.some((record) => record.checkInTime || record.checkOutTime);
+    if (hasPunch) return 'present';
+    return finalize ? 'absent' : 'pending';
  }
  async createLessonAttendanceFromDingTalk(
    scheduleId: number,
    lessonDate: string,
    userId: number,
+    finalize = false,
  ) {
    const schedule = await this.getScheduleOccurrence(scheduleId, lessonDate);
    const now = new Date();
@@ -244,9 +236,13 @@ export class AttendanceService {
        });
        return { schedule, session: existing, records };
      }
+      if (existing.status !== 'in_progress' && !(finalize && existing.status === 'settling')) {
+        throw new BadRequestException('课程考勤正在结算');
+      }

      // Refresh in_progress session from latest DingTalk data
      return this.dataSource.transaction(async (manager) => {
+        const sessionRepo = manager.getRepository(AttendanceSession);
        const recordRepo = manager.getRepository(AttendanceRecord);
        const rawByStudent = await this.fetchDingTalkRawByStudent(schedule.classId!, lessonDate);
        const existingRecords = await recordRepo.find({
@@ -264,8 +260,8 @@ export class AttendanceService {

        const updatedRecords = existingRecords.map((record) => {
          record.student = studentsById.get(record.studentId)!;
-          // Preserve manually corrected records.
-          if (record.source !== 'dingtalk') return record;
+          // Preserve manual corrections only while the lesson is still in progress.
+          if (!finalize && record.source !== 'dingtalk') return record;

          const raw = this.selectDingTalkRecordsForLesson(
            rawByStudent.get(record.studentId) ?? [],
@@ -273,8 +269,12 @@ export class AttendanceService {
            schedule.startTime,
            schedule.endTime,
          );
-          record.status = this.mapDingTalkStatus(raw);
-          record.remark = raw.length === 0 ? '未获取到钉钉打卡结果，请老师确认' : null;
+          record.status = this.mapDingTalkStatus(raw, finalize);
+          record.remark = raw.some((item) => item.checkInTime || item.checkOutTime)
+            ? null
+            : finalize
+              ? '课程截止仍未打卡'
+              : '未获取到钉钉打卡结果';
          return record;
        });
        for (const classStudent of classStudents) {
@@ -294,14 +294,24 @@ export class AttendanceService {
              attendanceSessionId: existing.id,
              attendanceDate: lessonDate,
              session: this.mapScheduleTimeToSession(schedule.startTime),
-              status: this.mapDingTalkStatus(raw),
+              status: this.mapDingTalkStatus(raw, finalize),
              source: 'dingtalk',
-              remark: raw.length === 0 ? '未获取到钉钉打卡结果，请老师确认' : undefined,
+              remark: raw.some((item) => item.checkInTime || item.checkOutTime)
+                ? undefined
+                : finalize
+                  ? '课程截止仍未打卡'
+                  : '未获取到钉钉打卡结果',
            }),
          );
        }

        const saved = await recordRepo.save(updatedRecords);
+        if (finalize) {
+          existing.status = 'completed';
+          existing.completedBy = userId;
+          existing.completedAt = new Date();
+          await sessionRepo.save(existing);
+        }
        return { schedule, session: existing, records: saved };
      });
    }
@@ -366,12 +376,22 @@ export class AttendanceService {
          attendanceSessionId: session.id,
          attendanceDate: lessonDate,
          session: this.mapScheduleTimeToSession(schedule.startTime),
-          status: this.mapDingTalkStatus(raw),
+          status: this.mapDingTalkStatus(raw, finalize),
          source: 'dingtalk',
-          remark: raw.length === 0 ? '未获取到钉钉打卡结果，请老师确认' : undefined,
+          remark: raw.some((item) => item.checkInTime || item.checkOutTime)
+            ? undefined
+            : finalize
+              ? '课程截止仍未打卡'
+              : '未获取到钉钉打卡结果',
        });
      });
      const saved = await recordRepo.save(records);
+      if (finalize) {
+        session.status = 'completed';
+        session.completedBy = userId;
+        session.completedAt = new Date();
+        session = await sessionRepo.save(session);
+      }
      return { schedule, session, records: saved };
    });
  }
--- a/docs/superpowers/plans/2026-07-13-binary-course-attendance.md
+++ b/docs/superpowers/plans/2026-07-13-binary-course-attendance.md
@@ -0,0 +1,76 @@
+# 课程二态考勤与截止自动结算 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 教师课程考勤只显示已打卡/未打卡，并在课程截止后自动最终拉取、落库和完成场次。
+
+**Architecture:** 保留钉钉原始迟到状态；课程服务根据“是否存在实际打卡时间”生成临时二态结果和最终 `present/absent`。新增 Attendance 模块内的 NestJS 定时结算服务，每分钟扫描到期课程并复用导入与课程考勤服务，失败留待下一轮补偿。
+
+**Tech Stack:** NestJS 11、@nestjs/schedule 6、TypeORM 0.3、Jest、React 19、Ant Design 6。
+
+## Global Constraints
+
+- 仅调整排课关联的课程考勤。
+- 不迁移历史记录，不改变钉钉原始记录。
+- 不新增依赖、队列、兼容层或重复状态模型。
+- 课程截止后有实际打卡写 `present`，无实际打卡写 `absent`。
+- 单节失败不得阻断其他课程，后续扫描必须可补偿。
+
+---
+
+### Task 1: 课程二态映射
+
+**Files:**
+- Modify: `apps/server/src/attendance/attendance.service.ts`
+- Test: `apps/server/src/attendance/attendance.lesson-session.spec.ts`
+
+**Interfaces:**
+- Produces: `createLessonAttendanceFromDingTalk(scheduleId, lessonDate, userId, finalize?)`；`finalize=false` 返回临时二态，`finalize=true` 写最终二态并完成场次。
+
+- [ ] 添加失败测试：`Late` 且有 `checkInTime` 应为 `present`；无实际时间应为 `pending`；最终结算时无时间应为 `absent` 且 session 为 `completed`。
+- [ ] 运行 `npm test -- attendance.lesson-session.spec.ts --runInBand`，确认新增断言按预期失败。
+- [ ] 将课程状态映射改为只检查课程窗口内是否存在 `checkInTime` 或 `checkOutTime`；最终结算参数控制无打卡为 `absent`，并在同一事务完成场次。
+- [ ] 再次运行相同测试，确认通过。
+
+### Task 2: 截止自动结算
+
+**Files:**
+- Create: `apps/server/src/attendance/attendance-settlement.service.ts`
+- Create: `apps/server/src/attendance/attendance-settlement.service.spec.ts`
+- Modify: `apps/server/src/attendance/attendance.module.ts`
+- Modify: `apps/server/src/app.module.ts`
+
+**Interfaces:**
+- Consumes: `AttendanceImportService.importFromDingTalk(...)`、`AttendanceService.getTeacherClassDingUserIds(...)`、`AttendanceService.createLessonAttendanceFromDingTalk(..., true)`。
+- Produces: `AttendanceSettlementService.settleEndedLessons(now?: Date): Promise<void>`，由 `@Cron('* * * * *')` 调用。
+
+- [ ] 添加失败测试：未截止不处理、已完成不处理、到期课程最终拉取并结算、一个课程失败后继续处理下一个、昨日跨午夜课程可结算。
+- [ ] 运行 `npm test -- attendance-settlement.service.spec.ts --runInBand`，确认因服务不存在而失败。
+- [ ] 实现每分钟扫描今天普通到期课程及昨日跨午夜到期课程；逐课程捕获异常并记录；使用课程 `teacherId` 作为自动导入审计用户。
+- [ ] 在 `AttendanceModule` 注册服务，在根模块启用 `ScheduleModule.forRoot()`。
+- [ ] 再次运行相同测试，确认通过。
+
+### Task 3: 教师二态界面
+
+**Files:**
+- Modify: `apps/admin/src/pages/Attendance/attendance-workspace.ts`
+- Modify: `apps/admin/src/pages/Attendance/index.tsx`
+- Test: `apps/admin/src/pages/Attendance/attendance-workspace.test.ts`
+
+**Interfaces:**
+- Produces: `summarizeLessonCheckins(records)`，将 `present`/`late` 归为已打卡，将其余归为未打卡。
+
+- [ ] 添加失败测试：`present` 与遗留 `late` 均计入已打卡，`pending`/`absent` 计入未打卡。
+- [ ] 运行 admin 的定向测试命令并确认失败。
+- [ ] 教师抽屉改为“已打卡 / 未打卡”标签、汇总和手动修改选项；管理员档案保持原五态。
+- [ ] 再次运行定向测试，确认通过。
+
+### Task 4: 聚焦验证
+
+**Files:**
+- Verify only; no planned production edits.
+
+- [ ] 运行 server 两个定向 Jest 测试文件。
+- [ ] 运行 server `npm run typecheck`。
+- [ ] 运行 admin 定向测试与 `npm run typecheck`。
+- [ ] 用现有数据库场景确认王子琪的 `Late` 在教师视图归为已打卡、陈浩无记录归为未打卡；不修改数据库数据。
--- a/docs/superpowers/specs/2026-07-13-binary-course-attendance-design.md
+++ b/docs/superpowers/specs/2026-07-13-binary-course-attendance-design.md
@@ -0,0 +1,63 @@
+# 课程二态考勤与截止自动结算设计
+
+## 目标
+
+课程考勤仅向教师展示“已打卡 / 未打卡”。迟到属于已打卡。每节课程到达截止时间后，系统自动从钉钉做最后一次拉取并将最终结果写入课程考勤记录；截止仍无实际打卡的学生记为缺勤。
+
+## 范围
+
+- 仅调整排课关联的课程考勤。
+- 不迁移历史记录。
+- 不改变后台其他考勤来源、迟到统计或钉钉原始数据。
+- 不引入队列或新依赖，复用 NestJS Schedule 与现有导入、匹配、课程考勤服务。
+
+## 状态规则
+
+### 教师当前课程页面
+
+- 存在课程时间窗口内的实际打卡时间：显示“已打卡”。
+- 不存在实际打卡时间：显示“未打卡”。
+- `Late`、`SeriousLate` 和 `Normal` 均显示为“已打卡”。
+- 页面汇总仅显示已打卡数、未打卡数和总人数。
+
+### 最终记录
+
+- 截止时存在实际打卡时间：`present`。
+- 截止时不存在实际打卡时间：`absent`。
+- 钉钉原始记录继续保留 `timeResult`，因此不会丢失迟到信息。
+- 自动结算完成后，课程考勤场次状态改为 `completed`，不再被后续拉取覆盖。
+
+## 自动结算
+
+后台任务每分钟扫描：
+
+1. 当天有效的内部课程；
+2. 当前时间已经达到课程 `endTime`；
+3. 对应日期的课程考勤场次尚未完成或尚未创建。
+
+对每节符合条件的课程：
+
+1. 获取该班在读学生的钉钉用户 ID；
+2. 拉取当天最终钉钉考勤并自动匹配；
+3. 创建或刷新课程考勤记录；
+4. 将有实际打卡的记录归为 `present`，其余归为 `absent`；
+5. 将场次标记为 `completed`。
+
+任务按课程独立处理。单节课拉取失败只记录错误，其他课程继续；下一分钟继续补偿失败课程。现有 `(scheduleId, lessonDate)` 唯一约束和完成状态保证重复扫描幂等。
+
+跨午夜课程以结束时间不晚于开始时间判断为次日截止；扫描同时覆盖昨日跨午夜课程。
+
+## 手动查看
+
+课程开始后，教师点击“查看当前考勤”仍会拉取最新数据。课程截止前结果是临时二态视图；课程截止后读取自动结算的最终记录。若自动任务尚未成功，手动查看可继续拉取，但只有自动结算或明确完成操作会冻结最终结果。
+
+## 测试
+
+- 迟到且存在实际打卡时间时，当前课程视图为“已打卡”。
+- 无实际打卡时间时，当前课程视图为“未打卡”。
+- 截止结算把迟到和正常打卡写为 `present`。
+- 截止结算把无打卡写为 `absent` 并完成场次。
+- 未截止课程不结算。
+- 重复扫描已完成课程不重复拉取或写入。
+- 单节课程失败不阻断其他课程，后续扫描可补偿。
+- 跨午夜课程在次日截止后结算。