Sync Job Management — Admin API | HNU-TimeLetter

The sync jobs API manages the full lifecycle of Feishu data sync tasks. Each job pulls records from Feishu Bitable and writes them to JSON output files under src/data/. The frontend reads those files through the public runtime API (/api/content, /api/contributors, /api/creation-board) at request time — no build or server restart is needed after a sync completes.

All sync jobs execute asynchronously. A 202 Accepted response means the job has been queued successfully — it does not mean the sync has finished. Poll GET /api/admin/sync/jobs/:jobId or stream GET /api/admin/sync/jobs/:jobId/logs to track progress.

Enum reference

SyncJobKind

Value	Description
`sync-data`	Pull records from Feishu Bitable and write JSON output files to `src/data/`.

SyncJobStatus

Value	Description
`queued`	Job has been created and is waiting to run.
`running`	Job is actively executing.
`success`	All tables synced successfully.
`partial_success`	Some tables failed, but output files were still written.
`failed`	Job failed; output files were not updated.
`canceled`	Job was canceled before completion.

SyncStepStatus

Value	Description
`pending`	Step is waiting to be executed.
`running`	Step is currently executing.
`success`	Step completed without issues.
`success_with_warnings`	Step completed but some records had non-fatal issues.
`skipped`	Step was skipped due to missing dependencies or an earlier termination.
`failed`	Step failed.

DependencyMode

Value	Description
`read_local`	(Default) Sync only the selected tables; read dependency data from local output files.
`run_dependencies`	Automatically run dependency tables before the selected tables.
`strict`	Fail immediately if a dependency is missing — no local read, no automatic run.

GET /api/admin/sync/jobs

Returns a paginated list of sync job records, sorted by createdAt descending (most recent first). Authentication: admin_auth cookie required.

Query parameters

limit

number

default:"20"

Maximum number of records to return. Accepted range: 1 – 100.

Response fields

items

SyncJobRecord[]

required

Array of sync job records sorted newest-first.

Show SyncJobRecord fields

jobId

string

required

Unique job identifier. Format: sync_{YYYYMMDDHHmmss}_{random6} (e.g. sync_20260430100000_ab12cd).

kind

SyncJobKind

required

Job type. Currently always "sync-data".

status

SyncJobStatus

required

Current lifecycle status of the job.

tables

SyncTableKey[]

required

The table keys originally requested for this job.

effectiveTables

SyncTableKey[]

required

The table keys actually executed, after dependency resolution.

dependencyMode

DependencyMode

required

How dependency tables were handled for this job.

includeAssets

boolean

required

Whether attachment processing and OSS URL back-fill were enabled for this job.

continueOnTableError

boolean

required

Whether the job continued executing remaining tables after a single-table failure.

triggeredBy

string

required

Source label indicating what triggered the job (e.g. "admin-ui", "scheduler", "webhook").

note

string

required

Optional human-readable note attached to the job at creation time.

createdAt

string

required

ISO 8601 timestamp when the job record was created.

startedAt

string | null

required

ISO 8601 timestamp when execution began. null if the job has not yet started.

syncedAt

string | null

required

ISO 8601 timestamp when the Feishu data fetch completed and files were written. null if not yet reached.

finishedAt

string | null

required

ISO 8601 timestamp when the job reached a terminal status. null if still running or queued.

durationMs

number | null

required

Total execution time in milliseconds. null if the job has not finished.

steps

SyncJobStep[]

required

Per-table step results. See GET /api/admin/sync/jobs/:jobId for the expanded structure.

summary

object | null

required

Aggregate record counts and files written across all steps. null if the job has not finished.

Show summary fields

summary.totalRecords

number

required

Total records processed across all tables.

summary.successRecords

number

required

Records written successfully.

summary.skippedRecords

number

required

Records skipped (e.g. missing required fields).

summary.failedRecords

number

required

Records that failed to process.

summary.locationCount

number

Number of location records written (populated when locations table is included).

summary.storyCount

number

Number of story records written (populated when stories table is included).

summary.filesWritten

string[]

required

Relative paths of every JSON file updated by this job.

warnings

string[]

required

Aggregated non-fatal warning messages from all steps.

errors

string[]

required

Aggregated error messages from all steps.

curl example

curl -X GET "https://himematsu.cn/api/admin/sync/jobs?limit=10" \
  --cookie "admin_auth=<YOUR_SESSION_COOKIE>"

POST /api/admin/sync/jobs

Creates a new sync job and immediately queues it for background execution. The response is returned as soon as the job is queued — before any Feishu API calls are made. Authentication: admin_auth cookie required.

Request body

kind

SyncJobKind

Job type. Defaults to the value from the scheduler configuration. Currently the only accepted value is "sync-data".

tables

SyncTableKey[]

Which tables to sync in this job. Defaults to config.defaultTables when omitted. Cannot be an empty array.

dependencyMode

DependencyMode

default:"read_local"

Controls how tables that other selected tables depend on are handled. See the DependencyMode enum above.

includeAssets

boolean

default:"true"

When true, attachment files are downloaded and their OSS URLs are back-filled into the output JSON.

continueOnTableError

boolean

default:"false"

When true, a failure in one table step does not abort the remaining steps.

triggeredBy

string

default:"admin-ui"

A free-form label identifying the caller. Stored in the job record for auditing.

note

string

Optional human-readable note stored with the job record (e.g. "手动刷新首页内容").

Responses

202 Accepted — Job was queued successfully.

{
  "jobId": "sync_20260430100000_ab12cd",
  "status": "queued",
  "kind": "sync-data",
  "tables": ["locations", "stories"],
  "effectiveTables": ["locations", "stories"],
  "createdAt": "2026-04-30T10:00:00.000Z"
}

409 Conflict — Another sync job is already running. Wait for it to finish before creating a new one.

{
  "message": "已有同步任务正在执行",
  "currentJobId": "sync_20260430095900_xy99zz"
}

400 Bad Request — One or more table keys are not valid SyncTableKey values.

{ "message": "不支持的同步表: unknown_table" }

curl example

curl -X POST https://himematsu.cn/api/admin/sync/jobs \
  --cookie "admin_auth=<YOUR_SESSION_COOKIE>" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": ["locations", "stories"],
    "dependencyMode": "read_local",
    "includeAssets": true,
    "note": "手动刷新首页内容"
  }'

GET /api/admin/sync/jobs/:jobId

Returns the full SyncJobRecord for a single job, including the expanded steps array with per-table results. Authentication: admin_auth cookie required.

Path parameters

jobId

string

required

The job identifier returned when the job was created. Format: sync_{YYYYMMDDHHmmss}_{random6} (e.g. sync_20260430100000_ab12cd).

Response fields

The top-level object matches the SyncJobRecord shape described under GET /api/admin/sync/jobs. The steps array is always fully expanded here.

steps

SyncJobStep[]

required

One entry per table included in the job.

Show SyncJobStep fields

step

string

required

The SyncTableKey this step processed (e.g. "locations").

status

SyncStepStatus

required

Execution status of this individual step.

startedAt

string | null

required

ISO 8601 timestamp when this step began. null if not yet started.

finishedAt

string | null

required

ISO 8601 timestamp when this step finished. null if not yet finished.

summary

object | null

required

Record counts and output files for this step.

Show step summary fields

summary.totalRecords

number

required

Records fetched from Feishu for this table.

summary.successRecords

number

required

Records written successfully.

summary.skippedRecords

number

required

Records skipped due to missing fields or filters.

summary.failedRecords

number

required

Records that failed to process.

summary.filesWritten

string[]

required

Output files updated by this step.

warnings

string[]

required

Non-fatal warnings for this step (e.g. missing optional fields on individual records).

errors

string[]

required

Error messages for this step.

Example response

{
  "jobId": "sync_20260430100000_ab12cd",
  "kind": "sync-data",
  "status": "success",
  "tables": ["locations", "stories"],
  "effectiveTables": ["locations", "stories"],
  "dependencyMode": "read_local",
  "includeAssets": true,
  "continueOnTableError": false,
  "triggeredBy": "admin-ui",
  "note": "",
  "createdAt": "2026-04-30T10:00:00.000Z",
  "startedAt": "2026-04-30T10:00:00.200Z",
  "syncedAt": "2026-04-30T10:01:30.000Z",
  "finishedAt": "2026-04-30T10:01:30.000Z",
  "durationMs": 90000,
  "steps": [
    {
      "step": "locations",
      "status": "success",
      "startedAt": "2026-04-30T10:00:00.500Z",
      "finishedAt": "2026-04-30T10:00:45.000Z",
      "summary": {
        "totalRecords": 5,
        "successRecords": 5,
        "skippedRecords": 0,
        "failedRecords": 0,
        "filesWritten": ["src/config/locations.json"]
      },
      "warnings": [],
      "errors": []
    },
    {
      "step": "stories",
      "status": "success_with_warnings",
      "startedAt": "2026-04-30T10:00:45.000Z",
      "finishedAt": "2026-04-30T10:01:30.000Z",
      "summary": {
        "totalRecords": 7,
        "successRecords": 6,
        "skippedRecords": 0,
        "failedRecords": 1,
        "filesWritten": ["src/data/content.json"]
      },
      "warnings": ["记录 recXXX 缺少主图，已跳过图片处理"],
      "errors": []
    }
  ],
  "summary": {
    "totalRecords": 12,
    "successRecords": 11,
    "skippedRecords": 0,
    "failedRecords": 1,
    "locationCount": 5,
    "storyCount": 6,
    "filesWritten": [
      "src/config/locations.json",
      "src/data/content.json"
    ]
  },
  "warnings": ["记录 recXXX 缺少主图，已跳过图片处理"],
  "errors": []
}

404 Not Found — No job exists with the given ID.

{ "message": "Not found" }

curl example

curl -X GET https://himematsu.cn/api/admin/sync/jobs/sync_20260430100000_ab12cd \
  --cookie "admin_auth=<YOUR_SESSION_COOKIE>"

GET /api/admin/sync/jobs/:jobId/logs

Returns the tail of the raw execution log for a job. Up to the last 200 lines are returned. For a job that is still running, polling this endpoint lets you observe progress in real time. Authentication: admin_auth cookie required.

Path parameters

jobId

string

required

The job identifier. Format: sync_{YYYYMMDDHHmmss}_{random6}.

Response fields

lines

string[]

required

The last up-to-200 log lines for the job. Each line includes a timestamp and step prefix, e.g. "[2026-04-30T10:00:01.000Z] [locations] 获取飞书 token 成功". Empty array when no log file exists yet.

total

number

required

Total number of lines in the full log file. Useful for detecting whether lines were truncated. 0 when no log file exists.

Example responses

With log data:

{
  "lines": [
    "[2026-04-30T10:00:00.500Z] [locations] 开始同步...",
    "[2026-04-30T10:00:01.000Z] [locations] 获取飞书 token 成功",
    "[2026-04-30T10:00:45.000Z] [locations] 完成，写入 src/config/locations.json"
  ],
  "total": 156
}

No log file yet (job still queued):

{ "lines": [], "total": 0 }

404 Not Found — No job exists with the given ID.

{ "message": "Not found" }

curl example

curl -X GET https://himematsu.cn/api/admin/sync/jobs/sync_20260430100000_ab12cd/logs \
  --cookie "admin_auth=<YOUR_SESSION_COOKIE>"

Overview

Admin API

Frontend API

Sync Job Management — Admin API | HNU-TimeLetter

Enum reference

SyncJobKind

SyncJobStatus

SyncStepStatus

DependencyMode

GET /api/admin/sync/jobs

Query parameters

Response fields

curl example

POST /api/admin/sync/jobs

Request body

Responses

curl example

GET /api/admin/sync/jobs/:jobId

Path parameters

Response fields

Example response

curl example

GET /api/admin/sync/jobs/:jobId/logs

Path parameters

Response fields

Example responses

curl example

Build docs developers (and LLMs) love

Overview

Admin API

Frontend API

Documentation Index

​Enum reference

​SyncJobKind

​SyncJobStatus

​SyncStepStatus

​DependencyMode

​GET /api/admin/sync/jobs

​Query parameters

​Response fields

​curl example

​POST /api/admin/sync/jobs

​Request body

​Responses

​curl example

​GET /api/admin/sync/jobs/:jobId

​Path parameters

​Response fields

​Example response

​curl example

​GET /api/admin/sync/jobs/:jobId/logs

​Path parameters

​Response fields

​Example responses

​curl example

Build docs developers (and LLMs) love

Enum reference

SyncJobKind

SyncJobStatus

SyncStepStatus

DependencyMode

GET /api/admin/sync/jobs

Query parameters

Response fields

curl example

POST /api/admin/sync/jobs

Request body

Responses

curl example

GET /api/admin/sync/jobs/:jobId

Path parameters

Response fields

Example response

curl example

GET /api/admin/sync/jobs/:jobId/logs

Path parameters

Response fields

Example responses

curl example