Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HNU-himematsu/HNU-TimeLetter/llms.txt

Use this file to discover all available pages before exploring further.

The HNU-TimeLetter admin panel lives at /admin and provides a browser-based interface for all operational tasks: triggering Feishu data syncs, monitoring job execution, configuring the scheduler, browsing synced content, and managing the announcement popup. It is built into the Next.js application and does not require a separate service.

​
Accessing the Admin Panel

Navigate to https://your-domain.com/admin. Any request to a protected route under /admin automatically redirects to /admin/login if no valid session cookie is present.

​
Login

Enter the administrator password (configured via the ADMIN_PASSWORD environment variable). On success, the server sets an admin_auth HttpOnly cookie with a 7-day expiry and redirects to the dashboard.
After 5 consecutive failed login attempts, the account enters a 30-minute lockout. The login page displays the remaining cooldown seconds. The lockout resets automatically after the window expires — there is no manual override.

​
Logout

Click 退出登录 (Log Out) in the sidebar footer. This calls DELETE /api/admin/login, which clears the admin_auth cookie and redirects to the login page.

​
Dashboard (/admin/dashboard)

The dashboard is the primary operational view. It auto-refreshes every 5 seconds; you can also click the 刷新状态 (Refresh) button in the top-right corner. The dashboard has four sections:
SectionDescription
同步状态 (Sync Status)Shows the most recent job: ID, status, last-run timestamp
手动同步 (Manual Sync)Configure and trigger an immediate sync
定时任务配置 (Scheduler)Set the cron schedule and default tables
最近任务 (Recent Jobs)Paginated history with step details and log access

​
Manual Sync

1

Select tables to sync

In the 手动同步 card, check the tables you want to update:
KeySourceOutput File
locationsFeishu location tablesrc/config/locations.json
storiesFeishu stories tablesrc/data/content.json
creation_headersCreation board header tablesrc/data/creation-board-headers.json
creation_boardCreation board main tablesrc/data/creation-board.json
contributorsContributors tablesrc/data/contributors.json
Click 使用默认表 to restore the scheduler’s default table set, or 全选表 to select all five.
2

Choose dependency mode

Select how to handle tables that other tables depend on:
ModeBehavior
read_localUse existing local JSON for dependencies (default, fastest)
run_dependenciesAutomatically sync dependency tables first
strictFail immediately if any dependency is missing
3

Configure options

  • 包含附件 (Include Assets): When enabled, downloads Feishu attachments, uploads to OSS, and back-fills URLs. Disable for text-only updates to save time.
  • 单表失败时继续 (Continue on Table Error): When enabled, a failure in one table does not abort the remaining tables.
  • 备注 (Note): Optional label shown in the job history list (useful for auditing).
4

Trigger the sync

Click 同步数据 (Sync Data). The API returns 202 Accepted immediately with a jobId. The job runs asynchronously in the background.
Only one sync job can run at a time. If a job is already running, the button is disabled and shows the active jobId. Wait for the current job to finish before triggering a new one.

​
Scheduler Configuration

The scheduler uses node-schedule to trigger syncs automatically on a cron schedule.
The scheduler only works on self-hosted deployments where the Node.js process is long-lived (e.g. managed by PM2). It does not persist across Vercel serverless function invocations.
FieldDescription
启用 (Enabled)Toggle the scheduler on/off
Cron 表达式 (Cron Expression)Standard 5-segment cron (e.g. 0 2 * * * = 2 AM daily)
默认同步表 (Default Tables)Table keys synced on each scheduled run; cannot be empty
Configuration changes are applied immediately (hot-reload) — no restart required.

​
Job History and Logs

Click any job in the 最近任务 list to open its detail view. Each SyncJobRecord shows:
  • Job metadata: jobId, kind, status, triggeredBy, note, timestamps, total duration
  • Summary: totalRecords, successRecords, skippedRecords, failedRecords, filesWritten
  • Steps: per-table step records with individual status, timing, and summary
  • Warnings and errors: any per-record or per-step issues (e.g. missing attachments)

​
Viewing Raw Logs

Click 查看日志 (View Logs) on a job record to fetch the last 200 lines from the job’s log file. This is the fastest way to diagnose sync failures: 
[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
[2026-04-30T10:01:30.000Z] [stories] 记录 recXXX 缺少主图，已跳过图片处理
Log files are stored in the path configured by SYNC_LOG_DIR (default: logs/sync).

​
Announcement Configuration (/admin/announcement)

The announcement popup shown on the frontend reads its configuration from this page.
FieldDescription
文档链接 (docUrl)Feishu document URL embedded in the popup (cannot be an empty string)
功能配置 (featureConfig)JSON object for Feishu SDK feature flags (extensions key)
Click 保存 to persist changes. The public endpoint GET /api/announcement-config serves the updated config immediately — no sync or restart needed.

​
Content Viewer (/admin/content)

The content viewer at /admin/content reads the current JSON artifact files directly and displays them in a searchable, tabbed interface:
  • 地点与故事 tab: all LocationPoint entries with nested Story arrays
  • 创作公示板 tab: CreationIdea and CardHeaderInfo records
  • 鸣谢名单 tab: Contributor list
This is useful for quickly verifying that a sync produced the expected data without writing a custom script.
For fully automated real-time updates (e.g. when a community member submits a new creation board idea via Feishu form), configure Feishu Automation to POST to the sync webhook. This triggers a creation_board sync without any manual admin action, and the updated data is live as soon as the job completes.

Build docs developers (and LLMs) love

Get started for freeTalk to us