yelaixiang/AGENTS.md

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 或其他敏感配置复制到新文档、日志或回复中；如需变更，优先改为环境或配置注入，并让用户提供具体值。
• 微信能力相关变更需要说明需在微信开发者工具中验证，命令行构建不能完全替代。

命令

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

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

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

# 后台 ESLint 检查
npm run lint

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

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

Windows 下也可以使用：

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