开发规范

1. 技术栈与工程约束

• 框架：Nuxt 4（启用 future.compatibilityVersion: 4，使用 app/ 目录结构）
• 语言：Vue 3 + TypeScript（仓库为 ESM：package.json 中 "type": "module"）
• 状态管理：Pinia（Nuxt 模块：@pinia/nuxt，Store 目录：app/store/**）
• UI/组件库：Ant Design Vue、Element Plus（按需/插件方式接入）
• 国际化：@nuxtjs/i18n（app/i18n/config.ts）
• 构建与开发：Vite（Nuxt 内置），开发端口固定为 5173（见 nuxt.config.ts）

2. 代码风格

2.1 代码格式化（Prettier）

• 工具：Prettier（统一作为唯一的格式化来源）
• 配置文件：.prettierrc.json
• 执行命令：npm run format（仅格式化 app/ 目录）

当前关键配置（摘自 .prettierrc.json）：

• tabWidth: 4
• printWidth: 160
• singleQuote: false（默认双引号）
• semi: true
• trailingComma: none
• endOfLine: auto（兼容 Windows/Unix 行尾）

2.2 代码检查（ESLint）

• 工具：ESLint 9 + Nuxt ESLint（@nuxt/eslint）
• 配置文件：eslint.config.mjs
• 执行命令：
  • npm run lint
  • npm run lint:fix

约束特点：

• Prettier 作为 ESLint 规则执行：eslint-plugin-prettier + eslint-config-prettier（格式不符合会直接报错）
• 生产环境限制：
  • no-console: production 为 warn
  • no-debugger: production 为 error
• TypeScript：
  • @typescript-eslint/no-explicit-any: warn（尽量避免 any）
  • @typescript-eslint/no-unused-vars: error（允许使用 _ 前缀忽略）
• Vue：
  • 允许单词组件名（vue/multi-word-component-names: off）
  • v-html 仅告警（vue/no-v-html: warn）

2.3 缩进与换行

• 本项目未提供统一的 .editorconfig，请以 Prettier 输出为准。
• 推荐编辑器启用：
  • 保存时执行 Prettier（Format on Save）
  • 行尾符不强制（由 endOfLine: auto 兜底）

2.4 命名规范

• 变量/函数：camelCase
• 类型/接口/类/组件名：PascalCase
• 常量：UPPER_SNAKE_CASE
• 布尔值：优先 is/has/can/should 前缀（如 isOverseas、hasToken）

2.5 注释规范（JSDoc）

• 对外复用的工具函数、适配层、复杂逻辑应补充 JSDoc。
• 注释应解释 “为什么” 与 边界条件，不要复述代码本身。

参考：app/utils/request.ts、app/decorate/normalize.ts。

3. 目录结构与职责（Nuxt 4：app/）

主目录以 app/ 为核心（见 docs/基础文档/项目结构.md）：

• app/pages/：页面路由（自动生成路由）
• app/components/：通用/业务组件（自动导入）
• app/composables/：组合式函数（自动导入，命名以 useXxx 开头）
• app/store/：Pinia store（业务模块拆分）
• app/api/：接口定义（按业务域拆分）
• app/utils/：纯工具/适配层/通用方法
• app/types/：类型定义（业务类型、API 类型等）
• app/plugins/：Nuxt 插件（客户端/通用初始化）
• app/middleware/：路由中间件（登录态、游客态等）
• app/assets/：会参与构建处理的静态资源（LESS、图片、SVG 图标等）
• public/：不经构建处理的静态资源

4. Vue / Nuxt 编码规范

4.1 组件文件与命名

• 组件文件名：PascalCase.vue
• 页面文件：按路由结构组织（目录/文件名与路由匹配）
• 单文件组件结构：建议顺序 template → script setup → style

4.2 Props / Emits / Slots

• Props 一律 显式类型（defineProps<T>() 或 PropType<T>）
• 数组/对象默认值必须使用工厂函数（避免引用共享）
• 事件建议定义类型（defineEmits<...>()）

4.3 SSR / Client 边界

本项目支持通过环境变量启用 SSR（见 nuxt.config.ts）：

• 涉及 window/localStorage 等仅客户端对象时：
  • 使用 import.meta.client 或 Nuxt 的 process.client 分支
  • 或放到 .client.ts 插件 / onMounted 内执行

参考：app/i18n/config.ts 对 localStorage 的访问使用 import.meta.client 保护。

5. TypeScript 规范

• 避免 any：优先使用具体类型、联合类型、unknown + 类型收窄
• 导出类型：公共类型放入 app/types/，避免在页面/组件中散落重复定义
• API 返回：为接口返回建立明确类型（推荐以业务域分文件维护）

6. 状态管理（Pinia）

• Store 统一放在 app/store/，按业务域拆分（如 user.ts、cart.ts）
• 命名建议：useXxxStore
• 只把“跨页面/跨组件共享且有价值”的状态放入 store；页面私有状态留在组件内

7. API 请求与错误处理

7.1 统一请求入口

• 新代码优先使用 app/composables/useApi.ts（统一处理：baseURL、headers、登录态、错误提示等）
• app/utils/request.ts 属于 兼容层/适配器（对旧调用方式保持向后兼容）

7.2 SSR 友好请求

按照 app/utils/request.ts 的约定：

• 页面初始化/SSR 场景：使用 request（内部委托 useApiFetch / useFetch）
• 交互触发/客户端场景：使用 asyncRequest（内部委托 useApi / $fetch）

7.3 错误处理

• 禁止空 catch：如确需吞错，请说明原因并记录必要信息
• 用户可感知失败需给出明确提示（message/弹窗），并保证不会卡死页面

8. 国际化（i18n）

• i18n 配置：app/i18n/config.ts，Nuxt 配置：nuxt.config.ts 中 @nuxtjs/i18n
• 文案：
  • 业务文案统一走 $t(...)
  • 避免在组件内硬编码大量中文/英文文案
• 未翻译 key 的处理：
  • 当前实现会在海外场景缓存未翻译 key 并上报翻译（见 app/i18n/config.ts）

9. 样式规范

• 全局样式入口：nuxt.config.ts 中 css: ["~/assets/css/global.less"]
• 建议：
  • 组件样式优先使用局部作用域（scoped 或更明确的类名约束）
  • 避免滥用 !important
  • 颜色、间距等建议沉淀为变量（便于主题/多端一致性）

10. 环境变量与运行配置

• 环境变量使用指南：docs/基础文档/环境变量配置指南.md
• 本项目核心环境变量（与 nuxt.config.ts 强关联）：
  • VITE_API_URL、VITE_API_PREFIX
  • VITE_PROXY（是否启用 Nitro 代理转发 /api/**）
  • VITE_SSR（是否启用 SSR）
  • VITE_APP_BASE_URL（部署子路径）

11. 提交与协作（建议）

• 不要混用包管理器：仓库提供 package-lock.json，团队应统一使用 npm（除非迁移并提交对应 lock 文件）。
• PR/合并前建议必做：
  • npm run lint
  • npm run format
  • 对关键改动补充说明文档/变更记录（放在 docs/ 对应模块）

代码审查可直接参考：docs/基础文档/代码质量检查清单.md。

12. 常用命令速查

# 安装依赖
npm install

# 开发
npm run dev

# 构建（会先导出 i18n）
npm run build

# 预览
npm run preview

# 代码检查
npm run lint
npm run lint:fix

# 格式化（仅 app/）
npm run format