feat: add student wallet utility billing

apps/server/src/wallets/dto/wallet.dto.ts

@@ -0,0 +1,18 @@
+import { IsIn, IsInt, IsNumber, IsOptional, IsString, MaxLength, NotEquals } from 'class-validator';
+
+export class ChangeWalletBalanceDto {
+  @IsInt()
+  studentId: number;
+
+  @IsNumber({ maxDecimalPlaces: 2 })
+  @NotEquals(0)
+  amount: number;
+
+  @IsIn(['recharge', 'adjustment'])
+  type: 'recharge' | 'adjustment';
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(300)
+  description?: string;
+}

apps/server/src/wallets/wallets.controller.ts

@@ -0,0 +1,44 @@
+import { Body, Controller, Get, Post, Query, Request, UseGuards } from '@nestjs/common';
+import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequirePermission } from '../auth/decorators/permission.decorator';
+import { OperationLogsService } from '../operation-logs/operation-logs.service';
+import { extractRequestInfo } from '../common/request-utils';
+import { ChangeWalletBalanceDto } from './dto/wallet.dto';
+import { WalletsService } from './wallets.service';
+
+@UseGuards(JwtAuthGuard)
+@Controller('wallets')
+export class WalletsController {
+  constructor(private service: WalletsService, private logService: OperationLogsService) {}
+
+  @Get()
+  @RequirePermission('wallet:view')
+  findAll(@Query('keyword') keyword?: string, @Query('debtOnly') debtOnly?: string) {
+    return this.service.findAll({ keyword, debtOnly: debtOnly === 'true' });
+  }
+
+  @Get('transactions')
+  @RequirePermission('wallet:view')
+  findTransactions(@Query('studentId') studentId: string) {
+    return this.service.findTransactions(Number(studentId));
+  }
+
+  @Post('change-balance')
+  @RequirePermission('wallet:edit')
+  async changeBalance(@Body() dto: ChangeWalletBalanceDto, @Request() req: any) {
+    const result = await this.service.changeBalance(dto, req.user?.id);
+    const { ipAddress, userAgent } = extractRequestInfo(req);
+    await this.logService.log({
+      userId: req.user?.id,
+      username: req.user?.username,
+      module: '学生余额',
+      action: dto.type === 'recharge' ? '余额充值' : '余额调账',
+      targetId: dto.studentId,
+      targetType: 'student_wallet',
+      detail: `金额 ¥${dto.amount}${dto.description ? `，${dto.description}` : ''}`,
+      ipAddress,
+      userAgent,
+    });
+    return result;
+  }
+}

apps/server/src/wallets/wallets.module.ts

@@ -0,0 +1,17 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { Bill } from '../entities/bill.entity';
+import { Student } from '../entities/student.entity';
+import { StudentWallet } from '../entities/student-wallet.entity';
+import { WalletTransaction } from '../entities/wallet-transaction.entity';
+import { OperationLogsModule } from '../operation-logs/operation-logs.module';
+import { WalletsController } from './wallets.controller';
+import { WalletsService } from './wallets.service';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([StudentWallet, WalletTransaction, Student, Bill]), OperationLogsModule],
+  controllers: [WalletsController],
+  providers: [WalletsService],
+  exports: [WalletsService],
+})
+export class WalletsModule {}

apps/server/src/wallets/wallets.service.spec.ts

@@ -0,0 +1,52 @@
+import { BadRequestException } from '@nestjs/common';
+import { WalletsService } from './wallets.service';
+import { Bill } from '../entities/bill.entity';
+
+const manager = (walletBalance: number) => {
+  const wallet = { id: 1, studentId: 10, balance: walletBalance };
+  const saved: any[] = [];
+  return {
+    wallet,
+    saved,
+    value: {
+      findOne: jest.fn(async () => wallet),
+      findOneByOrFail: jest.fn(async () => wallet),
+      save: jest.fn(async (value: any) => { saved.push(value); return value; }),
+      create: jest.fn((_entity: unknown, value: unknown) => value),
+      createQueryBuilder: jest.fn(),
+    },
+  };
+};
+
+describe('WalletsService payment rules', () => {
+  const service = new WalletsService({} as any, {} as any, {} as any, {} as any);
+
+  it('partially pays a bill when balance is insufficient', async () => {
+    const ctx = manager(40);
+    const bill = { id: 9, studentId: 10, totalAmount: 100, paidAmount: 0, outstandingAmount: 100, status: 'unpaid' } as Bill;
+    const result = await service.debitBill(ctx.value as any, bill, 1);
+    expect(result.status).toBe('partially_paid');
+    expect(Number(result.paidAmount)).toBe(40);
+    expect(Number(result.outstandingAmount)).toBe(60);
+    expect(Number(ctx.wallet.balance)).toBe(0);
+    expect(ctx.saved.some((row) => row.type === 'bill_payment' && Number(row.amount) === -40)).toBe(true);
+  });
+
+  it('marks a bill paid when balance covers it', async () => {
+    const ctx = manager(120);
+    const bill = { id: 9, studentId: 10, totalAmount: 100, paidAmount: 0, outstandingAmount: 100, status: 'unpaid' } as Bill;
+    const result = await service.debitBill(ctx.value as any, bill);
+    expect(result.status).toBe('paid');
+    expect(Number(result.outstandingAmount)).toBe(0);
+    expect(Number(ctx.wallet.balance)).toBe(20);
+  });
+
+  it('refunds paid amount and cancels the bill', async () => {
+    const ctx = manager(10);
+    const bill = { id: 9, studentId: 10, totalAmount: 100, paidAmount: 40, outstandingAmount: 60, status: 'partially_paid' } as Bill;
+    const result = await service.refundBill(ctx.value as any, bill, '录入错误', 1);
+    expect(result.status).toBe('cancelled');
+    expect(Number(ctx.wallet.balance)).toBe(50);
+    expect(ctx.saved.some((row) => row.type === 'bill_refund' && Number(row.amount) === 40)).toBe(true);
+  });
+});

apps/server/src/wallets/wallets.service.ts

@@ -0,0 +1,167 @@
+import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { DataSource, EntityManager, Repository } from 'typeorm';
+import { Bill } from '../entities/bill.entity';
+import { Student } from '../entities/student.entity';
+import { StudentWallet } from '../entities/student-wallet.entity';
+import { WalletTransaction } from '../entities/wallet-transaction.entity';
+import { In } from 'typeorm';
+import { ChangeWalletBalanceDto } from './dto/wallet.dto';
+
+const money = (value: number | string | null | undefined) => Number(Number(value || 0).toFixed(2));
+
+@Injectable()
+export class WalletsService {
+  constructor(
+    @InjectRepository(StudentWallet) private walletRepo: Repository<StudentWallet>,
+    @InjectRepository(WalletTransaction) private transactionRepo: Repository<WalletTransaction>,
+    @InjectRepository(Student) private studentRepo: Repository<Student>,
+    private dataSource: DataSource,
+  ) {}
+
+  async findAll(query?: { keyword?: string; debtOnly?: boolean }) {
+    const students = await this.studentRepo
+      .createQueryBuilder('student')
+      .where('student.status = :status', { status: 'active' })
+      .andWhere(
+        query?.keyword
+          ? '(student.name LIKE :keyword OR student.studentNo LIKE :keyword)'
+          : '1 = 1',
+        query?.keyword ? { keyword: `%${query.keyword}%` } : {},
+      )
+      .orderBy('student.name', 'ASC')
+      .getMany();
+    if (!students.length) return [];
+
+    const ids = students.map((student) => student.id);
+    const wallets = await this.walletRepo.find({ where: { studentId: In(ids) } });
+    const bills = await this.dataSource.getRepository(Bill)
+      .createQueryBuilder('bill')
+      .select('bill.studentId', 'studentId')
+      .addSelect('SUM(bill.outstandingAmount)', 'outstandingAmount')
+      .where('bill.studentId IN (:...ids)', { ids })
+      .andWhere('bill.status IN (:...statuses)', { statuses: ['unpaid', 'partially_paid'] })
+      .groupBy('bill.studentId')
+      .getRawMany<{ studentId: number; outstandingAmount: string }>();
+    const walletMap = new Map(wallets.map((wallet) => [wallet.studentId, wallet]));
+    const debtMap = new Map(bills.map((bill) => [Number(bill.studentId), money(bill.outstandingAmount)]));
+    return students
+      .map((student) => ({
+        studentId: student.id,
+        studentName: student.name,
+        studentNo: student.studentNo,
+        balance: money(walletMap.get(student.id)?.balance),
+        outstandingAmount: debtMap.get(student.id) || 0,
+      }))
+      .filter((row) => !query?.debtOnly || row.outstandingAmount > 0);
+  }
+
+  async findTransactions(studentId: number) {
+    return this.transactionRepo.find({ where: { studentId }, order: { createdAt: 'DESC' } });
+  }
+
+  async changeBalance(dto: ChangeWalletBalanceDto, recordedBy?: number) {
+    if (dto.type === 'recharge' && dto.amount <= 0) throw new BadRequestException('充值金额必须大于 0');
+    const student = await this.studentRepo.findOne({ where: { id: dto.studentId } });
+    if (!student) throw new NotFoundException('学生不存在');
+    return this.dataSource.transaction(async (manager) => {
+      const wallet = await this.getOrCreateWallet(manager, dto.studentId);
+      const nextBalance = money(Number(wallet.balance) + dto.amount);
+      if (nextBalance < 0) throw new BadRequestException('调账后余额不能小于 0');
+      wallet.balance = nextBalance;
+      await manager.save(wallet);
+      await manager.save(
+        manager.create(WalletTransaction, {
+          studentId: dto.studentId,
+          billId: null,
+          type: dto.type,
+          amount: money(dto.amount),
+          balanceAfter: nextBalance,
+          description: dto.description || (dto.type === 'recharge' ? '财务充值' : '余额调账'),
+          recordedBy: recordedBy || null,
+        }),
+      );
+      const payments = dto.amount > 0 ? await this.settleOutstandingBills(manager, dto.studentId, recordedBy) : [];
+      const finalWallet = await manager.findOneByOrFail(StudentWallet, { studentId: dto.studentId });
+      return { wallet: finalWallet, payments };
+    });
+  }
+
+  async debitBill(manager: EntityManager, bill: Bill, recordedBy?: number) {
+    if (bill.status === 'cancelled' || money(bill.outstandingAmount) <= 0) return bill;
+    const wallet = await this.getOrCreateWallet(manager, bill.studentId);
+    const amount = money(Math.min(Number(wallet.balance), Number(bill.outstandingAmount)));
+    if (amount <= 0) {
+      bill.status = money(bill.paidAmount) > 0 ? 'partially_paid' : 'unpaid';
+      return manager.save(bill);
+    }
+    wallet.balance = money(Number(wallet.balance) - amount);
+    bill.paidAmount = money(Number(bill.paidAmount) + amount);
+    bill.outstandingAmount = money(Number(bill.totalAmount) - Number(bill.paidAmount));
+    bill.status = bill.outstandingAmount <= 0 ? 'paid' : 'partially_paid';
+    await manager.save(wallet);
+    await manager.save(bill);
+    await manager.save(
+      manager.create(WalletTransaction, {
+        studentId: bill.studentId,
+        billId: bill.id,
+        type: 'bill_payment',
+        amount: -amount,
+        balanceAfter: wallet.balance,
+        description: `账单 #${bill.id} 自动扣款`,
+        recordedBy: recordedBy || null,
+      }),
+    );
+    return bill;
+  }
+
+  async refundBill(manager: EntityManager, bill: Bill, reason: string, recordedBy?: number) {
+    const paid = money(bill.paidAmount);
+    if (paid > 0) {
+      const wallet = await this.getOrCreateWallet(manager, bill.studentId);
+      wallet.balance = money(Number(wallet.balance) + paid);
+      await manager.save(wallet);
+      await manager.save(
+        manager.create(WalletTransaction, {
+          studentId: bill.studentId,
+          billId: bill.id,
+          type: 'bill_refund',
+          amount: paid,
+          balanceAfter: wallet.balance,
+          description: `取消账单 #${bill.id} 冲正：${reason}`,
+          recordedBy: recordedBy || null,
+        }),
+      );
+    }
+    bill.status = 'cancelled';
+    bill.paidAmount = 0;
+    bill.outstandingAmount = 0;
+    bill.cancelledAt = new Date();
+    bill.cancelReason = reason;
+    return manager.save(bill);
+  }
+
+  private async settleOutstandingBills(manager: EntityManager, studentId: number, recordedBy?: number) {
+    const bills = await manager
+      .createQueryBuilder(Bill, 'bill')
+      .where('bill.studentId = :studentId', { studentId })
+      .andWhere('bill.status IN (:...statuses)', { statuses: ['unpaid', 'partially_paid'] })
+      .andWhere('bill.outstandingAmount > 0')
+      .orderBy('bill.periodStart', 'ASC')
+      .addOrderBy('bill.id', 'ASC')
+      .getMany();
+    const settled: Bill[] = [];
+    for (const bill of bills) {
+      const wallet = await manager.findOne(StudentWallet, { where: { studentId } });
+      if (!wallet || money(wallet.balance) <= 0) break;
+      settled.push(await this.debitBill(manager, bill, recordedBy));
+    }
+    return settled;
+  }
+
+  private async getOrCreateWallet(manager: EntityManager, studentId: number) {
+    let wallet = await manager.findOne(StudentWallet, { where: { studentId } });
+    if (!wallet) wallet = await manager.save(manager.create(StudentWallet, { studentId, balance: 0 }));
+    return wallet;
+  }
+}