feat: add student wallet utility billing

apps/server/src/expenses/dto/expense.dto.ts

@@ -1,4 +1,4 @@
-import { IsInt, IsString, IsNumber, IsOptional } from 'class-validator';
+import { IsIn, IsInt, IsString, IsNumber, IsOptional, Matches, Min } from 'class-validator';
 
 export class CreateRoomExpenseDto {
   @IsInt()
@@ -52,3 +52,28 @@ export class BatchRoomExpenseDto {
 
   expenses: { roomId: number; expenseType: string; amount: number; description?: string }[];
 }
+
+
+export class CreateStudentUtilityBillDto {
+  @IsInt()
+  studentId: number;
+
+  @IsIn(['water', 'electricity'])
+  expenseType: 'water' | 'electricity';
+
+  @IsNumber({ maxDecimalPlaces: 2 })
+  @Min(0.01)
+  amount: number;
+
+  @IsString()
+  @Matches(/^\d{4}-\d{2}-\d{2}$/)
+  periodStart: string;
+
+  @IsString()
+  @Matches(/^\d{4}-\d{2}-\d{2}$/)
+  periodEnd: string;
+
+  @IsOptional()
+  @IsString()
+  description?: string;
+}

apps/server/src/expenses/expenses.controller.ts

@@ -20,6 +20,7 @@ import {
   CreateRoomExpenseDto,
   CreatePersonalExpenseDto,
   BatchRoomExpenseDto,
+  CreateStudentUtilityBillDto,
 } from './dto/expense.dto';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
 import { OperationLogsService } from '../operation-logs/operation-logs.service';
@@ -78,6 +79,25 @@ export class ExpensesController {
     return this.service.getFormLookups();
   }
 
+  @Post('student-utility')
+  @RequirePermission('expense:create')
+  async createStudentUtilityBill(@Body() dto: CreateStudentUtilityBillDto, @Request() req: any) {
+    const result = await this.service.createStudentUtilityBill(dto, req.user?.id);
+    const { ipAddress, userAgent } = extractRequestInfo(req);
+    await this.logService.log({
+      userId: req.user?.id,
+      username: req.user?.username,
+      module: '费用管理',
+      action: '录入学生水电费并出账',
+      targetId: result.bill.id,
+      targetType: 'bill',
+      detail: `学生${dto.studentId} ${dto.expenseType} ¥${dto.amount}，自动扣款 ¥${result.bill.paidAmount}`,
+      ipAddress,
+      userAgent,
+    });
+    return result;
+  }
+
   @Post('room')
   @RequirePermission('expense:create')
   async createRoomExpense(@Body() dto: CreateRoomExpenseDto, @Request() req: any) {

apps/server/src/expenses/expenses.module.ts

@@ -7,11 +7,13 @@ import { Student } from '../entities/student.entity';
 import { ExpensesService } from './expenses.service';
 import { ExpensesController } from './expenses.controller';
 import { OperationLogsModule } from '../operation-logs/operation-logs.module';
+import { BillsModule } from '../bills/bills.module';
 
 @Module({
   imports: [
     TypeOrmModule.forFeature([RoomExpense, PersonalExpense, Room, Student]),
     OperationLogsModule,
+    BillsModule,
   ],
   controllers: [ExpensesController],
   providers: [ExpensesService],

apps/server/src/expenses/expenses.service.ts

@@ -9,8 +9,10 @@ import {
   CreateRoomExpenseDto,
   CreatePersonalExpenseDto,
   BatchRoomExpenseDto,
+  CreateStudentUtilityBillDto,
 } from './dto/expense.dto';
 import { RoomsService } from '../rooms/rooms.service';
+import { BillsService } from '../bills/bills.service';
 
 
 @Injectable()
@@ -20,6 +22,7 @@ export class ExpensesService {
     @InjectRepository(PersonalExpense) private personalExpRepo: Repository<PersonalExpense>,
     @InjectRepository(Room) private roomRepo: Repository<Room>,
     @InjectRepository(Student) private studentRepo: Repository<Student>,
+    private billsService: BillsService,
   ) {}
 
   async getFormLookups() {
@@ -96,6 +99,30 @@ export class ExpensesService {
     return this.roomExpRepo.save(e);
   }
 
+  async createStudentUtilityBill(dto: CreateStudentUtilityBillDto, userId?: number) {
+    if (dto.periodEnd < dto.periodStart) throw new BadRequestException('账期结束日期不能早于开始日期');
+    const student = await this.studentRepo.findOne({ where: { id: dto.studentId } });
+    if (!student) throw new NotFoundException('学生不存在');
+    const expense = await this.personalExpRepo.save(
+      this.personalExpRepo.create({
+        studentId: dto.studentId,
+        expenseType: dto.expenseType,
+        amount: dto.amount,
+        expenseDate: dto.periodEnd,
+        description: dto.description || (dto.expenseType === 'water' ? '学生水费' : '学生电费'),
+        recordedBy: userId,
+        billId: null,
+      }),
+    );
+    try {
+      const bill = await this.billsService.createImmediatePersonalBill(expense, dto.periodStart, dto.periodEnd, userId);
+      return { expense, bill };
+    } catch (error) {
+      await this.personalExpRepo.delete(expense.id);
+      throw error;
+    }
+  }
+
   // 个人附加费
   async createPersonalExpense(dto: CreatePersonalExpenseDto, userId?: number) {
     const student = await this.studentRepo.findOne({ where: { id: dto.studentId } });