把 task 的 helper独立出来了

apps/backend/src/routes/admin/shared.js

@@ -1,8 +1,45 @@
+// @ts-check
+
 import { requireAdminRole, verifyAdminSessionToken } from '../../services/admin/admin-auth-service.js'
 import { writeAdminAuditLog } from '../../services/admin/admin-audit-service.js'
 import { buildSuccessPayload, createHttpError, sendRouteError } from '../../utils/http.js'
 import { logWarn } from '../../utils/logger.js'
 
+/** @typedef {import('express').NextFunction} NextFunction */
+/** @typedef {import('express').Request} ExpressRequest */
+/** @typedef {import('express').Response} ExpressResponse */
+/** @typedef {import('../../types/admin-route-inputs.js').AdminRouteAdminSession} AdminRouteAdminSession */
+/** @typedef {ExpressRequest & { adminSession?: AdminRouteAdminSession | null }} AdminExpressRequest */
+
+/**
+ * @typedef {{
+ *   action?: string
+ *   targetType?: string
+ *   targetId?: string
+ *   data?: Record<string, unknown>
+ * }} AdminAuditPayload
+ */
+
+/**
+ * @typedef {{
+ *   successMessage?: string
+ *   errorMessage?: string
+ *   scope?: string
+ *   audit?: (req: AdminExpressRequest, data: unknown) => (AdminAuditPayload | null | undefined)
+ * }} AdminJsonHandlerOptions
+ */
+
+/**
+ * @typedef {{
+ *   errorMessage?: string
+ *   scope?: string
+ * }} AdminFileHandlerOptions
+ */
+
+/**
+ * @param {(req: AdminExpressRequest, res: ExpressResponse) => unknown | Promise<unknown>} action
+ * @param {AdminJsonHandlerOptions} [options]
+ */
 export function createJsonHandler(action, { successMessage = 'ok', errorMessage, scope, audit } = {}) {
   return async (req, res) => {
     try {
@@ -15,6 +52,10 @@ export function createJsonHandler(action, { successMessage = 'ok', errorMessage,
   }
 }
 
+/**
+ * @param {(req: AdminExpressRequest, res: ExpressResponse) => string | Promise<string>} action
+ * @param {AdminFileHandlerOptions} [options]
+ */
 export function createFileHandler(action, { errorMessage, scope } = {}) {
   return async (req, res) => {
     try {
@@ -26,6 +67,9 @@ export function createFileHandler(action, { errorMessage, scope } = {}) {
   }
 }
 
+/** @param {AdminExpressRequest} req */
+/** @param {ExpressResponse} res */
+/** @param {NextFunction} next */
 export async function requireAdminSession(req, res, next) {
   try {
     req.adminSession = await verifyAdminSessionToken(extractBearerToken(req))
@@ -35,6 +79,7 @@ export async function requireAdminSession(req, res, next) {
   }
 }
 
+/** @param {string[]} allowedRoles */
 export function requireAdminRoles(allowedRoles) {
   return (req, res, next) => {
     try {