公开摘要
本文整理前端团队在项目命名、目录结构、HTML/CSS/JavaScript（TypeScript）编码、提交流程等方面的统一实践。关联后端规范与 Git 使用规范时，页面中以纯文本呈现，不保留 Obsidian 双链格式。
规范目的与能愿动词
- 高效协作：降低沟通与接手成本。
- 风格统一：统一代码风格和工程组织方式。
- 质量可控：通过自动化检查减少低级错误。
- 便于维护：提升可读性、可扩展性和可追溯性。
文档中的“必须”表示无条件遵守，“绝不”表示严令禁止，“应该”表示强烈建议，“不应该”表示强烈不建议。
项目与文件命名
- 项目名必须全小写，多单词必须使用中划线分隔，例如
clinic-admin-web、drug-inventory-h5。 - 项目名绝不使用中文、空格、下划线或驼峰，例如
ClinicAdminWeb、clinic_admin_web都不建议。 - 普通目录和文件应该使用小写中划线风格，例如
order-list.ts。 - 组件文件在框架允许时可以使用
PascalCase，但同一项目内必须统一。
目录结构建议
project-name/
├── src/
│ ├── assets/ # 静态资源
│ ├── components/ # 通用组件
│ ├── pages/ # 页面级模块
│ ├── layouts/ # 布局组件
│ ├── router/ # 路由配置
│ ├── store/ # 状态管理
│ ├── services/ # API 请求层
│ ├── hooks/ # 复用逻辑
│ ├── utils/ # 工具函数
│ ├── styles/ # 全局样式/变量
│ ├── constants/ # 常量定义
│ └── types/ # 类型定义
├── public/
├── tests/
└── docs/HTML、CSS 与 TypeScript
HTML
- 标签与属性名必须小写，属性值必须使用双引号。
- 结构类标签应该使用语义化元素，例如
header、main、section、footer。 img必须提供alt，表单控件应该配套label。- 缩进必须统一，建议 2 空格。
CSS / SCSS
- class 名必须小写中划线，复杂样式应该使用 BEM 命名法。
- 样式不应该依赖
id选择器，绝不滥用!important。 - 颜色、间距、字号应该抽为变量或 token，嵌套层级不应该超过 3 层。
JavaScript / TypeScript
- 变量和函数使用
camelCase，类、类型、接口、组件使用PascalCase，常量使用UPPER_SNAKE_CASE。 - 布尔变量应该使用
is、has、can前缀。 - 一个函数应该只做一件事，优先使用
const，必要时再使用let，绝不使用var。 - 异步流程必须处理错误，TypeScript 项目不应该随意使用
any。
前端规范的关键，是把“个人习惯”翻译成“团队可以检查的接口”。
组件、状态与质量门禁
- 组件职责应该单一：页面组装与业务逻辑拆分。
- 可复用逻辑应该抽离到
hooks/或composables/。 - API 调用必须收敛在
services/，页面层不直接拼接请求。 - 全局状态应该只存共享状态，不存纯展示状态。
- 项目必须配置并启用
ESLint + Prettier。 - 合并前必须通过
lint、type-check、test、build。 - 应该启用
husky + lint-staged，在提交前自动检查；CI 必须在 PR 阶段执行质量校验。
Git 与 PR 自检
分支规范应与团队 Git 流程对齐，例如 dev/{日期}/{需求} 与 fix/{日期}/{需求}。提交信息建议使用语义化前缀：feat:、fix:、refactor:、docs:、style:、test:、chore:。
- 命名是否符合项目、目录、文件、变量规范。
- 是否通过 lint、type-check、test、build。
- 是否存在内联样式、
!important滥用或超深嵌套。 - API 调用是否集中在
services/。 - 分支命名与提交信息是否符合规范。