hookehuyr

docs: 添加项目文档AGENTS.md

添加详细的项目文档,包含项目概述、常用命令、环境配置、技术栈与构建、目录结构、路由约定、请求约定、编码风格、验证建议和协作注意事项等内容,以便新成员快速了解项目。
Showing 1 changed file with 141 additions and 0 deletions
# AGENTS.md
## 项目概述
本仓库是“童声无界”前端项目,`package.json` 包名为 `tjws`。项目基于 Vue 3、Vite 2、Vant 4、Pinia 和 vue-router,主要面向移动端 H5 场景。
README 当前只包含简短说明:
- 项目名:童声无界
- 发布前需要切换到 `voice` 分支再推送
## 常用命令
- 本地开发:`npm run dev`
- 指定 host 启动:`npm run start`
- 构建:`npm run build`
- 类型检查并构建:`npm run build-ts`
- 预览构建结果:`npm run serve`
- 构建并打包:`npm run build_tar`
- 构建、打包、上传并清理:`npm run voice_upload`
## 环境配置
项目使用 Vite 环境变量。
- `.env`
- `VITE_PORT = 8006`
- `VITE_PROXY_TARGET = http://voice.onwall.cn`
- `VITE_PROXY_PREFIX = /srv/`
- `VITE_OUTDIR = voice`
- `VITE_CONSOLE = 0`
- `.env.development`
- `VITE_BASE = /`
- 包含本地调试用 openid、B 端账号、验证码配置
- `.env.production`
- `VITE_BASE = /f/voice/`
- 生产环境构建公共路径
## 技术栈与构建
- Vue 3 单文件组件
- Vite 2
- Vant 4 移动端组件库
- Pinia 状态管理
- vue-router 4
- Less
- Axios
- `postcss-px-to-viewport`,设计稿宽度为 375,默认将 px 转为 vw
- `unplugin-auto-import` 自动导入 Vue 和 vue-router API
- `vite-plugin-dynamic-import` 支持更灵活的动态导入
- `unplugin-vue-define-options` 支持 `<script setup>` 中定义组件名
构建输出目录由 `VITE_OUTDIR` 控制,默认是 `voice`。生产公共路径由 `.env.production``VITE_BASE=/f/voice/` 控制。
## 目录结构
- `src/main.js`:应用入口,注册 Vue、Pinia、路由、Vant 组件和全局 `$http`
- `src/App.vue`:根组件
- `src/router.js`:路由入口,自动加载模块路由,并处理模拟动态路由
- `src/route.js`:基础公共路由
- `src/router/routes/modules/`:业务路由模块
- `client/`:客户端/家长端路由
- `me/`:个人中心路由
- `business/`:B 端/老师端路由
- `auth/`:授权相关路由
- `src/views/client/`:客户端页面,如首页、选择幼儿园、书籍、视频详情、排行榜、捐赠等
- `src/views/me/`:个人中心页面
- `src/views/business/`:B 端页面
- `src/components/`:业务组件
- `src/composables/`:组合式逻辑
- `src/api/`:接口封装
- `C/`:客户端接口
- `B/`:B 端接口
- `wx/`:微信相关接口
- `src/utils/`:工具函数、axios 封装、路由生成、分享、上传等
- `src/assets/`:样式和静态资源
- `build/proxy.js`:Vite 开发代理生成逻辑
## 路由约定
`src/router.js` 使用 `import.meta.globEager('@/router/routes/modules/**/*.js')` 自动加载所有模块路由。新增业务页面时,优先在对应模块下维护路由文件。
路由使用 hash history:
```js
createWebHashHistory('/index.html')
```
客户端主路由位于 `src/router/routes/modules/client/index.js`,根路径 `/``/client/index` 都指向 `src/views/client/index.vue`
## 请求约定
Axios 封装在 `src/utils/axios.js`
- 默认请求参数包含 `f: 'voice'`
- GET 请求会追加时间戳,避免缓存
- POST 请求默认使用 `qs.stringify` 序列化
- 上传接口和七牛上传地址会跳过 POST 序列化
- 响应 `code === 401` 时跳转 `/auth`,并携带当前 hash 和 `prefixAPI`
- B 端出现“老师请先登录!”或“老师不存在!”时跳转 `/business/login`
新增接口时应优先放入 `src/api/C``src/api/B``src/api/wx` 的对应分组。
## 编码风格
- 保持现有 JavaScript/Vue 风格,项目中 JS 文件较多,TypeScript 只在部分文件中使用
- 优先复用现有组件、composables、工具函数和 API 封装
- 页面样式以移动端为主,注意 px 会被转换为 vw
- 不做无关重构,不随意调整旧页面结构
- 修改路由、请求拦截、全局配置时要评估影响范围
- 项目使用 Vant,新增移动端交互优先采用 Vant 组件或已有组件封装
## 验证建议
常规变更后至少运行:
```bash
npm run build
```
涉及类型或 TS 文件时可运行:
```bash
npm run build-ts
```
涉及页面交互时建议启动:
```bash
npm run dev
```
然后在浏览器中检查对应 hash 路由。
## 协作注意事项
- 不要覆盖用户未提交的改动;修改前先查看 `git status --short`
- 发布相关操作涉及远程服务器和分支切换,执行前需要确认当前分支和用户意图
- `voice_upload` 会构建、打包、上传、远程解压并清理本地产物,属于发布操作,不能在未确认时执行
- `.env.development` 内有调试账号信息,避免无关改动
- 生产环境路径依赖 `/f/voice/`,改动 `VITE_BASE``VITE_OUTDIR` 前要确认部署要求