17 KiB
17 KiB
项目协作规范
默认分支与工作目录
- 新增功能、新增文件、修复问题和重构,默认全部在本项目根目录的
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,避免正文操作与默认关闭按钮重复。
全屏抽屉与关闭入口
- 新建剧本、项目全局配置、拆解设置、拆解问题等已确认使用全屏的界面统一复用
AppDrawer。后续同类复杂表单、设置和问题处理界面默认沿用全屏抽屉;简短确认或轻量提示仍可使用AppDialog。 - 全屏必须同时覆盖容器与正文:内容使用可用的完整宽度,不能只把外壳放大而保留原弹窗的固定宽度或居中最大宽度。
- 标题区和底部操作区固定,只有正文独立滚动。长内容不能把关闭或提交按钮挤出视口,也不能产生页面与抽屉重复滚动。
- 抽屉标题、说明、正文和底栏左右边界统一。复用公共抽屉的桌面、移动端内边距;正文
padding-top保持为0,不要额外叠加顶部空白。 - 所有弹窗和抽屉底部至少保留一个可见的“关闭”或“取消”按钮,不能只有右上角叉号。底部操作使用公共组件的
footer插槽,避免正文末尾再放一套底栏或重复关闭按钮。 - 关闭、取消统一为灰色底面和中性文字的普通按钮,不使用绿色主按钮;右上角关闭图标的尺寸、底色与交互反馈也统一复用公共样式。
- 提交期间按真实业务状态防止重复操作及意外关闭;普通只读加载不能无故阻止用户关闭。关闭、切换或定位后,不回填已失效的异步结果。
布局、说明与间距
- 页面外边距、模块间距优先复用
--app-content-padding、--app-content-gap;表单与抽屉内部复用对应公共组件的间距,不在各页面随意添加不同数值。 - 表单字段间距为强制要求:页面、弹窗、抽屉中的标签不能紧贴输入框、下拉框或选择组;自定义字段默认使用
--app-field-label-gap(8px),相邻字段默认使用--app-field-gap(16px)。紧凑布局和移动端也不得取消这些必要间距,除非用户明确要求调整。 - 自定义的“标签 + 控件”优先复用
src/styles/admin.css中的workspace-form-field,使用真实的纵向 Flex/Gridgap;成熟表单继续复用AppForm/NFormItem的公共排版。禁止仅给行内span套space-y-*或垂直 margin 后,就认定标签间距已经生效。 - 修改表单布局时必须核对同模块的全部同类字段,保证同排标签、控件分别对齐;图片与表单并排时,图片标题和字段标签必须复用同一纵向间距值,图片与首排控件的上沿必须对齐;在本地 Chrome 检查桌面、窄屏及必要的加载/校验状态,确认实际留白生效后才算完成。
- 同级模块使用一致的标题、说明、字段间距和上下留白。需要说明时采用“模块标题 + 一句简短说明”,例如画布设置、图片配置、视频配置、动作与物理规则;优先复用
WorkspaceSectionHeading。 - 页面、弹窗和抽屉中的同级模块共用左右边界。普通分区直接对齐;需要突出一组内容时,优先用已有的中性背景包住整组内容。背景外沿与相邻模块对齐,组内使用统一内边距,避免透明容器单独缩进。
- 新建剧本等长表单默认每个字段单独占一行并铺满内容宽度;不因改成全屏就自动把原来的字段挤成两列。
- 图片、视频等已有明确分组的并列模块可以保留协调的分栏,窄屏改为单列;同一行的标签、控件及操作必须分别对齐,不能因说明或校验消息出现而上下错位。
- 行内按钮按输入控件本身的基线对齐,不能按包含标签的整块区域垂直居中。动态例外行中的移除按钮与输入框底部对齐,使用
Trash2等现有图标,不再显示“移除”文字,并提供可访问名称。 - 项目生成配置等普通表单分区不铺大块背景色,使用标题、说明和统一间距组织;常规错误沿用中性底色,只有明确的严重错误或通过检查的成功状态才使用对应状态底色。
按钮、图标与状态颜色
- 绿色背景、白色文字用于保存、提交、开始生成等主要执行操作;关闭、取消和普通辅助操作使用中性样式。
- 普通请求失败、表单校验、审核未通过和可修复问题默认使用中性底面,配合短文字、图标或细线提示。红色底面只用于明确需要立即关注的严重错误,例如任务中断且可能重复计费。保留深浅主题对应的柔和状态色。
- 普通镜头定位使用中性提示。从明确问题定位时,可加细线标记;正文刷新后清除旧标记。
- 错误入口按钮使用中性底面,文字、图标和焦点保留错误语义。默认、悬停、按下和聚焦时保持清晰的键盘焦点与状态反馈。
- 只有执行完成且结果明确通过校验时,成功任务区域才使用柔和浅绿背景。执行结束但校验失败、质量待审或结果未确认时,不能显示成绿色成功状态,也不能用满格绿色进度条暗示业务成功。
- 卡片内的定位、复查、修订和历史入口使用带图标、独立中性底面的按钮,不添加边框,不能与说明文字混在一起;复用
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等含糊信息。