开发规范

1. 代码风格

1.1 格式化（Prettier）

• 配置文件：.prettierrc.json
• 关键配置：
  • "useTabs": false（空格缩进）
  • "tabWidth": 4
  • "printWidth": 160
  • "singleQuote": false（双引号）
  • "trailingComma": "none"
  • "semi": true
  • "endOfLine": "auto"
• 命令：
  • npm run format（对 src/ 执行 prettier --write）

1.2 代码检查（ESLint）

• 配置文件：eslint.config.js（Flat Config）
• 集成：eslint-config-prettier + eslint-plugin-prettier（以 Prettier 规则作为 ESLint 报错源）
• 约束要点：
  • 禁止/告警 console：默认 warn，允许 console.warn / console.error
  • TypeScript：
    • any：warn
    • 未使用变量：warn（以 _ 开头的参数/变量允许忽略）
  • Vue：
    • 模板中组件命名：PascalCase（vue/component-name-in-template-casing）
• 命令：
  • npm run lint
  • npm run lint:fix

1.3 提交前检查（lint-staged）

• 配置位置：package.json -> lint-staged
• 规则：
  • src/**/*.{ts,vue}：eslint --fix + prettier --write
  • src/**/*.scss：prettier --write

2. TypeScript 规范

• TypeScript 配置：tsconfig.json
• 约束（必须通过）：
  • strict: true
  • noUnusedLocals: true
  • noUnusedParameters: true
  • noImplicitReturns: true
  • noFallthroughCasesInSwitch: true
  • forceConsistentCasingInFileNames: true
• 别名：
  • @/* -> src/*
• 命令：
  • npm run type-check（vue-tsc --noEmit）

3. 命名规范

3.1 文件与目录命名

• 页面目录：放在 src/pages/ 下，使用多级目录组织，页面入口文件统一使用 index.vue（例如：pages/cart/index.vue）。
• 组件目录：放在 src/components/ 下，建议采用“目录名/同名组件文件”结构：
  • components/xxx/xxx.vue
• TypeScript 模块文件（API、Store、Utils、Types 等）：使用 camelCase 或语义化英文命名（与模块职责一致）。

3.2 组件命名（与自动导入一致）

• Vue 模板内组件名使用 PascalCase（ESLint 告警规则）。
• easycom（src/pages.json -> easycom.custom）自动导入规则：
  • ^uni-(.*) -> @dcloudio/uni-ui
  • ^u--(.*) / ^up-(.*) / ^u-([^-].*) -> uview-plus
  • vort-(.*) -> @/components/vort/vort-$1/vort-$1.vue
  • format-price -> @/components/format-price/format-price.vue
  • loading-box -> @/components/loading-box/loading-box.vue
  • empty-box -> @/components/empty-box/empty-box.vue

3.3 变量/函数/Store 命名

• 变量/函数：统一 camelCase
• 常量：统一 UPPER_SNAKE_CASE（如 API_CODE、REQUEST_TIMEOUT）
• Pinia Store：
  • 命名：useXxxStore
  • 文件：src/store/modules/xxx.ts
  • 统一在 src/store/index.ts 导出

4. 目录结构与职责

• src/api/：接口模块，按业务域分目录，统一从 src/api/index.ts 对外导出（xxxApi 对象化调用）。
• src/utils/：工具与基础能力（请求、权限、加密、上传、MQTT/WebSocket 等）。
• src/store/：Pinia（modules/ 为各业务 Store）。
• src/pages/：业务页面（与 src/pages.json 对应）。
• src/components/：通用组件与业务组件（含 components/vort/ 系列组件）。
• src/i18n/、src/locale/：国际化。
• src/constants/：常量集中管理，统一从 src/constants/index.ts 导出。
• src/types/：类型定义。
• src/static/：静态资源（css/、images/、font/）。
• src/uni.scss：全局 SCSS 变量（颜色/尺寸等）。

5. 路由与分包

• 路由配置文件：src/pages.json
• 规则：
  • 新增页面必须同时：
    • 在 src/pages/ 创建页面文件
    • 在 src/pages.json 注册（pages 或 subPackages）
  • 分包页面使用 subPackages，以 root 对应 src/pages/<root>/...
  • tabBar 页必须配置在 tabBar.list，并确保页面路径一致

6. 权限与页面跳转

• 权限拦截器：src/utils/permission.ts
• 拦截范围：navigateTo、redirectTo、reLaunch、switchTab
• 规则：
  • 白名单：permission.ts -> whiteList 内页面允许免登录跳转
  • 非白名单且无 token：跳转登录页 /pages/login/index（或走微信授权登录流程）
• 新增“免登录页面”时：必须补充到 whiteList

7. 请求与接口调用

7.1 请求统一入口

• 禁止直接使用 uni.request；统一使用 src/utils/request.ts：
  • request(config)
  • get(url, params, config?)
  • post(url, data, config?)

7.2 请求配置约定（按需启用）

• method：仅使用大写 "GET" | "POST"
• prefix：默认使用 import.meta.env.VITE_API_PREFIX
• noSkipLogin：跳过未登录处理（仅在明确无需登录的接口使用）
• showLoading / loadingText：控制加载提示
• silent：静默失败（不弹 toast）
• retry / retryDelay / exponentialBackoff：重试策略
• cache / cacheTime：GET 缓存策略
• requestKey + cancelPrevious：同 key 请求取消（搜索/联想等场景）

7.3 Header 与鉴权

• Token：从 uni.getStorageSync("token") 读取并写入 Satoken 头
• 统一附带：
  • X-Client-Type（来自 useAppStore().XClientType）
  • X-Locale-Code（来自 useI18nStore().langCode）
  • X-Request-Id（请求追踪）

7.4 API 调用方式

• 统一从 @/api 引入对象化 API：
  • import { loginApi, productApi } from "@/api"
• src/api/* 内按业务域拆分，模块入口统一在各目录 index.ts 聚合导出（保持对外 API 稳定）。

8. 国际化（i18n）

• i18n 实例：src/i18n/index.ts（vue-i18n，legacy: false，全局注入）
• 语言包：src/locale/zh.json、src/locale/en.json（统一从 src/locale/index.ts 汇总）
• 约束：
  • 业务文案使用 i18n key，不直接写死多语言文本
  • i18n key 需保持稳定（避免动态拼接导致无法命中翻译与缓存）

9. 样式与资源

• 全局样式入口：src/App.vue 内引入：
  • uview-plus/index.scss
  • src/static/css/style.css
• 全局变量：src/uni.scss
• 静态资源：
  • 图片：src/static/images/
  • 字体：src/static/font/
  • 样式：src/static/css/

10. 环境变量

• 使用 import.meta.env 读取：
  • VITE_API_URL
  • VITE_API_PREFIX
  • VITE_NODE_ENV