用户端小程序个人中心接口开发设计文档

模块：ruoyi-user（会员业务）+ ruoyi-gateway（路由/鉴权头注入）
日期：2026-10-13
需求来源：“个人中心页的接口功能实现，根据现在展示的字段实现对应的 java 后端业务”
关联前端：hugray-user-miniapp（pages/profile/index.vue）
关联文档：doc/design/用户端_登录注册_20261012.md（C 端会员落库与令牌载体方案）、doc/design/用户端_首页与导航_20261012.md（9.3 个人中心页规格）
数据权威源：192.168.110.111:3306/hugray-account（实际表结构优先于本文档）

一、功能概述

个人中心页（pages/profile/index.vue）当前为本地 mock，需由后端下发以下字段，页面据此渲染：

展示字段	页面位置	现状	本次是否提供
姓名 `nickname`	头部文本	mock `辉煌G891`	是（`account_user.nickname`；注册未采集姓名字段，落库为空，前端回退展示脱敏手机号）
手机号 `phone`（脱敏）	头部名称回退	无	是（`account_user.phone`，脱敏为 `133****5555`，不下发明文）
会员等级 `memberLevel`	等级胶囊 `C`/`L1~L4`	mock `L4`	是（复用既有 `account_user.system_level`）
头像 `avatar`	头部头像	相机图标占位（「我的资料」页已支持点击上传更换）	是（已存在字段，有值前端渲染图片，无值回退图标）
今日 / 本月 / 累计收益	收益玻璃卡三栏	mock `10.00 / 400.00 / 128000.00`	是（新增收益流水表，实时聚合）
仓库订单角标数量	菜单角标	mock `1`	否（见 2.5，无数据来源，本期不入接口）

展示规则（沿用已确认业务约定）：isRestrictedView = !isLoggedIn || memberLevel === 'C'；**未登录或 C 普通用户**仅展示「收货地址」「联系我们」两行菜单并隐藏收益卡；**L1~L4** 展示全部内容。该判定由前端完成，后端只负责下发 memberLevel 真实值。

本期只新增 一个 C 端查询接口：GET /miniapp/account/user/info（对应前端已预留的 getMemberInfo()）。

二、现状与关键约束

2.1 表结构缺口

account_user（hugray-account 库）现有字段：user_id, username, phone, password, nickname, avatar, gender, birthday, status, del_flag, my_referral_code, system_level, referrer_id, referrer_bind_time, create_*, update_*, remark。

已有「会员等级」字段 system_level（varchar(8)，默认 C），无任何「收益」相关表/字段 → 收益部分本次新增；等级复用既有列，不再新增重复列。

2.2 已有接口不足以支撑

ruoyi-user 现有控制器：

AccountUserController（/user，后台 CRUD，全部挂 @RequiresPermissions）——面向后端管理，不适合 C 端调用。
AccountMemberInnerController（/member，@InnerAuth）——仅服务间调用，按手机号查会员 / 注册。

无按当前登录会员返回个人中心数据的接口 → 本次新增。

2.3 登录态与取数来源（已定方案）

C 端令牌沿用 RuoYi TokenService，网关 AuthFilter 校验通过后向目标服务注入请求头 user_id、username（SecurityConstants.DETAILS_USER_ID/DETAILS_USERNAME）。
ruoyi-user 侧通过 SecurityUtils.getUserId() 读取 user_id，即当前登录会员 ID。
该路径**不经过** /miniapp/system/user/getInfo（后者面向后台 sys_user，见 2.4）。

2.4 前端预留入口的取舍

hugray-user-miniapp/api/index.js 现有两个未接线函数：

函数	路径	处理
`getMemberInfo()`	`/miniapp/account/user/info`	本期采用（指向 ruoyi-user）
`getUserInfo()`	`/miniapp/system/user/getInfo`	误导：指向后台 `sys_user`，与 C 端会员不同源；全仓无调用点，建议删除

结论：个人中心统一走 getMemberInfo()；getUserInfo() 予以移除（避免后续误用）。

2.5 仓库订单角标数量：本期不提供

角标数量应来源于「仓库订单」，但 ruoyi-product 模块**当前仅有一个启动类**（无订单/仓库任何表与接口），无数据来源。本期接口不返回该字段，前端保持现状（withBadge 已登录展示，值仍为本地 mock 1），待订单模块就绪后由订单服务提供独立接口，不在本次范围。

2.6 金额单位约定

用户规范要求“金额用分（long）”。故接口 earnings 三值均以分返回（如 1000 = 10.00 元），前端新增 分→元 格式化后再展示为两位小数。

三、接口设计

统一响应体：R<T>（code=200 成功），与 C 端 /miniapp/** 既有约定一致；前端 utils/request.js 按 successCode=200 / unauthorizedCode=401 解包，调用方取 res.data。

规范说明：用户规则中的“Result<T>、code=0 成功、错误码分段”为通用模板；本工程实际框架为 RuoYi R/AjaxResult（200 成功）+ @RestControllerAdvice 全局异常。按“与现有工程保持一致”优先，采用框架既有约定。

3.1 查询当前会员个人中心信息

外部路径：GET /miniapp/account/user/info（网关 StripPrefix=2 → 服务内 /user/info）
鉴权：需登录。路径不在网关白名单内，未登录由 AuthFilter 直接返回 401，前端 request.js 自动跳登录页；**后端不做未登录分支**。
入参：无（会员身份取自网关注入的 user_id 头）
出参：R<AccountUserInfoVo>

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "userId": 100,
    "nickname": null,
    "phone": "133****5555",
    "avatar": null,
    "memberLevel": "L4",
    "earnings": { "today": 1000, "month": 40000, "total": 12800000 }
  }
}

字段	类型	说明
userId	Long	会员ID
nickname	String	姓名/昵称（注册未采集，可为空；为空时前端回退展示脱敏手机号）
phone	String	手机号（脱敏，形如 `133****5555`，不下发明文）
avatar	String	头像地址，可为空
memberLevel	String	会员等级 `C`/`L1~L4`（空或非法兜底为 `C`；对外字段名沿用 `memberLevel`，数据源为 `account_user.system_level`）
earnings.today	Long	今日收益（单位：分）
earnings.month	Long	本月收益（单位：分）
earnings.total	Long	累计收益（单位：分）

错误提示：获取会员信息失败（会员不存在或查询异常）
说明：手机号仅下发**脱敏**值（133****5555），不下发明文；userName（C 端即手机号）不下发，避免敏感信息外泄。

四、数据库设计

库：hugray-account（权威库 192.168.110.111:3306）。脚本：sql/hugray_account_20261013.sql（与代码同一次提交，含变更 + 回滚）。

4.1 会员等级：复用既有 `account_user.system_level`（无 DDL）

权威库 account_user 已存在 system_level varchar(8) DEFAULT 'C'（取值 C<L1<L2<L3<L4，从低到高），故**不再新增 member_level 重复列**。代码统一读写既有 system_level，对外出参仍为 memberLevel。

4.2 变更：新增收益流水表 `account_earning_record`

CREATE TABLE `account_earning_record` (
  `record_id`   bigint(20)   NOT NULL AUTO_INCREMENT COMMENT '收益记录ID',
  `user_id`     bigint(20)   NOT NULL                COMMENT '会员ID（关联 account_user.user_id）',
  `amount`      bigint(20)   NOT NULL DEFAULT 0      COMMENT '收益金额（单位：分，可正可负）',
  `source`      char(1)      NOT NULL                COMMENT '收益来源（1订单收益 2邀请奖励 3等级差价 9其他）',
  `biz_no`      varchar(64)  DEFAULT NULL            COMMENT '业务单号（同来源幂等去重）',
  `remark`      varchar(255) DEFAULT NULL            COMMENT '备注',
  `create_time` datetime     DEFAULT NULL            COMMENT '发生时间',
  `update_time` datetime     DEFAULT NULL            COMMENT '更新时间',
  PRIMARY KEY (`record_id`),
  KEY `idx_earning_user_time` (`user_id`, `create_time`),
  UNIQUE KEY `uk_earning_source_biz` (`source`, `biz_no`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='会员收益流水表';

采用**流水 + 实时聚合**而非三个汇总结算字段：今日 / 本月随日期自然滚动，无需定时归零；同时天然支撑菜单「收入明细」页（后续）。
idx_earning_user_time 覆盖 WHERE user_id=? AND create_time>=? 聚合，避免全表扫描。
uk_earning_source_biz 由 (source, biz_no) 保证业务幂等；biz_no 为 NULL 时 MySQL 唯一索引不冲突（手工补录场景允许）。

回滚：

DROP TABLE IF EXISTS `account_earning_record`;

五、流程设计

5.1 查询个人中心信息（`AccountUserServiceImpl.getAccountUserInfo`）

STEP 1: 校验 userId 非空（未登录由网关拦截，此处兜底），为空抛「获取会员信息失败」
STEP 2: 按 userId 查 account_user（del_flag='0'）；为空抛「获取会员信息失败」
STEP 3: 查收益汇总（单条 SQL，单位分），无流水返回 0
STEP 4: 组装 AccountUserInfoVo：nickname/avatar 直取；phone 脱敏（`133****5555`）；memberLevel 取 system_level，空或非法兜底 MemberLevelEnum.C
STEP 5: 返回 VO

收益汇总 SQL（一次查询出三值）：

SELECT
  IFNULL(SUM(CASE WHEN create_time >= CURDATE() THEN amount END), 0)                        AS today,
  IFNULL(SUM(CASE WHEN create_time >= DATE_FORMAT(CURDATE(), '%Y-%m-01') THEN amount END), 0) AS month,
  IFNULL(SUM(amount), 0)                                                                     AS total
FROM account_earning_record
WHERE user_id = #{userId}

六、枚举与状态

名称	取值	说明
会员等级 `memberLevel`（源 `system_level`）	`C` / `L1` / `L2` / `L3` / `L4`	`MemberLevelEnum`：`C`=普通用户（受限展示）；`L1~L4`=会员；含 `code` + `desc` + `getByCode` + `normalize`
会员状态 `status`	`0` 正常 / `1` 停用	复用现有语义
删除标志 `delFlag`	`0` 存在 / `2` 删除	复用现有语义
收益来源 `source`	`1` 订单收益 / `2` 邀请奖励 / `3` 等级差价 / `9` 其他	`EarningSourceEnum`（本期仅建枚举，写入方待订单/邀请模块接入）

等级升降级规则（何种行为升到 L1~L4）属于会员体系策略，尚未定义。本期 system_level 由后台维护（AccountUserController 编辑），接口只负责读取下发；后续等级规则确定后新增独立升级流程。

七、影响范围与文件清单

新增（ruoyi-user）

文件	说明
`enums/MemberLevelEnum.java`	会员等级枚举（`C`/`L1~L4`，含 `getByCode` + `normalize`）
`enums/EarningSourceEnum.java`	收益来源枚举（`1/2/3/9`）
`domain/AccountEarningRecord.java`	收益流水实体（含字段注释）
`domain/vo/AccountUserInfoVo.java`	个人中心信息出参 VO（含脱敏手机号 `phone`）
`domain/vo/EarningSummaryVo.java`	收益汇总出参（today/month/total，单位分）
`mapper/AccountEarningRecordMapper.java` + `resources/mapper/user/AccountEarningRecordMapper.xml`	收益汇总查询
`controller/AccountProfileController.java`	C 端接口 `GET /user/info`

修改

文件	改动
ruoyi-user `domain/AccountUser.java`	复用既有 `systemLevel`（源 `system_level`）字段；推荐关系字段为 `referrerId`（源 `referrer_id`）+ getter/setter + toString
ruoyi-user `mapper/AccountUserMapper.xml`	`system_level` / `referrer_id` 纳入 resultMap / 列 / insert / update
ruoyi-user `service/IAccountUserService.java` + `service/impl/AccountUserServiceImpl.java`	新增 `getAccountUserInfo(Long userId)`；注册不再以手机号填充姓名（`nickname` 留空）；出参手机号脱敏
`sql/hugray_account_20261013.sql`	新增 DDL（变更 + 回滚）
前端 `hugray-user-miniapp/api/index.js`	删除误导且无调用的 `getUserInfo()`
前端 `hugray-user-miniapp/utils/`（新增格式化方法）	`分→元` 两位小数格式化
前端 `hugray-user-miniapp/pages/profile/index.vue`	`onShow` 调 `getMemberInfo()` 替换 mock；头部名称优先姓名、为空回退脱敏手机号
`doc/design/用户端_首页与导航_20261012.md`	9.3 / 9.5 标注 mock 已由接口替换

网关无需改动：/miniapp/account/** → ruoyi-user 路由已存在。

八、边界与异常清单

#	场景	处理
1	未登录访问	网关 `AuthFilter` 返回 401，前端跳登录页；后端不做分支
2	`user_id` 头缺失/为空	服务内兜底判空，抛「获取会员信息失败」（不 NPE）
3	会员不存在 / 已逻辑删除	抛「获取会员信息失败」
4	`system_level` 为空或非法（历史脏数据）	兜底为 `C`，不影响页面渲染
5	无任何收益流水	三值均返回 `0`（分），前端展示 `0.00`
6	收益为负（退款冲正）	`amount` 支持负数，聚合自然抵扣
7	金额单位一致性	接口统一返回分；前端统一格式化，禁止后端直接返回字符串金额
8	敏感信息	接口下发脱敏手机号（`133****5555`），不下发明文与 `userName`；日志手机号脱敏
9	越权	会员身份取自令牌注入头，不接受前端传入 `userId`，天然防水平越权
10	姓名未采集（注册未填）	`nickname` 为空，前端头部回退展示脱敏手机号，不报错

九、规范符合性说明

分层：Controller 只做取身份 + 转发，业务在 Service，SQL 在 Mapper；Controller 不直接调 Mapper。
命名：getAccountUserInfo / selectEarningSummary 等见名知意；Entity / VO 分离。
注释：类注释、字段注释（含取值与单位说明）、Javadoc、核心流程 // STEP x: 注释。
魔法值：等级、收益来源收口枚举；CUCRATE 等 SQL 表达式内聚在 Mapper。
异常：统一 ServiceException + 全局处理器，不散落 try-catch 拼返回值。
日志：@Slf4j 占位符 + [业务标记] 前缀，敏感字段脱敏。
数据库：字段显式长度 + COMMENT；聚合列有索引；无 SELECT *；无 ${} 拼接；无循环查库。
单测：getAccountUserInfo（正常 / 会员不存在 / 无流水 / 等级空兜底 / 等级非法兜底）补充单测，Mockito Mock Mapper。
说明（与现有工程一致优先）：account_earning_record 主键沿用自增（与同库 account_user 及全工程 RuoYi 风格一致），未采用雪花 ID，作为已知项记录。

十、已确认决策

等级存储方式：**已定** —— 复用既有 account_user.system_level（C/L1~L4，默认 C），不新增 member_level 重复列。
收益数据模型：**已定** —— 新建流水表 account_earning_record + 实时聚合。
金额单位：**已定** —— 接口返回分（long），前端格式化为两位小数。
仓库订单角标：**已定** —— 本期不提供（ruoyi-product 尚无订单实现）。
数据库连接：**已定** —— ruoyi-user-dev.yml master 已由 localhost 改为权威库 192.168.110.111:3306/hugray-account（与 ruoyi-system/ruoyi-product 一致）。

用户端小程序 个人中心 接口 开发设计文档