feat: 扩展 Agent 业务查询与学生增改工具

apps/server/src/deposits/deposits.service.ts

@@ -145,6 +145,65 @@ export class DepositsService {
     return deposits;
   }
 
+  /**
+   * Agent tool: 押金查询，返回白名单字段（学生姓名/学号、金额、状态、退款）。
+   */
+  async agentSearchDeposits(query?: {
+    keyword?: string;
+    status?: string;
+    limit?: number;
+  }): Promise<
+    {
+      id: number;
+      studentName: string;
+      studentNo: string;
+      amount: number;
+      status: string;
+      paidDate: string;
+      refundAmount: number | null;
+      refundDate: string | null;
+    }[]
+  > {
+    const qb = this.repo
+      .createQueryBuilder('d')
+      .leftJoin('d.student', 'student')
+      .select('d.id', 'id')
+      .addSelect('student.name', 'studentName')
+      .addSelect('student.studentNo', 'studentNo')
+      .addSelect('d.amount', 'amount')
+      .addSelect('d.status', 'status')
+      .addSelect('d.paidDate', 'paidDate')
+      .addSelect('d.refundAmount', 'refundAmount')
+      .addSelect('d.refundDate', 'refundDate')
+      .where('d.status != :archived', { archived: 'archived' });
+    if (query?.keyword) {
+      qb.andWhere(
+        '(student.name LIKE :keyword OR student.studentNo LIKE :keyword)',
+        { keyword: `%${query.keyword}%` },
+      );
+    }
+    if (query?.status && query.status !== 'archived') {
+      qb.andWhere('d.status = :status', { status: query.status });
+    }
+    const rows = await qb
+      .orderBy('d.createdAt', 'DESC')
+      .limit(Math.max(1, Math.min(query?.limit ?? 20, 50)))
+      .getRawMany<Record<string, unknown>>();
+    return rows.map((row) => ({
+      id: Number(row.id),
+      studentName: row.studentName == null ? '' : String(row.studentName),
+      studentNo: row.studentNo == null ? '' : String(row.studentNo),
+      amount: money(row.amount as number | string | null | undefined),
+      status: String(row.status),
+      paidDate: row.paidDate == null ? '' : String(row.paidDate),
+      refundAmount:
+        row.refundAmount == null
+          ? null
+          : money(row.refundAmount as number | string | null | undefined),
+      refundDate: row.refundDate == null ? null : String(row.refundDate),
+    }));
+  }
+
   async findOne(id: number) {
     const deposit = await this.repo.findOne({ where: { id }, relations: ['student', 'installments'] });
     if (!deposit) throw new NotFoundException('押金记录不存在');