235 lines
10 KiB
Markdown
235 lines
10 KiB
Markdown
# 通用前端开发规范
|
||
|
||
## 1. 文档定位
|
||
|
||
本文记录可跨项目复用的前端开发约定，适用于以页面展示、交互、状态管理、接口调用和用户体验为核心的前端项目。
|
||
|
||
复制到新项目后，应根据实际技术栈、目录结构、启动命令、接口契约、设计系统和业务约束做项目级补充。当前项目的业务专属规则不应写入本文。
|
||
|
||
## 2. 技术栈原则
|
||
|
||
具体版本以项目内依赖文件为准，例如 `client/package.json`、锁文件和构建配置。
|
||
|
||
通用要求：
|
||
|
||
- 使用 TypeScript 时应开启严格类型检查。
|
||
- 构建、Lint、类型检查、测试命令必须可重复执行。
|
||
- 不引入与项目规模不匹配的大型模板或重型依赖。
|
||
- UI 组件库、路由、状态管理和请求库应在项目级文档中明确。
|
||
- 生成代码应进入专门目录，并标记为禁止手工修改。
|
||
- 新项目必须明确 Node.js、包管理器、框架、语言、构建工具、Lint、类型检查和测试框架的兼容关系。
|
||
- TypeScript 版本必须与类型检查、Lint 和框架工具链支持范围一致。
|
||
- Vue 单文件组件项目应配置 `vue-tsc` 或等价工具覆盖 `.vue` 文件类型检查。
|
||
|
||
## 3. 目录约定
|
||
|
||
推荐目录：
|
||
|
||
```text
|
||
client/src
|
||
├── components
|
||
│ └── common
|
||
├── composables
|
||
├── generated
|
||
├── i18n
|
||
│ └── locales
|
||
├── layouts
|
||
├── router
|
||
├── services
|
||
├── stores
|
||
├── styles
|
||
├── tests
|
||
├── types
|
||
└── views
|
||
```
|
||
|
||
目录规则：
|
||
|
||
- API 请求封装放入 `src/services`。
|
||
- 手写类型定义放入 `src/types`。
|
||
- OpenAPI 或其他工具生成代码放入 `src/generated`，禁止手工修改。
|
||
- 可复用组合逻辑放入 `src/composables`。
|
||
- 路由定义放入 `src/router`。
|
||
- 客户端状态放入 `src/stores`。
|
||
- i18n 入口和语言包放入 `src/i18n`。
|
||
- 页面级组件放入 `src/views`。
|
||
- 可复用组件放入 `src/components`。
|
||
- 通用布局放入 `src/layouts`。
|
||
- 全局样式和设计 token 放入 `src/styles`。
|
||
|
||
## 4. 组件规范
|
||
|
||
- 页面组件负责展示、交互和页面编排，不直接承载复杂业务规则。
|
||
- Props、Emits、响应式状态和服务返回值必须有明确类型。
|
||
- 避免在模板中写复杂业务逻辑，复杂逻辑放入 computed、composable 或服务层。
|
||
- 不在组件里直接拼接后端 URL，统一通过 services。
|
||
- 不在组件里直接访问浏览器全局存储保存业务事实。
|
||
- 不把中文或英文显示文案作为业务判断依据。
|
||
- 可复用组件应通过清晰 props 和 emits 对外暴露能力。
|
||
- 大组件应按职责拆分，避免一个页面文件同时承担数据请求、复杂表单、表格、弹窗和业务判断。
|
||
|
||
## 5. 状态管理规则
|
||
|
||
客户端状态和服务端数据要分开管理。
|
||
|
||
客户端状态适合保存：
|
||
|
||
- 当前用户上下文。
|
||
- 语言、主题和页面偏好。
|
||
- 轻量 UI 状态。
|
||
- 当前页面临时筛选条件或展开状态。
|
||
|
||
服务端数据适合通过请求缓存库或服务层管理：
|
||
|
||
- 列表、详情、统计、字典和远程配置。
|
||
- Mutation 完成后按 query key 或明确缓存规则失效。
|
||
- 不把服务端数据长期复制进客户端全局 Store。
|
||
- 不用前端状态绕过后端权限、状态机或业务校验。
|
||
|
||
## 6. API 请求规范
|
||
|
||
- 浏览器默认只调用本项目后端。
|
||
- 所有请求封装到 `src/services`。
|
||
- 服务函数返回明确 TypeScript 类型。
|
||
- 统一处理 JSON、错误结构、超时、取消请求和认证失效。
|
||
- 前端不直接调用数据库、对象存储、持有 Secret 的第三方系统或内部 Provider。
|
||
- 前端不发送后端 Secret、Provider API Key、数据库凭证或内部访问密钥。
|
||
- 调试页面如果需要触发受控后端能力，应由后端提供 debug-only 包装接口，Secret 保留在后端。
|
||
|
||
## 7. 国际化与展示文案
|
||
|
||
- 新增页面和组件不得把业务逻辑绑定到展示文案。
|
||
- 系统固定文案应使用稳定 i18n key。
|
||
- 后端应返回稳定业务代码和必要 `labelKey`，前端按 key 显示。
|
||
- 用户输入、外部来源原文和备注应保持原文，不做无依据翻译。
|
||
- 日期、时间、数字和货币按当前语言、时区和币种配置格式化。
|
||
- API 仍传递结构化原始值，不传本地化展示字符串作为业务参数。
|
||
|
||
如果项目不需要国际化，也应保留“业务判断不依赖展示文本”的规则。
|
||
|
||
## 8. 类型与业务代码
|
||
|
||
- TypeScript 类型应贴近后端 API 契约。
|
||
- 稳定业务代码使用 string union、枚举型常量或后端生成类型，避免散落 magic string。
|
||
- 动态字段使用稳定 `fieldKey`。
|
||
- 表单字段展示使用 `labelKey` 或 i18n key。
|
||
- 不用 `label`、中文标题或英文标题做字段标识。
|
||
- 接口字段变更时，同步更新 `src/types`、services、页面和测试。
|
||
|
||
## 9. UI 与交互规范
|
||
|
||
- UI 应优先服务真实工作流，不堆叠无意义装饰。
|
||
- 列表、详情、表单、弹窗、空状态、加载状态和错误状态必须完整。
|
||
- 重要操作必须有明确反馈。
|
||
- 危险操作必须有确认、权限或后端校验。
|
||
- 复杂表单应区分草稿、提交中、提交成功、提交失败和版本冲突。
|
||
- 涉及敏感信息时，应默认最小展示。
|
||
- 组件样式应遵守项目设计 token，避免随意写一次性颜色、间距和字号。
|
||
- 页面文本必须在移动端和桌面端都不溢出、不遮挡。
|
||
|
||
## 10. 前端安全规范
|
||
|
||
- 公开环境变量会暴露到浏览器构建产物，不能保存 Secret。
|
||
- 前端不得保存数据库密码、Provider API Key、访问令牌、内部重放密钥或生产凭证。
|
||
- 不在 LocalStorage、SessionStorage 或 URL 中保存敏感业务数据。
|
||
- 错误提示不展示 Authorization、Cookie、Token、原始敏感正文或附件 URL。
|
||
- 测试夹具不得使用真实客户、真实生产数据或真实支付信息。
|
||
|
||
## 11. 配置规范
|
||
|
||
常见公开配置示例：
|
||
|
||
```text
|
||
VITE_API_BASE_URL=http://localhost:8080
|
||
VITE_APP_ENV=local
|
||
VITE_DEFAULT_LOCALE=zh-CN
|
||
VITE_ENABLE_MOCKS=false
|
||
```
|
||
|
||
规则：
|
||
|
||
- 公开配置可以放入前端环境变量。
|
||
- Secret 一律不进入前端环境变量。
|
||
- 生产需要运行时配置时，应由部署系统生成公开配置文件，例如 `/app-config.json`。
|
||
- 需要秘密的外部调用一律经后端代理或适配器。
|
||
|
||
## 12. 路由规范
|
||
|
||
- 新增业务路由前确认对应后端 API、权限边界和页面恢复能力。
|
||
- 详情页路由参数使用稳定 ID。
|
||
- 页面刷新后必须能通过后端详情接口恢复必要状态，不依赖内存临时状态。
|
||
- 未确认的业务入口不要提前硬编码到导航。
|
||
- 路由守卫只做访问控制和基础上下文检查，不承载复杂业务流程。
|
||
|
||
## 13. 表单规范
|
||
|
||
- 表单字段应来自稳定契约或明确的本地模型。
|
||
- 保存草稿时使用稳定字段名或 `fieldKey`。
|
||
- 不把显示文案作为提交字段名。
|
||
- 提交前前端可做基础格式校验，但最终业务校验在后端。
|
||
- 发生版本冲突时，应提示用户刷新或重新确认，不静默覆盖。
|
||
- 表单错误应能定位到字段或操作区域。
|
||
|
||
## 14. Agent 前端开发 Skill 使用原则
|
||
|
||
如果当前 agent 环境提供前端、设计、浏览器验证或可视化相关 skill，应按任务类型选择使用。Skill 是辅助能力，不替代项目技术栈、组件库、设计 token、接口契约和用户明确要求。
|
||
|
||
通用原则：
|
||
|
||
- 新增页面、复杂组件、交互流程或明显视觉调整前，应优先使用设计或前端类 skill 辅助确认方案。
|
||
- 重构已有页面视觉时，应优先使用现有项目审视和重构类 skill，避免破坏原有功能。
|
||
- 根据截图、设计稿或视觉参考还原页面时，应使用图像到代码或视觉分析类 skill。
|
||
- 设计 token、组件规范或样式体系调整时，应使用设计系统类 skill。
|
||
- 需要生成图片资产时，可使用图像生成类 skill，但不得替代项目内已有品牌资产或图标规范。
|
||
- 涉及可视化结果的前端改动，完成后应通过浏览器、截图或交互测试验证桌面端和移动端表现。
|
||
- Skill 建议不得直接引入新的 UI 框架、组件库、状态管理方案或重型依赖；如确有必要，必须先确认。
|
||
- 如果相关 skill 不可用，应按同等原则手动完成设计、实现和验证，并在交付说明中说明。
|
||
|
||
## 15. 测试与检查命令
|
||
|
||
前端项目应至少提供：
|
||
|
||
```bash
|
||
cd client
|
||
pnpm lint
|
||
pnpm typecheck
|
||
pnpm test
|
||
pnpm build
|
||
```
|
||
|
||
如果项目不是 pnpm，应在项目级文档中替换为实际命令。
|
||
|
||
聚焦开发时可运行：
|
||
|
||
```bash
|
||
cd client
|
||
pnpm test -- SomeSpecName.spec.ts
|
||
```
|
||
|
||
如果命令尚未配置或因环境问题无法运行，必须明确说明，不能假装通过。
|
||
|
||
## 16. Git 与协作流程
|
||
|
||
- 改动前说明目标、范围和将修改的文件。
|
||
- 每次只处理一个模块、一个页面或一个纵向切片。
|
||
- 不修改与当前任务无关的用户变更。
|
||
- 前后端接口变化前，先确认 API 契约和字段映射。
|
||
- 修改后运行项目已配置的检查命令。
|
||
- Git commit message 使用中文，清楚说明本次提交的业务或技术变更。
|
||
|
||
## 17. 前端提交前检查清单
|
||
|
||
- [ ] 是否只调用本项目后端或明确允许的公开服务？
|
||
- [ ] 是否没有把 Secret 放入前端环境变量、源码、测试或 URL？
|
||
- [ ] 新文案是否按项目约定处理？
|
||
- [ ] 是否避免用中文或英文显示文本做业务判断？
|
||
- [ ] API 请求是否放在 `src/services`？
|
||
- [ ] 手写类型是否放在 `src/types`？
|
||
- [ ] 可复用逻辑是否放在 `src/composables`？
|
||
- [ ] 服务端数据是否没有长期塞进客户端全局 Store？
|
||
- [ ] 是否没有手工修改 `src/generated`？
|
||
- [ ] 是否覆盖加载、空状态、错误、成功和权限不足等关键状态？
|
||
- [ ] 涉及 UI、交互或视觉变更时，是否使用或说明未使用合适的前端 / 设计 skill？
|
||
- [ ] 涉及可视化结果时，是否做过浏览器、截图或响应式验证？
|
||
- [ ] 是否运行了项目前端检查命令或说明了无法运行原因？
|