Files

159 lines
25 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 项目协作规范
## 默认分支与工作目录
- 新增功能、新增文件、修复问题和重构,默认全部在本项目根目录的 `dev` 分支进行。
- 开始修改前先确认当前分支。若不在 `dev`,应保留现有修改并安全切换到 `dev`,不得丢弃或覆盖用户已有工作。
- 不创建新的 Git worktree,不在 `worktree`、`worktrees`、`.worktree` 或 `.worktrees` 目录中新增或修改文件。
- 不因技能、模板或默认隔离流程而创建工作树;本规则覆盖此前“新功能在 worktree 中开发”的项目约定。
- 已有工作树仅在用户要求迁回改动时作为只读来源;迁回后在项目根目录的 `dev` 分支继续修改和验证。
- 未经用户明确要求,不提交代码、不推送、不切换或合并到其他发布分支。
## 开发与验证
- 尽量使用中文沟通,沿用项目现有的 Vue 3、TypeScript、Tailwind CSS 和 pnpm 约定。
- 新增或修改的函数、类型、响应式状态及页面模块需要中文注释;函数有参数或返回值时补充 `@param`、`@returns`。
- 无参数、无返回值的函数使用 `/** 描述 */`;类型及其字段分别注释,`ref`、`computed`、`defineProps`、`defineEmits` 等也要说明用途;Vue 模板中的功能模块之间换行并添加中文模块注释。
- 超过两个位置使用的相同功能或组件,应抽成公共方法或组件。
- 页面和交互验证使用本地 Chrome,地址使用 `localhost`,禁止使用 Playwright;已有对应测试标签页时复用它。
- 以真实接口和后端契约为准,不用占位数据或其他功能代替缺失能力。
- 根据后端新增或重构前端功能前,先核对真实路由、请求参数、返回结果、服务逻辑和接口文档;不能只补类型而遗漏页面流程。缺少契约且无法确认时明确说明,不猜测或用其他功能代替。
- 提交代码时遵循项目的 Conventional Commits 规范,使用中文描述;提交前先检查实际差异。
## 全局页面与交互规范
以下规则是用户长期确认的项目要求,适用于后续所有新增、修改和重构的页面、弹窗及抽屉。换窗口后也应直接沿用,不等待用户再次指出同类问题。
### 整体协调与公共实现
- 修改前先查看所在完整页面、相邻模块及已有公共组件,同时考虑整体协调、元素间距和功能一致性,不能只修改截图中的一个局部而忽略其他状态。
- 同类布局、按钮、状态色、关闭入口和交互流程保持一致;发现本次改动涉及的同类问题时,一并修正相关公共组件或当前功能中的使用位置。
- 优先复用 `src/components/ui` 中的公共组件、`src/styles/admin.css` 中的设计变量和现有主题配置;公共问题在公共层解决,避免各页面重复覆盖或硬编码颜色、尺寸。
- 所有折叠、展开和历史详情区域统一使用 Naive UI 的 `NCollapse`、`NCollapseItem` 等组件,不再使用原生 `details`、`summary` 或自制折叠控件;修改同类区域时同步统一现有实现。
- 维持项目现有简洁、扁平的视觉风格。用标题、简短说明、留白和对齐区分普通功能区域,避免无意义的底色、边框和装饰线。
- 页面文案保持精简,说明应帮助用户理解当前操作;不把大量错误、技术细节和重复提示堆在设置页面。
### 面向普通用户的文案
- 默认使用者不了解软件开发。页面、弹窗、按钮、说明、校验、空状态和错误提示不得直接描述“前端做什么”“后端做什么”,应说明当前结果、影响和下一步操作。
- 英文技术术语优先改成易懂的中文,例如 `Checkpoint` 用“保存记录”、`Storyboard` 用“分镜”、`Prompt` 用“画面描述”或“提示词”、`Thinking` 用“深度思考”。不要把内部字段名、错误码、任务标识直接作为主要说明。
- 接口返回的系统提示也需要在展示层转换为可读中文;错误详情只提取有助于操作的业务原因,不把调试对象、堆栈或整段原始数据直接输出给用户。原始错误和错误码保留在数据层,不改动业务判断依据。
- 只调整展示文案,不翻译或改写请求字段、枚举值、接口地址、用户创作的剧本与提示词正文、文件名、自定义名称或模型品牌。分类等内部值使用中文选项展示,提交仍保留真实取值。
- 用短句直说结果和下一步。同一个意思只写一次;标题和按钮已说明用途时,删掉重复说明。提示一行能说清就不写成段落,必需的限制和费用信息要保留。
- 导航只显示名称。禁用原因放到可通过悬停和键盘聚焦查看的提示里,菜单行高保持一致。
- 问题提示放在能直接处理它的页面。素材图库不常驻展示下游镜头的生产警告和列表;从镜头主动定位素材时,只保留定位所需的信息与返回入口。普通浏览不发仅供该定位使用的全项目检查请求。
- 费用、覆盖、删除、适用范围与待审核限制必须保留并说清楚,不能为了简化文字改变功能含义。无法确认的能力不要用容易误解的描述代替。
- 日常操作先展示中文业务摘要;排查用的原始技术数据保留在数据层、专用排查入口或显式导出中,不能仅以“高级详情”为名把整段接口响应搬进普通弹窗。同一弹窗的操作统一放入公共 `footer`,避免正文操作与默认关闭按钮重复。
- 所有页面、弹窗和抽屉首屏优先显示当前结果、待处理事项、主要输入和操作;流程解释与历史长说明放到 info、二级详情或默认收起的区域。普通详情也只展示明确需要的中文业务字段,不展示无助于决策的接口对象、整段 JSON、内部字段、任务编号或指纹;不能因为接口返回某个字段就把它加入界面。费用、来源冲突、覆盖和正式采用限制仍须在操作处清楚显示。
- 重要内容较多时复用主题中的中性背景分组,区分当前事实、规划和操作风险;背景不能暗示尚未取得的审核通过。
### 全屏抽屉与关闭入口
- 新建剧本、项目全局配置、拆解设置、拆解问题等已确认使用全屏的界面统一复用 `AppDrawer`。后续同类复杂表单、设置和问题处理界面默认沿用全屏抽屉;简短确认或轻量提示仍可使用 `AppDialog`。
- 全屏必须同时覆盖容器与正文:内容使用可用的完整宽度,不能只把外壳放大而保留原弹窗的固定宽度或居中最大宽度。
- 标题区和底部操作区固定,只有正文独立滚动。长内容不能把关闭或提交按钮挤出视口,也不能产生页面与抽屉重复滚动。
- PC和移动端弹窗、抽屉的头部与底部均不使用border分隔正文;footer不使用box-shadow,header默认也不显示阴影,仅当正文向下滚动、顶部有内容被遮挡时显示更淡的主题阴影,回到顶部即隐藏。监听实际正文滚动容器,重新打开时清除旧状态;保持固定区域的背景和堆叠顺序,阴影不能遮挡正文或交互入口。
- 手机端公共弹窗与全屏抽屉统一复用底部浮动面板,顶部横条支持按住向下拖动关闭,仅手柄区域接收关闭手势,正文正常滚动。轻触、短拖及取消手势保持展开;保留关闭按钮和键盘入口,提交期间包括拖动在内的关闭方式均须锁定,切换布局或重新打开时清除旧手势状态。
- 底部浮动面板沿用项目直角样式,顶部不增加border-radius;只有正文滚动后的header使用淡阴影,footer保持无阴影、无分隔边框。
- 移动端弹窗和抽屉的footer按钮需占满内容宽度:单个按钮铺满整行,多个按钮等宽分配并铺满每一行,中间仅保留统一的小间隙;长标签宽度不足时允许按钮换行。复用公共底栏样式,保留按钮文字及提交锁;PC端保持原底栏布局。
- PC和移动端公共弹层footer按钮高度统一为组件原始 `--n-height` 的1.2倍,字号保持原样;复用公共CSS,不在业务页面再次叠加放大。
- 抽屉标题、说明、正文和底栏左右边界统一。复用公共抽屉的桌面、移动端内边距;正文 `padding-top` 保持为 `0`,不要额外叠加顶部空白。
- PC和移动端弹窗、抽屉的header标题最多显示一行,超出可用宽度以省略号显示;复用 `app-panel-title`,完整标题保留在原文、可访问名称及title提示中。标题可收缩,状态图标、说明入口和关闭按钮保持可见;副标题与正文继续按各自规则展示。
- 所有弹窗和抽屉底部至少保留一个可见的“关闭”或“取消”按钮,不能只有右上角叉号。底部操作使用公共组件的 `footer` 插槽,避免正文末尾再放一套底栏或重复关闭按钮。
- 关闭、取消统一为灰色底面和中性文字的普通按钮,不使用绿色主按钮;右上角关闭图标的尺寸、底色与交互反馈也统一复用公共样式。
- 提交期间按真实业务状态防止重复操作及意外关闭;普通只读加载不能无故阻止用户关闭。关闭、切换或定位后,不回填已失效的异步结果。
### 布局、说明与间距
- 页面外边距、模块间距优先复用 `--app-content-padding`、`--app-content-gap`;表单与抽屉内部复用对应公共组件的间距,不在各页面随意添加不同数值。
- 区分功能组间距与组内间距:未使用交替底面的独立功能组可复用 `workspace-section-stack-spacious`(两倍模块间距),组内复用普通模块间距;字段之间使用 `workspace-form-stack` 的16px,标签到控件为8px。同类区域只能使用同一套间距,不叠加默认 margin、padding 和 gap,也不把每个按钮都当成独立大分区。
- 同级折叠列表复用 `workspace-collapse`,收起时统一44px行高;首项、后续项及相邻折叠组不能因组件默认样式出现忽大忽小的空白。展开正文统一内边距,仍保留完整内容和输入状态。
- **表单字段间距为强制要求**:页面、弹窗、抽屉中的标签不能紧贴输入框、下拉框或选择组;自定义字段默认使用 `--app-field-label-gap`(8px),相邻字段默认使用 `--app-field-gap`(16px)。紧凑布局和移动端也不得取消这些必要间距,除非用户明确要求调整。
- 自定义的“标签 + 控件”优先复用 `src/styles/admin.css` 中的 `workspace-form-field`,使用真实的纵向 Flex/Grid `gap`;成熟表单继续复用 `AppForm` / `NFormItem` 的公共排版。禁止仅给行内 `span` 套 `space-y-*` 或垂直 margin 后,就认定标签间距已经生效。
- 修改表单布局时必须核对同模块的全部同类字段,保证同排标签、控件分别对齐;图片与表单并排时,图片标题和字段标签必须复用同一纵向间距值,图片与首排控件的上沿必须对齐;在本地 Chrome 检查桌面、窄屏及必要的加载/校验状态,确认实际留白生效后才算完成。
- 同级模块使用一致的标题、说明、字段间距和上下留白。需要说明时采用“模块标题 + 一句简短说明”,例如画布设置、图片配置、视频配置、动作与物理规则;优先复用 `WorkspaceSectionHeading`。
- 页面、弹窗和抽屉中的同级模块共用左右边界。普通分区直接对齐;需要突出一组内容时,优先用已有的中性背景包住整组内容。背景外沿与相邻模块对齐,组内使用统一内边距,避免透明容器单独缩进。
- 新建剧本等长表单默认每个字段单独占一行并铺满内容宽度;不因改成全屏就自动把原来的字段挤成两列。
- 图片、视频等已有明确分组的并列模块可以保留协调的分栏,窄屏改为单列;同一行的标签、控件及操作必须分别对齐,不能因说明或校验消息出现而上下错位。
- 行内按钮按输入控件本身的基线对齐,不能按包含标签的整块区域垂直居中。动态例外行中的移除按钮与输入框底部对齐,使用 `Trash2` 等现有图标,不再显示“移除”文字,并提供可访问名称。
- 项目生成配置等普通表单分区不铺大块背景色,使用标题、说明和统一间距组织;常规错误沿用中性底色,只有明确的严重错误或通过检查的成功状态才使用对应状态底色。
### 长文本与多功能块布局(默认模板)
- **适用范围**:后续新增或优化页面、弹窗、抽屉时,遇到多段长文本与状态、历史、编辑、预览或确认操作混排,默认沿用当前摄影草案审核的布局;适用于全项目同类界面,不限于分镜或摄影功能。简单提示、短表单及单一剧本正文继续使用适合其内容的简洁布局。
- **先按功能分组**:将概况、正式内容与历史、编辑、差异、预览和确认等实际存在的功能分别组织成块。首屏突出主要信息与操作,历史和次要说明按需展开;相关按钮、状态和说明归入对应功能块。
- **统一序标标题**:独立功能块使用“罗马数字 I、II、III… + 标题”,复用 `WorkspaceSectionHeading` 的 `marker`。按可见块依次编号,条件区域隐藏时不跳号;字段、普通说明及嵌套详情不重复编号。序标仅表示阅读顺序,执行进度、质量与费用状态仍分别表达。
- **统一交替底色**:外层复用 `workspace-section-stack workspace-numbered-sections`,每块复用 `workspace-numbered-section`。两种中性底色均须与页面或弹窗背景区分,同时保持输入控件清晰可辨。功能块连续排列,块间不留额外 gap、margin 或装饰线,以底色表达边界。
- **同级严格对齐**:所有功能块使用相同内边距,序标、标题和同类正文各自共用左边线。标题与正文放在同一个功能块内,不因某块另套卡片而单独缩进。桌面块内边距20px,手机复用 `--app-content-padding`;正文避免再嵌套一层同色背景和重复内边距。
- **块内保持阅读间距**:去掉的是功能块之间的额外空白。组内说明与操作沿用公共模块间距;字段复用 `workspace-form-stack` 的16px,标签到控件保留8px。折叠列表复用 `workspace-collapse`,统一44px收起行高及展开正文间距。普通辅助按钮保持就地宽度,避免拉伸为整条灰色区域。
- **控制长文行宽与高度**:关联的长文编辑字段可在宽屏分栏、窄屏单列,标签和控件上沿对齐;列内字段间距不受另一列内容高度影响。复用 `workspace-prose-input` 的字号和行距、有界自动高度及必要的内部滚动,完整原文保持可查看、可编辑,不裁剪或改写创作内容。
- **复用与验收**:优先参考 `ShotDerivedReview.vue`、`JointDraftReviewPanel.vue` 及公共样式增量实现。保留原有历史、来源、费用和确认条件;在本地 Chrome 核对桌面、手机、长内容、折叠展开、序号变化、标题对齐、交替底色、内容滚动和固定底栏后交付。
### 图片列表与详情浮层
- 图片列表使用可用内容宽度,复用公共网格;不能因固定最大宽度在大屏右侧留下整片可利用的空白。图片以紧凑缩略图展示,少量图片不无限拉伸成巨图;窄屏按可用宽度调整列数。
- 同一图片列表的卡片高度一致,操作区对齐。长名称、模型名、历史错误和说明不能撑高某一项;完整信息仍可通过详情查看,不能为了等高截掉必要内容。
- 图片卡片的信息顺序统一为“图片 → 状态标签 → 图片名称 → 日期时间 → 操作”。名称必须可识别,不能只显示日期;无独立名称时可使用镜头名称和稳定展示序号,不覆盖用户名称或写回资产。
- 标签放在名称上方,标签、名称和操作之间保持紧凑且一致的间距;不要为未出现的第二行标签预留空白。卡片等高依靠网格与操作区对齐,不依靠给短内容增加大块空白。
- 列表先展示主要状态与名称;尺寸、型号、完整历史、可修复错误和技术说明放在 info 或二级详情。影响当前执行的费用风险、来源冲突和采用限制仍在对应操作处显示,不能全部藏进图标。
- 弹窗、抽屉和滚动区域中的提示及详情浮层必须避开容器裁切:优先复用公共组件,Naive UI `NPopover` 明确使用 `:to="true"` 挂到页面浮层,并启用边缘自动翻转;不能只提高 `z-index` 掩盖父容器的 `overflow` 问题。
- 浮层宽度不得超出当前视口,计入内边距并保留屏幕边距。长模型名、连续字符和长说明必须换行;长详情限制高度并允许内部滚动,不能横向裁切正文或遮住必要操作。
- 同一按钮的详情打开后,停用重复的悬浮操作说明,避免提示覆盖详情标题或正文;保留按钮的可访问名称与键盘操作。信息浮层不能触发生成、保存、审核或采用。
### 按钮、图标与状态颜色
- 绿色背景、白色文字用于保存、提交、开始生成等主要执行操作;关闭、取消和普通辅助操作使用中性样式。
- 普通请求失败、表单校验、审核未通过和可修复问题默认使用中性底面,配合短文字、图标或细线提示。红色底面只用于明确需要立即关注的严重错误,例如任务中断且可能重复计费。保留深浅主题对应的柔和状态色。
- 普通镜头定位使用中性提示。从明确问题定位时,可加细线标记;正文刷新后清除旧标记。
- 错误入口按钮使用中性底面,文字、图标和焦点保留错误语义。默认、悬停、按下和聚焦时保持清晰的键盘焦点与状态反馈。
- 只有执行完成且结果明确通过校验时,成功任务区域才使用柔和浅绿背景。执行结束但校验失败、质量待审或结果未确认时,不能显示成绿色成功状态,也不能用满格绿色进度条暗示业务成功。
- 卡片内的定位、复查、修订和历史入口使用带图标、独立中性底面的按钮,不添加边框,不能与说明文字混在一起;复用 `workspace-action-button` / `workspace-action-group`,不把辅助操作改成绿色主按钮。
- 工具栏中相邻按钮保持一致的高度、内边距、图标大小和间距。问题入口使用图标加文字;分镜结构校验失败时文案为“分镜校验未通过”,其他问题按真实类型命名。
- 移动端的工具栏操作优先只显示图标,保留完整的 `aria-label`、提示文本和足够点击区域;普通表单的底部关闭、取消、提交按钮仍保留文字。
- 仅显示单个图标的操作按钮统一使用正方形,图标居中,并使用 Naive UI `NPopover` 展示完整操作名称;优先复用 `WorkspaceActionTooltip`,保留对应 `aria-label`,相邻按钮尺寸和间距一致。
- 按钮已显示完整文字时,不再重复添加同名悬浮提示;桌面有文字、移动端仅图标的响应式按钮,仅在隐藏文字的屏幕尺寸下启用 `NPopover`。桌面仍为纯图标的按钮继续保留提示。
- 诊断结果卡片的定位、可选 AI 复查、修订及历史按钮在移动端也保留图标和完整文字,宽度不足时自动换行,不套用顶部工具栏仅显示图标的规则。
- 页面左侧汇总状态在运行、成功、失败等状态下均有意义,应保留;右侧操作入口负责打开对应处理界面,避免把状态展示和操作混成重复文案。
### 设置、问题处理与任务进度
- 拆解设置与问题处理分开:设置界面负责模块选择、分组预览、启动拆解、候选确认与提交;问题界面负责错误查看、分镜定位、人工修订、读取修复清单及阶段恢复。
- 普通目录浏览不增加无必要的勾选框;多选只在用户主动进入的批量操作中提供。进入页面或刷新时不自动弹出生成配置,不自动提交生成;配置由明确的操作入口打开。
- 质量规则确认以服务端 revision、fingerprint、confirmed 和独立 confirm 接口为准,不能用 LocalStorage 或格式版本 policy.version 代替。规则保存携带 expectedRevision,拆解启动携带本次已确认修订;候选提交预检查必须包含 qualityPolicyMatches。
- 首次拆解前只确认表现方式、动作许可和自定义规则,不显示精确动作例外的空白编辑行。已有例外可只读核对,隐藏输入不能清空已有规则或在保存时覆盖后来新增的例外。
- 新增精确动作例外统一放在拆解后的问题修订中,从当前版本的真实冲突证据自动带入角色、部位或物品及动作,用户填写允许原因。证据缺失时不能猜测或用其他镜头代替;按后端实际范围说明影响,保存例外不能直接标记质量通过。
- 不在拆解设置中重复堆放详细错误列表和修复说明;问题按剧集、节拍、镜头分组并去重,保留后端原始问题及可定位位置。
- 从问题界面定位正文时,先关闭抽屉,等离场和焦点约束释放后再定位,不能同时叠加两个主界面。
- 后端从其他入口启动或重新执行任务时,前端也应发现任务并显示真实运行阶段、进度、作用范围及更新时间;重新进入页面后能够恢复观察,不能只依赖前端本次点击形成的加载状态。
- 执行状态与质量校验结果分别表达,不能把“执行完成”直接等同于“校验通过”;没有真实进度或结果时明确显示待确认,不伪造百分比。
- 已修订且当前审核通过的镜头,不因未运行或过期的独立 AI 诊断再次列为“需处理”。AI 复查单独作为可选项,只有当前明确冲突或实时结构化问题才提示修复;复查入口受限不能直接解释为正式分镜需要重拆。
- 默认收起的“高级检查详情”只保留必要的检查记录和当前复查范围,不再单独展示旧手部覆盖率或未填写手部记录;缺少记录使用中性说明,不作为错误,实际检出的动作冲突仍在普通问题区域展示。
- 拆解执行中暂不显示“查看诊断”等需要稳定结果的入口。问题可以只读查看,但人工修改、候选提交、修复和恢复操作应遵守真实活动任务锁,避免冲突。
- 拆解任务卡片与相邻模块采用统一边距和状态底色,必要的阶段、范围、进度和时间直接简洁展示;不要把重要信息只藏在“任务详情”折叠中,也不默认展示无助于操作的内部编号或原始数据。
### 表单校验与交互时机
- 打开表单、加载已有配置或添加一条空白例外时,不立即展示红色校验错误。
- 点击保存、提交时再执行完整校验,阻止不完整请求;需要字段交互校验时,只在用户已操作该字段或已尝试提交后显示。
- 用户修改相关内容后及时清除或更新旧错误,不能让已经失效的提示长期挂在表单上。
- 必填标记、字段提示和错误信息保持统一位置与间距;删除行、增添行和错误出现时,操作按钮仍应与对应控件对齐。
### 页面验收
- 涉及页面或交互的改动,必须在已有本地 Chrome 标签页使用 `localhost` 验证后才算完成,不能只根据代码、构建或 DOM 测试声称布局通过。
- 验证本次改动涉及的桌面、移动端、长内容滚动、固定底栏及必要的加载、错误、成功状态;检查普通、悬停和键盘聚焦时的颜色、对齐与可访问名称。
- 页面模块之间复用公共间距;按钮、标题和辅助说明须有清晰留白。已有相邻页面使用骨架屏时,同类入口也应在项目加载和正文加载阶段预留相同结构。
- 骨架与图片占位默认静态显示,避免闪动。图库按真实卡片结构分别预留图片、文字和操作位置。
- 图片卡片在请求图片前就预留画面区域,优先用已有宽高,缺少宽高时使用稳定比例。检查慢速、加载失败和无图时卡片都不会塌陷。
- 图片列表及浮层验收需覆盖最左、最右和底部卡片、少量与多行图片、长名称和模型名、长错误、桌面与手机窄屏;确认详情不会被弹窗或滚动容器裁切,边缘避让、换行、滚动和提示互斥实际生效。
- 界面验收不得为了制造状态而触发真实付费生成、覆盖正式结果或提交用户数据;使用现有状态、只读操作和合适的自动化测试验证。
- 测试与检查按改动范围执行;纯文档变更无需启动页面或重复完整构建。报告时区分自动化检查与真实浏览器验证,并明确未完成项,不把尝试操作当作验收通过。
## 提交规范补充
- 仅用户明确要求“提交”时才提交,“提交并 push”才同时授权推送;不因界面修改完成而自动提交或推送。
- 提交前必须查看 `git diff --stat` 和 `git diff`,按实际文件与所属包确定提交类型及作用域;不根据用户描述猜测,也不覆盖已有无关改动。
- 提交类型仅使用 `feat`、`perf`、`fix`;中文描述用动词开头,简洁明确,提交信息不超过 50 个字符。
- 单包修改优先以 `package.json` 的 `name` 作为 scope;多个项目或公共基础设施改动可省略 scope,不用目录名代替包名。
- 不使用 `update`、`fix bug`、`修改代码`、`提交代码`、`test`、`wip`、`temp` 等含糊信息。