新更新的商户

doc/农资商城web/组织管理/商户管理/商户管理前端技术方案.md

@@ -65,8 +65,8 @@
 │   ├── 列：所属单位、类型、名称、联系人、手机、店铺数、认证状态、认证时间
 │   └── 操作：详情、编辑（canEdit）、删除（canDelete）
 ├── 添加/编辑弹窗（860px · el-tabs）
-│   ├── Tab「主体资质」：个人 / 企业字段 + 证件照上传
-│   ├── Tab「商户经营信息」（仅编辑）：名称、地址、联系人、结算等
+│   ├── Tab「主体资质」：个人 / 企业字段 + 证件照上传；企业注册地区 el-cascader
+│   ├── Tab「商户经营信息」（仅编辑）：名称、经营地区 cascader、联系人、结算等
 │   └── Tab「绑定经营账号」（仅新增）：管理员 / 会员远程搜索
 └── 详情抽屉（detail.vue · 72% 宽）
     ├── 概要、主体资质、经营信息、关联店铺
@@ -97,8 +97,19 @@
 | 场景 | 组件 | 提交拆分 |
 |------|------|----------|
 | 个人证件有效期 | `el-date-picker type="daterange"` → `idValidRange` | `idValidStart` / `idValidEnd` |
+| 法人证件有效期 | `el-date-picker type="daterange"` → `legalIdValidRange` | `legalIdValidStart` / `legalIdValidEnd` |
 | 企业营业期限 | `el-date-picker type="daterange"` → `licenseValidRange` | `licenseValidStart` / `licenseValidEnd` |
-| 长期有效 | `idValidType=2` / `licenseValidType=2`，仅填起始日 | `*ValidEnd` 可为 null |
+| 长期有效 | `idValidType=2` / `legalIdValidType=2` / `licenseValidType=2`，仅填起始日 | `*ValidEnd` 可为 null |
+
+**省市区级联（v1.7 · `el-cascader`）：**
+
+| 场景 | 组件 | 数据源 | 落库字段 |
+|------|------|--------|----------|
+| 企业注册地址 | `form.regRegionCascader` | `getRegionTree()` | `regRegionCode`（区县 `code`）、`regRegionName`（省/市/区县 `/` 连接） |
+| 经营地址（编辑 Tab） | `form.bizRegionCascader` | 同上 | `bizRegionCode`、`bizRegionName` |
+| 详细地址 | `el-input` | — | `companyDetailAddress` / `bizDetailAddress` |
+
+级联配置：`value: code`、`label: name`、`children: children`、`emitPath: true`；支持 `filterable`、`clearable`。编辑回显按已存 `*RegionCode` 在树中查找路径；提交前剔除 `regRegionCascader` / `bizRegionCascader` 仅 UI 字段。
 
 ---
 
@@ -119,7 +130,17 @@
 | `adminUserOptions` | GET | `/adminUserOptions` | 新增绑定管理员远程搜索 |
 | `memberOptions` | GET | `/memberOptions` | 新增绑定会员远程搜索 |
 
-### 6.1 列表请求参数
+### 6.1 省市区（v1.7）
+
+**基路径：** `/agri/region`（见 `src/api/agri/region.js`）
+
+| 前端方法 | HTTP | 路径 | 说明 |
+|----------|------|------|------|
+| `getRegionTree` | GET | `/tree` | 省/市/区县三级树；节点含 `id`、`pid`、`name`、`type`（1省/2市/3区县）、`code`、`children` |
+
+页面 `created` 预加载并缓存；添加/编辑弹窗打开时若未加载则再次请求。落库规则与后端 §9.9 一致：`code` 取选中区县，`name` 为路径名称用 `/` 拼接。
+
+### 6.2 列表请求参数
 
 | 字段 | 说明 |
 |------|------|
@@ -127,7 +148,7 @@
 | merchantName | 模糊（名称 / 所属单位） |
 | certStatus | `0` 正常 / `1` 冻结 / `2` 注销 |
 
-### 6.2 列表行字段
+### 6.3 列表行字段
 
 | 字段 | 展示规则 |
 |------|----------|
@@ -136,18 +157,18 @@
 | contactName, contactPhone | 未完善显示「—」 |
 | canEdit, canDelete | 后端布尔，控制按钮显隐 |
 
-### 6.3 新增请求体要点（v1.5 / v1.6）
+### 6.4 新增请求体要点（v1.5 / v1.6）
 
 - **仅** 主体资质 + `bindType`（`SYS_USER` / `MEMBER`）+ `bindUserId` 或 `bindMemberId`
 - **不含** 经营信息字段
 - **平台新增最小必填**（`validateSubjectOnInsert`）：
   - 个人：仅 `personName`
   - 企业：仅 `legalName` + `companyName`
-- **v1.5 新增主体字段**：`idCardType` / `legalIdCardType`（1 大陆身份证 / 2 来往内地通行证）、`regRegionCode` / `regRegionName`、`corpBankAccount`、法人证件有效期区间等
+- **v1.5 新增主体字段**：`idCardType` / `legalIdCardType`（1 大陆身份证 / 2 来往内地通行证）、`regRegionCode` / `regRegionName`（v1.7 由级联写入）、`corpBankAccount`、法人证件有效期区间等
 - **会员绑定（v1.6）**：登录名=会员名称、管理员姓名=会员昵称；密码复制会员 `sys_user.password`；**不传** `sysUserInitPassword`
 - **管理员绑定（v1.6）**：检索范围 `role_key=merchant`；登录名=`user_name`、管理员姓名=`nick_name`
 
-### 6.3.1 绑定 Tab UI
+### 6.4.1 绑定 Tab UI
 
 | bindType | 远程搜索 | 下拉展示 |
 |----------|----------|----------|
@@ -156,13 +177,13 @@
 
 顶部 `el-alert` 说明绑定落库规则；**已移除** 会员「初始密码」输入框。
 
-### 6.4 编辑请求体要点
+### 6.5 编辑请求体要点
 
-- 含 `merchantId`、主体字段、经营信息字段
+- 含 `merchantId`、主体字段、经营信息字段；经营 Tab 含 `bizRegionCode` / `bizRegionName` / `bizDetailAddress`
 - **不传** `certStatus`（认证仅在详情改）
 - 入驻后 `idCardNo`、`creditCode` 前端 disabled，仍随表单提交
 
-### 6.5 认证状态变更
+### 6.6 认证状态变更
 
 ```json
 { "certStatus": "1", "confirm": true }
@@ -170,7 +191,7 @@
 
 详情页先 `$modal.confirm(confirmMessage)`，再 `confirm: true` 提交。
 
-### 6.6 保存成功扩展
+### 6.7 保存成功扩展
 
 | response.data | 前端行为 |
 |---------------|----------|
@@ -188,6 +209,7 @@
 | 新增校验 | 个人仅姓名必填；企业仅法人姓名+企业名称必填；证件号/信用代码选填 |
 | 绑定搜索 | `el-select` + `remote` + `filterable`；keyword 空不请求 |
 | 编辑 Tab | 「主体资质」+「商户经营信息」；无绑定 Tab |
+| 注册/经营地址 | 企业主体 Tab 选注册地区；编辑经营 Tab 选经营地区；均为 `el-cascader` + 详细地址输入 |
 | 详情跳转店铺 | `$router.push({ path: '/agri/org/shop', query: { merchantName } })` |
 | 删除 | 先 `deleteMerchantCheck`；`canDelete=false` 展示 reasons；通过后再二次确认 |
 | 列表名称 | `merchantName` 空显示「待完善」 |
@@ -222,7 +244,7 @@ v-hasPermi="['agri:merchant:cert']"
 - [ ] 新增个人仅填姓名可提交；企业仅法人姓名+企业名称可提交  
 - [ ] 绑定会员无初始密码字段；admin/member 远程搜索展示正确  
 - [ ] 删除 deleteCheck 阻断并展示 reasons  
-- [ ] 详情展示 idCardType、regRegion、corpBankAccount、法人完整字段  
+- [ ] 详情展示 idCardType、regRegion、bizRegion、corpBankAccount、法人完整字段  
 - [ ] 菜单组件路径 `agri/org/merchant/index` 可打开  
 - [ ] 列表分页、检索、canEdit/canDelete 正确  
 - [ ] 新增仅主体 + 绑定；成功后提示完善经营信息  
@@ -230,8 +252,8 @@ v-hasPermi="['agri:merchant:cert']"
 - [ ] 详情 `allowedCertStatuses` 流转与二次确认  
 - [ ] 证件号/信用代码编辑页 disabled  
 - [ ] 删除前置条件后端 msg 正常弹出  
-- [ ] （可选）`GET /agri/region/tree` 返回三级树；编辑提交 `bizRegionCode`/`bizRegionName` 与 §9.9 一致  
-- [ ] 编辑页 **经营地址**、企业 **注册地址** 级联选择器可选省/市/区县并正确落库  
+- [ ] `GET /agri/region/tree` 返回三级树；级联选中后 `regRegionCode`/`regRegionName`、`bizRegionCode`/`bizRegionName` 与后端 §9.9 一致  
+- [ ] 编辑回显：已存区县 code 能正确还原级联路径  
 
 ---
 
@@ -248,14 +270,12 @@ v-hasPermi="['agri:merchant:cert']"
 
 | 版本 | 日期 | 说明 |
 |------|------|------|
-
-| v1.3 | 2026-05 | 商户编辑页接入 `el-cascader` 选择注册/经营省市区 |
-| v1.2 | 2026-05 | 对齐 v1.7：省市区接口 `/agri/region/tree` |
-
+| v1.3 | 2026-06 | 接入 `GET /agri/region/tree`；企业注册地址、经营地址改为 `el-cascader`；新增 `api/agri/region.js` |
+| v1.2 | 2026-05 | 对齐 v1.6：绑定 Tab、主体扩展字段、deleteCheck |
 | v1.1 | 2026-05 | 对齐 v1.6：角色 merchant/member；会员绑定不传初始密码 |
 | v1.0 | 2026-05 | 首版：列表 CRUD、详情抽屉、绑定远程搜索 |
 
 ---
 
-*文档版本：v1.3 · ruoyi-ui · 关联《商户管理功能需求.md》v1.7*
+*文档版本：v1.3 · ruoyi-ui · 关联《商户管理功能需求.md》v1.7 / 《商户管理技术方案.md》v1.7*
 

ruoyi-ui/src/api/agri/region.js

@@ -0,0 +1,9 @@
+import request from '@/utils/request'
+
+// 查询省市区三级树（平台端）
+export function getRegionTree() {
+  return request({
+    url: '/agri/region/tree',
+    method: 'get'
+  })
+}

ruoyi-ui/src/views/agri/org/merchant/detail.vue

@@ -76,8 +76,7 @@
           <el-descriptions-item label="统一社会信用代码">{{ detail.creditCode || '—' }}</el-descriptions-item>
           <el-descriptions-item label="注册地区">{{ detail.regRegionName || '—' }}</el-descriptions-item>
           <el-descriptions-item label="注册地区编码">{{ detail.regRegionCode || '—' }}</el-descriptions-item>
-          <el-descriptions-item label="注册地址">{{ detail.regAddress || '—' }}</el-descriptions-item>
-          <el-descriptions-item label="详细地址">{{ detail.companyDetailAddress || '—' }}</el-descriptions-item>
+          <el-descriptions-item label="注册详细地址">{{ detail.companyDetailAddress || '—' }}</el-descriptions-item>
           <el-descriptions-item label="经营范围" :span="2">{{ detail.businessScope || '—' }}</el-descriptions-item>
           <el-descriptions-item label="营业期限" :span="2">{{ validPeriodText(detail.licenseValidType, detail.licenseValidStart, detail.licenseValidEnd) }}</el-descriptions-item>
         </el-descriptions>
@@ -89,7 +88,8 @@
         <el-descriptions-item label="商户名称">{{ detail.merchantName || '—' }}</el-descriptions-item>
         <el-descriptions-item label="客服电话">{{ detail.servicePhone || '—' }}</el-descriptions-item>
         <el-descriptions-item label="经营地址">{{ detail.bizRegionName || '—' }}</el-descriptions-item>
-        <el-descriptions-item label="详细地址">{{ detail.bizDetailAddress || '—' }}</el-descriptions-item>
+        <el-descriptions-item label="经营地区编码">{{ detail.bizRegionCode || '—' }}</el-descriptions-item>
+        <el-descriptions-item label="经营详细地址" :span="2">{{ detail.bizDetailAddress || '—' }}</el-descriptions-item>
         <el-descriptions-item label="联系人">{{ detail.contactName || '—' }}</el-descriptions-item>
         <el-descriptions-item label="联系人手机">{{ detail.contactPhone || '—' }}</el-descriptions-item>
         <el-descriptions-item label="联系人邮箱">{{ detail.contactEmail || '—' }}</el-descriptions-item>

ruoyi-ui/src/views/agri/org/merchant/index.vue

@@ -20,6 +20,8 @@
       </el-form>
     </el-card>
 
+    <br/>
+
     <!-- 列表区 -->
     <el-card shadow="never" class="table-card">
       <el-row :gutter="10" class="mb8">
@@ -207,10 +209,21 @@
                     <el-input v-model="form.creditCode" maxlength="18" :disabled="!!form.merchantId" placeholder="选填" />
                   </el-form-item>
                 </el-col>
-                <el-col :span="12"><el-form-item label="注册地区编码" prop="regRegionCode"><el-input v-model="form.regRegionCode" placeholder="如 110105" maxlength="64" /></el-form-item></el-col>
-                <el-col :span="12"><el-form-item label="注册地区名称" prop="regRegionName"><el-input v-model="form.regRegionName" placeholder="如 北京市/西城区" maxlength="128" /></el-form-item></el-col>
-                <el-col :span="12"><el-form-item label="注册地址" prop="regAddress"><el-input v-model="form.regAddress" maxlength="255" placeholder="选填" /></el-form-item></el-col>
-                <el-col :span="12"><el-form-item label="详细地址" prop="companyDetailAddress"><el-input v-model="form.companyDetailAddress" maxlength="255" /></el-form-item></el-col>
+                <el-col :span="24">
+                  <el-form-item label="注册地区" prop="regRegionCascader">
+                    <el-cascader
+                      v-model="form.regRegionCascader"
+                      :options="regionTree"
+                      :props="regionCascaderProps"
+                      clearable
+                      filterable
+                      placeholder="请选择省/市/区县"
+                      style="width: 100%"
+                      @change="handleRegRegionChange"
+                    />
+                  </el-form-item>
+                </el-col>
+                <el-col :span="24"><el-form-item label="注册详细地址" prop="companyDetailAddress"><el-input v-model="form.companyDetailAddress" maxlength="255" placeholder="选填，街道门牌号" /></el-form-item></el-col>
                 <el-col :span="24"><el-form-item label="经营范围" prop="businessScope"><el-input v-model="form.businessScope" type="textarea" :rows="2" maxlength="1000" /></el-form-item></el-col>
                 <el-col :span="24">
                   <el-form-item label="营业期限" prop="licenseValidType">
@@ -239,8 +252,20 @@
             <el-row :gutter="16">
               <el-col :span="12"><el-form-item label="商户名称" prop="merchantName"><el-input v-model="form.merchantName" maxlength="128" /></el-form-item></el-col>
               <el-col :span="12"><el-form-item label="客服电话" prop="servicePhone"><el-input v-model="form.servicePhone" maxlength="20" /></el-form-item></el-col>
-              <el-col :span="12"><el-form-item label="经营地区编码" prop="bizRegionCode"><el-input v-model="form.bizRegionCode" placeholder="如 110105" maxlength="64" /></el-form-item></el-col>
-              <el-col :span="12"><el-form-item label="经营地区名称" prop="bizRegionName"><el-input v-model="form.bizRegionName" placeholder="如 北京市/朝阳区" maxlength="128" /></el-form-item></el-col>
+              <el-col :span="24">
+                <el-form-item label="经营地区" prop="bizRegionCascader">
+                  <el-cascader
+                    v-model="form.bizRegionCascader"
+                    :options="regionTree"
+                    :props="regionCascaderProps"
+                    clearable
+                    filterable
+                    placeholder="请选择省/市/区县"
+                    style="width: 100%"
+                    @change="handleBizRegionChange"
+                  />
+                </el-form-item>
+              </el-col>
               <el-col :span="24"><el-form-item label="经营详细地址" prop="bizDetailAddress"><el-input v-model="form.bizDetailAddress" maxlength="255" /></el-form-item></el-col>
               <el-col :span="12"><el-form-item label="联系人姓名" prop="contactName"><el-input v-model="form.contactName" maxlength="64" /></el-form-item></el-col>
               <el-col :span="12"><el-form-item label="联系人手机" prop="contactPhone"><el-input v-model="form.contactPhone" maxlength="20" /></el-form-item></el-col>
@@ -311,6 +336,7 @@
 
 <script>
 import { listMerchant, getMerchant, addMerchant, updateMerchant, delMerchant, deleteMerchantCheck, adminUserOptions, memberOptions } from "@/api/agri/merchant"
+import { getRegionTree } from "@/api/agri/region"
 import MerchantDetail from "./detail"
 
 export default {
@@ -330,6 +356,14 @@ export default {
       bindSearchLoading: false,
       adminUserList: [],
       memberList: [],
+      regionTree: [],
+      regionTreeLoaded: false,
+      regionCascaderProps: {
+        value: "code",
+        label: "name",
+        children: "children",
+        emitPath: true
+      },
       queryParams: {
         pageNum: 1,
         pageSize: 10,
@@ -365,6 +399,7 @@ export default {
   },
   created() {
     this.getList()
+    this.loadRegionTree()
   },
   methods: {
     /** 查询商户列表 */
@@ -421,6 +456,7 @@ export default {
         creditCode: undefined,
         regRegionCode: undefined,
         regRegionName: undefined,
+        regRegionCascader: [],
         regAddress: undefined,
         companyDetailAddress: undefined,
         businessScope: undefined,
@@ -430,7 +466,8 @@ export default {
         licenseValidEnd: undefined,
         bindType: "SYS_USER",
         bindUserId: undefined,
-        bindMemberId: undefined
+        bindMemberId: undefined,
+        bizRegionCascader: []
       }
       this.activeTab = "subject"
       this.adminUserList = []
@@ -451,15 +488,18 @@ export default {
     },
     handleAdd() {
       this.reset()
+      this.loadRegionTree()
       this.open = true
       this.title = "添加商户"
     },
-    /** 打开编辑并组装日期区间 */
+    /** 打开编辑并组装日期区间、省市区回显 */
     handleUpdate(row) {
       this.reset()
-      getMerchant(row.merchantId).then(response => {
+      this.loadRegionTree().then(() => {
+        return getMerchant(row.merchantId)
+      }).then(response => {
         const data = response.data || {}
-        this.form = { ...data }
+        this.form = { ...data, regRegionCascader: [], bizRegionCascader: [] }
         if (data.idValidType === "1" && data.idValidStart && data.idValidEnd) {
           this.form.idValidRange = [data.idValidStart, data.idValidEnd]
         }
@@ -469,6 +509,7 @@ export default {
         if (data.licenseValidType === "1" && data.licenseValidStart && data.licenseValidEnd) {
           this.form.licenseValidRange = [data.licenseValidStart, data.licenseValidEnd]
         }
+        this.syncRegionCascaderFromForm()
         this.activeTab = "subject"
         this.open = true
         this.title = "编辑商户"
@@ -487,7 +528,83 @@ export default {
       this.adminUserList = []
       this.memberList = []
     },
-    /** 管理员下拉展示：昵称 / 用户名 / 手机号 */
+    /** 加载省市区树 */
+    loadRegionTree() {
+      if (this.regionTreeLoaded) {
+        return Promise.resolve()
+      }
+      return getRegionTree().then(response => {
+        this.regionTree = response.data || []
+        this.regionTreeLoaded = true
+      }).catch(() => {
+        this.regionTree = []
+      })
+    },
+    /** 根据区县 code 回显级联选中路径 */
+    findRegionPath(nodes, targetCode, path) {
+      if (!nodes || !nodes.length) {
+        return null
+      }
+      for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i]
+        const nextPath = (path || []).concat(node.code)
+        if (String(node.code) === String(targetCode)) {
+          return nextPath
+        }
+        if (node.children && node.children.length) {
+          const found = this.findRegionPath(node.children, targetCode, nextPath)
+          if (found) {
+            return found
+          }
+        }
+      }
+      return null
+    },
+    /** 根据级联 code 路径拼地区名称 */
+    getRegionNamesByCodes(codes) {
+      const names = []
+      let nodes = this.regionTree
+      for (let i = 0; i < codes.length; i++) {
+        const code = codes[i]
+        const node = (nodes || []).find(item => String(item.code) === String(code))
+        if (!node) {
+          break
+        }
+        names.push(node.name)
+        nodes = node.children || []
+      }
+      return names
+    },
+    /** 编辑回显：把库里的 code 转成 cascader 路径 */
+    syncRegionCascaderFromForm() {
+      if (this.form.regRegionCode && this.regionTree.length) {
+        this.form.regRegionCascader = this.findRegionPath(this.regionTree, this.form.regRegionCode) || []
+      }
+      if (this.form.bizRegionCode && this.regionTree.length) {
+        this.form.bizRegionCascader = this.findRegionPath(this.regionTree, this.form.bizRegionCode) || []
+      }
+    },
+    /** 企业注册地区变更：写入 regRegionCode / regRegionName */
+    handleRegRegionChange(codes) {
+      this.applyRegionSelection(codes, "reg")
+    },
+    /** 经营地区变更：写入 bizRegionCode / bizRegionName */
+    handleBizRegionChange(codes) {
+      this.applyRegionSelection(codes, "biz")
+    },
+    /** 级联选择落库：code=区县 code，name=省/市/区县用 / 连接 */
+    applyRegionSelection(codes, prefix) {
+      const codeKey = prefix + "RegionCode"
+      const nameKey = prefix + "RegionName"
+      if (!codes || !codes.length) {
+        this.form[codeKey] = undefined
+        this.form[nameKey] = undefined
+        return
+      }
+      const names = this.getRegionNamesByCodes(codes)
+      this.form[codeKey] = String(codes[codes.length - 1])
+      this.form[nameKey] = names.join("/")
+    },
     formatAdminOption(item) {
       const parts = [item.nickName || item.userName, item.userName]
       if (item.phonenumber) {
@@ -549,6 +666,8 @@ export default {
       delete payload.idValidRange
       delete payload.legalIdValidRange
       delete payload.licenseValidRange
+      delete payload.regRegionCascader
+      delete payload.bizRegionCascader
       // 新增时不传绑定无关字段；会员绑定不传 sysUserInitPassword（后端忽略）
       if (!payload.merchantId) {
         delete payload.sysUserInitPassword
@@ -612,7 +731,7 @@ export default {
 
 <style scoped>
 .search-card {
-  margin-bottom: 10px;
+  margin-bottom: 0;
 }
 .form-section-title {
   font-size: 13px;