qihang-ecom-erp-open/AGENTS.md

AGENTS.md - 智能编码指南

项目概述

启航电商ERP系统 (qihang-ecom-erp-open) 技术栈：

• 前端: Vue 2 + ElementUI + Vuex + Vue Router
• 后端: SpringCloud 微服务 (Java 17) + Maven
• 数据库: MySQL 8 + Redis 7

---

构建与测试命令

前端 (Vue)

cd vue
npm install
npm run dev              # 开发服务器 (端口 88)
npm run build:prod      # 生产构建
npm run build:stage      # 测试环境构建
npm run preview          # 预览构建结果
npm run lint             # 代码检查
npm run lint -- --fix    # 自动修复
npx eslint --ext .js,.vue src/views/example.vue  # 检查单个文件

后端 (Java/Maven)

mvn clean install                  # 构建所有模块
mvn clean package -DskipTests     # 构建跳过测试
mvn -pl <module-name> clean install  # 构建指定模块
java -jar target/*.jar            # 运行 SpringBoot 应用

---

代码风格指南

基本原则

1. 添加注释 - 除非用户明确要求，否则要添加注释
2. 中文注释 - 如需注释，使用中文
3. 保持一致 - 遵循现有代码模式

---

Vue/JavaScript 规范

命名规范

• 组件: PascalCase (UserProfile.vue)
• 文件/变量: camelCase (userName, orderList)
• 常量: UPPER_SNAKE_CASE
• 布尔变量: 使用 is、has、can 前缀

导入顺序

1. Vue/Vue Router/VueX
2. 第三方库 (axios, element-ui)
3. @ 别名导入 (@/utils, @/api)
4. 相对路径 (./, ../)

// 正确示例
import Vue from 'vue'
import axios from 'axios'
import { getToken } from '@/utils/auth'
import Cookies from 'js-cookie'

ESLint 格式化

• 缩进: 2 空格
• 引号: 单引号
• 分号: 不使用
• 大括号: 1TBS 风格

模板规范

• 组件名 PascalCase 或 kebab-case
• v-for 必须带 :key

<template>
  <el-input v-model="form.username" />
  <UserProfile :user-id="userId" />
</template>

组件结构

<template>
  <!-- 模板内容 -->
</template>

<script>
export default {
  name: 'ComponentName',
  components: {},
  props: {},
  data() { return {} },
  computed: {},
  watch: {},
  created() {},
  methods: {}
}
</script>

<style lang="scss">
/* 样式内容 */
</style>

---

Java 规范

包结构

cn.qihangerp
├── api/              # Controller
├── module/service    # Service 接口
├── serviceImpl/      # Service 实现
├── mapper/           # MyBatis Mapper
├── model/            # Entity, DTO, VO, BO
│   ├── entity/       # 数据库实体
│   ├── dto/          # 数据传输对象
│   ├── vo/           # 视图对象
│   ├── bo/           # 业务对象
│   └── query/        # 查询条件
└── common/           # 通用工具

命名规范

• 类: PascalCase
• 接口: 以 I 开头 (IUserService)
• 方法: camelCase

Spring 规范

• Service: I{Entity}Service / {Entity}ServiceImpl
• Controller: {Entity}Controller
• 使用 @Autowired 注入
• 使用 MyBatis-Plus IService<T>

代码风格

• 使用 Lombok @Data, @Slf4j
• 使用 fastjson2 处理 JSON
• 返回 ResultVo<T>
• 使用 PageQuery / PageResult<T> 分页

public interface OOrderService extends IService<OOrder> {
    PageResult<OOrder> queryPageList(OrderSearchRequest bo, PageQuery pageQuery);
    ResultVo<Integer> manualShipmentOrder(OrderShipRequest shipBo, String createBy);
}

---

错误处理

前端: 使用 ElementUI this.$message() 反馈

this.$message({ message: '操作失败', type: 'error' })

后端: 返回 ResultVo 错误码，使用 @ExceptionHandler

@ExceptionHandler(Exception.class)
public ResultVo<String> handleException(Exception e) {
    return ResultVo.error(e.getMessage());
}

---

Git 工作流

1. 从 main 创建功能分支
2. 提交格式: feat: add feature / fix: resolve issue
3. 提交前运行 npm run lint

---

项目目录结构

前端 (vue/src/)

vue/src/
├── api/           # API 接口定义
├── assets/        # 静态资源
├── components/    # 公共组件
├── layout/        # 布局组件
├── plugins/       # Vue 插件
├── router/        # 路由配置
├── store/         # Vuex 状态管理
├── utils/         # 工具函数
└── views/         # 页面组件

后端模块

api/          # API 模块 (gateway, erp-api, open-api, ai-agent)
core/         # 公共库
mapper/       # MyBatis Mapper
model/        # 实体类
service/      # Service 接口
serviceImpl/  # Service 实现

---

开发技巧

路径别名

使用 @ 代替相对路径

// 推荐
import foo from '@/utils/foo'
// 避免
import foo from '../../../utils/foo'

API 请求

通过 utils/request.js，自动处理 token 和 401

环境变量

在 vue/ 下创建 .env.development

VUE_APP_BASE_API=/prod-api
NODE_OPTIONS=--openssl-legacy-provider

---

技术栈版本

• Node.js >= 20.0.0 | Java 17 | Maven 3.9
• Vue 2.6.12 | ElementUI 2.15.13
• Spring Boot 3.0.2 | Spring Cloud 2022.0.0

---

平台命名规范

平台	前缀	示例
淘宝/天猫	Tao	TaoOrderService
京东	Jd	JdGoodsService
拼多多	Pdd	PddOrderService
抖音/抖店	Dou	DouRefundService
微信小店	Wei	WeiOrderService
线下/私域	Offline	OfflineOrderService

---

关键文件

文件	用途
vue/src/utils/request.js	Axios 拦截器
vue/src/utils/auth.js	Token 管理
vue/src/api/	API 端点定义
vue/src/store/	Vuex 模块
vue/.eslintrc.js	ESLint 配置
vue/vue.config.js	Vue CLI 配置
pom.xml	Maven 父 POM

---

数据库规范

• 表名: o_ 订单, g_ 商品, s_ 库存
• 使用 MyBatis-Plus 注解
• Entity 类位于 model/src/main/java/cn/qihangerp/model/entity/
• 使用 PageQuery 分页查询
• 时间戳: createTime, updateTime

---

API 响应格式

后端

// 成功
ResultVo.success(data);
ResultVo.success();

// 失败
ResultVo.error("错误信息");
ResultVo.error(500, "错误信息");

前端

// 统一通过 utils/request.js 处理
// 成功返回 res.data，失败抛出异常