feat: improve attendance scheduling and API validation

2026-07-14 23:12:14 +08:00
parent c75a08affe
commit e45da7f998
33 changed files with 869 additions and 297 deletions
--- a/apps/server/src/deposits/deposits.controller.ts
+++ b/apps/server/src/deposits/deposits.controller.ts
@@ -9,6 +9,7 @@ import {
  Query,
  UseGuards,
  Request,
+  ParseIntPipe,
 } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Repository } from 'typeorm';
@@ -16,7 +17,12 @@ import { Student } from '../entities/student.entity';
 import { DepositsService } from './deposits.service';
 import { NotificationsService } from '../notifications/notifications.service';
 import { NotificationType } from '../entities/notification.entity';
-import { CreateDepositDto, RefundDepositDto } from './dto/deposit.dto';
+import {
+  CreateDepositDto,
+  CreateDepositInstallmentDto,
+  RefundDepositDto,
+  UpdateDepositInstallmentDto,
+} from './dto/deposit.dto';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
 import { OperationLogsService } from '../operation-logs/operation-logs.service';
 import { extractRequestInfo } from '../common/request-utils';
@@ -40,9 +46,12 @@ export class DepositsController {

  @Get()
  @RequirePermission('deposit:view')
-  findAll(@Query('studentId') studentId?: string, @Query('status') status?: string) {
+  findAll(
+    @Query('studentId', new ParseIntPipe({ optional: true })) studentId?: number,
+    @Query('status') status?: string,
+  ) {
    return this.service.findAll({
-      studentId: studentId ? +studentId : undefined,
+      studentId,
      status: status || undefined,
    });
  }
@@ -55,8 +64,8 @@ export class DepositsController {

  @Get(':id')
  @RequirePermission('deposit:view')
-  findOne(@Param('id') id: string) {
-    return this.service.findOne(+id);
+  findOne(@Param('id', ParseIntPipe) id: number) {
+    return this.service.findOne(id);
  }

  @Post()
@@ -93,12 +102,12 @@ export class DepositsController {
  @Post(':id/installments')
  @RequirePermission('deposit:edit')
  async addInstallment(
-    @Param('id') id: string,
-    @Body() body: { amount: number; dueDate: string },
+    @Param('id', ParseIntPipe) id: number,
+    @Body() body: CreateDepositInstallmentDto,
    @Request() req: { user?: { id: number; username: string }; headers?: Record<string, string> },
  ) {
    const { ipAddress, userAgent } = extractRequestInfo(req);
-    const result = await this.service.addInstallment(+id, body.amount, body.dueDate);
+    const result = await this.service.addInstallment(id, body.amount, body.dueDate);
    await this.logService.log({
      userId: req.user?.id,
      username: req.user?.username,
@@ -116,18 +125,18 @@ export class DepositsController {
  @Put('installments/:installmentId')
  @RequirePermission('deposit:edit')
  async updateInstallment(
-    @Param('installmentId') installmentId: string,
-    @Body() body: { paidDate?: string; status?: string },
+    @Param('installmentId', ParseIntPipe) installmentId: number,
+    @Body() body: UpdateDepositInstallmentDto,
    @Request() req: { user?: { id: number; username: string }; headers?: Record<string, string> },
  ) {
    const { ipAddress, userAgent } = extractRequestInfo(req);
-    const result = await this.service.updateInstallment(+installmentId, body);
+    const result = await this.service.updateInstallment(installmentId, body);
    await this.logService.log({
      userId: req.user?.id,
      username: req.user?.username,
      module: '押金管理',
      action: '更新分期',
-      targetId: +installmentId,
+      targetId: installmentId,
      targetType: 'deposit-installment',
      detail: `更新分期${installmentId}, 状态：${result.status ?? '-'}, 实付日：${result.paidDate ?? '-'}`,
      ipAddress,
@@ -139,17 +148,17 @@ export class DepositsController {
  @Delete('installments/:installmentId')
  @RequirePermission('deposit:delete')
  async deleteInstallment(
-    @Param('installmentId') installmentId: string,
+    @Param('installmentId', ParseIntPipe) installmentId: number,
    @Request() req: { user?: { id: number; username: string }; headers?: Record<string, string> },
  ) {
    const { ipAddress, userAgent } = extractRequestInfo(req);
-    const result = await this.service.deleteInstallment(+installmentId);
+    const result = await this.service.deleteInstallment(installmentId);
    await this.logService.log({
      userId: req.user?.id,
      username: req.user?.username,
      module: '押金管理',
      action: '删除分期',
-      targetId: +installmentId,
+      targetId: installmentId,
      targetType: 'deposit-installment',
      detail: `删除分期${installmentId}`,
      ipAddress,
@@ -160,15 +169,15 @@ export class DepositsController {

  @Put(':id/refund')
  @RequirePermission('deposit:refund')
-  async refund(@Param('id') id: string, @Body() dto: RefundDepositDto, @Request() req: any) {
+  async refund(@Param('id', ParseIntPipe) id: number, @Body() dto: RefundDepositDto, @Request() req: any) {
    const { ipAddress, userAgent } = extractRequestInfo(req);
-    const result = await this.service.refund(+id, dto, req.user?.id);
+    const result = await this.service.refund(id, dto, req.user?.id);
    await this.logService.log({
      userId: req.user?.id,
      username: req.user?.username,
      module: '押金管理',
      action: '退还押金',
-      targetId: +id,
+      targetId: id,
      targetType: 'deposit',
      detail: `退还全部可用押金 ¥${result.refundAmount}`,
      ipAddress,
@@ -191,15 +200,15 @@ export class DepositsController {

  @Delete(':id')
  @RequirePermission('deposit:delete')
-  async remove(@Param('id') id: string, @Request() req: any) {
+  async remove(@Param('id', ParseIntPipe) id: number, @Request() req: any) {
    const { ipAddress, userAgent } = extractRequestInfo(req);
-    const result = await this.service.remove(+id);
+    const result = await this.service.remove(id);
    await this.logService.log({
      userId: req.user?.id,
      username: req.user?.username,
      module: '押金管理',
      action: '删除押金记录',
-      targetId: +id,
+      targetId: id,
      targetType: 'deposit',
      ipAddress,
      userAgent,
--- a/apps/server/src/deposits/deposits.refund.spec.ts
+++ b/apps/server/src/deposits/deposits.refund.spec.ts
@@ -2,7 +2,7 @@ import { DepositsService } from './deposits.service';
 import { Deposit } from '../entities/deposit.entity';

 describe('DepositsService — direct refund', () => {
-  it('stores the refund result on the main status and renamed audit fields', async () => {
+  it('refunds the full available balance and stores audit fields', async () => {
    const deposit = {
      id: 1,
      amount: 500,
@@ -16,20 +16,16 @@ describe('DepositsService — direct refund', () => {

    const result = await service.refund(
      1,
-      {
-        refundDate: '2026-07-13',
-        deductionAmount: 100,
-        deductionReason: '物品损坏',
-      },
+      { refundDate: '2026-07-13', notes: '退还剩余押金' },
      42,
    );

    expect(result).toMatchObject({
      refundDate: '2026-07-13',
-      refundAmount: 400,
-      deductionAmount: 100,
-      deductionReason: '物品损坏',
-      status: 'partial_refund',
+      amount: 0,
+      refundAmount: 500,
+      notes: '退还剩余押金',
+      status: 'refunded',
      refundedBy: 42,
    });
    expect(result.refundedAt).toBeInstanceOf(Date);
--- a/apps/server/src/deposits/dto/deposit.dto.ts
+++ b/apps/server/src/deposits/dto/deposit.dto.ts
@@ -1,13 +1,14 @@
-import { IsInt, IsNumber, IsString, IsOptional } from 'class-validator';
+import { IsDateString, IsIn, IsInt, IsNumber, IsString, IsOptional, Min } from 'class-validator';

 export class CreateDepositDto {
  @IsInt()
  studentId: number;

-  @IsNumber()
+  @IsNumber({ maxDecimalPlaces: 2 })
+  @Min(0.01)
  amount: number;

-  @IsString()
+  @IsDateString()
  paidDate: string;

  @IsOptional()
@@ -16,10 +17,29 @@ export class CreateDepositDto {
 }

 export class RefundDepositDto {
-  @IsString()
+  @IsDateString()
  refundDate: string;

  @IsOptional()
  @IsString()
  notes?: string;
 }
+
+export class CreateDepositInstallmentDto {
+  @IsNumber({ maxDecimalPlaces: 2 })
+  @Min(0.01)
+  amount: number;
+
+  @IsDateString()
+  dueDate: string;
+}
+
+export class UpdateDepositInstallmentDto {
+  @IsOptional()
+  @IsDateString()
+  paidDate?: string;
+
+  @IsOptional()
+  @IsIn(['pending', 'paid', 'overdue'])
+  status?: string;
+}