店铺关注

doc/消费者APP/我的店铺关注/我的店铺关注前端技术方案.md

@@ -0,0 +1,174 @@
+# 我的店铺关注 — 前端技术方案（C 端 · shop-app）
+
+> **依据：** 《我的店铺关注功能需求.md》v1.0、《我的店铺关注技术方案.md》v1.0（仅作接口对照，**本文档独立维护**）  
+> **关联：** 《店铺主页前端技术方案》、《我的服务前端技术方案》  
+> **范围：** C 端 **已关注店铺列表、进店、列表内取消关注**；**不** 改后端、**不** 在本模块新增关注（在店铺主页完成）。  
+> **实现状态：** 页面与 API 封装已落地，待与 `GET /api/member/shop-follows` 联调。
+
+---
+
+## 1. 技术栈与约定
+
+| 项 | 说明 |
+|----|------|
+| 框架 | uni-app **Vue 3** + **uview-plus** |
+| 请求 | `@/utils/request`；列表为 **`TableDataInfo`**（`rows` + `total`） |
+| 鉴权 | **须登录**；`ensureApiToken` / `navigateMinePage` 与我的服务 **MS0** 一致 |
+| 写操作 | 取消关注 **复用** `DELETE /api/shop/{shopId}/follow`（`api/shop.js`） |
+| 展示映射 | `mapShopFollowList`（`utils/shopDisplay.js`），字段口径与店铺主页一致 |
+| 导航返回 | `SafeNavBar` + `smartNavigateBack`（从 Tab「我的」进入分包） |
+
+---
+
+## 2. 页面与路由
+
+| 页面 | 需求代号 | 路径 | 入口 |
+|------|----------|------|------|
+| 我的店铺关注列表 | **A** | `subpackage/account/shop-follow-list` | 我的 Tab →「我的店铺关注」 |
+
+**`pages.json`：** 分包 `pkg-account`，`navigationStyle: custom`（与入驻列表一致）
+
+**路径常量：** `PAGE_SHOP_FOLLOW_LIST`（`utils/pageRoute.js`）
+
+**无 Query 参数**；未登录由 `ensureApiToken` 拦截并引导登录。
+
+---
+
+## 3. 文件清单
+
+| 类型 | 路径 | 说明 |
+|------|------|------|
+| 列表页 | `shop-app/subpackage/account/shop-follow-list.vue` | 下拉刷新、上拉分页、空态、取关 |
+| 列表 UI | `shop-app/components/shop/ShopFollowList.vue` | 店铺卡片 +「取消关注」 |
+| 会员 API | `shop-app/api/member.js` | `getShopFollowList` |
+| 店铺 API | `shop-app/api/shop.js` | `unfollowShop`（复用） |
+| 常量 | `shop-app/constants/shopFollow.js` | 分页大小、空态文案 |
+| 我的 Tab | `shop-app/pages/mine/index.vue` | 菜单「我的店铺关注」 |
+
+---
+
+## 4. 接口封装
+
+### 4.1 列表（本模块）
+
+| 方法 | HTTP | 路径 | 鉴权 |
+|------|------|------|------|
+| `getShopFollowList(params)` | GET | `/api/member/shop-follows` | **须 Token** |
+
+**Query：** `pageNum`、`pageSize`（默认 10，`SHOP_FOLLOW_PAGE_SIZE`）
+
+**`rows` 元素映射为：**
+
+| 字段 | 前端用途 |
+|------|----------|
+| shopId | 进店、取关 |
+| shopName | 卡片标题 |
+| shopAvatar | `displayAvatar` |
+| shopStatus | `isClosed` →「休息中」标签 |
+| rating | `showRating` / `ratingText` |
+| fansCount | 粉丝展示 |
+| followTime | 仅排序依据，**UI 不展示** |
+
+### 4.2 取消关注（复用店铺主页）
+
+| 方法 | HTTP | 路径 |
+|------|------|------|
+| `unfollowShop(shopId)` | DELETE | `/api/shop/{shopId}/follow` |
+
+成功后 **本地移除** 该项（可选再调列表刷新；当前实现为本地 filter）。
+
+### 4.3 进店
+
+| 方法 | 说明 |
+|------|------|
+| `goShopHome(shopId)` | `utils/shopNav.js` → 店铺主页 |
+
+---
+
+## 5. 页面逻辑（`shop-follow-list.vue`）
+
+```text
+onShow
+  → ensureApiToken(false) 未登录则 return
+  → reloadList(true) 拉第一页
+
+下拉刷新
+  → refresherrefresh → reloadList(true)
+
+上拉触底
+  → scrolltolower → fetchPage(false)
+
+点击卡片
+  → goShopHome(shopId)
+
+点击「取消关注」
+  → showModal 确认
+  → unfollowShop
+  → 成功：列表移除该项 + Toast
+
+空列表
+  → 「暂无关注的店铺」+ 按钮「去逛逛」→ switchTab 首页
+```
+
+| 规则编号 | 前端实现 |
+|----------|----------|
+| SF0 / SF2 | `ensureApiToken`、`navigateMinePage` |
+| SF3 | 后端 `ORDER BY create_time DESC` |
+| SF5 | 整卡点击进店 |
+| SF6 | 本页 **无** 关注按钮 |
+| SF7 | 已删店由后端 JOIN 过滤 |
+| SF8 | 取关后项消失 |
+| 停业展示 | `shopStatus=1` 显示「休息中」，仍可进店 |
+
+---
+
+## 6. 组件说明（`ShopFollowList.vue`）
+
+- 布局对齐 `components/search/ShopList.vue`，增加 **取消关注**（`@click.stop` 防冒泡）
+- 停业标签文案：`SHOP_CLOSED_LABEL`（`constants/shop.js`）
+
+---
+
+## 7. 异常与空态
+
+| 情形 | 行为 |
+|------|------|
+| 从未关注 | `u-empty` +「去逛逛」 |
+| 首屏加载失败 | 错误区 +「点击重试」 |
+| 取关失败 | request Toast；**不** 移除列表项 |
+| Token 失效 | request 401 → 登录引导（全局拦截） |
+
+---
+
+## 8. 联调检查清单
+
+- [ ] 登录后 `GET /api/member/shop-follows` 返回分页数据
+- [ ] 关注时间倒序与店主页关注后刷新可见
+- [ ] 点击进店跳转 `subpackage/shop/index?shopId=`
+- [ ] 列表取关后粉丝数在店主页同步（刷新店主页）
+- [ ] 已删店不出现在列表
+- [ ] 停业店显示「休息中」且可进店
+- [ ] 未登录从「我的」点菜单 → 引导登录
+
+---
+
+## 9. 非本期（前端不实现）
+
+| 项 | 说明 |
+|------|------|
+| 列表内搜索/筛选 | 需求未要求 |
+| 本页新增关注 | 仅店铺主页 |
+| 批量取消关注 | 未要求 |
+| 展示关注时间 | UI 可不展示 |
+
+---
+
+## 10. 修订记录
+
+| 版本 | 说明 |
+|------|------|
+| **v1.0** | 首版：关注列表页、分页、下拉刷新、取关、我的 Tab 入口 |
+
+---
+
+*文档版本：v1.0 · 不修改《我的店铺关注技术方案.md》（后端方案）。*

shop-app/PAGES.md

@@ -23,7 +23,8 @@ subpackage/
 │   ├── address-edit.vue
 │   ├── entry-apply.vue
 │   ├── entry-list.vue
-│   └── entry-detail.vue
+│   ├── entry-detail.vue
+│   └── shop-follow-list.vue
 ├── category/            # 分类子页
 │   ├── level1.vue
 │   └── goods-list.vue
@@ -60,6 +61,7 @@ subpackage/
 | `PAGE_HOME` | `/pages/index/index` |
 | `PAGE_GOODS_DETAIL` | `/subpackage/goods/detail` |
 | `PAGE_SEARCH_INDEX` | `/subpackage/search/index` |
+| `PAGE_SHOP_FOLLOW_LIST` | `/subpackage/account/shop-follow-list` |
 | `PAGE_SHOP_HOME` | `/subpackage/shop/index` |
 | `PAGE_SHOP_SEARCH` | `/subpackage/shop/search` |
 | `PAGE_REGISTER` | `/subpackage/account/register` |

shop-app/api/member.js

@@ -101,3 +101,15 @@ export function setDefaultAddress(addressId) {
     method: 'PUT'
   })
 }
+
+/**
+ * 我的店铺关注列表（须登录）
+ * @returns {Promise<{code,msg,rows,total}>}
+ */
+export function getShopFollowList(params) {
+  return request({
+    url: '/api/member/shop-follows',
+    method: 'GET',
+    params
+  })
+}

shop-app/components/shop/ShopFollowList.vue

@@ -0,0 +1,103 @@
+<template>
+	<view class="follow-list">
+		<view
+			v-for="item in list"
+			:key="item.shopId"
+			class="follow-card"
+			@click="emit('item-click', item)"
+		>
+			<image class="follow-card__avatar" :src="item.displayAvatar" mode="aspectFill" />
+			<view class="follow-card__body">
+				<view class="follow-card__title-row">
+					<text class="follow-card__name">{{ item.shopName }}</text>
+					<text v-if="item.isClosed" class="follow-card__tag">{{ closedLabel }}</text>
+				</view>
+				<view v-if="item.showRating || item.showFans" class="follow-card__meta">
+					<text v-if="item.showRating" class="follow-card__meta-item">评分 {{ item.ratingText }}</text>
+					<text v-if="item.showFans" class="follow-card__meta-item">粉丝 {{ item.fansCount }}</text>
+				</view>
+			</view>
+			<text class="follow-card__unfollow" @click.stop="emit('unfollow', item)">取消关注</text>
+		</view>
+	</view>
+</template>
+
+<script setup>
+import { SHOP_CLOSED_LABEL } from '@/constants/shop'
+
+defineProps({
+	list: {
+		type: Array,
+		default: () => []
+	}
+})
+
+const emit = defineEmits(['item-click', 'unfollow'])
+const closedLabel = SHOP_CLOSED_LABEL
+</script>
+
+<style lang="scss" scoped>
+.follow-list {
+	padding: 0 24rpx;
+}
+.follow-card {
+	display: flex;
+	align-items: center;
+	padding: 24rpx;
+	margin-bottom: 16rpx;
+	background: #fff;
+	border-radius: 12rpx;
+	box-shadow: 0 2rpx 12rpx rgba(0, 0, 0, 0.04);
+}
+.follow-card__avatar {
+	width: 96rpx;
+	height: 96rpx;
+	border-radius: 12rpx;
+	background: #eee;
+	flex-shrink: 0;
+}
+.follow-card__body {
+	flex: 1;
+	margin: 0 16rpx;
+	min-width: 0;
+}
+.follow-card__title-row {
+	display: flex;
+	align-items: center;
+	flex-wrap: wrap;
+	gap: 8rpx;
+}
+.follow-card__name {
+	font-size: 30rpx;
+	color: #333;
+	font-weight: 500;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+	max-width: 280rpx;
+}
+.follow-card__tag {
+	font-size: 22rpx;
+	color: #e65100;
+	background: #fff3e0;
+	padding: 4rpx 10rpx;
+	border-radius: 6rpx;
+	flex-shrink: 0;
+}
+.follow-card__meta {
+	margin-top: 8rpx;
+	display: flex;
+	flex-wrap: wrap;
+	gap: 16rpx;
+}
+.follow-card__meta-item {
+	font-size: 24rpx;
+	color: #999;
+}
+.follow-card__unfollow {
+	flex-shrink: 0;
+	font-size: 24rpx;
+	color: #999;
+	padding: 8rpx 0 8rpx 8rpx;
+}
+</style>

shop-app/constants/shopFollow.js

@@ -0,0 +1,5 @@
+/** 我的店铺关注列表每页条数 */
+export const SHOP_FOLLOW_PAGE_SIZE = 10
+
+/** 空列表文案 */
+export const SHOP_FOLLOW_EMPTY_TEXT = '暂无关注的店铺'

shop-app/pages.json

@@ -96,6 +96,13 @@
 						"navigationBarTitleText": "申请详情",
 						"navigationStyle": "custom"
 					}
+				},
+				{
+					"path": "shop-follow-list",
+					"style": {
+						"navigationBarTitleText": "我的店铺关注",
+						"navigationStyle": "custom"
+					}
 				}
 			]
 		},

shop-app/pages/mine/index.vue

@@ -58,7 +58,8 @@ import {
   PAGE_PASSWORD,
   PAGE_ADDRESS_LIST,
   PAGE_ENTRY_APPLY,
-  PAGE_ENTRY_LIST
+  PAGE_ENTRY_LIST,
+  PAGE_SHOP_FOLLOW_LIST
 } from '@/utils/pageRoute'
 
 const loggedIn = ref(false)
@@ -86,6 +87,10 @@ const menuSections = [
     title: '收货地址',
     items: [{ label: '收货地址', path: PAGE_ADDRESS_LIST, icon: 'map' }]
   },
+  {
+    title: '店铺关注',
+    items: [{ label: '我的店铺关注', path: PAGE_SHOP_FOLLOW_LIST, icon: 'heart' }]
+  },
   {
     title: '商家入驻',
     items: [

shop-app/subpackage/account/shop-follow-list.vue

@@ -0,0 +1,215 @@
+<template>
+	<view class="follow-page-wrap">
+		<safe-nav-bar title="我的店铺关注" />
+		<view class="follow-page">
+			<scroll-view
+				class="follow-page__scroll"
+				scroll-y
+				:style="{ height: scrollHeight }"
+				refresher-enabled
+				:refresher-triggered="refreshing"
+				@refresherrefresh="onPullRefresh"
+				@scrolltolower="onLoadMore"
+			>
+				<view v-if="loading && !list.length" class="follow-page__loading">
+					<u-loading-icon mode="circle" />
+				</view>
+
+				<view v-else-if="loadFailed && !list.length" class="follow-page__error">
+					<u-empty mode="list" text="加载失败" icon-size="80" />
+					<text class="follow-page__retry" @click="reloadList(true)">点击重试</text>
+				</view>
+
+				<view v-else-if="!list.length" class="follow-empty">
+					<u-empty mode="list" :text="emptyText" icon-size="80" />
+					<button class="mine-btn-primary follow-empty__btn" @click="goHome">去逛逛</button>
+				</view>
+
+				<template v-else>
+					<shop-follow-list
+						:list="list"
+						@item-click="onShopClick"
+						@unfollow="onUnfollow"
+					/>
+					<view class="follow-page__footer">
+						<text v-if="loadingMore">加载中...</text>
+						<text v-else-if="finished">没有更多了</text>
+					</view>
+				</template>
+			</scroll-view>
+		</view>
+	</view>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { onShow } from '@dcloudio/uni-app'
+import SafeNavBar from '@/components/common/SafeNavBar.vue'
+import ShopFollowList from '@/components/shop/ShopFollowList.vue'
+import { getShopFollowList } from '@/api/member'
+import { unfollowShop } from '@/api/shop'
+import { mapShopFollowList } from '@/utils/shopDisplay'
+import { ensureApiToken } from '@/utils/apiAuth'
+import { goShopHome } from '@/utils/shopNav'
+import { SHOP_FOLLOW_PAGE_SIZE, SHOP_FOLLOW_EMPTY_TEXT } from '@/constants/shopFollow'
+import { PAGE_HOME } from '@/utils/pageRoute'
+
+const list = ref([])
+const loading = ref(false)
+const loadingMore = ref(false)
+const finished = ref(false)
+const loadFailed = ref(false)
+const refreshing = ref(false)
+const pageNum = ref(1)
+const scrollHeight = ref('600px')
+const emptyText = SHOP_FOLLOW_EMPTY_TEXT
+const unfollowLoading = ref(false)
+
+function calcScrollHeight() {
+	try {
+		const sys = uni.getSystemInfoSync()
+		const h = sys.windowHeight || 600
+		// 自定义导航栏 + 状态栏约 88px
+		scrollHeight.value = `${h - 88}px`
+	} catch (e) {
+		scrollHeight.value = '600px'
+	}
+}
+
+async function fetchPage(isReset) {
+	if (isReset) {
+		loading.value = true
+		loadFailed.value = false
+		pageNum.value = 1
+		finished.value = false
+	} else {
+		if (finished.value || loadingMore.value) return
+		loadingMore.value = true
+	}
+	try {
+		const res = await getShopFollowList({
+			pageNum: pageNum.value,
+			pageSize: SHOP_FOLLOW_PAGE_SIZE
+		})
+		const rows = mapShopFollowList(res.rows || [])
+		const total = Number(res.total) || 0
+		if (isReset) {
+			list.value = rows
+		} else {
+			list.value = list.value.concat(rows)
+		}
+		finished.value =
+			rows.length < SHOP_FOLLOW_PAGE_SIZE || (total > 0 && list.value.length >= total)
+		if (!finished.value) {
+			pageNum.value += 1
+		}
+	} catch (e) {
+		loadFailed.value = true
+		if (isReset) {
+			list.value = []
+		}
+	} finally {
+		loading.value = false
+		loadingMore.value = false
+		refreshing.value = false
+	}
+}
+
+function reloadList(isReset) {
+	if (isReset) {
+		pageNum.value = 1
+	}
+	fetchPage(isReset)
+}
+
+function onPullRefresh() {
+	refreshing.value = true
+	reloadList(true)
+}
+
+function onLoadMore() {
+	if (!loading.value && !loadingMore.value && !finished.value && list.value.length) {
+		fetchPage(false)
+	}
+}
+
+function onShopClick(item) {
+	if (item && item.shopId) {
+		goShopHome(item.shopId)
+	}
+}
+
+function onUnfollow(item) {
+	if (!item || !item.shopId || unfollowLoading.value) return
+	uni.showModal({
+		title: '提示',
+		content: `确定取消关注「${item.shopName || '该店铺'}」吗？`,
+		success: (res) => {
+			if (!res.confirm) return
+			unfollowLoading.value = true
+			unfollowShop(item.shopId)
+				.then(() => {
+					list.value = list.value.filter((row) => row.shopId !== item.shopId)
+					uni.showToast({ title: '已取消关注', icon: 'none' })
+				})
+				.catch(() => {})
+				.finally(() => {
+					unfollowLoading.value = false
+				})
+		}
+	})
+}
+
+function goHome() {
+	uni.switchTab({ url: PAGE_HOME })
+}
+
+onShow(() => {
+	if (!ensureApiToken(false)) return
+	calcScrollHeight()
+	reloadList(true)
+})
+</script>
+
+<style lang="scss" scoped>
+@import '@/styles/mine.scss';
+
+.follow-page-wrap {
+	min-height: 100vh;
+	background: #f5f6f8;
+}
+.follow-page {
+	flex: 1;
+}
+.follow-page__scroll {
+	width: 100%;
+}
+.follow-page__loading,
+.follow-page__error {
+	padding: 80rpx 24rpx;
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+}
+.follow-page__retry {
+	margin-top: 24rpx;
+	font-size: 28rpx;
+	color: #2e7d32;
+}
+.follow-empty {
+	padding: 80rpx 48rpx;
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+}
+.follow-empty__btn {
+	margin-top: 40rpx;
+	width: 320rpx;
+}
+.follow-page__footer {
+	padding: 24rpx;
+	text-align: center;
+	font-size: 24rpx;
+	color: #999;
+}
+</style>

shop-app/utils/pageRoute.js

@@ -36,6 +36,8 @@ export const PAGE_ENTRY_APPLY = '/subpackage/account/entry-apply'
 export const PAGE_ENTRY_LIST = '/subpackage/account/entry-list'
 /** 入驻申请详情 */
 export const PAGE_ENTRY_DETAIL = '/subpackage/account/entry-detail'
+/** 我的店铺关注列表 */
+export const PAGE_SHOP_FOLLOW_LIST = '/subpackage/account/shop-follow-list'
 
 // —— 分包：分类 ——
 

shop-app/utils/shopDisplay.js

@@ -66,3 +66,28 @@ export function mapShopCardList(list) {
   if (!Array.isArray(list)) return []
   return list.map(mapShopCard).filter(Boolean)
 }
+
+/** 我的店铺关注列表行 */
+export function mapShopFollowItem(row) {
+  if (!row) return null
+  const rating = row.rating
+  const fansCount = row.fansCount != null ? Number(row.fansCount) : 0
+  return {
+    shopId: row.shopId,
+    shopName: row.shopName || '',
+    shopAvatar: row.shopAvatar,
+    displayAvatar: resolveFileUrl(row.shopAvatar) || SHOP_PLACEHOLDER,
+    shopStatus: row.shopStatus,
+    isClosed: String(row.shopStatus) === SHOP_STATUS_CLOSED,
+    rating,
+    fansCount,
+    showRating: rating != null && rating !== '',
+    ratingText: rating != null && rating !== '' ? String(rating) : '',
+    followTime: row.followTime
+  }
+}
+
+export function mapShopFollowList(list) {
+  if (!Array.isArray(list)) return []
+  return list.map(mapShopFollowItem).filter(Boolean)
+}