feat(M08-B): 增加保洁结算单和超时回收

backend/src/routes/cleaning.ts

@@ -27,11 +27,31 @@ const assignSchema = z.object({
 }).strict();
 const completeSchema = z.object({ note: z.string().trim().max(512).optional() }).strict();
 const rejectSchema = z.object({ reason: z.string().trim().min(1).max(512) }).strict();
+const settlementStatusSchema = z.enum(['DRAFT', 'CONFIRMED', 'PAID', 'CANCELLED']);
+const settlementListSchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  pageSize: z.coerce.number().int().min(1).max(50).default(20),
+  status: settlementStatusSchema.optional()
+});
+const settlementParamsSchema = z.object({ settlementId: z.string().regex(/^[1-9]\d{0,19}$/) });
+const settlementGenerateSchema = z.object({
+  cleanerUserId: z.string().regex(/^[1-9]\d{0,19}$/),
+  storeId: z.string().regex(/^[1-9]\d{0,19}$/).optional(),
+  note: z.string().trim().max(512).optional()
+}).strict();
+const settlementConfirmSchema = z.object({
+  note: z.string().trim().max(512).optional()
+}).strict();
+const reclaimSchema = z.object({
+  olderThanMinutes: z.coerce.number().int().min(5).max(1440).default(60),
+  limit: z.coerce.number().int().min(1).max(100).default(20)
+});
 
 export interface CleaningRouteOptions {
   repository: Pick<CleaningTaskRepository,
     'listHall' | 'listMine' | 'listManage' | 'claim' | 'start' | 'rework' | 'submit'
     | 'assign' | 'complete' | 'reject' | 'settlementCandidates'
+    | 'listSettlements' | 'generateSettlement' | 'confirmSettlement' | 'reclaimTimeouts'
     | 'assertCanUploadPhoto' | 'stats'>;
   mediaStorage?: MediaStorage;
   authRepository: Pick<AuthRepository, 'validateSession'>;
@@ -109,6 +129,18 @@ export async function registerCleaningRoutes(
     }));
   });
 
+  app.get('/admin-api/cleaning/settlements', async (request, reply) => {
+    const actor = await requireActor(request, reply, options, 'read');
+    if (!actor) return;
+    const query = settlementListSchema.safeParse(request.query);
+    if (!query.success) return invalid(reply, request.traceId);
+    return handle(reply, request.traceId, async () => ({
+      code: 0,
+      data: await options.repository.listSettlements({ ...actor, ...query.data }),
+      traceId: request.traceId
+    }));
+  });
+
   app.post('/app-api/cleaning/tasks/:taskId/claim', async (request, reply) => {
     const actor = await requireActor(request, reply, options, 'write');
     if (!actor) return;
@@ -239,6 +271,47 @@ export async function registerCleaningRoutes(
       traceId: request.traceId
     }));
   });
+
+  app.post('/admin-api/cleaning/reclaim-timeouts', async (request, reply) => {
+    const actor = await requireActor(request, reply, options, 'write');
+    if (!actor) return;
+    const body = reclaimSchema.safeParse(request.body ?? {});
+    if (!body.success) return invalid(reply, request.traceId);
+    return handle(reply, request.traceId, async () => ({
+      code: 0,
+      data: await options.repository.reclaimTimeouts({ ...actor, ...body.data }),
+      traceId: request.traceId
+    }));
+  });
+
+  app.post('/admin-api/cleaning/settlements', async (request, reply) => {
+    const actor = await requireActor(request, reply, options, 'write');
+    if (!actor) return;
+    const body = settlementGenerateSchema.safeParse(request.body ?? {});
+    if (!body.success) return invalid(reply, request.traceId);
+    return handle(reply, request.traceId, async () => reply.status(201).send({
+      code: 0,
+      data: await options.repository.generateSettlement({ ...actor, ...body.data }),
+      traceId: request.traceId
+    }));
+  });
+
+  app.post('/admin-api/cleaning/settlements/:settlementId/confirm', async (request, reply) => {
+    const actor = await requireActor(request, reply, options, 'write');
+    if (!actor) return;
+    const params = settlementParamsSchema.safeParse(request.params);
+    const body = settlementConfirmSchema.safeParse(request.body ?? {});
+    if (!params.success || !body.success) return invalid(reply, request.traceId);
+    return handle(reply, request.traceId, async () => ({
+      code: 0,
+      data: await options.repository.confirmSettlement({
+        ...actor,
+        settlementId: params.data.settlementId,
+        note: body.data.note
+      }),
+      traceId: request.traceId
+    }));
+  });
 }
 
 async function requireActor(
@@ -290,7 +363,8 @@ async function handle(reply: FastifyReply, traceId: string, work: () => Promise<
       });
     }
     if (!(error instanceof CleaningTaskError)) throw error;
-    const statusCode = error.code === 'CLEANING_TASK_FORBIDDEN' ? 403 : 409;
+    const statusCode = error.code === 'CLEANING_TASK_FORBIDDEN'
+      || error.code === 'CLEANING_SETTLEMENT_FORBIDDEN' ? 403 : 409;
     return reply.status(statusCode).send({
       code: error.code,
       message: 'The cleaning task request cannot be completed.',