会员管理代码

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

@@ -1,6 +1,6 @@
 # 商户管理 — 前端技术方案
 
-> **依据：** 《商户管理功能需求.md》v1.6、《商户管理技术方案.md》v1.6  
+> **依据：** 《商户管理功能需求.md》v1.7、《商户管理技术方案.md》v1.7  
 > **前端规范：** `doc/前端设计/前端设计.md`  
 > **范围：** 仅 **ruoyi-ui 平台管理端** 列表、添加、编辑、详情；商家端、C 端 **不在 ruoyi-ui 实现**。  
 > **实现状态：** 页面与 API 封装已落地，待后端 `/agri/merchant` 联调。
@@ -27,6 +27,7 @@
 | 列表页 | `ruoyi-ui/src/views/agri/org/merchant/index.vue` | 列表、添加/编辑弹窗 |
 | 详情抽屉 | `ruoyi-ui/src/views/agri/org/merchant/detail.vue` | 详情展示、认证状态调整 |
 | API | `ruoyi-ui/src/api/agri/merchant.js` | 列表、详情、增删改、认证、绑定检索 |
+| 省市区 | `ruoyi-ui/src/api/agri/region.js` | `getRegionTree` → `GET /agri/region/tree` |
 
 **组件 name（keep-alive）：** `AgriMerchant`
 
@@ -209,6 +210,8 @@ v-hasPermi="['agri:merchant:cert']"
 - [ ] 详情 `allowedCertStatuses` 流转与二次确认  
 - [ ] 证件号/信用代码编辑页 disabled  
 - [ ] 删除前置条件后端 msg 正常弹出  
+- [ ] （可选）`GET /agri/region/tree` 返回三级树；编辑提交 `bizRegionCode`/`bizRegionName` 与 §9.9 一致  
+- [ ] 编辑页 **经营地址**、企业 **注册地址** 级联选择器可选省/市/区县并正确落库  
 
 ---
 
@@ -218,7 +221,6 @@ v-hasPermi="['agri:merchant:cert']"
 |----|------|
 | 商家端登录 | 另端 |
 | OCR / 导出 Excel | 不做 |
-| 省市区级联选择器 | 本期用手工填 `bizRegionCode` + `bizRegionName` |
 
 ---
 
@@ -226,9 +228,11 @@ v-hasPermi="['agri:merchant:cert']"
 
 | 版本 | 日期 | 说明 |
 |------|------|------|
+| v1.3 | 2026-05 | 商户编辑页接入 `el-cascader` 选择注册/经营省市区 |
+| v1.2 | 2026-05 | 对齐 v1.7：省市区接口 `/agri/region/tree` |
 | v1.1 | 2026-05 | 对齐 v1.6：角色 merchant/member；会员绑定不传初始密码 |
 | v1.0 | 2026-05 | 首版：列表 CRUD、详情抽屉、绑定远程搜索；对齐功能需求 v1.4 与已落地代码 |
 
 ---
 
-*文档版本：v1.1 · ruoyi-ui · 关联《商户管理功能需求.md》v1.6*
+*文档版本：v1.3 · ruoyi-ui · 关联《商户管理功能需求.md》v1.7*

doc/农资商城web/组织管理/商户管理/商户管理功能需求.md

@@ -2,6 +2,7 @@
 
 > 本文档在《商户管理功能需求-草稿》基础上整理，并关联《农资商城web》目录下店铺管理、商品管理等模块需求做边界与流程对齐。  
 > 范围：平台侧 **商户管理** 功能需求；不涉及数据库结构、接口定义及技术实现细节。  
+> **v1.7：** 企业 **注册地址**、个人/企业 **经营地址** 的省市区选项统一由 **`GET /agri/region/tree`**（平台端）获取；落库 `reg_region_*` / `biz_region_*`。  
 > **v1.6：** 绑定经营账号角色权限字符统一为 **merchant** / **member**（替代历史数字编码）；会员绑定 **不新建 sys_user**，追加 merchant 角色并复制密码。  
 > **v1.5：** 明确 **移动端 C 端** 与 **平台端** 入驻字段差异；C 端须完整填写并走 **审核+公示**；平台端仅主体最小必填 + 强制绑定账号；**数据库字段注释** 以 `sql/biz_merchant.sql` 为准。  
 > **v1.4：** 平台 **新增商户** 须强制绑定 **平台管理员账号** 或 **C 端会员账号**，并同步创建该商户下首条 **商户经营账号**（`biz_merchant_account`）。  
@@ -171,6 +172,35 @@
 
 > **商户名称** 入驻时不采集；在 **编辑** 填写时校验平台唯一（第 9 节）。
 
+### 6.6 资料完整度与开店前置
+
+| 资料块 | 完成时机 | 开店要求 |
+|--------|----------|----------|
+| 主体资质 | **入驻** 提交成功 | 已有 |
+| 商户经营信息 | **编辑商户** 中填写并保存 | **开设店铺前必须完整** |
+
+**商户经营信息 — 完整判定（全部有值且校验通过）：**
+
+| 字段 | 个人/企业 |
+|------|-----------|
+| 商户名称 | 必填；平台唯一 |
+| 客服电话 | 必填 |
+| 经营地址、详细地址 | 必填；**经营地址省市区** 通过 §6.8 接口选择后写入 `biz_region_code` / `biz_region_name` |
+| 联系人姓名、手机、邮箱 | 必填 |
+| 开户银行、支行名称 | 必填 |
+| 银行卡号 / 对公银行卡号 | 必填（个人/企业对应） |
+| 营业执照电子版 | 企业 **必填** |
+| 开户许可证 | 企业 **必填** |
+
+店铺管理 **添加店铺** 选择商户时：
+
+```text
+校验商户认证=正常且未删除
+    → 校验商户经营信息是否完整
+    ├── 否 → 阻断，提示「请先完善该商户的经营与结算信息」
+    └── 是 → 允许继续开店（店铺经营账号见《店铺管理功能需求》）
+```
+
 ### 6.7 新增商户 — 强制绑定经营账号（v1.6）
 
 新增提交前 **必须** 选择绑定类型（二选一），并完成远程搜索选定一条记录；未选则阻断提交。
@@ -208,34 +238,21 @@
 
 > **说明：** 本条仅在 **平台新增商户** 生效；编辑商户、店铺侧增删经营账号规则仍见《店铺管理功能需求》。
 
-### 6.6 资料完整度与开店前置
-
-| 资料块 | 完成时机 | 开店要求 |
-|--------|----------|----------|
-| 主体资质 | **入驻** 提交成功 | 已有 |
-| 商户经营信息 | **编辑商户** 中填写并保存 | **开设店铺前必须完整** |
+### 6.8 注册地址 / 经营地址 — 省市区选择（v1.7）
 
-**商户经营信息 — 完整判定（全部有值且校验通过）：**
-
-| 字段 | 个人/企业 |
-|------|-----------|
-| 商户名称 | 必填；平台唯一 |
-| 客服电话 | 必填 |
-| 经营地址、详细地址 | 必填 |
-| 联系人姓名、手机、邮箱 | 必填 |
-| 开户银行、支行名称 | 必填 |
-| 银行卡号 / 对公银行卡号 | 必填（个人/企业对应） |
-| 营业执照电子版 | 企业 **必填** |
-| 开户许可证 | 企业 **必填** |
+企业 **注册地址**、个人/企业 **经营地址** 的省市区数据，由 **`biz_region`** 表提供，平台端通过 **`GET /agri/region/tree`** 获取三级树，编辑页使用 **Element 级联选择器**（`el-cascader`）选择。
 
-店铺管理 **添加店铺** 选择商户时：
+| 项 | 说明 |
+|----|------|
+| 平台端接口 | `GET /agri/region/tree`（登录即可；数据源 `sql/biz_region.sql`） |
+| C 端接口 | `GET /api/region/tree`（匿名；收货地址、入驻等同源，本文仅说明商户字段用法） |
+| 树节点字段 | `id`、`pid`、`name`、`type`（1省 2市 3区县）、`code`（行政区划编码）、`children` |
+| **注册地址**（企业主体） | 选定 **区县** 后：`reg_region_code` = 区县 `code`（字符串）；`reg_region_name` = 省/市/区县 `name` 用 `/` 拼接 |
+| **经营地址**（个人/企业） | 选定 **区县** 后：`biz_region_code` = 区县 `code`；`biz_region_name` = 省/市/区县 `name` 用 `/` 拼接 |
+| 详细地址 | 分别写入 `company_detail_address`（注册）、`biz_detail_address`（经营），与省市区字段独立 |
+| 校验 | `code` 与 `name` **须同时有值**；缺一则经营完整度 `biz_complete=0` 或 C 端入驻校验失败 |
 
-```text
-校验商户认证=正常且未删除
-    → 校验商户经营信息是否完整
-    ├── 否 → 阻断，提示「请先完善该商户的经营与结算信息」
-    └── 是 → 允许继续开店（店铺经营账号见《店铺管理功能需求》）
-```
+**示例：** 选择「北京市 / 市辖区 / 东城区」→ `biz_region_code=110101`，`biz_region_name=北京市/市辖区/东城区`。
 
 ---
 
@@ -364,6 +381,7 @@
 | R2 | **新增商户** 须绑定管理员或会员并创建首条经营账号；会员模块能力不在本文展开 |
 | R12 | 绑定管理员：须具备 **role_key=merchant**；经营账号登录名 = `user_name`，管理员姓名 = `nick_name` |
 | R13 | 绑定会员：向会员用户 **追加 role_key=merchant**；经营账号 **登录名** = 会员名称（`user_name`），**管理员姓名** = 会员昵称（`nick_name`） |
+| R14 | 注册/经营地址省市区：`reg_region_*` / `biz_region_*` 的 code 与 name **须成对**；数据来自 **`GET /agri/region/tree`**（§6.8） |
 | R3 | 入驻成功 → 认证 **正常** + 认证时间 |
 | R4 | 个人/企业类型创建后不可互转 |
 | R5 | 认证状态仅在 **查看详情** 修改 |
@@ -403,7 +421,7 @@
 |------|------|
 | 添加商户 | **主体资质** + **绑定类型**（管理员/会员）+ 远程搜索选人；**无** 经营结算字段 |
 | 添加成功 | 提示去 **编辑** 完善经营信息后再开店 |
-| 编辑商户 | **主体资质** + **商户经营信息**；认证状态只读 |
+| 编辑商户 | **主体资质** + **商户经营信息**；认证状态只读；企业注册地址/经营地址省市区通过 §6.8 接口选择 |
 | 列表 | **联系人/联系人手机**（来自经营信息）；无会员相关列 |
 | 详情 | 经营信息未完成时 **待完善** 提示 |
 | 删除 / 认证 | 同前序定稿 |
@@ -419,8 +437,8 @@
 | 主键/状态 | `merchant_type`, `cert_status`, `cert_time`, `biz_complete`, `shop_count` | 认证与开店前置 |
 | 【个人】 | `person_name`, `id_card_type`, `id_card_no`, `birth_date`, `id_valid_*`, `residence_address`, `gender`, `id_card_front/back` | `id_card_type`：1大陆身份证 2来往内地通行证 |
 | 【企业·法人】 | `legal_*`, `corp_bank_account`, `account_permit` | 对公账号、开户许可证 |
-| 【企业】 | `company_name`, `credit_code`, `reg_region_*`, `company_detail_address`, `business_scope`, `license_valid_*` | 注册地址用 `reg_region_code/name` + 详细地址 |
-| 经营信息 | `merchant_name`, `service_phone`, `biz_region_*`, `contact_*`, `bank_*`, `business_license` | 平台新增可不填；C 端入驻申请中可完整采集 |
+| 【企业】 | `company_name`, `credit_code`, `reg_region_*`, `company_detail_address`, `business_scope`, `license_valid_*` | 注册地址：`reg_region_code/name`（§6.8 区县 code + 省/市/区 name 拼接）+ 详细地址 |
+| 经营信息 | `merchant_name`, `service_phone`, `biz_region_*`, `contact_*`, `bank_*`, `business_license` | 经营地址：`biz_region_code/name`（§6.8）；平台新增可不填 |
 | 经营账号 | `biz_merchant_account.login_name/admin_name/password` | 见 §6.7；**不在** `biz_shop` |
 
 **枚举约定：** `gender`/`legal_gender`：0男 1女；`*_valid_type`：1区间 2长期；`del_flag`：0存在 2删除。
@@ -437,8 +455,9 @@
 | **v1.3.1** | **取消** 单商户最多 3 店限制；`shop_count` 仅统计 |
 | **v1.4** | 新增商户强制绑定平台管理员或会员，并创建首条 `biz_merchant_account` |
 | **v1.5** | 平台/移动端字段差异定稿；§15 数据库字段与 SQL 对齐 |
+| **v1.7** | 注册地址、经营地址省市区统一 **`GET /agri/region/tree`** 选择（§6.8） |
 | **v1.6** | 角色权限字符统一为 **merchant** / **member**；会员绑定密码复制会员 `sys_user.password`（不使用初始密码字段） |
 
 ---
 
-*文档版本：v1.6 · 关联《商户管理技术方案.md》v1.6、《商户入驻审核功能需求.md》v1.1、《店铺管理功能需求.md》v1.3.6*
+*文档版本：v1.7 · 关联《商户管理技术方案.md》v1.7、《商户入驻审核功能需求.md》v1.1、《店铺管理功能需求.md》v1.3.6*

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

@@ -1,6 +1,7 @@
 # 商户管理 — 技术方案
 
-> **依据：** 《商户管理功能需求.md》v1.6  
+> **依据：** 《商户管理功能需求.md》v1.7  
+> **v1.7：** 省市区三级数据 **`GET /agri/region/tree`**（平台）、**`GET /api/region/tree`**（C 端）；商户 **注册地址** `reg_region_*`、**经营地址** `biz_region_*` 落库约定见 §9.9。  
 > **v1.6：** 角色 **role_key=merchant/member**；`MerchantBindMapper` 严格按 `role_key` 过滤；会员绑定 **login_name=会员名称、admin_name=会员昵称**；`sysUserInitPassword` DTO 字段 **后端未使用**。  
 > **v1.5：** 同步 `sql/biz_merchant.sql` 全字段 COMMENT；新增 `id_card_type`、`legal_id_card_type`、`reg_region_*`、`corp_bank_account`；平台企业新增仅校验法人姓名+企业名称。  
 > **关联：** 《店铺管理》《商品分类》《商品管理》功能需求 v1.3.6 / v1.3.1 / v1.3.3（`doc/农资商城web/`）  
@@ -149,6 +150,8 @@ biz_merchant（商户）
 | GET | `/{merchantId}/openShopCheck` | 是否可开店 |
 | GET | `/{merchantId}/shops` | 商户下店铺简要列表 |
 
+**省市区（注册/经营地址选择，独立模块）：** `GET /agri/region/tree` — 见 §9.9；C 端同源 `GET /api/region/tree`。
+
 ### 3.2 列表 `GET /list`
 
 | Query | 说明 |
@@ -299,8 +302,8 @@ biz_merchant（商户）
 
 | 文档 | 版本 |
 |------|------|
-| 商户管理功能需求.md | v1.6 |
-| 商户管理测试用例.md | v1.3 |
+| 商户管理功能需求.md | v1.7 |
+| 商户管理测试用例.md | v1.4 |
 | 店铺管理功能需求/技术方案 | v1.3.6 / v1.2.5 |
 | 商品分类功能需求/技术方案 | v1.3.1 / v1.1 |
 | 商品管理功能需求/技术方案 | v1.3.3 / v1.2 |
@@ -543,6 +546,47 @@ SQL：`mapper/merchant/MerchantBindMapper.xml`
 
 存储仍明文；可使用 RuoYi `@Sensitive` 或 VO 转换。
 
+### 9.9 省市区接口与落库（`biz_region`）
+
+**数据源：** 表 `biz_region`（`sql/biz_region.sql`）；Service `RegionServiceImpl`（内存缓存树）。
+
+| 端 | 方法 | 路径 | 权限 |
+|----|------|------|------|
+| 平台 | GET | `/agri/region/tree` | 登录即可 |
+| C 端 | GET | `/api/region/tree` | `@Anonymous` |
+
+**响应节点（`RegionTreeVO`）：**
+
+| 字段 | 说明 |
+|------|------|
+| id, pid | 表主键与父 id（省级 pid=0） |
+| name | 区域名称 |
+| type | 1省 2市 3区县 |
+| code | 行政区划编码（如 110101） |
+| children | 下级节点数组 |
+
+**商户表单落库（选定区县 leaf 节点）：**
+
+| 场景 | code 字段 | name 字段 | 详细地址 |
+|------|-----------|-----------|----------|
+| 企业注册地址 | `reg_region_code` = `String.valueOf(区县.code)` | `reg_region_name` = 省/市/区县 name 用 `/` 连接 | `company_detail_address` |
+| 经营地址（个人/企业） | `biz_region_code` | `biz_region_name` | `biz_detail_address` |
+
+**示例：**
+
+```json
+{
+  "regRegionCode": "110101",
+  "regRegionName": "北京市/市辖区/东城区",
+  "companyDetailAddress": "xx路1号",
+  "bizRegionCode": "110101",
+  "bizRegionName": "北京市/市辖区/东城区",
+  "bizDetailAddress": "yy大厦"
+}
+```
+
+**校验：** 与 §9.2 一致，`biz_region_code` 与 `biz_region_name` 须同时非空方计入 `biz_complete`；C 端入驻 `EntryApplyFormValidator.requireRegion` 同理。
+
 ---
 
-*文档版本：v1.6 · MySQL 5.7.39 · RuoYi v3.9.2-springboot2 · 关联《商户管理功能需求.md》v1.6、《商户管理测试用例.md》v1.3*
+*文档版本：v1.7 · MySQL 5.7.39 · RuoYi v3.9.2-springboot2 · 关联《商户管理功能需求.md》v1.7、《商户管理测试用例.md》v1.4*

doc/农资商城web/组织管理/商户管理/商户管理测试用例.md

@@ -1,7 +1,7 @@
 # 商户管理 — 测试用例
 
-> **依据：** 《商户管理功能需求.md》v1.6、《商户管理技术方案.md》v1.6  
-> **范围：** 平台管理端 **商户管理** 模块（列表、入驻含 **绑定经营账号**、详情、编辑、认证、删除、协作接口）  
+> **依据：** 《商户管理功能需求.md》v1.7、《商户管理技术方案.md》v1.7  
+> **范围：** 平台管理端 **商户管理** 模块（列表、入驻含 **绑定经营账号**、详情、编辑、认证、删除、协作接口）；**省市区依赖** `GET /agri/region/tree`（§6.8 / §9.9）  
 > **排除：** C 端商城、会员模块独立 CRUD、商品/店铺/分类/订单模块的独立功能用例（订单 Facade 未建时按桩 `false` 测删商户正向）  
 > **环境：** RuoYi v3.9.2 平台端；接口基路径 `/agri/merchant`；UI 默认 `http://{host}/` + 农资管理菜单（以实际路由为准）
 
@@ -1128,6 +1128,32 @@
 | **测试步骤** | `GET /adminUserOptions` |
 | **预期结果** | 403 |
 
+### MER-API-051 省市区树接口（经营/注册地址数据源）
+
+| 要素 | 内容 |
+|------|------|
+| **测试模块** | 商户管理（依赖） |
+| **测试项** | GET /agri/region/tree |
+| **测试类型** | 接口测试 |
+| **测试工具** | Apifox |
+| **测试目的** | 验证 §6.8 三级树供地址选择 |
+| **前置条件** | 已登录平台；`biz_region` 表有数据 |
+| **测试步骤** | `GET /agri/region/tree` |
+| **预期结果** | `code=200`；`data[]` 为省级节点；含 `type=1` 及 `children`；末级区县 `type=3` 且带 `code` |
+
+### MER-API-052 编辑写入经营地址省市区
+
+| 要素 | 内容 |
+|------|------|
+| **测试模块** | 商户管理 |
+| **测试项** | PUT / |
+| **测试类型** | 接口测试 |
+| **测试工具** | Apifox |
+| **测试目的** | 验证 §9.9 落库与 `biz_complete` |
+| **前置条件** | 正常商户仅主体；从 MER-API-051 选取区县 |
+| **测试步骤** | `PUT /` 提交 `bizRegionCode=110101`、`bizRegionName=北京市/市辖区/东城区` 及其余经营必填项 |
+| **预期结果** | 成功；库表 `biz_region_code/name` 一致；`biz_complete=1` 时 msg 可含「已可开设店铺」 |
+
 ---
 
 ## 三、界面测试（Playwright）
@@ -1595,6 +1621,7 @@
 | **role_key=merchant** 的平台用户 | 用于 adminUserOptions、SYS_USER 绑定（MER-API-044/047） |
 | 有 user_name（memberCode）+ nickName 的会员 | 用于 MEMBER 绑定（MER-API-048） |
 | 会员名称已被经营账号 login_name 占用的会员 | 用于 MER-API-049 |
+| `biz_region` 省市区表数据 | MER-API-051 树接口；MER-API-052 编辑落库 |
 
 ---
 
@@ -1639,4 +1666,4 @@ test('MER-UI-001 列表加载', async ({ page }) => {
 
 ---
 
-*文档版本：v1.3 · 关联《商户管理功能需求.md》v1.6、《商户管理技术方案.md》v1.6*
+*文档版本：v1.4 · 关联《商户管理功能需求.md》v1.7、《商户管理技术方案.md》v1.7*