融合推荐算法的Next.js二手奢侈品电商平台

管理员使用独立后台登录页（/admin/login），仅role=admin的账号可进入后台；后台所有API路由经管理员权限中间件校验JWT role字段；非管理员访问后台路由重定向到403页面。

管理员后台用户列表：表格展示用户ID、邮箱、昵称、角色、注册时间、状态（正常/封禁）；支持按邮箱/昵称搜索，按角色筛选；操作列包含封禁/解封按钮（封禁用户无法登录，封禁需二次确认弹窗）、修改角色下拉选择。

管理员后台商品审核列表：展示待审核商品（标题、卖家、发布时间、缩略图）；点击进入审核详情页查看完整商品信息+证书；审核通过→商品上架公开可见，审核驳回→填写驳回理由（必填≥20字）并通知卖家；支持批量通过。

管理员后台独立证书审核列表面板：表格展示所有证书（缩略图、关联商品标题、上传时间、审核状态）；支持按审核状态筛选（待审核/已通过/已驳回）；支持批量通过（勾选多条待审核证书→点击批量通过按钮）；点击单条证书行进入证书审核详情页（见FR-CERT-002）；分页每页20条。

管理员后台"卖家申请审核"面板：表格展示所有待审核卖家申请（真实姓名、身份证号脱敏显示如"张**"、手机号脱敏、申请时间）；操作：通过（用户role变更为seller，发送通知）/ 驳回（填写理由≥10字，发送通知）；支持按状态筛选（待审核/已通过/已驳回）。

管理员后台"退款管理"面板：表格展示所有退款记录（订单号、退款金额、申请人、原因、状态、申请时间）；支持按状态筛选；卖家48小时未处理的退款自动升级标记"待仲裁"；管理员可查看退款详情（退款原因+说明+凭证图+双方信息），操作"同意退款"或"驳回退款"（需填写处理意见≥10字），处理后通知双方。

管理员后台"品牌管理"页面：表格展示预设品牌列表（品牌中文名、英文名、logo缩略图、状态启用/禁用）；支持搜索品牌名；操作：启用/禁用切换（禁用的品牌不出现在商品发布下拉列表中）、新增品牌（中英文名+logo图URL）；自定义品牌（卖家发布时输入的）自动进入品牌待审核列表，管理员可审核入库或驳回。

卖家在商品发布或编辑时可上传鉴定证书图片（最多5张，单张≤10MB，支持jpg/png/pdf）；上传后展示缩略图预览，支持删除重选；证书随商品一同提交审核；三态：上传进度条、格式/大小校验失败行内提示、上传成功缩略图。

管理员从证书审核列表（FR-ADMIN-004）点击进入证书审核详情页：展示证书大图预览（支持点击放大lightbox）、关联商品完整信息（标题/品牌/卖家）；底部操作区：审核通过按钮（绿色）、驳回按钮（红色）；驳回需弹出理由填写框（必填≥10字）；审核结果通过系统通知告知卖家；通过后证书在商品详情页公开展示，驳回后卖家可重新上传。

商品详情页设有"鉴定证书"独立展示区：审核通过的证书以可点击放大的缩略图展示，未通过或无证书时不显示该区域；点击缩略图弹出lightbox大图查看，支持左右切换多张证书。

商品详情页和列表卡片上展示收藏按钮（心形图标）；已登录用户点击切换收藏/取消收藏状态，POST /api/favorites/toggle 入参 {product_id}；未登录用户点击跳转登录页；收藏成功后按钮变为实心红色+toast提示"已收藏"。

个人中心"我的收藏"页面：以网格/列表展示所有收藏商品，按收藏时间倒序；支持分页加载（每页20条）；可在此页面取消收藏；三态：loading骨架屏、空收藏夹引导去逛逛、正常列表。

用户登录后自动记录浏览过的商品（去重，保留最近100条）；个人中心"浏览历史"页面按浏览时间倒序展示；支持单条删除和清空全部；未登录不记录历史。

前端埋点采集用户行为事件：商品浏览（进入详情页且停留≥3秒触发）、收藏、加入购物车、搜索关键词；POST /api/events 批量上报（每5条或每30秒批量发送），入参 {events:[{event_type, product_id, timestamp, metadata}]}；后端写入行为日志表供推荐算法离线训练。

已登录用户可将商品加入购物车（POST /api/cart/add 入参{product_id, quantity}，默认quantity=1）；购物车页面展示商品缩略图、标题、单价、数量加减、小计、全选/单选复选框、合计金额；支持批量删除选中项；商品下架或售出时购物车项标记"已失效"并置灰不可选中。

从购物车选中商品或商品详情页直接购买进入下单页：确认商品信息、选择收货地址（默认取最近使用）、填写买家备注（≤200字）；POST /api/orders 入参{items:[{product_id, quantity}], address_id, remark}；后端校验库存/商品状态，锁定商品为"已售出"；成功返回订单号并跳转订单详情页。

个人中心"我的订单"页面：按订单状态Tab切换（全部/待付款/待发货/待收货/已完成），订单卡片展示商品缩略图、标题、金额、状态标签、下单时间；点击进入订单详情：完整商品信息、收货地址、物流单号（已发货时）、状态时间线。卖家端"卖出订单"同理。

订单状态机：待付款→（买家确认付款）→已付款→（卖家填写物流单号发货）→已发货→（买家确认收货）→已完成；待付款订单30分钟未支付自动取消并释放商品；已完成订单15天后不可申请退款；每个状态变更记录时间戳并在详情页时间线展示。

卖家在"卖出订单"列表中已付款订单可见"发货"按钮；点击进入发货页：选择快递公司（下拉预设：顺丰/京东/中通/圆通/韵达等）、填写物流单号（必填，前端校验非空）；POST /api/orders/{id}/ship 入参{carrier, tracking_number}；后端校验订单状态为"已付款"且订单归属当前卖家；成功后订单状态变更为"已发货"，记录发货时间，发送通知给买家。

买家在订单详情页"已发货"状态时可见"确认收货"按钮；点击弹出二次确认弹窗（提示"确认收到商品后货款将打给卖家"）；确认后 POST /api/orders/{id}/confirm，后端校验订单状态为"已发货"且归属当前买家；成功后订单状态变更为"已完成"，发送通知给卖家，订单详情出现"去评价"入口。

卖家发布表单：商品标题、品牌（下拉选择+自定义）、品类（包包/腕表/珠宝/服饰/鞋履）、成色（全新/99新/95新/9成新/85新）、购买年份、原价、售价、库存数量（必填，≥1整数）、商品描述（富文本）、多图上传（最多12张，单张≤5MB）；必填字段前端+后端双重校验；发布后状态为"待审核"。

首页商品瀑布流/网格展示；支持按发布时间、价格高低排序；分页加载（每页20条，触底自动加载下一页）；每条卡片展示封面图、标题、价格、成色标签、收藏数；三态：loading骨架屏、空结果插画+文案、正常列表。

顶部搜索栏支持关键词模糊搜索（商品标题+品牌+描述）；侧边/顶部筛选面板：品牌多选、品类单选、成色多选、价格区间滑块（0–500000）、排序方式；筛选参数同步到URL query string，支持分享和浏览器回退；搜索结果高亮匹配关键词。

Next.js SSR渲染商品详情，含图片轮播、品牌/品类/成色/年份/价格信息、卖家信息卡片、商品描述富文本、鉴定证书展示区、收藏按钮、加入购物车按钮；页面meta标签动态生成（标题+描述+og:image）以优化SEO；底部展示"猜你喜欢"推荐卡片。

卖家可在"我的商品"列表对已发布商品进行编辑（修改标题、描述、价格、图片等）和下架操作；编辑后状态重置为"待审核"；下架商品不再出现在公开列表但保留数据，支持重新上架。

系统预设奢侈品品牌和品类数据供商品发布和筛选使用。品类固定为：包包、腕表、珠宝、服饰、鞋履（5个一级品类）。品牌预设≥30个主流奢侈品牌（Louis Vuitton/Gucci/Chanel/Hermès/Rolex/Cartier/Prada/Dior/Burberry等），品牌含中英文名+logo图URL；品牌支持启用/禁用（管理员后台管理）；商品发布时品牌下拉模糊搜索+支持输入自定义品牌（自定义品牌需管理员审核入库）。

卖家中心"我的商品"页面：表格展示该卖家所有商品（标题、缩略图、价格、状态标签、发布时间）；状态Tab筛选（全部/待审核/已上架/已下架/已驳回）；分页每页20条；操作列：编辑（跳转编辑页）、下架/上架切换按钮；驳回商品显示驳回理由tooltip；三态：loading骨架屏、空列表引导"发布第一件商品"、正常列表。

卖家发布商品时设置库存数量（必填，≥1，整数）；商品发布表单新增"库存数量"字段；下单时后端原子扣减库存（SELECT FOR UPDATE防超卖）；库存为0时商品仍展示但标记"已售罄"不可加入购物车；订单超时取消或退款成功时自动恢复对应库存数量。

Python FastAPI实现：提取商品特征向量（品牌、品类、成色、价格区间、描述TF-IDF），计算商品间余弦相似度；给定用户最近浏览/收藏商品ID，返回Top-N相似商品列表；接口 POST /api/recommend/content-based，入参 {user_id, top_n}，出参 {items:[{product_id, score}]}。

Python实现User-Based Collaborative Filtering：构建用户-商品交互矩阵（浏览/收藏/购买加权），计算用户间Pearson相似度，聚合相似用户的高分商品；接口 POST /api/recommend/collaborative，入参 {user_id, top_n}，出参 {items:[{product_id, score}]}；支持定期离线重算相似矩阵。

已登录用户首页展示混合推荐Feed：60%协同过滤+40%基于内容，去重后取Top-30；未登录用户展示热门商品（按收藏数+浏览量加权排序）；接口 GET /api/recommend/feed?user_id=&page=&size=，支持分页；每张卡片含推荐理由标签（如"与你浏览过的XX相似"）。

商品详情页底部展示"猜你喜欢"推荐横滑卡片（6-10张），基于当前商品的内容相似度+用户协同过滤结果混合排序；接口 GET /api/recommend/similar?product_id=&user_id=&top_n=10；未登录用户仅基于内容相似度推荐。

新用户冷启动：首次登录后弹出品类偏好引导页（选择感兴趣的奢侈品品类，至少选1项最多选5项），基于所选品类推荐热门商品；新商品冷启动：新上架商品在前7天获得1.5倍曝光加权系数，确保有机会进入推荐候选池；曝光加权随时间线性衰减至1.0。

离线评估脚本（Python）：基于历史行为日志划分训练集/测试集（8:2按时间截断），计算 Precision@K、Recall@K、NDCG@K（K=10,20,30）；对比基线（随机推荐、热门推荐）与协同过滤、基于内容、混合策略共4组实验；输出评估报告表格和指标对比图表（matplotlib）。

前端Next.js（Node.js，端口3000）通过API Routes代理转发请求到Python FastAPI推荐微服务（端口8000）；非推荐类业务API由Next.js API Routes直接处理（连接数据库）；前端使用fetch/axios封装统一请求模块，自动携带JWT token，统一处理401/403/500错误码并toast提示。

使用关系型数据库（PostgreSQL推荐，或SQLite开发环境）；核心表：users（用户+角色）、products（商品+状态）、certificates（证书+审核状态）、favorites（收藏关联）、browse_history（浏览记录）、cart_items（购物车）、orders+order_items（订单）、user_behaviors（行为日志）、notifications（通知）、reviews（评价）、refunds（退款）、seller_applications（卖家申请）、brands（品牌字典）；所有表含created_at/updated_at时间戳，软删除字段deleted_at。

Next.js middleware拦截/api/*路由校验JWT（排除/api/auth/*）；token从Authorization Bearer头提取，验证签名+过期时间，解析user_id和role注入request context；Token过期返回401 {error:"token_expired"}；FastAPI侧同样实现JWT校验依赖注入。

Python FastAPI推荐微服务独立进程运行，使用uvicorn启动（端口8000）；Next.js通过内部网络调用推荐API（docker-compose编排或本地localhost）；推荐服务无状态设计，依赖数据库读取用户行为数据；支持水平扩展（多实例负载均衡）。

全站使用响应式布局（Tailwind CSS或CSS Grid/Flexbox）；断点：mobile（<640px）、tablet（640-1024px）、desktop（>1024px）；移动端导航折叠为汉堡菜单，商品列表从网格变为单列，筛选面板改为底部抽屉弹出；触摸交互友好（按钮最小44×44px点击区域）。

所有商品详情页使用Next.js SSR/SSG生成静态HTML；页面<head>动态注入title（"{商品标题} - LuxeTrade"）、meta description（截取商品描述前160字）、og:image（商品首图）、结构化数据JSON-LD（Product schema含品牌/价格/成色）；生成sitemap.xml并提交搜索引擎。

首页LCP（最大内容绘制）<2.5s，商品详情页LCP<2s；推荐接口P95响应时间<500ms，商品列表接口P95<300ms；图片使用Next.js Image组件自动优化（WebP格式、懒加载、响应式尺寸）；全站Lighthouse Performance评分≥80。

商品图片和证书图片统一存储方案：本地开发使用本地文件系统（/public/uploads目录），生产环境建议对接对象存储（AWS S3/MinIO）；前端上传使用FormData + 进度条，Next.js API Routes接收文件并校验格式（jpg/png/webp/pdf）+大小（商品图≤5MB，证书≤10MB）；后端返回文件URL存入数据库；文件命名规则：{user_id}_{timestamp}_{random}.{ext}；支持删除旧文件（商品图片变更或证书重传时清理旧文件）。

用户密码使用bcrypt加盐哈希存储（cost factor≥10）；注册和密码重置时明文密码经bcrypt哈希后写入users表password_hash字段；登录时bcrypt.compare校验；禁止明文密码出现在日志、API响应、数据库查询结果中。

敏感接口实施速率限制：登录接口/api/auth/login同一IP 10次/分钟，超过返回 429 {error:"too_many_requests"}；注册接口/api/auth/register同一IP 3次/小时；密码重置邮件发送同一邮箱3次/小时；推荐接口全局100次/秒；使用内存级计数器（开发环境）或Redis（生产环境）。

Next.js默认XSS防护（React JSX自动转义）；API输入统一使用参数化查询防SQL注入（Prisma ORM预处理语句）；CSRF防护：SameSite=Strict Cookie属性 + CSRF token校验（针对状态变更API POST/PUT/DELETE）；所有API响应设置安全头：X-Content-Type-Options: nosniff, X-Frame-Options: DENY。

个性化推荐Feed结果缓存：已登录用户首页推荐Feed结果缓存（key=rec:feed:{user_id}，TTL=5分钟）；用户有新行为（收藏/浏览/加购）时主动失效该用户缓存；推荐服务先查缓存，未命中再实时计算；商品详情页"猜你喜欢"同理缓存（key=rec:similar:{product_id}，TTL=10分钟）；缓存后端使用Redis或内存Map（开发环境）。

注册表单含邮箱、密码（≥8位含字母数字）、确认密码；前端校验邮箱格式与密码强度，后端校验邮箱唯一性；成功跳转登录页并toast提示；三态：loading（按钮禁用+spinner）、error（行内错误文案）、success。

登录表单含邮箱+密码；POST /api/auth/login 返回JWT access_token（有效期24h）+ refresh_token；前端存储token到httpOnly cookie或localStorage；登录失败3次触发15分钟锁定；按角色路由分流（买家→首页、卖家→卖家中心、管理员→后台）。

展示用户头像、昵称、手机号、收货地址；支持编辑昵称和手机号（手机号需短信/邮箱验证码校验）；收货地址增删改查，最多保留10条；所有修改操作需重新验证JWT。

系统内置三种角色：买家（默认注册角色）、卖家（需申请或管理员赋予）、管理员（后台手动设置）；不同角色对应不同前端路由和API权限；JWT payload中包含role字段，后端中间件校验角色权限。

登录页"忘记密码"链接→输入注册邮箱→POST /api/auth/forgot-password 入参{email}；后端校验邮箱存在后生成6位数字验证码（有效期10分钟），模拟发送到邮箱（开发环境打印到控制台日志）；用户输入验证码+新密码+确认新密码→POST /api/auth/reset-password 入参{email, code, new_password}；后端校验验证码正确且未过期，更新密码；成功跳转登录页toast提示"密码已重置"。

以下事件触发时后端自动生成通知记录写入notifications表：①证书审核通过/驳回（通知卖家，含驳回理由）；②商品审核通过/驳回（通知卖家，含驳回理由）；③订单状态变更（已付款/已发货/已完成，通知买家；已付款通知卖家）；④退款申请/审核结果（通知对方）。通知字段：user_id、type、title、body、related_id（关联业务ID）、is_read、created_at。

个人中心"消息通知"页面：按时间倒序展示所有通知，每条显示类型图标+标题+摘要+时间+已读/未读状态；支持点击跳转关联页面（如跳转到对应订单详情）；支持单条标记已读、全部标记已读；分页加载每页20条；三态：loading骨架屏、空通知插画+文案、正常列表。

全局导航栏"消息"图标右上角展示未读通知数量红色徽标（>99显示"99+"）；GET /api/notifications/unread-count 返回未读数量；每30秒轮询刷新；用户点击进入通知列表后红点消除（已读即消除对应数量）；首次加载时立即查询一次。

订单详情页"待付款"状态时展示"确认付款"按钮；点击弹出二次确认弹窗（显示订单金额+商品摘要）；确认后 POST /api/pay/confirm 入参{order_id}，后端校验订单状态为"待付款"且未超时（30分钟），更新状态为"已付款"，释放支付超时定时器，发送通知给卖家；成功跳转订单详情页并toast"支付成功"。

买家在已完成订单详情页（15天内）可见"申请退款"按钮；点击进入退款申请页：选择退款原因（下拉：商品与描述不符/质量问题/其他）、退款说明（必填≥20字）、上传凭证图片（最多3张，选填）；POST /api/refunds 入参{order_id, reason, description, images}；后端校验订单状态为已完成且未超15天、无进行中的退款；成功后创建退款记录状态为"申请中"，通知卖家。

卖家在"卖出订单"中看到退款申请，进入退款审核页：查看退款原因+说明+凭证图；操作按钮：同意退款→退款记录状态变更为"退款中"（模拟资金处理延迟，2秒后自动变更为"已退款"，订单同步标记退款状态）/ 拒绝退款（填写拒绝理由≥10字，退款记录变更为"已拒绝"）；卖家48小时未处理自动升级为管理员介入（退款记录标记"待仲裁"，管理员后台FR-ADMIN-006强制处理）。

订单状态为"已完成"后，买家可在订单详情页看到"去评价"入口；评价表单：商品评分（1-5星）、卖家服务评分（1-5星）、文字评价（选填，≤500字）；POST /api/reviews 入参{order_id, product_rating, seller_rating, content}；后端校验订单归属+状态为已完成+未评价过（同一订单仅可评价一次）；成功后toast提示并刷新订单详情，评价内容写入reviews表。

商品详情页底部"用户评价"区域：展示该商品所有已评价记录（分页每页10条），每条含买家昵称（脱敏显示如"张***"）、商品评分星级、评价文字、评价时间；头部汇总显示平均评分和评价总数；卖家个人主页展示其所有商品的评价汇总（平均分+总数）；三态：有评价正常展示、无评价显示"暂无评价"、loading骨架屏。

卖家登录后进入卖家中心首页（/seller/dashboard）：展示数据卡片（在售商品数、待审核商品数、本月订单数、本月销售额——基于已付款/已发货/已完成订单金额求和计算）；快捷入口（发布商品、我的商品、卖出订单）；最近5条订单动态列表；卖家中心左侧导航栏包含：概览、商品管理、订单管理、退款处理。

买家在个人中心可见"成为卖家"入口；点击进入申请页：填写真实姓名、身份证号、手机号（用于平台联系，后端存储加密）；阅读并勾选《卖家协议》复选框；POST /api/seller/apply 入参{real_name, id_number, phone}；提交后状态为"待审核"，管理员后台审核通过后用户role变更为seller；审核中不可重复提交；审核通过/驳回发送通知。