开发规范

版本：v3.0 ｜ 最后更新：2026-07 ｜ 文档状态：已同步代码

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

---

通用规则

规则	说明
数据库	使用 docs/sql/mall.sql 现有表，不新增表。表数量唯一来源见 docs/dev/context.md 第 3.1 节
验收标准	每个模块末尾有 AC-xxx 格式的验收条件
权限注册	新增 API 需注册到资源管理，新增页面需注册到菜单管理
操作日志	所有订单操作必须写入操作历史表
文档同步	改接口/路径/表/页面后必须回写对应文档，清单见 AGENTS.md「改代码后必须回写的文档」
状态标注	文档中的完成状态必须与代码核实，禁止留虚假 ✔

后端约定

接口路径

• 后台管理：统一使用 /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 插槽
ProductCard	商品卡片（前台统一样式）

useTableList（composables/useTableList.ts）与 PageHeader（components/PageHeader/）虽在仓库中存在，但当前 0 个页面引用，不作为约定的一部分。

API 文件

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

Vite 代理

前端路径	代理到	说明
/api	http://localhost:8080	后台管理接口
/papi	http://localhost:8085	前台商城接口（rewrite 替换为 /api：/papi/x → /api/x）
/member	http://localhost:8085	会员接口

上传组件使用 /api/minio/upload，命中 /api 规则转发到 mall-admin，无需单独的 /minio 代理。

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

数据存储：MySQL（业务数据）+ Redis（缓存/验证码/登录锁定）+ MongoDB（商品收藏、浏览历史）