HNU-TimeLetter Data Model and Domain Types Reference

Feishu Bitable (CMS)
    │
    │  npm run sync  /  POST /api/admin/sync/jobs
    ▼
src/lib/sync/ (orchestrator + per-table modules)
    │  ├─ OSS upload pipeline (attachment → MD5 → OSS → back-fill URL)
    │  └─ JSON writer (*.tmp → validate → rename)
    ▼
src/data/*.json  +  src/config/locations.json  (build-time artifacts)
    │
    │  Runtime API routes (no-store)
    ▼
Frontend pages  (/, /map, /creation)
    │
    │  src/components/creation/utils.ts
    ▼
CreationCard aggregation (client-side, by CardID)

interface Character {
  id: string;        // Feishu field: 角色ID
  name: string;      // Feishu field: 角色名称
  avatarUrl: string; // Feishu field: 头像OSS_URL (back-filled by sync)
}

interface Story {
  id: string;           // Feishu record_id
  characterId: string;  // Feishu field: 角色ID
  characterName: string; // Injected from characters table at sync time
  avatarUrl: string;    // Injected from characters table at sync time
  mainImageUrl: string; // Feishu field: 大图OSS_URL (preferred) or 大图 attachment
  content: string;      // Feishu field: 故事内容
  author: string;       // Feishu field: 投稿人
  locationId: string;   // Feishu field: 地点ID
}

interface LocationPoint {
  id: string;       // e.g. "lib-001"
  name: string;     // e.g. "图书馆"
  x: number;        // SVG horizontal position, 0–100 (percentage)
  y: number;        // SVG vertical position, 0–100 (percentage)
  stories: Story[]; // All stories whose locationId === this id
}

interface CreationIdea {
  id: string;        // Feishu record_id
  cardId: string;    // Feishu: CardID → fallback: 自动编号 → fallback: record_id
  author: string;    // Feishu: 你的昵称 → fallback: 提交人
  submitter: string; // Feishu: 提交人 (raw Feishu identity — NOT exposed to frontend)
  tags: string;      // Feishu: 请选择你要添加的内容（…）
  content: string;   // Feishu: 文本 (also holds back-filled OSS URL in image scenarios)
  images: string[];  // Feishu: 请上传你的图片 (downloaded → uploaded to OSS)
  createdAt: string; // Feishu: 提交时间 (ISO 8601 string)
}

interface CreationEntry {
  id: string;        // CreationIdea.id
  cardId: string;    // CreationIdea.cardId
  author: string;    // CreationIdea.author (display alias)
  tags: string;      // CreationIdea.tags
  content: string;   // CreationIdea.content
  images: string[];  // CreationIdea.images (OSS URLs)
  createdAt: string; // CreationIdea.createdAt
}

interface CreationCard {
  id: string;              // The shared CardID value
  cardId: string;          // Same as id — kept explicit for clarity
  addIdeaUrl: string;      // "Add Idea" button deep-link (Feishu form URL)
  entries: CreationEntry[]; // All projected entries for this card, sorted by createdAt
}

interface Contributor {
  id: string;      // Feishu record_id
  name: string;    // Feishu: 姓名
  role?: string;   // Feishu: 职位 or 角色 (optional)
  message?: string; // Feishu: 留言 / 寄语 / 感言 (optional)
}

// src/lib/store.ts
interface AppState {
  // ── Envelope ceremony ──────────────────────────────────────
  isEnvelopeOpened: boolean;
  setEnvelopeOpened: (v: boolean) => void;

  // ── Full-screen transition overlay ─────────────────────────
  isTransitioning: boolean;
  setTransitioning: (v: boolean) => void;

  // ── Map experience — location pin selection ─────────────────
  selectedLocationId: string | null;
  setSelectedLocationId: (id: string | null) => void;

  // ── Story reader — current card in the stack ────────────────
  currentStoryIndex: number;
  setCurrentStoryIndex: (i: number) => void;
}