# AGENTS.md

本文件是给 Codex 或其他自动化代理使用的项目协作指南。进入本仓库后，先阅读本文件，再阅读具体任务涉及的真实文件。

## 项目概况

- 仓库路径：`E:\project\yelaixiang`。
- 项目类型：前端混合仓库，包含 Vue2 管理后台和微信小程序端。
- 管理后台：基于 RuoYi-Vue 3.8.7、Vue 2.6、Vue Router 3、Vuex 3、Element UI、Axios、Vue CLI 4。
- 小程序端：根目录包含 `app.js`、`app.json`、`pages/`、根级 `utils/`、`project.config.json`，由微信开发者工具识别为小程序项目。
- 依赖文件：存在 `pnpm-lock.yaml`，但仓库脚本和 `bin/*.bat` 使用 `npm run ...`。不要随意更换包管理器或重写锁文件。

## 重要目录

- `src/main.js`：管理后台入口，注册 Element UI、全局组件、全局方法、字典组件、权限控制。
- `src/router/index.js`：后台固定路由和动态路由入口。新增后台页面时，先确认是后端菜单动态路由还是本文件中的本地固定路由。
- `src/permission.js`：后台路由守卫，依赖 token、用户信息和动态路由生成。
- `src/utils/request.js`：后台 Axios 统一封装，处理 baseURL、Authorization、响应码、重复提交、文件下载。
- `src/api/`：后台接口封装。新增或修改接口时优先在对应业务目录中维护，不要在 Vue 页面里直接散写请求。
- `src/views/`：后台页面。业务模块包括系统管理、监控、订单、技师、项目、优惠券、评价、财务、租户等。
- `src/store/`：后台 Vuex 状态，权限、用户、字典、标签页等逻辑应复用现有模块。
- `src/components/`：后台通用组件，优先复用现有 RuoYi 组件和 Element UI 组件。
- `pages/`：微信小程序页面，页面通常由 `.js`、`.json`、`.wxml`、`.wxss` 或 `.scss` 组成。
- 根级 `utils/`：小程序端工具和请求封装，与 `src/utils/` 不是同一套运行环境。
- `style/`：小程序端公共样式和 tabBar 图标资源。
- `public/`：后台 Vue CLI 静态资源。
- `bin/`：Windows 批处理脚本，当前封装了后台运行和打包命令。

## 工作原则

- 默认使用中文沟通，先分析真实代码路径，再做小范围、易审查的修改。
- 修改前说明会改哪些文件，并给出 3 到 6 个要点的计划。
- 不要凭空新增接口、路径、环境变量、页面路由或配置项。若不确定，先用 `rg` 搜索项目。
- 后台和小程序是两套入口与请求体系，修改时必须先确认目标端，不要把 `src/utils/request.js` 和根级 `utils/httpService.js` 混用。
- 保持现有代码风格：JavaScript、Vue 单文件组件、2 空格缩进、单引号、无分号，遵循 `.eslintrc.js` 和 `.editorconfig`。
- 尽量复用 RuoYi 现有模式，包括 `src/api/*` 接口封装、`Pagination`、`RightToolbar`、`DictTag`、权限指令、字典工具和下载工具。

## 后台开发规则

- API 调用放在 `src/api/` 对应业务文件中，页面通过导入函数调用。
- GET 请求参数使用 `params`，POST/PUT 请求体使用 `data`，保持与 `src/utils/request.js` 的拦截器行为一致。
- 需要携带登录态的后台请求走统一 Axios 实例，不要手动拼接 Authorization。
- 新增后台页面时，优先检查后端是否通过 `/getRouters` 返回动态路由；只有本地固定入口、隐藏页、详情页等才修改 `src/router/index.js`。
- 新增权限控制时，优先使用已有权限指令、`auth` 插件和路由 `permissions`/`roles` 规则。
- 列表页优先沿用 RuoYi 常见结构：查询表单、分页、`loading` 状态、`queryParams`、增删改查 API、`Pagination`。

## 小程序开发规则

- 小程序接口优先维护 `pages/api/index.js` 和 `pages/api/request.js`，旧的根级 `utils/httpService.js`、`utils/remoteDataService.js` 也可能被页面引用，改动前先查调用方。
- 新增页面必须同步维护 `app.json` 的 `pages` 列表；涉及 tabBar 时同步检查图标资源与路径。
- 小程序登录、token、用户信息目前分散在 `app.js`、`pages/api/request.js`、本地 storage 中。调整登录态前必须先梳理完整调用链。
- 不要把小程序硬编码域名、AppID、token 或其他敏感配置复制到新文档、日志或回复中；如需变更，优先改为环境或配置注入，并让用户提供具体值。
- 微信能力相关变更需要说明需在微信开发者工具中验证，命令行构建不能完全替代。

## 命令

在执行命令前说明目的。优先运行与改动最相关的检查。

```bash
# 安装依赖，按当前 README 和脚本习惯使用 npm
npm install

# 启动 Vue 管理后台，默认端口来自 vue.config.js
npm run dev

# 后台 ESLint 检查
npm run lint

# 构建测试或预发环境
npm run build:stage

# 构建生产环境
npm run build:prod
```

Windows 下也可以使用：

```bat
bin\run-web.bat
bin\build.bat
```

## 验证建议

- 只改后台 JS/Vue：优先运行 `npm run lint`；影响构建配置、路由、全局入口或依赖时，再运行 `npm run build:stage` 或 `npm run build:prod`。
- 只改小程序页面：命令行检查有限，至少做文件读回和调用链检查；涉及交互、授权、支付、扫码、地图、上传时，需要微信开发者工具验证。
- 只改文档：读回目标文件，必要时用 `git diff -- AGENTS.md` 核对。

## 安全规则

- 不要新增遥测、统计、埋点或额外网络请求，除非用户明确要求。
- 不要提交、打印或复制 token、私钥、`.env` 内容、真实账号密码、支付密钥、上传凭证等敏感信息。
- 仓库中已有环境文件和硬编码地址时，只引用文件路径和配置用途，不在回复或新文档中展开具体敏感值。
- 若任务需要密钥或环境差异配置，要求用户通过环境变量或本地配置提供，不要把值写死进代码。

## 修改边界

- 优先保持小 diff。不要顺手重构无关页面、格式化全仓、重排路由或重写请求层。
- 遇到已有未提交改动时，先确认是否与任务相关；不要回滚用户改动。
- 发现编码显示异常、历史注释乱码或旧代码风格不一致时，不要做无关清理。只在任务必须触达的行附近做最小修复。
- 修改完成后，输出简短摘要、修改文件列表、执行过的验证命令及结果。