代码规范

代码规范的目标是让多人协作中的改动可预测、可审查、可持续升级。Art Design Pro X 已配置 ESLint、Prettier、Stylelint、Commitlint 和安全检查脚本，新模块应沿用现有规则，不在局部建立另一套风格。

基础风格

Prettier 核心规则：

{
  "printWidth": 100,
  "tabWidth": 2,
  "semi": false,
  "singleQuote": true,
  "trailingComma": "none",
  "proseWrap": "never"
}

ESLint 进一步要求：

• JavaScript 和 TypeScript 使用单引号。
• 语句末尾不使用分号。
• 禁止 var，使用 const 或 let。
• 不允许意外的多行表达式。
• Vue、TypeScript 和 Prettier 规则统一执行。

不要为了个人习惯在单个目录关闭格式化或批量添加 eslint-disable。确有例外时，应限制到最小代码范围并说明原因。

文件与命名

推荐约定：

类型	命名示例
Vue 组件	CustomerDialog.vue
Hook	useCustomerFilters.ts
Store	customer.ts，导出 useCustomerStore
API 模块	customer.ts
类型文件	customer.d.ts 或 customer.ts
常量	DEFAULT_PAGE_SIZE
布尔状态	isLoading、hasPermission、canEdit

页面目录遵循现有路由和业务域结构。页面专属组件放在 modules/，跨业务复用后再提升到公共组件目录。

Vue 组件

推荐使用 <script setup lang="ts"> 和 Composition API：

<script setup lang="ts">
  interface Props {
    customerId: number
    readonly?: boolean
  }

  const props = withDefaults(defineProps<Props>(), {
    readonly: false
  })

  const emit = defineEmits<{
    success: []
  }>()
</script>

组件设计原则：

• props 只读，不直接修改父级数据。
• emits 使用明确事件名和参数类型。
• 派生状态使用 computed。
• 异步状态包含 loading、error 和 finally 清理。
• 监听器、定时器、图表实例在卸载时释放。
• 页面不直接操作全局 DOM，优先使用组件引用和 Hook。

TypeScript

• API 参数和响应定义明确类型。
• 避免没有边界的 Record<string, any>。
• 对外部 JSON 在入口处校验，不假设类型声明等于运行时真实数据。
• 公共函数声明返回值和错误语义。
• 枚举值、权限码、路由名保持稳定英文代码。
• 不使用非空断言掩盖初始化问题。

项目没有强制禁用所有 any，但这不是放弃类型设计的理由。与第三方库交界处可以有限使用，业务数据和公共接口应保持可推导。

API 与错误处理

页面通过 src/api 和统一 HTTP 层请求数据：

页面 / Hook / Store -> API -> request -> 后端

• 所有接口 URL、请求函数和返回类型统一放在 src/api。
• 不在页面中新建 Axios 实例。
• 不在 src/services 中定义 HTTP 接口。
• 不重复拼接 Token 和基础 URL。
• 不吞掉错误后伪造成功数据。
• 成功提示按操作需要开启，避免请求层和页面重复提示。
• 401 使用统一登出流程。
• Mock 和真实 API 的切换必须显式。

样式规范

Stylelint 覆盖 CSS、SCSS 和 Vue 样式：

• 属性顺序由配置统一整理。
• Vue 样式使用正确的解析器。
• 主题色和通用间距优先使用项目变量。
• 避免大范围 !important。
• 避免依赖 Element Plus 不稳定的深层 DOM 结构。
• 页面样式默认使用 scoped，全局样式进入明确的主题文件。

响应式布局应验证常用桌面和移动视口，不通过固定高度或隐藏溢出来掩盖内容问题。

代码检查命令

命令	作用
pnpm lint	执行 ESLint
pnpm fix	自动修复可处理的 ESLint 问题
pnpm lint:stylelint	检查并修复样式
pnpm build	TypeScript 检查并生产构建
pnpm security:check	执行前端安全基线检查
pnpm release:check	安全检查、Lint 和构建的完整链路

提交前至少执行与改动范围相匹配的检查。涉及公共组件、路由、请求层或构建配置时，应执行完整 pnpm release:check。

提交规范

项目使用 Conventional Commits，常用类型：

feat: 新增功能
fix: 修复缺陷
docs: 文档变更
refactor: 不改变行为的重构
perf: 性能优化
test: 测试变更
build: 构建或依赖变更
ci: CI 配置变更
chore: 工具与维护任务

示例：

feat(customer): add customer import dialog
fix(auth): clear stale routes after token expiration
docs(frontend): document remote menu contract

一次提交应表达一个可审查目标。格式化全仓库、依赖升级和业务功能不要无关地混在同一提交中。

安全基线

scripts/security-check.mjs 用于执行项目定义的前端安全检查。除此之外，开发时还需要保持：

• 不把密钥写入 VITE_ 环境变量。
• 不使用 v-html 直接渲染不可信内容。
• 上传文件不能只检查扩展名。
• 权限按钮不替代后端鉴权。
• 不记录完整 Token、密码或敏感响应。
• 依赖升级后检查变更说明和构建结果。

Review 检查清单

• 改动是否符合现有模块边界。
• API、Store 和组件类型是否清晰。
• 是否覆盖 loading、空数据、错误和权限状态。
• 是否处理刷新、退出和账号切换。
• 是否引入重复组件或重复 Hook。
• 是否存在硬编码环境地址、密钥或中文枚举值。
• pnpm lint、pnpm build 是否通过。
• 用户可见行为是否与文档和交付边界一致。

具体业务扩展流程见扩展开发指南，发布阶段见构建部署。