# 商城设置 — 前端技术方案

> **依据：** 《商城设置功能需求.md》v1.1、《商城设置技术方案.md》v1.1  
> **前端规范：** `doc/前端设计/前端设计.md`  
> **范围：** 仅 **ruoyi-ui 平台端** 全平台商城设置 **单页分区表单**（备案、商品、订单、会员默认头像）；**不含** 店铺设置、C 端/商家端页面。  
> **实现状态：** `index.vue`、`api/agri/mall/setting.js` **已落地**；待菜单配置及 `/agri/mallSetting` 联调。

---

## 1. 技术栈与写法约定

| 项 | 说明 |
|----|------|
| 框架 | Vue 2 + Element UI |
| 请求 | `@/utils/request`（**无** `X-Shop-Id`；平台全平台配置） |
| 参考页面 | `agri/org/shopSetting/index.vue`（单例配置 GET/PUT）、`agri/content/mallServiceAgreement/index.vue`（分区卡片 + 只读项） |
| 布局 | 多个 `el-card` 分区 + `<br/>` 分隔；**非** 检索+表格 CRUD |
| 图片 | 全局 `image-upload` + `image-preview` |
| URL 校验 | `@/utils/validate` · `validURL` |

---

## 2. 业务要点（前端需体现）

| 项 | 说明 |
|----|------|
| 单例配置 | 全平台 **一套**；与 **店铺设置** 菜单、接口 **独立** |
| 只读项 | 货币符 ¥、货币中文「元」、编号前缀 SN、已支付/已发货可取消（固定 **否**）— **展示不可改** |
| 可编辑项 | 备案四字段、是否显示销量、自动确认收货天数、售后申请限制天数、会员默认头像 |
| 备案 | 号与链接 **可空**；链接非空须 http/https |
| 销量开关 | `showSales`：`1` 是 / `0` 否；关闭后 C 端 **隐藏销量数字**，排序逻辑不变 |
| 订单天数 | 自动确认 **1～90** 自然日；售后限制 **1～365** 自然日（自确认收货起） |
| 默认头像 | **必填**；png/jpg/jpeg，≤5MB；更换不覆盖已有自定义头像会员 |
| 保存体 | **仅** 可编辑字段；只读项 **不参与** PUT |

---

## 3. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 配置页 | `ruoyi-ui/src/views/agri/mall/setting/index.vue` | 分区表单、校验、保存/重置 |
| API | `ruoyi-ui/src/api/agri/mall/setting.js` | GET/PUT `/agri/mallSetting` |

**组件 name（keep-alive）：** `AgriMallSetting`

**不提供：** 商家发品 `entryHints` 调用（商家端另册）；C 端 config 拉取；配置导出/审计。

---

## 4. 菜单与路由

| 菜单名称 | 组件路径 | 路由 path（建议） | 权限标识 |
|----------|----------|-------------------|----------|
| 商城设置 | `agri/mall/setting/index` | `mall/setting` | 见下表 |

**上级菜单：** 平台管理端 → **内容管理**（与 Banner、商城服务协议同级，以实现 SQL 为准）

| 能力 | 权限 | 页面落点 |
|------|------|----------|
| 查看配置 | `agri:mall:setting:query` | 进入页面、GET 加载 |
| 保存配置 | `agri:mall:setting:edit` | 「保存」按钮 `v-hasPermi` |

---

## 5. 页面结构（与代码一致）

```text
商城设置 index.vue
├── 页头说明 card
│   └── 全平台生效提示 + 与店铺设置/订单超时分工说明
├── <br/>
├── 备案信息 card
│   ├── ICP 备案号 icpNo
│   ├── ICP 备案链接 icpLink
│   ├── 公安备案号 psbNo
│   └── 公安备案链接 psbLink
├── <br/>
├── 商品设置 card
│   ├── 商品货币符 currencySymbol（只读 ¥）
│   ├── 商品货币中文 currencyNameCn（只读 元）
│   ├── 商品编号前缀 goodsSnPrefix（只读 SN）
│   └── 是否显示销量 showSales（单选 1/0）
├── <br/>
├── 订单设置 card
│   ├── 自动确认收货 autoConfirmDays（1～90）
│   ├── 买家申请售后限制 aftersaleLimitDays（1～365）
│   ├── 已支付订单可取消 paidOrderCancelable（只读 否）
│   └── 已发货订单可取消发货 shippedOrderCancelable（只读 否）
├── <br/>
├── 会员默认头像 card
│   ├── image-upload defaultAvatar
│   └── image-preview 预览
└── <br/>
    └── 操作 card：保存 / 重置（重新 GET）
```

---

## 6. API 封装

**模块：** `ruoyi-ui/src/api/agri/mall/setting.js`

| 方法 | HTTP | 路径 | 说明 |
|------|------|------|------|
| `getMallSetting()` | GET | `/agri/mallSetting` | 加载 `MallSettingVO` |
| `saveMallSetting(data)` | PUT | `/agri/mallSetting` | 提交 `MallSettingSaveDTO` |

### 6.1 GET 响应字段（前端使用）

| 字段 | 类型 | 页面用途 |
|------|------|----------|
| icpNo / icpLink / psbNo / psbLink | string | 备案输入 |
| currencySymbol / currencyNameCn | string | 只读展示 |
| goodsSnPrefix | string | 只读展示 |
| showSales | `"0"` \| `"1"` | 单选绑定 |
| autoConfirmDays | number | `el-input-number` |
| aftersaleLimitDays | number | `el-input-number` |
| paidOrderCancelable / shippedOrderCancelable | boolean | 只读「是/否」 |
| defaultAvatar | string | 图片 URL |

### 6.2 PUT 请求体（仅可编辑项）

```json
{
  "icpNo": "",
  "icpLink": "",
  "psbNo": "",
  "psbLink": "",
  "showSales": "1",
  "autoConfirmDays": 7,
  "aftersaleLimitDays": 7,
  "defaultAvatar": "https://..."
}
```

**不传：** `currencySymbol`、`currencyNameCn`、`goodsSnPrefix`、取消开关只读字段。

---

## 7. 交互与校验

| 校验项 | 前端规则 | 失败提示 |
|--------|----------|----------|
| icpLink / psbLink | 非空时 `validURL` | 备案链接格式不正确 |
| autoConfirmDays | 必填；组件 min=1 max=90 | 请填写自动确认收货天数 |
| aftersaleLimitDays | 必填；组件 min=1 max=365 | 请填写售后申请限制天数 |
| showSales | 必选 | 请选择是否显示销量 |
| defaultAvatar | 必填 | 请上传会员默认头像 |

| 操作 | 行为 |
|------|------|
| 保存 | `validate` → PUT → 成功提示 → 重新 GET |
| 重置 | 放弃未保存修改，重新 `loadConfig` |

---

## 8. 与兄弟模块区分

| 模块 | 路径 | 职责 |
|------|------|------|
| **商城设置（本页）** | `agri/mall/setting` | 备案、销量展示、订单时限、默认头像 |
| 店铺设置 | `agri/org/shopSetting` | 商品默认审核、子管理员上限 |
| 商城服务协议 | `agri/content/mallServiceAgreement` | 买家注册协议 |
| 首页 Banner | `agri/content/banner` | 首页运营位 |

---

## 9. 联调与验收对照

| 编号 | 场景 | 前端预期 |
|------|------|----------|
| MC-T1 | 保存 ICP 号+链接 | 保存成功；C 端页脚联调可见（后端/C 端） |
| MC-T2 | 关闭显示销量 | `showSales=0` 提交成功 |
| MC-T6 | 只读项 | 货币/前缀/取消开关 **不可编辑** |
| MC-A1 | 未传头像保存 | 前端校验阻断 |
| — | 首次 GET 无数据 | 后端 lazy init 默认值后返回；前端兜底默认 7 天、销量开 |

---

## 10. 菜单配置示例（运维）

```text
菜单名称：商城设置
组件路径：agri/mall/setting/index
路由地址：mall/setting
权限字符：agri:mall:setting:query
按钮：agri:mall:setting:edit（保存）
父级：内容管理
```

---

*文档版本：v1.0 · 关联《商城设置功能需求.md》v1.1、《商城设置技术方案.md》v1.1*
