Files
lpt-fe/roles/code-standards.md
T

86 lines
7.6 KiB
Markdown
Raw 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.
# 前端代码标准
- **功能**:约束前端交互、按钮、颜色与主题、卡片列表、移动端、界面质量与可访问性、代码整洁、请求层与类型、组合式函数的写法,保证全站一致、可维护。
- **何时用**:新增或修改前端组件、样式、请求封装、composable 时;评审前端改动时。
## 规则
### 交互防抖与加载原则
- 点击后需要跳转到其他页面时,应立刻执行跳转,不要在跳转前等待接口返回;目标页面在数据未加载完成时必须展示页面级 loading。
- 点击后不跳转页面时,触发接口的按钮必须自身展示 loading 或在请求期间禁用,防止网络慢时被多次触发。
- 登录、创建/更新、结束会话等必须确认后端成功的操作属于例外:按钮先进入 loading,成功后再跳转。
- 同一异步动作执行期间必须通过 loading 或 disabled 阻止重复触发,不能只依赖路由跳转后的页面卸载。
### 按钮规范
- 主操作 / 卡片 CTA:`size="large"`(实测 40px 高、15px 字),如 Study 开始任务、Welcome 快速入口。
- 区块工具栏 / 页内操作:默认尺寸(32px 高、14px 字),如 Review 刷新、ReviewRecall 面板操作。
- 表格/列表行内操作:`size="small"`(28px 高、13px 字;不得再调小)。
- 弹窗 footer:默认尺寸;确认按钮 `type="success"`,取消按钮默认;危险操作统一 `type="danger"`。
- 正向/保存语义统一 `success`,次级编辑语义可用 `primary`,不要在同一功能上混用。
- 窄屏(`max-width: 768px`)操作区按钮纵向全宽,全局规则位于 `src/assets/main.css` 的 `.action-row / .edit-actions / .fragment-edit-actions / .task-actions`。
### 颜色与主题
- 禁止在组件内写颜色字面量:新增颜色先加到 `src/assets/base.css` 的 `:root`,组件只用 `var(--x)`。语义色已提供 `--accent-warning / --accent-warning-soft / --accent-warning-strong / --accent-success-soft / --accent-success-softer / --accent-success-strong / --accent-success-text`。
- Element Plus 主题色在 `src/assets/main.css` 的 `:root` 覆盖(`--el-color-success` / `--el-color-primary` 指向 `--green-700`),全站按钮/标签/开关自动生效,不要在组件里逐个覆盖 EP 组件色。
- `src/main.ts` 中自定义样式必须写在 `import 'element-plus/dist/index.css'` **之后**,否则主题覆盖会被 EP 覆盖。
- 实底主色统一用满足 WCAG AA(白字对比度 ≥4.5:1)的 `--green-700`;`--green-600` 仅用于文字/链接。
- 颜色字面量不得出现在 JS/模板表达式里(如 `:color="'#xxx'"` 引 CSS 变量会失效),需要动态色时保留字面量或改用 CSS 类。
### 界面质量与可访问性
交付前逐项过 `roles/ui-review-checklist.md`;本节只列代码层面的写法要求。
- 可聚焦元素必须有 `:focus-visible` 焦点环;不得写 `outline: none` 而不给替代。粘性头部/遮罩不得盖住获得焦点的控件。
- 过渡显式列出属性(`transition: opacity .2s ease, transform .2s ease`),**禁止 `transition: all`**;只动 `transform` / `opacity`。
- 需要动效时给 `@media (prefers-reduced-motion: reduce)` 降级;全站统一的淡入上移不作为入场方案。
- 统计、覆盖率、计时、金额等需要上下比较的数字加 `font-variant-numeric: tabular-nums`。
- 加载/处理中的文案以 `…`(省略号字符)结尾,不用 `...`。
- 长内容容器加 `min-width: 0` 并允许换行或省略,验证 URL、ID 与用户输入的极端情况。
- 空态与错误态分开:空态给下一步动作,错误态给原因 + 重试;不要用同一个 `el-empty` 兜住失败。
- 加载指示延迟约 150–300ms 再显示,并保证最短可见约 300–500ms,避免快响应时闪一下。**统一用 `useDelayedVisible`**,不要自己写定时器。
- 骨架形状要与最终内容一致(清单在 `roles/ui-review-checklist.md`);骨架用 `main.css` 的 `.skeleton-line`,不要在组件里另造一套灰。
- 纯图标按钮必须有 `aria-label`;装饰图标 `aria-hidden="true"`。
> 页面的信息架构与视觉层级取舍见 `roles/design-principles.md`,设计变量的当前取值见 `roles/design-system.md`;出现新页面或大范围 UI 改动时走 `skills/ui-review/`。
### 卡片列表交互
- 卡片列表的卡片整体可点击进入详情:外层加 `role="link" tabindex="0"` 与 `aria-label`,并绑定 `@click` 及 `@keydown.enter/@keydown.space.prevent`。
- 卡片内的附加按钮必须 `@click.stop`,避免被卡片点击吞掉(如 Review 的「回忆复习」)。
- 卡片操作使用右对齐操作簇(`justify-content: flex-end`),**禁止用 `space-between` 把两个按钮拉到卡片两端**。
- 加载失败必须区分于空数据:保留一个 `loadFailed` 状态,失败时给出可读提示 + 重试按钮,重试前先重置该状态;不要只靠 `finally` 关 loading 导致空白页。
### 移动端适配
- 断点约定:按钮/弹窗使用 768px,卡片与汇总布局使用 900px。
- 弹窗:窄屏宽度 `calc(100% - 24px)`,body 允许纵向滚动,footer 按钮等宽;全局规则位于 `main.css` 的 `@media (max-width: 768px)`,新增弹窗不需要再逐页适配。
- 多按钮弹窗(如 Welcome 回忆卡片)在窄屏纵向堆叠。
- 列表页优先使用卡片列表而非 `el-table`,桌面与移动端视觉统一,参考 `Review.vue` 的 `.task-list`。
- 文案不缩写:使用完整字段名,如 `学习报告数量`、`学习残片数量`,不使用 `报告数`、`残片数`。
### 代码整洁
- Markdown 渲染统一使用 `src/utils/markdown.ts` 的 `renderMarkdown`,禁止在组件内复制实现。
- 应用场景状态常量统一使用 `src/utils/taskApplication.ts` 的 `applicationStatusOptions`。
- 用户可见错误提示必须口语化、可理解,不要直接展示接口原始 message、JSON、参数名或“服务器返回”等技术信息;技术细节留在日志。
- 不保留无消费者代码:未使用的 import、prop、事件、API 封装、CSS class、组件文件与依赖应及时删除。
- 组件公开 props/events 只在有实际消费者时保留,例如 MindMapViewer 通过 `toOutline()` 导出编辑内容,不依赖无人监听的 change 事件。
- Vite 模板遗留文件(示例组件、icon、logo)不进入业务代码。
### 请求层与类型规范
- 所有接口封装必须放在 `src/api/`,组件内禁止直接拼 URL 调用 `request`(历史遗留的裸调用在改动到时迁移)。
- request 层统一返回 `Promise<ApiResponse<T>>`:新增接口必须显式标注泛型 `T`,组件消费 `res.data` 时应有明确类型,禁止把后端字段拼错暴露到运行期。
- 默认超时 30 秒;AI 聚合类接口(残片生成、思维导图生成/对比、报告草稿、结束会话)在 api 层显式覆写 `{ timeout: 300_000 }`,不要调大全局默认值。
- 组件解构响应时使用 `res?.data` 判空兜底;`ApiResponse` 从 `@/utils/request` 导入复用。
### 组合式函数复用
- “已等待 N 秒”类秒表计时统一使用 `useElapsedSeconds`,禁止组件内手写 `setInterval` 秒数递增。
- 骨架/加载指示的「延迟显示 + 最短可见」统一使用 `useDelayedVisible`,禁止组件内手写 setTimeout 开关加载态。
- 页面新增功能域时先抽 composable(参考 `useSessionHistory` / `useSummaryReport` / `useSessionExpectation`),不要继续膨胀 StartTask 等大页面组件。
- 通用解析器、格式化工具放 `src/utils/`,不埋在组件内(如大纲文本转树应放 utils)。