# 我的服务 — 前端技术方案（C 端 · shop-app）

> **依据：** 《我的服务功能需求.md》v1.1、《我的服务技术方案.md》v1.3（仅作接口对照，**本文档独立维护**）  
> **关联：** 《会员注册登录前端技术方案.md》（登录前置）、后续《订单管理》等（地址被结算引用）  
> **范围：** C 端 **个人资料、修改密码、收货地址、商家入驻**；**不** 改后端、**不** 实现我的订单/消息中心/换绑手机。  
> **实现状态：** 已对齐 v1.3（地址 `regionCode`/`regionName` + 省市区级联），待联调。

---

## 1. 技术栈与约定

| 项 | 说明 |
|----|------|
| 框架 | uni-app **Vue 3** + **uview-plus** |
| 请求 | `@/utils/request`；须登录接口默认带 `Authorization: Bearer {token}` |
| 登录前置 | **MS0**：子功能经 `ensureApiToken` / `navigateMinePage` 拦截 |
| 上传 | `@/utils/upload` → `POST /common/upload` |
| 省市区 | `GET /api/region/tree`（匿名）+ `up-cascader`；逻辑对齐 `ruoyi-ui/utils/region.js` |
| 样式 | `styles/mine.scss` |
| 路由 | 业务页在 **`subpackage/account/`**；Tab 在 **`pages/mine/index`** |

---

## 2. 页面与路由

| 页面 | 路径 | 包 | 入口 |
|------|------|-----|------|
| 我的（服务入口） | `pages/mine/index` | 主包 Tab | TabBar「我的」 |
| 个人资料 | `subpackage/account/profile` | 分包 | 我的 → 编辑个人资料 |
| 修改密码 | `subpackage/account/password` | 分包 | 我的 → 修改密码 |
| 收货地址列表 | `subpackage/account/address-list` | 分包 | 我的 → 收货地址 |
| 地址编辑 | `subpackage/account/address-edit` | 分包 | 列表新增/编辑 |
| 商家入驻 | `subpackage/account/entry-apply` | 分包 | 我要入驻 |
| 我的入驻申请 | `subpackage/account/entry-list` | 分包 | 我的入驻申请 |
| 申请详情 | `subpackage/account/entry-detail` | 分包 | 列表项 |

**路径常量：** `utils/pageRoute.js` → `PAGE_PROFILE`、`PAGE_PASSWORD`、`PAGE_ADDRESS_*`、`PAGE_ENTRY_*`

---

## 3. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 我的 Tab | `shop-app/pages/mine/index.vue` | 服务菜单入口 |
| 资料/密码/地址/入驻 | `shop-app/subpackage/account/*.vue` | 各子页 |
| 会员 API | `shop-app/api/member.js` | profile / password / address |
| 地区 API | `shop-app/api/region.js` | `GET /api/region/tree` |
| 入驻 API | `shop-app/api/merchantEntry.js` | agreement / apply / my |
| 地区工具 | `shop-app/utils/region.js` | normalize、路径回显、解析区县 |
| 地区组件 | `shop-app/components/mine/RegionFields.vue` | **级联选择**（替换手填三栏） |
| 入驻表单 | `shop-app/utils/entryForm.js` | 分步校验、提交体 |
| 导航返回 | `utils/navBack.js`、`components/common/SafeNavBar.vue` | Tab 进分包无系统返回键时回「我的」 |
| 其它 | `mineNav.js`、`entryConstants.js`、`ImageUpload`、`entry/*` | 见 v1.0 |

---

## 4. 接口封装

### 4.1 会员 `/api/member`（须 Token）

| 方法 | HTTP | 路径 |
|------|------|------|
| `getMemberProfile` | GET | `/profile` |
| `updateMemberProfile` | PUT | `/profile` |
| `changeMemberPassword` | PUT | `/password` |
| `getAddressList` | GET | `/address/list` |
| `addAddress` | POST | `/address` |
| `updateAddress` | PUT | `/address` |
| `deleteAddress` | DELETE | `/address/{id}` |
| `setDefaultAddress` | PUT | `/address/{id}/default` |

#### 个人资料（v1.2）

可写：`nickName`、`avatar`、`email`、`sex`。**无** `birthday`。

#### 收货地址（v1.3 · 重要变更）

| 字段 | 说明 |
|------|------|
| `regionCode` | 区县级 `code`（字符串提交） |
| `regionName` | 省/市/区，**`/` 拼接**（如 `青海省/西宁市/城西区`） |
| `detailAddress` | 街道门牌 |
| ~~province/city/district~~ | **已废弃**，勿再提交 |

列表项 `MemberAddressVO`：`regionCode`、`regionName`、`fullAddress`（后端拼接展示用）。

### 4.2 省市区 `/api/region`

| 方法 | HTTP | 路径 | 鉴权 |
|------|------|------|------|
| `getRegionTree` | GET | `/tree` | **匿名** |

响应：树节点 `code`、`name`、`type`（1 省 2 市 3 区县）、`children`。

**前端规则：**

- `normalizeRegionTree` 供 `up-cascader` 使用；
- 确认时 `parseRegionSelection`：**末级须 type=3**；
- `regionName = 路径名称 join('/')`；
- `regionCode = 末级 code`。

### 4.3 入驻 `/api/merchant/entry`

与 v1.2 相同；经营/注册地址字段为 `bizRegionCode`/`bizRegionName`、`regRegionCode`/`regRegionName`，UI 共用 `RegionFields`。

---

## 5. 地区组件（`RegionFields.vue`）

```text
点击「所在地区」行
    → 弹出 up-cascader（省 → 市 → 区）
    → 确认后 emit：
        regionCode、regionName、pathCodes（回显用）
        兼容 code、name（入驻 applyRegion 使用）
```

**使用页面：**

- `address-edit.vue` — 收货地址；
- `EntryPersonBiz` / `EntryEnterpriseBiz` / `EntryEnterpriseSubject` — 入驻经营/注册地址。

**缓存：** `loadRegionCascaderTree()` 模块内缓存，避免重复请求。

---

## 6. 关键交互与规则

| 规则 | 前端落实 |
|------|----------|
| MS-A · 级联 | 功能需求 §8.3「省/市/区级联」→ `RegionFields` + `/api/region/tree` |
| MS-A1～A4 | 默认互斥、删除确认、列表用 `fullAddress` 或 `regionName`+详细 |
| MS-P2 | 昵称 ≤30 字 |
| MS-E6 | 待审/公示阻塞新入驻 |

---

## 7. 联调检查清单

- [ ] `GET /api/region/tree` 返回三级树
- [ ] 地址新增/编辑提交 `regionCode`+`regionName`，**无** province/city/district
- [ ] 编辑地址能按 `regionCode` 回显级联路径
- [ ] 未选至区县时前端提示「请选择完整的省市区」
- [ ] 入驻经营/注册地址同样走级联
- [ ] 资料、密码、入驻其它项同 v1.2 清单

---

## 8. 非本期

| 项 | 说明 |
|----|------|
| 我的订单、消息中心 | 另模块 |
| 手机号换绑 | — |

---

## 9. 修订记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版：我的 Tab、资料/密码/地址/入驻分包 |
| **v1.1** | password 独立；email/sex |
| **v1.2** | 资料移除 birthday；昵称 ≤30 |
| **v1.3** | 地址字段改为 **regionCode/regionName**；`api/region` + `RegionFields` 级联 |
| **v1.3.1** | 入驻列表/详情/申请：`SafeNavBar` + `smartNavigateBack`（Tab 进分包可返回） |

---

*文档版本：v1.3.1 · 关联《我的服务功能需求.md》v1.1*
