# 商户管理 — 功能需求说明

> 本文档在《商户管理功能需求-草稿》基础上整理，并关联《农资商城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.5：** 对齐 `biz_merchant_account` 新结构：绑定仅写关联行（`account_id=user_id`，`shop_id=NULL`）；登录凭证在 `sys_user`。  
> **v1.4：** 平台 **新增商户** 须强制绑定 **平台管理员账号** 或 **C 端会员账号**，并同步创建该商户下首条 **商户经营账号**（`biz_merchant_account`）。  
> **v1.3：** 除入驻绑定外，各模块 **不展开** 会员注册、会员运营等独立能力。  
> **v1.2：** 商户入驻 **仅采集主体资质**；经营与结算信息在 **编辑商户** 中补全。

---

## 1. 模块定位

### 1.1 业务目标

在农资商城 **平台管理端（Web）** 提供商户全生命周期管理能力：**主体入驻建档**、资料维护、认证状态管理，并为后续 **店铺开设** 提供可选商户主体。

**不包含：** 会员注册、会员等级运营、会员列表管理等 **会员模块** 能力（入驻时 **可选绑定已有会员** 除外）。

### 1.2 在业务链中的位置

```text
平台运营
    └── 商户管理（本模块）── 创建/维护商户主体（本期：仅主体资质入驻）
            └── 店铺管理 ── 按商户开设店铺（店铺经营账号在店铺侧配置，见店铺管理需求）
                    └── 商品管理 ── 店铺下商品上架与审核
                    └── 商品分类 ── 店铺侧分类维护
```

| 关联模块 | 与本模块关系 | 边界说明 |
|----------|----------|
| 店铺管理 | 下游依赖 | 选 **未删除且认证正常、经营信息完整** 的商户开店；入驻已创建首条经营账号，开店时仍可增删经营账号 |
| 会员管理 | 入驻可选数据源 | 新增商户选「会员」时从 `biz_member` 检索；**不** 在商户列表展示会员列 |
| 商品管理 | 间接关联 | 商户状态变更不自动改变商品状态 |
| 商品分类 | 无直接操作 | 由店铺侧维护 |

### 1.3 使用角色

| 角色 | 说明 |
|------|------|
| 平台管理员 | 商户列表、**主体入驻**、详情、认证状态、编辑（含补全经营信息）、删除 |

---

## 2. 业务概念

| 概念 | 说明 |
|------|------|
| 商户 | 平台入驻的经营主体，分 **个人**、**企业** |
| 主体资质 | 本期入驻 **必须** 完成的法定/身份资料：个人为 **个人信息**；企业为 **法定代表人信息 + 企业信息** |
| 商户经营信息 | 商户名称、客服电话、经营地址、联系人、结算银行等；**本期不入驻表单**，在 **编辑商户** 中补全 |
| 商户所属单位 | 列表展示：个人 = **姓名**；企业 = **企业名称**（来自主体资质） |
| 商户名称 | 对外经营名称；在 **编辑** 中填写；未填时列表可用所属单位代显或显示「待完善」 |
| 认证状态 | 正常 / 已冻结 / 已注销；新建提交后默认 **正常** |
| 认证时间 | 见第 7.3 节 |
| 资料完整度 | **主体资质**（入驻即有）+ **商户经营信息**（编辑补全）；**开店前** 须后者完整 |
| 已绑定店铺数量 | 该商户下未删除店铺数 |
| 商户经营账号 | 商家端登录账号；**新增商户成功时自动创建 1 条**（见第 6.7 节） |
| 绑定类型 | 新增时二选一：**平台管理员** / **会员** |
| 逻辑删除 | 见第 10 节 |

---

## 3. 功能结构

```text
商户管理
├── 商户列表（含高级检索）
├── 添加商户（本期：主体资质 + 强制绑定经营账号）
│   ├── 个人入驻 / 企业入驻
│   └── 绑定经营账号（平台管理员 或 会员）
├── 查看详情（含认证状态调整）
├── 编辑商户（主体资质 + 商户经营信息；认证状态只读）
└── 删除商户（逻辑删除）
```

---

## 4. 商户列表

### 4.1 列表字段

| 字段 | 说明 |
|------|------|
| 商户所属单位 | 个人：姓名；企业：企业名称 |
| 商户类型 | 个人 / 企业 |
| 商户名称 | 已填则显示；未填显示 **待完善** 或回退显示所属单位 |
| 联系人 | 经营信息中的联系人姓名；未完善显示 **—** |
| 联系人手机 | 经营信息中的联系人手机；未完善显示 **—** |
| 已绑定店铺数量 | 未删除店铺总数 |
| 认证状态 | 正常 / 已冻结 / 已注销 |
| 认证时间 | 见第 7.3 节 |
| 操作 | 查看详情、编辑、删除 |

### 4.2 列表行为

- 分页；默认 **创建时间倒序**。
- 默认不展示已逻辑删除商户。
- 全部未删除商户可查看详情。

### 4.3 列表操作可用性（随认证状态）

| 认证状态 | 查看详情 | 编辑 | 删除 |
|----------|:--------:|:----:|:----:|
| 正常 | ✓ | ✓ | 满足第 10 节时可用 |
| 已冻结 | ✓ | ✓ | 满足第 10 节时可用 |
| 已注销 | ✓ | ✗ | ✗ |

---

## 5. 高级检索

| 检索项 | 规则 |
|--------|------|
| 商户名称 | 模糊匹配（含「待完善」商户若用所属单位代显，则同时支持按所属单位检索，与产品统一） |
| 认证状态 | 正常 / 已冻结 / 已注销 |

---

## 6. 添加商户（平台端 · 仅主体最小必填）

新增时 **必须** 选择 **个人 / 企业** 主体类型，**必须** 绑定经营账号（§6.7）；**无需审核**；**不强制** 填写完整商户经营信息（可在编辑中补全）。

### 6.1 公共流程

```text
选择主体类型（个人 / 企业）
    → 填写主体资质（见 6.2 / 6.3）
    → 选择绑定类型并检索选定账号（见 6.7）
    → 提交
    → 系统校验（6.4、6.5、6.7）
    ├── 失败 → 逐项提示
    └── 成功 → 认证状态=正常，记录认证时间
            → 创建该商户下首条商户经营账号
            → 提示：「请尽快在编辑中完善商户经营信息后再开设店铺」
```

### 6.2 个人入驻 — 平台端填写项（最小必填）

| 区块 | 字段 | 平台端 |
|------|------|--------|
| 个人信息 | 姓名 | **必填** |
| 个人信息 | 其余（证件、地址、联系人、银行等） | **选填** |
| 商户经营信息 | 全部 | **不填**（编辑补全） |

> **对比移动端：** C 端个人入驻须完整填写个人信息 + 经营信息 + 店铺信息，并走 **入驻审核 + 公示**（见《商户入驻审核功能需求》v1.1）。

### 6.3 企业入驻 — 平台端填写项（最小必填）

| 区块 | 字段 | 平台端 |
|------|------|--------|
| 法人信息 | 法人姓名 | **必填** |
| 法人信息 | 其余 | **选填** |
| 企业信息 | 企业名称 | **必填** |
| 企业信息 | 其余（信用代码、注册地址等） | **选填** |
| 商户经营信息 | 全部 | **不填**（编辑补全） |

> **对比移动端：** C 端企业须完整填写企业信息 + 法人信息 + 经营信息 + 店铺信息，并走 **入驻审核 + 公示**。

### 6.4 添加时的通用校验

- 必填、格式、图片规格校验；证件/营业期限区间合法。
- 证件或营业期限已过期：风险提示后 **允许提交**；运营可改认证为已冻结。

### 6.5 添加时的唯一性校验

| 校验项 | 规则 | 提示示例 |
|--------|------|----------|
| 统一社会信用代码 | 企业类型；未删除企业商户不可重复 | 该统一社会信用代码已入驻 |

> **商户名称** 入驻时不采集；在 **编辑** 填写时校验平台唯一（第 9 节）。

### 6.6 资料完整度与开店前置

| 资料块 | 完成时机 | 开店要求 |
|--------|----------|----------|
| 主体资质 | **入驻** 提交成功 | 已有 |
| 商户经营信息 | **编辑商户** 中填写并保存 | **开设店铺前必须完整** |

**商户经营信息 — 完整判定（全部有值且校验通过）：**

| 字段 | 个人/企业 |
|------|-----------|
| 商户名称 | 必填；平台唯一 |
| 客服电话 | 必填 |
| 经营地址、详细地址 | 必填；**经营地址省市区** 通过 §6.8 接口选择后写入 `biz_region_code` / `biz_region_name` |
| 联系人姓名、手机、邮箱 | 必填 |
| 开户银行、支行名称 | 必填 |
| 银行卡号 / 对公银行卡号 | 必填（个人/企业对应） |
| 营业执照电子版 | 企业 **必填** |
| 开户许可证 | 企业 **必填** |

店铺管理 **添加店铺** 选择商户时：

```text
校验商户认证=正常且未删除
    → 校验商户经营信息是否完整
    ├── 否 → 阻断，提示「请先完善该商户的经营与结算信息」
    └── 是 → 允许继续开店（店铺经营账号见《店铺管理功能需求》）
```

### 6.7 新增商户 — 强制绑定经营账号（v1.6）

新增提交前 **必须** 选择绑定类型（二选一），并完成远程搜索选定一条记录；未选则阻断提交。

#### 6.7.1 绑定类型：平台管理员

| 项 | 规则 |
|----|------|
| 检索范围 | `sys_user` 中 **已分配 role_key=merchant**（商户经营角色）的账号 |
| 检索字段 | 手机号、用户名称（`user_name`）模糊匹配；展示用户昵称 |
| 保存 — `biz_merchant_account` | insert `(account_id=所选 user_id, merchant_id, shop_id=NULL)`；展示用 **nick_name** / **user_name** 来自既有 `sys_user` |
| 密码 | 沿用所选 `sys_user.password`（不在 `biz_merchant_account` 存储） |

#### 6.7.2 绑定类型：会员

| 项 | 规则 |
|----|------|
| 检索范围 | `sys_user` 中 **已分配 role_key=member** 的账号（`member_id=user_id`） |
| 检索字段 | 手机号、**会员名称**（`user_name`）模糊匹配 |
| 保存 — `sys_user_role` | 向已有会员用户 **追加** **merchant** 角色（`user_id=member_id`） |
| 保存 — `biz_merchant_account` | insert `(account_id=member_id, merchant_id, shop_id=NULL)`；登录名/姓名沿用会员 `sys_user`（**user_name** 必填、**nick_name** 必填） |
| 密码 | 沿用会员 `sys_user.password`（不在 `biz_merchant_account` 存储） |

#### 6.7.3 校验与提示

| 场景 | 提示示例 |
|------|----------|
| 未选绑定类型 | 请选择并绑定管理员账号或会员账号 |
| 选管理员但未选人 | 请选择平台管理员账号 |
| 选会员但未选人 | 请选择会员账号 |
| 用户无 merchant 角色 | 所选用户未分配商户经营角色 |
| 登录名已占用 | 经营账号登录名已存在 |
| 会员无昵称 | 会员昵称不能为空，无法作为经营账号管理员姓名 |
| 会员无名称 | 会员名称不能为空，无法作为经营账号登录名 |

> **说明：** 本条仅在 **平台新增商户** 生效；编辑商户、店铺侧增删经营账号规则仍见《店铺管理功能需求》。

### 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 端入驻校验失败 |

**示例：** 选择「北京市 / 市辖区 / 东城区」→ `biz_region_code=110101`，`biz_region_name=北京市/市辖区/东城区`。

---

## 7. 认证状态（定稿）

### 7.1 状态枚举

| 状态 | 含义 |
|------|------|
| **正常** | 主体已入驻；可编辑、可开店（须经营信息完整） |
| **已冻结** | 不可新开店；可编辑 |
| **已注销** | 资料只读；不可开店、不可编辑、不可删除 |

入驻提交后 **直接为正常**，不经「待审核」。

### 7.2 状态与操作权限矩阵

| 操作 | 正常 | 已冻结 | 已注销 |
|------|:----:|:------:|:------:|
| 店铺管理 **新增店铺** | ✓（且经营信息完整） | ✗ | ✗ |
| **编辑** 商户 | ✓ | ✓ | ✗ |
| **查看详情** | ✓ | ✓ | ✓ |
| 详情中 **改认证状态** | ✓ | ✓ | 仅可恢复为正常 |
| **删除** 商户 | 满足第 10 节时 ✓ | 满足第 10 节时 ✓ | ✗ |

店铺选商户：**未删除 + 认证正常 + 经营信息完整**。

### 7.3 认证时间 — 更新规则

| 触发 | 是否更新认证时间 |
|------|------------------|
| 入驻创建成功（正常） | ✓ |
| 详情保存认证状态变更 | ✓ |
| 编辑主体/经营信息 | ✗ |
| 店铺数量变化 | ✗ |

### 7.4 状态流转

（与 v1.1 相同：正常 ↔ 已冻结 ↔ 已注销，详情中操作及二次确认文案不变。）

| 流转 | 确认要点 |
|------|----------|
| 正常 → 已冻结 | 「冻结后不可新开店铺」 |
| 已冻结 → 正常 | 二次确认 |
| → 已注销 | 「注销后资料不可编辑」 |
| 已注销 → 正常 | 「恢复后可编辑、可开店（须经营信息完整）」 |

### 7.5 认证状态变更后的联动

| 变更 | 店铺管理 | 商品管理 |
|------|----------|----------|
| → 已冻结 | 不可新开店；已有店不自动停业 | 不自动下架 |
| → 已注销 | 不可新开店 | 不自动下架 |
| → 正常 | 可选商户（须经营信息完整） | — |

---

## 8. 查看详情

### 8.1 展示范围

- 主体资质（个人/法人/企业）全部字段及证照图。
- **商户经营信息**：已填则展示；未填则提示 **待完善** 及字段清单。
- 认证状态、认证时间、已绑定店铺数量。
- 可提供跳转店铺列表（按本商户筛选）。

### 8.2 详情页能力

| 能力 | 说明 |
|------|------|
| 信息展示 | 只读 |
| 认证状态调整 | **仅本页** 可改 |
| 完善经营信息 | 引导至 **编辑商户** |

### 8.3 与编辑的区别

| 项目 | 查看详情 | 编辑 |
|------|----------|------|
| 认证状态 | 可改（已注销仅可恢复） | 只读 |
| 主体资质、经营信息 | 只读 | 正常/已冻结时可改 |

---

## 9. 编辑商户

### 9.1 前置条件

认证状态为 **正常** 或 **已冻结**。

### 9.2 可编辑内容

| 资料块 | 说明 |
|--------|------|
| **主体资质** | 与入驻字段相同，可修改（商户类型仍不可改） |
| **商户经营信息** | 在编辑中 **首次填写或维护**（第 6.6 节字段表） |

### 9.3 不可编辑

- **商户类型**（个人/企业不可互转）。

### 9.4 校验

- 主体资质：同入驻。
- 经营信息：第 6.6 节必填及格式；**商户名称** 平台唯一（排除自身）。
- 企业：**统一社会信用代码** 入驻后 **只读**（不可改）；其他企业主体字段按产品是否允许修改（建议主体关键字段只读，仅经营信息可改）。

> **建议定稿：** 入驻后 **统一社会信用代码、个人证件号** 不可修改；若需更正走运营线下流程。文档写为：企业统一社会信用代码、个人证件号码 **保存后不可修改**。

### 9.5 保存成功

不更新认证时间。经营信息从未完整变为完整时，可 Toast「已可开设店铺」。

---

## 10. 删除商户（定稿）

（与 v1.1 相同：逻辑删除；前置为正常/已冻结、0 店铺、0 未完成订单、二次确认。）

---

## 11. 业务规则汇总

| 编号 | 规则 |
|------|------|
| R1 | 单商户可开设 **多个** 未删除店铺；**本期不设数量上限**（`shop_count` 仅作统计展示） |
| 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 | 认证状态仅在 **查看详情** 修改 |
| R6 | 开店可选商户：未删除 + **正常** + **经营信息完整** |
| R7 | **商户名称** 在编辑时校验平台唯一；企业 **统一社会信用代码** 入驻时唯一 |
| R8 | 删除为逻辑删除，满足第 10 节 |
| R9 | 商户认证变更不自动停业、不下架商品 |
| R10 | 入驻 **仅采主体资质**；经营与结算信息 **编辑补全** |
| R11 | 主体关键标识（证件号、统一社会信用代码）入驻后 **不可改** |

---

## 12. 与关联模块的协作流程

### 12.1 商户入驻 → 补全资料 → 开店

```text
平台：添加商户 → 主体资质 + 绑定管理员/会员 → 正常 + 首条经营账号
    ↓
平台：编辑商户 → 补全商户经营信息 → 保存
    ↓
平台：店铺管理 → 添加店铺 → 选择商户（可继续维护经营账号）
    → 校验经营信息完整
    ↓
店铺创建成功；已绑定店铺数量 +1
```

### 12.2 商户冻结 / 注销

（与 v1.1 相同。）

---

## 13. 页面与交互要点

| 场景 | 要求 |
|------|------|
| 添加商户 | **主体资质** + **绑定类型**（管理员/会员）+ 远程搜索选人；**无** 经营结算字段 |
| 添加成功 | 提示去 **编辑** 完善经营信息后再开店 |
| 编辑商户 | **主体资质** + **商户经营信息**；认证状态只读；企业注册地址/经营地址省市区通过 §6.8 接口选择 |
| 列表 | **联系人/联系人手机**（来自经营信息）；无会员相关列 |
| 详情 | 经营信息未完成时 **待完善** 提示 |
| 删除 / 认证 | 同前序定稿 |

---

## 15. 数据库字段说明（与 SQL 对齐）

> **权威来源：** [`sql/biz_merchant.sql`](../../../../sql/biz_merchant.sql)、[`sql/biz_merchant_account.sql`](../../../../sql/biz_shop.sql)（账号段）、[`sql/biz_member.sql`](../../../../sql/biz_member.sql)（绑会员时）。

| 分组 | 主要字段 | 说明 |
|------|----------|------|
| 主键/状态 | `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`（§6.8 区县 code + 省/市/区 name 拼接）+ 详细地址 |
| 经营信息 | `merchant_name`, `service_phone`, `biz_region_*`, `contact_*`, `bank_*`, `business_license` | 经营地址：`biz_region_code/name`（§6.8）；平台新增可不填 |
| 经营账号 | `biz_merchant_account`（`account_id`、`merchant_id`、`shop_id`）+ `sys_user` 登录凭证 | 见 §6.7；**不在** `biz_shop` |

**枚举约定：** `gender`/`legal_gender`：0男 1女；`*_valid_type`：1区间 2长期；`del_flag`：0存在 2删除。

---

## 14. 修订记录

| 版本 | 说明 |
|------|------|
| v1.1 | 认证状态、删除、认证时间等定稿 |
| v1.2 | 入驻仅主体资质；经营信息编辑补全 |
| **v1.3** | **全模块不考虑会员**；删除会员绑定/暂缓章节及列表会员列 |
| **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.7 · 关联《商户管理技术方案.md》v1.7、《商户入驻审核功能需求.md》v1.1、《店铺管理功能需求.md》v1.3.6*
