waynboot-mobile AGENTS.md

仓库开发指南 (Repository Guidelines)

基于项目的最新技术栈和迁移经验，本指南规范了 waynboot-mobile 的开发约定，以确保代码库的高质量和一致性。

1. 核心技术栈与架构

本项目已全面升级为现代前端技术栈，主要包括：

• 核心框架：Vue 3 (Composition API, <script setup>)
• 构建工具：Vite 4
• UI 组件库：Vant 4
• 状态管理与路由：Vuex 4 & Vue Router 4
• 样式预处理：Sass (Dart Sass，推荐使用 @use 语法) & 配合 postcss-pxtorem 进行移动端视口适配。

目录结构规范

• src/views/：页面级视图组件，通常按功能模块划分（例如 src/views/order/confirm/index.vue）。
• src/components/：全局共享或可复用的 UI 组件（推荐使用 PascalCase 命名，如 NavBar.vue）。
• src/api/：API 接口封装，按业务领域（domain）分组，如 order.js。
• src/store/：Vuex 状态管理模块。
• src/router/：Vue Router 路由配置。
• src/styles/：全局 SCSS/CSS 样式文件。
• src/icons/svg/：SVG 图标资源目录。
• src/assets/：图片等其他静态资源。

2. 开发、测试与构建命令

• 启动开发服务器：npm run dev (通过 Vite 启动本地服务，默认代理 /dev-api)。
• 构建生产包：npm run build:prod。
• 构建测试包：npm run build:dev。
• 代码规范检查：npm run lint (检查 src/ 下的 .js 和 .vue 文件)。
• SVG 图标优化：在 src/icons/svg/ 增删改图标后，运行 npm run svgo 进行压缩和规范化。

测试说明：目前项目未强制配置自动化测试用例，但在提交 PR 或推送代码前，务必在本地运行 npm run lint，并在移动端视图下完成相关功能的冒烟测试。

3. 编码风格与规范

遵循项目根目录的 .editorconfig 和 .eslintrc.js 规则：

• 基础格式：2 个空格缩进，删除行尾多余空格，文件末尾保留一个空行。
• JavaScript/Vue 规范：
  • 强制使用单引号 (')。
  • 不使用分号 (;)。
  • 使用全等号 (=== / !==)。
  • 变量和函数使用 camelCase (小驼峰命名法)。
• Vue 3 语法特别注意：
  • 全面使用 <script setup> 语法。
  • 避免使用 this：使用 useRouter, useRoute, useStore 等 Composition API 替代原有的 this.$router 或 this.$store。
  • Vant 4 调用：对于弹窗或轻提示，直接从 vant 导入函数式 API (如 import { showToast, showDialog } from 'vant')，不要再使用挂载在原型上的方法（如 this.$toast）。
  • 事件派发：使用 const emit = defineEmits(['xxx']) 声明并调用 emit('xxx')，不要使用旧版的 $emit(this, 'xxx')。

UI 与设计规范

总体原则

• 商城前台页面统一参考 DESIGN.md，但在本项目中采用“Apple 风格的浅色化、H5 化落地版本”，不是直接照搬官网的整页纯黑方案。
• 默认设计取向为：设计优先 > 美观优先 > 信息清晰 > 功能完整。
• 但任何视觉方案都不得破坏核心操作链路；当设计表现与下单、筛选、搜索、支付、跳转等关键操作冲突时，必须保证操作可达、状态清晰、信息可读。
• 页面重构不是简单“堆效果”，必须先整理版式层级，再做视觉细化。

页面气质

• 全站优先使用浅色背景体系：页面背景以 #f5f5f7、白色、浅灰为主，文字主色使用 #1d1d1f。
• 交互强调色统一使用蓝色系，优先 #0071e3，链接或弱一级交互可使用 #0066cc。
• 本项目中的 Apple 风格按浅色版本落地：强调留白、层级、字体、蓝色交互和轻模糊，不落地官网式大面积黑底。
• 禁止在商城前台页面使用大面积纯黑背景；首页、分类、搜索、购物车、我的、订单、优惠券等 H5 页面中的主按钮、主区域背景也不得使用纯黑或近黑底色。
• 不允许出现与商城功能无关的品牌文案、口号、长描述、装饰性说明文字。