AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

项目概述

这是一个基于 Vue 3 + Vite + Vant 4 的移动端 H5 项目（三坛大戒），用于展示佛教戒期相关信息。

常用命令

# 开发（pnpm/npm/yarn）
pnpm dev                    # 启动开发服务器（默认端口 5173）
pnpm build                  # 构建生产版本
pnpm lint                   # ESLint 检查并修复
pnpm serve                  # 预览构建产物

# 部署（依赖 qshell 和 ssh）
pnpm deploy                 # 执行完整部署流程：构建 -> 七牛上传 -> 服务器打包上传
bash scripts/deploy.sh      # 直接执行部署脚本

项目架构

全局 Loading 机制

项目使用计数器方式管理全局加载状态，优化低网速体验：

• 状态管理：src/stores/loading.js - 使用 pending_count 记录进行中的请求数
• 拦截器集成：src/utils/axios.js - 请求开始 +1，响应成功 -1，错误时重置
• UI 展示：src/App.vue - 全屏蒙版 + van-loading 组件

特殊 API：图片流媒体接口 getImgStreamAPI 配置了 { ignore_loading: true }，不触发全局 loading。

路由级加载：src/router/index.js 中路由守卫也会控制 loading，避免懒加载白屏。

登录态控制

• Token 存储：使用 js-cookie 存储 token-stdj
• 路由守卫：除 ['/', '/jz_login'] 白名单外，所有页面需登录
• 未登录处理：重定向到 /jz_login 并携带 redirect 参数

API 层设计

• API 定义：src/api/index.js - 统一定义接口路径和 JSDoc
• 请求封装：src/api/fn.js - 提供 fn() 处理响应、fetch 基于 axios
• 默认参数：所有请求自动携带 f: 'stdj' 和 timestamp（GET）

API 响应约定：

// 成功响应格式（res.code === 1）
{ code: 1, data: {...}, msg: 'success' }

// 错误处理使用 showFailToast

目录结构

src/
├── api/               # API 接口定义
│   ├── index.js       # 主接口（首页、文章、登录、用户信息）
│   ├── fn.js          # 请求封装与错误处理
│   ├── common.js      # 通用接口
│   └── wx/            # 微信相关（支付、配置等）
├── assets/            # 静态资源
├── components/        # 通用组件（VideoPlayer、LoadingSpinner、EmptyState）
├── router/            # Vue Router 配置（含登录守卫）
├── stores/            # Pinia 状态管理（loading store）
├── utils/             # 工具函数
│   ├── axios.js       # Axios 拦截器（接入 loading 计数）
│   ├── request.js     # Axios 实例导出
│   ├── upload.js      # 上传工具
│   └── vconsole.js    # 调试控制台
├── views/             # 页面组件
└── main.js            # 入口文件

关键配置

移动端适配

• 使用 postcss-px-to-viewport，设计稿基准 375px
• 选择器添加 ignore- 前缀可跳过转换

路径别名

@              → src/
@components    → src/components/
@utils         → src/utils/
@api           → src/api/
@assets        → src/assets/
@views         → src/views/
@stores        → src/stores/

环境变量

• .env - 默认配置
• .env.development - 开发环境
• .env.production - 生产环境

关键变量：

• VITE_BASE - 资源公共路径
• VITE_PROXY_TARGET - 代理目标服务器
• VITE_PROXY_PREFIX - 代理前缀（默认 /srv/）
• VITE_OUTDIR - 构建输出目录（默认 dist）

自动导入

• Vue API：通过 unplugin-auto-import 自动导入（见 auto-imports.d.ts）
• Vant 组件：通过 unplugin-vue-components 按需导入（见 components.d.ts）

部署说明

部署脚本 scripts/deploy.sh 执行以下流程：

1. 构建项目（pnpm run build）
2. 上传静态资源到七牛云（qshell qupload ~/.qshell/stdj_upload.conf）
3. 打包并上传到服务器（scp -P 12101 到 zhsy@oa.jcedu.org:/home/www/f）

依赖：本机需安装 qshell 并配置 ~/.qshell/stdj_upload.conf。

开发注意事项

1. 新增 API：在 src/api/index.js 定义接口，使用 fn(fetch.get/post()) 封装
2. 跳过全局 Loading：请求配置添加 { ignore_loading: true }
3. 路由配置：新页面如需登录，无需添加白名单（默认需登录）；公开页面添加到 white_list
4. 组件命名：文件名 kebab-case，组件名 PascalCase