Appearance

13 开发规范 ​

13.1 类型与命名 ​

  • 新增业务接口优先定义请求、响应和领域模型类型。
  • 使用 type / interface 表达明确边界，避免无理由使用 any。
  • API Client 使用 <Domain>ApiClient 命名。
  • Store 使用 use<Name>Store 命名。
  • Composable 使用 use<Name> 命名。
  • 页面和组件名称应与业务域保持一致。

13.2 请求与状态 ​

  • 页面不要重复创建 $fetch 实例。
  • 统一使用 API Client，必要时通过 Transformer 转换数据。
  • 认证和公司、语言参数交给 HTTP 插件统一注入。
  • 乐观更新必须保存旧值，并在请求失败时回滚。
  • 服务端执行路径不得直接访问浏览器存储。

13.3 国际化 ​

  • 用户可见文案使用 locale 资源。
  • 路由使用 useLocalePath()。
  • 新增语言同步修改语言定义、资源文件和接口映射。
  • 对阿拉伯语等 RTL 语言进行布局回归。

13.4 测试 ​

项目脚本提供 Vitest，部分 API Client、装修区块和工具函数已有测试文件。新增逻辑建议覆盖：

  • 正常响应和业务错误响应。
  • 401、网络错误、超时和重试行为。
  • 登录跳转及 redirect 参数。
  • 购物车乐观更新和失败回滚。
  • DSL 缺省配置、未知区块和链接解析。
  • 多语言路径和 locale 规范化。

13.5 提交前检查 ​

bash
pnpm lint
pnpm test
pnpm build

如果只修改样式或文档，也应至少执行 lint；修改 Nuxt 配置、类型、插件或请求层时应执行完整检查。

13.6 常见排障 ​

  • 接口地址错误：检查 .env、NUXT_PUBLIC_API_BASE，修改后重新构建。
  • 未登录反复跳转：检查 token Cookie、auth.global.ts 和语言前缀处理。
  • SSR 报 localStorage 未定义：将代码放到客户端分支或客户端插件。
  • 接口参数不符合后端要求：检查 HTTP 插件是否应使用 form-urlencoded、useJson 或跳过全局参数。
  • 购物车金额不一致：区分前端估算值和后端汇总值，优先以后端返回为准。
  • 装修区块不显示：检查 DSL 类型、注册表映射、默认 settings 和组件空数据处理。