Goodgame_web/AGENTS.md

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 输入框兼容性影响。
• 仓库当前缺少自动化验证手段；完成改动后，应至少说明需要用户手工验证的页面、流程或平台。