主题
Mall 商城系统 · 接口能力总览
版本：v3.0 ｜ 最后更新：2026-07 ｜ 文档状态：持续迭代中
文档性质：系统交互协议说明
适用范围：前台商城 + 后台管理全部接口
一、文档说明
本文档定义 Mall 商城系统对外提供的服务交互协议，包括统一的响应规范、认证机制、分页约定和错误处理策略。各模块的具体接口能力描述，请参阅对应的模块 PRD 中「接口能力」章节。
📌 本文档第 6 节的能力条目已与代码逐一核对，共 65 项（后台管理 40 项 + 前台商城 25 项）。精确的接口路径、请求方式请查阅
docs/api/admin-api.md与docs/api/portal-api.md。
二、服务分区
系统按使用端划分为两个独立的服务域：
| 服务域 | 面向用户 | 职责范围 |
|---|---|---|
| 后台管理服务 | 管理员、运营人员 | 商品管理、订单处理、会员管理、营销配置、权限控制、系统设置 |
| 前台商城服务 | 消费者（会员/游客） | 商品浏览、搜索、购物车、下单支付、售后、个人中心 |
两个服务域独立部署、独立鉴权，共享底层数据。
三、统一响应协议
系统所有接口遵循统一的响应结构，包含三个要素：
| 要素 | 说明 |
|---|---|
| 状态码 | 标识本次请求的处理结果 |
| 提示信息 | 面向用户的可读描述，成功时为"操作成功"，失败时为具体原因 |
| 业务数据 | 请求对应的返回内容，结构因接口而异 |
状态码定义
| 状态码 | 含义 | 典型场景 |
|---|---|---|
| 200 | 请求成功 | 正常返回数据或操作完成 |
| 400 | 请求参数有误 | 必填项缺失、格式不合法、业务校验不通过 |
| 401 | 身份未认证 | 未登录、登录凭证过期 |
| 403 | 无操作权限 | 当前角色不具备该功能的访问权限 |
| 500 | 服务内部异常 | 系统不可预期的错误 |
错误提示规范
- 业务校验失败（400）：返回明确的业务原因，如"验证码错误"、"商品库存不足"、"该分类下存在商品，无法删除"。
- 认证失败（401）：前端应引导用户重新登录。
- 权限不足（403）：前端应提示"暂无权限访问该功能"。
四、认证机制
后台管理
采用「账号 + 密码 + 图形验证码」的登录方式：
- 用户请求获取图形验证码（图片形式返回，同时下发验证码标识）。
- 用户提交账号、密码、验证码内容进行登录。
- 登录成功后，系统签发访问凭证（Token），后续所有请求携带该凭证。
- 凭证具有时效性，过期后需重新登录。
- 连续登录失败达到阈值后，账号将被临时锁定。
前台商城
采用「用户名/手机号 + 密码」的登录方式：
- 会员通过用户名或手机号加密码登录。
- 登录成功后签发访问凭证，机制与后台一致。
- 部分接口（如商品浏览、搜索）允许游客访问，无需登录。
- 涉及个人数据的操作（购物车、订单、收藏等）必须登录后使用。
凭证传递方式
所有需认证的接口，通过请求头携带访问凭证，格式为标准的 Bearer Token 方案。
五、分页约定
列表类接口统一支持分页查询：
请求侧：通过页码和每页条数两个参数控制，默认第1页、每页10条。
响应侧：返回以下分页信息：
| 信息项 | 说明 |
|---|---|
| 数据列表 | 当前页的记录集合 |
| 总记录数 | 满足筛选条件的全部记录数 |
| 当前页码 | 本次请求的页码 |
| 每页条数 | 本次请求的每页大小 |
六、接口能力清单
后台管理（40项能力）
权限与账号（17项）
| 能力 | 说明 | 是否需登录 |
|---|---|---|
| 获取图形验证码 | 返回验证码图片，用于登录校验 | 否 |
| 管理员登录 | 校验账号密码和验证码，签发凭证 | 否 |
| 获取当前用户信息 | 返回当前登录人的基本信息、角色、可访问菜单 | 是 |
| 退出登录 | 注销当前凭证 | 是 |
| 管理员列表查询 | 支持按关键词搜索，分页返回 | 是 |
| 新增管理员 | 创建账号并分配角色 | 是 |
| 修改管理员 | 更新基本信息、角色分配，可选修改密码 | 是 |
| 删除管理员 | 逻辑删除，不可恢复 | 是 |
| 启用/禁用管理员 | 切换账号可用状态 | 是 |
| 角色列表查询 | 返回全部角色 | 是 |
| 新增/修改/删除角色 | 角色增删改，有用户关联时不可删除 | 是 |
| 获取角色已分配菜单 | 返回角色关联的菜单ID集合 | 是 |
| 分配角色菜单 | 批量设置角色可访问的菜单 | 是 |
| 获取角色已分配资源 | 返回角色关联的资源ID集合 | 是 |
| 分配角色资源 | 批量设置角色可访问的接口资源 | 是 |
| 菜单树查询 | 返回完整菜单层级结构 | 是 |
| 菜单增删改 | 维护菜单节点（名称、路径、图标、排序、显隐） | 是 |
资源管理（2项）
| 能力 | 说明 | 是否需登录 |
|---|---|---|
| 资源分类列表 | 返回全部资源分类 | 是 |
| 资源列表（按分类分组） | 返回各分类下的接口资源清单 | 是 |
商品管理（12项）
| 能力 | 说明 | 是否需登录 |
|---|---|---|
| 商品分类树查询 | 返回多级分类层级结构 | 是 |
| 分类增删改 | 维护商品分类，有子分类或商品关联时不可删除 | 是 |
| 品牌分页查询 | 支持关键词搜索 | 是 |
| 品牌全量查询 | 用于下拉选择 | 是 |
| 品牌增删改 | 维护品牌信息，有商品关联时不可删除 | 是 |
| 商品列表查询 | 支持按关键词、品牌、分类、上下架状态筛选 | 是 |
| 商品详情查询 | 返回商品完整编辑信息 | 是 |
| 商品新增/修改/删除 | 商品全生命周期管理 | 是 |
| 批量上/下架 | 批量切换商品发布状态 | 是 |
| 批量设为新品 | 批量切换新品标记 | 是 |
| 批量设为推荐 | 批量切换推荐标记 | 是 |
| 图片上传 | 上传商品图片，返回访问地址 | 是 |
订单管理（9项）
| 能力 | 说明 | 是否需登录 |
|---|---|---|
| 订单列表查询 | 支持按订单号、状态、收货人、时间范围筛选 | 是 |
| 订单详情查询 | 返回订单信息、商品明细、操作记录 | 是 |
| 订单发货 | 填写物流公司和运单号，支持批量发货 | 是 |
| 发货地址列表 | 返回公司发货地址库 | 是 |
| 退货申请列表 | 支持按状态筛选 | 是 |
| 退货申请详情 | 返回退货单完整信息 | 是 |
| 退货审核 | 同意或拒绝退货，填写处理意见 | 是 |
| 退货原因列表 | 返回预设退货原因 | 是 |
| 订单设置 | 查询/修改超时关闭、自动收货等参数 | 是 |
会员管理（4项）
| 能力 | 说明 | 是否需登录 |
|---|---|---|
| 会员列表查询 | 支持按用户名、手机号、等级、状态筛选 | 是 |
| 会员详情 | 返回会员资料、收货地址、订单记录 | 是 |
| 调整积分/成长值 | 手动调整（update/integration、update/growth） | 是 |
| 会员等级配置 | 等级增删改，配置成长值阈值 | 是 |
内容与运营（4项）
| 能力 | 说明 | 是否需登录 |
|---|---|---|
| 专题/话题/优选管理 | 内容增删改查与商品关联 | 是 |
| 帮助中心管理 | 帮助分类与文章维护 | 是 |
| 举报处理 | 举报列表、统计与处理 | 是 |
| 权限审计日志 | 查询管理员/角色/菜单/资源的变更记录 | 是 |
前台商城（25项能力）
前台用户管理（4项）
| 能力 | 说明 | 是否需登录 |
|---|---|---|
| 会员注册 | 提交用户名、密码、手机号、验证码完成注册 | 否 |
| 会员登录 | 用户名或手机号加密码登录 | 否 |
| 获取会员信息 | 返回当前会员基本资料、积分、等级 | 是 |
| 修改会员信息 | 更新昵称、头像等 | 是 |
收货地址（4项）
| 能力 | 说明 | 是否需登录 |
|---|---|---|
| 地址列表 | 返回当前会员全部收货地址 | 是 |
| 新增地址 | 添加收货地址，可设为默认 | 是 |
| 修改地址 | 更新地址信息 | 是 |
| 删除地址 | 移除指定地址 | 是 |
前台商品与首页（4项）
| 能力 | 说明 | 是否需登录 |
|---|---|---|
| 首页内容聚合 | 一次性返回广告、推荐、分类导航等全部首页数据 | 否 |
| 商品搜索 | 按关键词搜索，支持排序和分页 | 否 |
| 分类商品列表 | 按分类浏览商品，支持排序和分页 | 否 |
| 商品详情 | 返回商品展示信息（价格、库存、描述、规格） | 否 |
购物车（6项）
| 能力 | 说明 | 是否需登录 |
|---|---|---|
| 购物车列表 | 返回当前会员购物车内容，含库存状态 | 是 |
| 加入购物车 | 指定商品、规格、数量加入 | 是 |
| 修改数量 | 调整购物车中某商品的数量 | 是 |
| 删除商品 | 从购物车移除指定商品 | 是 |
| 选中/取消选中 | 切换商品的结算选中状态 | 是 |
| 清空购物车 | 移除全部购物车商品 | 是 |
前台订单（5项）
| 能力 | 说明 | 是否需登录 |
|---|---|---|
| 提交订单 | 选定地址和购物车商品，生成订单并扣减库存 | 是 |
| 订单列表 | 查看自己的订单，支持按状态筛选 | 是 |
| 订单详情 | 查看订单完整信息 | 是 |
| 取消订单 | 仅限待付款状态，取消后释放库存 | 是 |
| 确认收货 | 仅限已发货状态，确认后交易完成 | 是 |
售后服务（2项）
| 能力 | 说明 | 是否需登录 |
|---|---|---|
| 提交退货申请 | 填写退货原因、金额、凭证图片 | 是 |
| 售后列表 | 查看自己的退货申请及进度 | 是 |
七、通用业务约束
| 约束项 | 规则 |
|---|---|
| 删除保护 | 被其他实体引用的记录不可删除（如品牌下有商品、分类下有子分类） |
| 逻辑删除 | 所有删除操作为逻辑删除，数据保留但不再展示 |
| 操作审计 | 订单相关的所有状态变更均记录操作日志（操作人、时间、备注） |
| 库存校验 | 下单时实时校验库存，库存不足则拒绝下单并提示具体商品 |
| 金额计算 | 订单金额 = 商品总额 + 运费 - 优惠减免，精度保留两位小数 |
| 图片限制 | 上传图片大小不超过 5MB，仅支持常见图片格式 |