我是个攻城狮
150 lines
9.0 KiB
Markdown
150 lines
9.0 KiB
Markdown
# AGENTS.md
|
||
|
||
本文件面向在当前仓库中协作的智能编码代理，目标是帮助代理快速理解项目结构、开发方式和既有约定，并在不破坏现有行为的前提下做最小改动。
|
||
|
||
## 1. 项目概览
|
||
|
||
- 项目类型：`uni-app`，以 `Vue 2 + Vuex + uni-app H5` 为主。
|
||
- 入口文件：`main.js`；根组件：`App.vue`；页面注册：`pages.json`。
|
||
- H5 路由：`router/index.js`，基于 `js_sdk/hhyang-uni-simple-router`。
|
||
- 运行配置：`config.js`、`vue.config.js`、`manifest.json`、`pages.json`。
|
||
- 当前未发现需合并的其他规则文件：`.cursorrules`、`.cursor/rules/`、`.github/copilot-instructions.md`、`CLAUDE.md` 均不存在。
|
||
|
||
## 2. 目录结构与模块组织
|
||
|
||
### 根目录关键文件
|
||
|
||
- `main.js`：应用启动、全局原型方法、请求封装、路由挂载。
|
||
- `App.vue`：全局生命周期与样式入口。
|
||
- `pages.json`：页面声明、全局样式、easycom 配置。
|
||
- `config.js`：接口地址、`app_id`、H5 地址等运行参数。
|
||
- `vue.config.js`：H5 构建配置、`postcss-px-to-viewport`、本地代理。
|
||
- `template.h5.html`、`uni.scss`：H5 模板与全局 SCSS 变量入口。
|
||
|
||
### 源代码目录
|
||
|
||
- `pages/`：主业务页面；优先修改 `pages.json` 已注册的正式页面。
|
||
- `pages/part/`：页面级公共组件，如 `layout.vue`、`header.vue`、`footer.vue`、`member_left.vue`、`pay.vue`。
|
||
- `components/`：通用组件，如 `jxs-slider/`、`u-charts/`、`uni-popup/`、`w-picker/`。
|
||
- `common/`：工具与辅助逻辑，如 `utils.js`、`bus.js`、`pc.js`。
|
||
- `router/`：H5 路由配置；`store/`：Vuex 状态；`styles/`：全局样式。
|
||
- `js_sdk/`：本地/第三方 SDK，重点是 `hhyang-uni-simple-router/`。
|
||
- `uni_modules/`：模块插件，如 `uview-ui/`、`uni-icons/`、`qiun-data-charts/`、`hjy-sign/`。
|
||
|
||
### 资源、测试与构建产物
|
||
|
||
- 静态资源主要在 `static/img/`、`static/imgs/`，页面大量使用相对路径引用。
|
||
- 当前未发现测试目录、`*.spec.*`、`*.test.*` 文件。
|
||
- 不直接编辑 `node_modules/`、`unpackage/`、`.hbuilderx/`。
|
||
|
||
### 备份/副本文件
|
||
|
||
- 仓库存在 `pages/index - 副本.vue`、`pages/game copy.vue`、`pages/asset_list copy.vue`、`config - 副本.js`、`pages/development1.vue` 等历史文件。
|
||
- 除非用户明确要求，否则不要修改这类“副本 / copy / 试验”文件。
|
||
|
||
## 3. 路由与页面协作
|
||
|
||
- 新增页面时，至少同步更新 `pages.json`。
|
||
- H5 需要别名访问时，通常还要同步更新 `router/index.js`。
|
||
- H5 首页依赖 `router/index.js` 中 `aliasPath: '/'`，不要随意改动。
|
||
- H5 通过 `RouterMount(app, '#app')` 挂载；非 H5 仍走 `app.$mount()`。
|
||
- 修改页面路径、文件名或导航逻辑时，至少检查：`pages.json`、`router/index.js`、页面内跳转代码。
|
||
|
||
## 4. 构建、运行、lint、测试
|
||
|
||
### 当前仓库现状
|
||
|
||
- 根目录 `package.json` 没有定义 `scripts`。
|
||
- 已确认可用命令：`npm install`。
|
||
- `vue.config.js` 中已配置 H5 代理，`/api` 转发到 `https://static-cog.scszsj.com`。
|
||
- 当前未发现 `eslint`、`prettier`、`stylelint` 脚本。
|
||
- 当前未发现 `jest`、`vitest`、`mocha`、`cypress` 等测试框架配置。
|
||
|
||
### 给代理的执行建议
|
||
|
||
- 运行、预览、发布更接近依赖 HBuilderX，而不是 npm scripts。
|
||
- 用户要求“构建/运行项目”时，优先按 uni-app / HBuilderX 方式处理，不要先假设有 Vite/Webpack 脚本。
|
||
- 用户要求“lint”时，应先说明仓库未配置 lint 脚本。
|
||
- 用户要求“测试”或“单个测试”时，应先说明当前没有现成测试框架与测试用例。
|
||
- 当前状态下无法运行单个测试；若后续新增测试框架，需补充测试入口与单测筛选命令。
|
||
|
||
## 5. 代码风格与实现习惯
|
||
|
||
### JavaScript / Vue
|
||
|
||
- 代码以 Options API 为主：`data`、`created`、`methods`、`watch`。
|
||
- 当前不是 TypeScript 项目；新增代码默认使用 `JS + Vue SFC`。
|
||
- 页面内公共布局通常由 `pages/part/*.vue` 组合，不主动抽复杂全局体系。
|
||
- 页面脚本里常把表单对象初始化为 `[]` 后再挂字段，这是历史写法；除非顺手修复当前问题，不要大面积“规范化”。
|
||
- 修改时保持局部风格一致，不做整仓格式化。
|
||
|
||
### imports / 命名 / 格式
|
||
|
||
- 先导入框架与第三方库，再导入本地模块。
|
||
- 本地导入以相对路径为主；若文件已稳定使用相对路径，不要仅为风格改成 `@/`。
|
||
- 组件注册名大小写并不统一，如 `memberleft`、`pay`；修改现有页面时保持原注册名即可。
|
||
- 页面文件常用小写或下划线风格，如 `asset_add.vue`、`pay_detail.vue`。
|
||
- 若字段名明显来自后端返回或接口参数，不要擅自重命名。
|
||
|
||
### 样式
|
||
|
||
- 全局样式主要来自 `styles/common.scss` 与 `styles/style.scss`。
|
||
- H5 适配依赖 `postcss-px-to-viewport`，默认会把 `px` 转成 `vw`；不想转换时可使用 `.ignore-` 选择器约定。
|
||
- 不要随意调整全局 `html` 字号和样式入口，除非用户明确要求。
|
||
- uni-app H5 中不要给 `input`、`textarea` 设置 `box-sizing: border-box`，否则可能导致无法聚焦或无法输入。
|
||
- 页面样式普遍直接引用 `static/img`、`static/imgs` 资源，并大量使用固定宽高；改版时优先保持目录与引用方式。
|
||
|
||
### easycom / uni_modules
|
||
|
||
- `pages.json` 已开启 `easycom.autoscan`。
|
||
- 当前自定义映射：`html2canvas -> html2canvas/dist/html2canvas.esm.js`。
|
||
- 使用 `uni_modules` 中已有组件时，优先沿用现有接入方式，不要重复复制到 `components/`。
|
||
|
||
## 6. 数据请求、错误处理与状态
|
||
|
||
- 全局请求封装在 `main.js`，通过 `Vue.prototype._get`、`Vue.prototype._post` 调用。
|
||
- 请求默认会附带 `token` 与 `app_id`。
|
||
- 登录失效由请求层统一处理：接口返回 `code === -1` 时触发 `doLogin()`。
|
||
- 页面错误提示普遍使用 `uni.showToast({ icon: 'none', ... })`；必要时中断流程。
|
||
- 现有代码中有不少 `console.log` 调试输出；新增代码不要继续扩散无意义日志。
|
||
|
||
### 接口调用隐性约定
|
||
|
||
- 接口路径通常只传业务片段，`main.js` 会统一拼接 `/api/` 前缀。
|
||
- 接口命名大小写并不统一，如 `asset.asset/index`、`asset.Asset/paymentDetail`、`user.User/updateInfo`、`gameasset.GameAsset/index`。
|
||
- 现有代码里接口路径是否以 `/` 开头也不统一；复用同一模块接口时优先跟随原写法，不要顺手批量改。
|
||
- 申请类页面常调用 `game.Apply/add` 或 `game.Apply/addApply`；改“我要资金/发行/技术”等表单时，先搜索同类页面保持参数结构一致。
|
||
|
||
### 状态管理
|
||
|
||
- `store/index.js` 当前较空，很多状态仍放在页面内部。
|
||
- 不要为了“更规范”就把局部状态机械迁移到 Vuex。
|
||
|
||
## 7. 隐性约定与协作边界
|
||
|
||
- 优先做最小正确改动，不主动重构超长 Vue 页面。
|
||
- 不主动清理历史副本文件、旧调试代码，除非它们直接影响当前需求。
|
||
- 修改接口请求、路由、登录态、上传、支付流程时，必须检查相关页面是否复用同逻辑。
|
||
- 变更静态资源路径时，要检查 H5 相对路径是否仍然有效。
|
||
|
||
### 页面跳转与布局约定
|
||
|
||
- H5 跳转是混用的：导航栏、页头、侧边菜单多用 `this.$router.push/replace({ path: 'xxx' })`；业务流程页也常直接用 `uni.navigateTo({ url: '/xxx' })`。
|
||
- 修改跳转时优先保持所在文件原有方式，不要在单页里再引入第三种封装；改完后手工验证 H5 路由是否正常。
|
||
- 项目大量使用短路径，如 `path: 'login'`、`url: '/apply'`，这是既有行为，新增同类跳转先参考相邻页面。
|
||
- `layout.vue` 常用于首页/资讯页等含 Banner 的页面；`layouts.vue` 用于常规内页；`layoutNo.vue` 用于不展示移动端头尾的内容页；`layoutNoh.vue` 常用于登录/注册/忘记密码等轻页面。
|
||
- 多个布局组件都会在 `created` 中请求 `game.index/setting` 获取站点配置；新增整页时优先复用布局，不要重复在页面里拉同类站点信息。
|
||
|
||
### 组件复用与前置校验
|
||
|
||
- 成员中心页面通常采用 `Layout + member_left + 右侧内容区` 双栏结构；付款场景会额外复用 `pages/part/pay.vue`。
|
||
- 资产新增、资产列表、付款记录等成员页进入关键操作前，常先检查 `apply_status`、`third_auth_status` 等本地认证状态；修改这些流程时不要漏掉前置校验。
|
||
- “我要发行 / 技术 / 出海 / 补贴”等专题页常带 `uni-popup` 申请弹窗，提交成功后关闭弹窗并 toast 提示；新增同类落地页时优先沿用该交互。
|
||
|
||
## 8. 给代理的工作建议
|
||
|
||
- 动手前先确认目标文件是正式入口文件，而不是“副本”。
|
||
- 涉及导航先看 `pages.json` 与 `router/index.js`；涉及接口先看 `main.js` 的 `_get` / `_post` 约定。
|
||
- 涉及样式先判断是否受全局 SCSS、`vw` 转换或 H5 输入框兼容性影响。
|
||
- 仓库当前缺少自动化验证手段；完成改动后，应至少说明需要用户手工验证的页面、流程或平台。
|