重构后台管理服务并推进渐进式类型化

apps/backend/src/repositories/task-repo.js

@@ -1,5 +1,14 @@
+// @ts-check
+
 import { query, withTransaction } from '../db/client.js'
 
+/** @typedef {import('../types/repository-inputs.js').TaskCreateInput} TaskCreateInput */
+/** @typedef {import('../types/repository-inputs.js').TaskListQueryInput} TaskListQueryInput */
+/** @typedef {import('../types/repository-inputs.js').TaskTencentContextPatch} TaskTencentContextPatch */
+/** @typedef {import('../types/repository-inputs.js').TaskUpdatePatch} TaskUpdatePatch */
+/** @typedef {import('../types/repository-rows.js').TaskListQueryResult} TaskListQueryResult */
+/** @typedef {import('../types/repository-rows.js').TaskRow} TaskRow */
+
 const TASK_FIELDS = `
   ft.*,
   ct.id AS primary_claim_token_id,
@@ -52,6 +61,7 @@ function buildTaskSelect(extraFields = '') {
   return `SELECT ${fieldSql} ${TASK_JOINS}`
 }
 
+/** @returns {Promise<TaskRow[]>} */
 export async function listTasksByOrderId(orderId) {
   const result = await query(
     `${buildTaskSelect()}
@@ -59,9 +69,11 @@ export async function listTasksByOrderId(orderId) {
      ORDER BY ft.id ASC`,
     [Number(orderId)],
   )
-  return result.rows
+  return /** @type {TaskRow[]} */ (result.rows)
 }
 
+/** @returns {Promise<TaskRow | null>} */
+/** @param {TaskCreateInput} input */
 export async function createTask(input) {
   return withTransaction(async (client) => {
     const taskResult = await client.query(
@@ -139,6 +151,8 @@ export async function createTask(input) {
   })
 }
 
+/** @returns {Promise<TaskRow | null>} */
+/** @param {TaskUpdatePatch} patch */
 export async function updateTask(taskId, patch) {
   const current = await getTaskById(taskId)
   if (!current) {
@@ -212,10 +226,12 @@ export async function updateTask(taskId, patch) {
   })
 }
 
+/** @returns {Promise<TaskRow | null>} */
 export async function getTaskById(taskId) {
   return getTaskByIdWithExecutor(query, taskId)
 }
 
+/** @returns {Promise<TaskRow | null>} */
 export async function findTaskByClaimTokenId(claimTokenId) {
   const result = await query(
     `${buildTaskSelect()}
@@ -224,9 +240,11 @@ export async function findTaskByClaimTokenId(claimTokenId) {
      LIMIT 1`,
     [Number(claimTokenId)],
   )
-  return result.rows[0] || null
+  return /** @type {TaskRow | null} */ (result.rows[0] || null)
 }
 
+/** @returns {Promise<TaskListQueryResult>} */
+/** @param {TaskListQueryInput} [queryInput] */
 export async function listTasks({
   page = 1,
   pageSize = 20,
@@ -237,7 +255,7 @@ export async function listTasks({
   roleId = '',
   dateFrom = '',
   dateTo = '',
-} = {}) {
+} = /** @type {TaskListQueryInput} */ ({})) {
   const offset = (page - 1) * pageSize
   const filters = []
   const params = []
@@ -301,11 +319,12 @@ export async function listTasks({
   )
 
   return {
-    items: itemsResult.rows,
+    items: /** @type {TaskRow[]} */ (itemsResult.rows),
     total: Number(totalResult.rows[0]?.total || 0),
   }
 }
 
+/** @param {TaskTencentContextPatch} patch */
 async function upsertTencentBrowserContextWithClient(client, taskId, patch = {}, timestamp) {
   const currentResult = await client.query(
     'SELECT * FROM tencent_browser_contexts WHERE task_id = $1 LIMIT 1',
@@ -399,6 +418,7 @@ async function upsertTencentBrowserContextWithClient(client, taskId, patch = {},
   )
 }
 
+/** @returns {Promise<TaskRow | null>} */
 async function getTaskByIdWithExecutor(executor, taskId) {
   const result = await executor(
     `${buildTaskSelect()}
@@ -406,7 +426,7 @@ async function getTaskByIdWithExecutor(executor, taskId) {
      LIMIT 1`,
     [Number(taskId)],
   )
-  return result.rows[0] || null
+  return /** @type {TaskRow | null} */ (result.rows[0] || null)
 }
 
 function containsTencentPatch(patch = {}) {