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：

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 组件或已有组件封装

验证建议

常规变更后至少运行：

npm run build

涉及类型或 TS 文件时可运行：

npm run build-ts

涉及页面交互时建议启动：

npm run dev

然后在浏览器中检查对应 hash 路由。

协作注意事项

• 不要覆盖用户未提交的改动；修改前先查看 git status --short
• 发布相关操作涉及远程服务器和分支切换，执行前需要确认当前分支和用户意图
• voice_upload 会构建、打包、上传、远程解压并清理本地产物，属于发布操作，不能在未确认时执行
• .env.development 内有调试账号信息，避免无关改动
• 生产环境路径依赖 /f/voice/，改动 VITE_BASE 或 VITE_OUTDIR 前要确认部署要求