项目编码：S002

一、系统介绍

本项目是一个前后端分离的二手房交易与信息平台，包含：

用户端：房源浏览与检索、小区与资讯、发布与编辑房源、预约看房、在线咨询、订单与钱包、消息与个人中心等。
管理端：用户与分群、房源审核与违规处理、小区与预约、资讯与分类、订单、投诉、统计看板、系统配置与数据字典、实名审核等后台能力。

系统形态

组件	说明
后端服务	`ershoufang_admin`（Spring Boot，上下文路径 `/api`）
前端应用	`ershoufang_web`（Vue 3 + Vite）

默认联调地址

后端：http://localhost:8080/api
前端（Vite 开发环境）：http://localhost:5173

https://wxa.wxs.qq.com/tmpl/pl/base_tmpl.html

二、角色与权限

当前代码中的账号类型为两类：

类型	说明
普通用户（User）	注册登录后使用用户端业务；登录成功返回 JWT，载荷中含 `userId`、`username`、`type=user`
管理员（Admin）	使用管理端；`AdminController` 中登录为写死账号校验，返回的 `token` 为 `admin-token-` + 时间戳的占位字符串，非 JWT

访问控制

前端：vue-router 全局前置守卫——meta.requiresAuth 校验用户端 localStorage.token，meta.requiresAdminAuth 校验 localStorage.adminToken。
后端：JwtInterceptor 全局拦截（/auth/** 与静态 /uploads/** 相关路径在 WebConfig 中排除）；从请求头 Authorization: Bearer <token> 解析 JWT 后将 userId、username、userType 写入 HttpServletRequest。拦截器对非法/缺失 Token 不直接拒绝请求，具体接口是否要求登录由各 Controller 通过 request.getAttribute("userId") 等自行判断（例如文件上传接口会校验 userId）。

与影院范本差异说明：前端 Axios 未按 X-User-Id / X-Admin-Id 传参，而是统一使用 Authorization: Bearer；若请求 URL 以 /admin 开头则自动附带管理员 adminToken，否则附带用户 token。

三、主要功能模块

1）用户端功能（与路由、页面一致）

用户认证：注册、登录、忘记密码（对应 Register.vue、Login.vue、ForgotPassword.vue）；认证接口位于 /auth/*。
首页与聚合：Home.vue；接口分组 /home/*（如首页数据、平台统计）。
房源：列表、详情、发布、编辑（/house/*）；多条件筛选、收藏、浏览历史等。
小区：列表与详情（/community/*）；小区关注（/community/follow）。
资讯：列表与详情（/article/*）；评论、点赞等（以实际接口为准）。
预约看房：用户侧预约（/appointment）。
咨询：房源咨询（/consultation）。
交易与资金：房源订单（/house-order）、钱包（/wallet）、服务订单（/service-order）等。
个人中心：资料与设置（/user、/user/settings）、实名认证（/user/auth 与 /auth 下实名相关接口）、消息中心（/user/messages）、订单详情（/user/order/:orderNo）。
其他：浏览历史（/browse-history）、搜索条件保存（/search/condition）、收藏（/favorite）、意见反馈（/feedback）、协议与关于页（/agreement、/privacy、/about）。

2）管理端功能（`/admin` 布局子路由）

登录：/admin/login，接口 POST /admin/login（账号密码写死：admin / admin123）。
仪表盘：Dashboard.vue；接口 /admin/dashboard/*。
用户与运营：用户列表与详情、标签、分群（/admin/users、/admin/tags、/admin/groups）；站内消息管理（/admin/message）。
房源：列表、管理、审核、违规（houses、house-management、house-audit、house-violation）；接口 /admin/house/*。
小区：列表与管理；接口 /admin/community/*。
预约：列表与管理；接口 /admin/appointment/*。
资讯：文章、分类、标签、推荐位管理；接口 /admin/article/*。
投诉：管理端处理；接口 /admin/complaint/*，用户端提交 /complaint/*。
统计：数据总览、用户/房源/访问统计；接口 /admin/statistics/*，前端 ECharts 展示。
实名审核：AdminAuthList；接口 /admin/auth/*。
订单：房源订单管理；接口 /admin/house-order/*。
系统：系统配置、数据字典；接口 /admin/system/* 及用户可读配置 /system/config/*。
管理员账号维护（在系统模块内）：/admin/system/admin/* 等（以 AdminSystemController 为准）。

四、技术栈

后端（`ershoufang_admin`）

技术	版本/说明
JDK	1.8
Spring Boot	2.6.13
Spring MVC	随 Spring Boot
MyBatis	`mybatis-spring-boot-starter` 2.2.2 + XML Mapper
数据源	Druid 1.2.8
MySQL	驱动 `mysql-connector-java`5.1.49
JWT	`io.jsonwebtoken:jjwt`0.9.1（`JwtUtil` 使用 `HS512`）
其他	Lombok、Hutool、Spring Validation、Apache POI（Excel 相关能力）
构建	Maven

前端（`ershoufang_web`）

技术	说明
Vue	3.x
Vite	7.x
TypeScript	5.9.x
Element Plus	UI 组件库
Vue Router	4.x
Pinia	状态管理
Axios	HTTP 客户端（`src/api/request.ts`）
ECharts	管理端统计图表
其他	`vue-i18n`、`sass`

五、项目结构

ershoufangjiaoyixitong/          # 项目根（名称以实际目录为准）
├─ ershoufang_admin/             # 后端
│  ├─ src/main/java/net/jingsky/ershoufang_admin/
│  │  ├─ controller/             # 接口层
│  │  ├─ service/                # 业务层
│  │  ├─ mapper/                 # MyBatis 接口
│  │  ├─ entity/ dto/ vo/        # 实体与传输对象（若有）
│  │  ├─ config/                 # Web、跨域、静态资源、定时任务等
│  │  ├─ interceptor/          # JWT 拦截器
│  │  ├─ common/ util/           # 统一返回、工具类
│  │  └─ ErshoufangAdminApplication.java
│  └─ src/main/resources/
│     ├─ application.yml         # 服务端口、数据源、MyBatis、JWT、上传目录等
│     └─ mapper/                 # MyBatis XML
├─ ershoufang_web/               # 前端
│  ├─ src/
│  │  ├─ views/                  # 页面（含 user/、house/、admin/ 等）
│  │  ├─ layouts/                # 布局（管理端 Layout 等）
│  │  ├─ router/                 # 路由与守卫（index.ts）
│  │  ├─ stores/                 # Pinia
│  │  ├─ api/request.ts          # Axios 实例与拦截器
│  │  └─ components/
│  ├─ package.json
│  └─ vite.config.ts
├─ database/                       # 数据库备份脚本
│  └─ ershoufang_20260115111106_backup.sql
├─ uploads/                        # 上传目录（运行时生成，与配置 file.upload.path 一致）
└─ 本地部署指南.md

六、数据库说明

初始化方式：使用项目根目录下 database/ershoufang_20260115111106_backup.sql 导入库 ershoufang（详见《本地部署指南》）。
表命名：业务表多为 tb_ 前缀（如 tb_user、tb_house、tb_house_order 等）。
更完整的表与功能对照：见同目录 系统功能清单与数据表说明.md（含用户、房源、订单、钱包、消息、资讯、预约、投诉等模块与表字段级说明）。

七、环境与运行

1）基础环境

JDK 1.8+
Maven 3.6+
MySQL 5.7+（文档亦兼容 8.0 常见部署）
Node.js（建议 16+；当前 package.json 生态偏新，以本地 npm install 结果为准）

2）后端启动

创建数据库并导入 database 目录下 SQL 备份。
修改 ershoufang_admin/src/main/resources/application.yml 中的数据源 URL、用户名、密码（默认示例为库名 ershoufang，用户 ershoufang / 密码 ershoufang，请按环境修改）。
启动入口类 net.jingsky.ershoufang_admin.ErshoufangAdminApplication，或于 ershoufang_admin 目录执行：

mvn spring-boot:run

3）前端启动

进入代码文件夹内

npm install
npm run dev

默认开发地址以 Vite 控制台输出为准，一般为 http://localhost:5173。

4）测试账号（与《本地部署指南》一致）

端	用户名	密码
用户端（示例库数据）	`cs123456`	`123456`
管理端（代码写死）	`admin`	`admin123`

八、接口与联调说明

请求基地址

前端 ershoufang_web/src/api/request.ts 中 baseURL：http://localhost:8080/api
后端 server.servlet.context-path：/api，故完整接口形态为：http://localhost:8080/api/<Controller 映射>

鉴权头

Authorization: Bearer <token>
- 用户端接口：使用 localStorage.token（JWT）。
- 管理端接口：请求路径以 /admin 开头时使用 localStorage.adminToken（当前为后端返回的 admin-token-... 字符串）。

静态资源与上传访问

本地上传目录由 application.yml 的 file.upload.path 指定（默认相对路径 uploads）。
ResourceConfig 将磁盘目录映射为 /uploads/**；因存在 context-path=/api，浏览器访问形如：http://localhost:8080/api/uploads/...
上传接口返回的 URL 若含 /api/uploads/...，需与上述规则一致联调。https://wxa.wxs.qq.com/tmpl/pl/base_tmpl.html