开发规范

项目开发中需要遵循的约定，确保代码风格统一。

---

通用规则

规则	说明
数据库	使用现有 73 张表，不新增表
验收标准	每个模块末尾有 AC-xxx 格式的验收条件
权限注册	新增 API 需注册到资源管理，新增页面需注册到菜单管理
操作日志	所有订单操作必须写入操作历史表

后端约定

接口路径

• 后台管理：统一使用 /api/ 前缀，如 /api/order、/api/product/list
• 前台会员接口：使用 /member/ 前缀，如 /member/login、/member/address/list
• 前台其他接口：使用 /api/ 前缀，如 /api/home/content、/api/cart/list

数据格式

• 请求参数统一使用 JSON Body（@RequestBody），不使用 URL 参数
• 分页使用 PageHelper.startPage(pageNum, pageSize)
• 响应结构统一为：{ code, message, data }

安全配置

• 不需要登录就能访问的接口，在 application.yml 的白名单中配置
• 后台白名单：mall-admin/src/main/resources/application.yml
• 前台白名单：mall-portal/src/main/resources/application.yml

获取当前用户

• 后台管理员：通过 SecurityContextHolder 获取
• 前台会员：通过 memberService.getCurrentMember() 获取

前端约定

页面风格

• 全站统一 shadcn/ui 风格
• 使用 PageCard 组件包裹内容区域（不用 el-card）
• 表格不加边框（el-table 不加 border）

列表页标准模式

每个列表页遵循统一结构：

筛选搜索区 → PageCard(title="筛选搜索")
数据列表区 → PageCard(title="数据列表")，操作按钮放 header 插槽
分页       → 放在 PageCard 内部，右对齐

通用组件

组件	用途
PageCard	卡片容器，支持标题和 header 插槽
PageHeader	页面标题
ProductCard	商品卡片（前台统一样式）
useTableList	列表页通用逻辑（分页/搜索/重置）

API 文件

• 后台接口文件：src/apis/*.ts，路径带 /api/ 前缀
• 前台接口文件：src/apis/portal.ts

Vite 代理

前端路径	代理到	说明
/api	http://localhost:8080	后台管理接口
/papi	http://localhost:8085	前台商城接口（去掉 /papi 前缀）
/member	http://localhost:8085	会员接口

Element Plus 注意事项

• 对话框显隐：用 v-model，不要用 v-model:visible
• 单选按钮：用 :value，不要用已废弃的 :label

模块结构

mall (父项目)
├── mall-common      → 通用工具类
├── mall-mbg         → 数据库访问层（MyBatis Generator 生成）
├── mall-security    → 安全认证（JWT + 权限）
├── mall-admin       → 后台管理 API（端口 8080）
├── mall-admin-web   → 后台管理前端（端口 5173）
├── mall-portal      → 前台商城 API（端口 8085）
└── mall-search      → 搜索服务（待配置 ES）

依赖顺序：mall-common → mall-mbg → mall-security → mall-admin / mall-portal