Skip to main content

命名约定：Sequence/Scene vs Episode/Frame

完整权威规范见仓库 docs/naming-conventions.md（2026-05-11 生效）。本页是精简版，写任何代码前必须读懂。

代码库存在一处命名分裂，你必须先理解再动手：

层命名例
User-facing（UI / 路由 / API endpoint）Sequence / SceneGET /api/v1/projects/:pid/sequences/:sid/scenes/:scid
Data layer（Firestore / 内部变量 / 文件名）Episode / Frameprojects/{pid}/episodes/{eid}/frames/{fid}

它们是同一实体。Sequence === Episode，Scene === Frame。 数据层未重命名，是因为迁移 Firestore 子集合成本不可接受（Phase 6 已永久取消）。

实体层级​

Project  >  Sequence  >  Scene  >  Shot
(项目)      (序列)       (场景)     (镜头)

必须 ✅​

  • 新代码用 sequencesApi / scenesApi（不是 episodesApi / framesApi）。
  • 新类型用 Sequence / Scene（类型别名已存在）。
  • 新路由用 /sequences/.../scenes/。
  • 新后端 endpoint 注册在 /sequences / /scenes 下。
  • 所有 user-visible 文本走 t() i18n，不硬编码英文。
  • Firestore 读写仍用 projects/{pid}/episodes/{eid}/frames/{fid}（这是对的！）。

禁止 ⛔​

  • 新建 sequences / scenes Firestore collection（它们不存在）。
  • 修改现有 Firestore 路径试图统一命名。
  • UI / 错误信息 / toast 中露出 "Episode" / "Frame" 字样。
  • 重命名现有 episode / frame 内部变量、文件、组件、hook（除非任务明确要求）。

i18n key 的特例​

i18n 的 key 名保留旧词（episodeSettings、sidebar.episodes），因为 key 是内部标识、用户看不到；只有 value 必须用 Sequence/Scene。

t('sidebar.episodes')   // key 用 episodes，value 是 "Sequences"

校验​

pnpm lint:naming 会校验这些规则，并已随 root pnpm lint 接入 CI（详见分支与部署）。

常见错误​

  • ❌ collection(db, 'projects', pid, 'sequences') → ✅ 查 episodes。
  • ❌ toast.success('Episode created!') → ✅ t('sidebar.newEpisode')（value: "New Sequence"）。
  • ❌ 新代码用 episodesApi.list() → ✅ sequencesApi.list()。
  • ❌ 把现有文件 EpisodeFramesPage.tsx 改名 → ✅ 保持不动，仅新文件用新命名。