# 项目协作指南

本仓库是一个基于 Vite 的 H5 Web 项目。本文档用于约束自动化 Agent 在仓库内的工作方式、目录约定与验证流程。

## 技术栈与入口

- 构建：Vite 5（ESM，`package.json` 中 `"type": "module"`）
- 框架：Vue 3 + TypeScript
- 路由：vue-router 4（入口为 `src/router/index.ts`，当前路由配置较少/可能未完成）
- 状态管理：Pinia（`src/stores/`）
- UI：Vant 4
- 样式：Tailwind CSS v4（通过 `@tailwindcss/vite`），并存在组件级 SCSS
- 国际化：vue-i18n（`src/i18n/`，含 Vant 语言同步）
- 网络/事件：axios、mitt

入口文件：

- 应用入口：`src/main.ts`
- 根组件：`src/App.vue`（`<RouterView />`）
- 全局样式/主题：`src/styles/main.css`

## 目录结构与新增代码放置

- 页面：`src/pages/<module>/...`
- 公共组件：`src/components/<ComponentName>/...`
- 国际化：`src/i18n/`
  - 语言包按模块拆分：`src/i18n/modules/{common,home,quick}/`
- 工具/请求：`src/utils/`（当前存在 `requets.ts`，文件名可能为历史拼写；不要在未确认引用关系前擅自更名）

组件目录常见形态（尽量遵循）：

- `src/components/Foo/index.vue`
- `src/components/Foo/styles/index.scss`
- 可选：`README.md`、`demo.vue`、`prompt.md`、`images/`

## 代码风格约定

- Vue 组件优先使用 `<script setup lang="ts">`
- 组件样式优先放在同目录 `styles/index.scss`，并在组件内通过 `lang="scss"` + `scoped` 方式引入/编写
- 全局主题与 Vant CSS 变量覆盖集中在 `src/styles/main.css`，避免把全局变量散落到页面/组件中
- TypeScript：开启 `strict`、`noUnusedLocals`、`noUnusedParameters` 等约束；新增代码需保持零 TS 报错
- 路径别名：`@/* -> src/*`（TS 与 Vite 均配置），新增引用优先使用 `@/` 形式

本仓库未集成 ESLint/Prettier 等统一格式化工具：变更时以“周边现有代码”为准保持一致性。

## 开发、构建与测试（变更后必须执行）

使用 Yarn。

- 安装依赖：`yarn`
- 本地开发：`yarn dev`（Vite dev server，端口 5174）
- 类型检查：`yarn typecheck`
- 构建：`yarn build`（包含 `vue-tsc --noEmit`）
- 预览：`yarn preview`
- 测试：`yarn test`（Node 原生 test runner，匹配 `src/**/*.test.ts`）

说明：

- `tsconfig.json` 排除了 `src/**/*.test.ts`，测试文件如需 TS 类型支持，请在测试内保持自包含，或按项目既有方式处理

## 修改流程（Agent 工作方式）

- 先定位：优先通过搜索/阅读定位真实调用链与使用方，再进行修改
- 小步提交：单次变更聚焦一个问题点；避免“顺手重构”影响范围
- 保守增依赖：不要新增第三方依赖或升级版本；确有必要时先征询确认并说明替代方案
- 不破坏接口：组件 props/事件/样式类名若被页面依赖，变更需兼容旧用法或同步修改所有调用点
- 变更必验证：完成代码修改后至少运行 `yarn typecheck`；涉及构建与运行差异时再运行 `yarn build` 与相关测试
- 开发计算时，有临时分支，需要提醒用户选择分支合并

## 限制条件

- 不要废话
- 不要缺失代码
- 不要出现伪需求
- 没有提及的代码不要修改
- 需要编译时就提醒用户手动确定
- 需要测试时就提醒用户手动执行
- 有滚动条的区域，需要添加scrollbar-none [-ms-overflow-style:none] [&::-webkit-scrollbar]:hidden 类名