# housekeeping

**Repository Path**: nice_HOME/housekeeping

## Basic Information

- **Project Name**: housekeeping
- **Description**: 家政服务预约平台 - SpringBoot + Vue3 + Uni-app
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-06-01
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 拿了项目记得帮我点个star 谢谢
# 家政服务预约平台
一个面向 C 端用户、家政服务人员与平台运营团队的预约平台骨架项目，包含：

- `backend`：基于 Spring Boot 的后端接口服务
- `admin-web`：基于 Vue 3 + Vite 的后台管理系统
- `miniapp`：基于 uni-app 的小程序端
- `docs`：产品设计、信息架构与实施建议

## 推荐阅读

- 对外项目总览：`docs/project-overview.md:1`
- 生产部署与维护手册：`docs/server-deployment.md:1`
- 三端实施规格：`docs/three-end-implementation-spec.md:1`
- 平台设计说明：`docs/platform-design.md:1`

## 设计定位

- 风格关键词：简洁、年轻化、高级感、可信赖
- 视觉方向：大留白、圆角卡片、浅色底、品牌渐变强调色
- 参考站点：`https://www.ayilaile.com/index`

## 当前实现范围

- 后端提供首页、服务列表、下单、管理看板等示例接口
- 管理后台提供概览、订单、服务、阿姨、用户等核心页面骨架
- 小程序提供首页、预约、订单、我的等核心页面骨架
- 小程序订单端已支持订单详情、取消订单和完成后评价
- 小程序个人中心已支持真实化展示、地址管理和售后/联系客服入口
- 小程序地址页支持新增、编辑、删除和设为默认
- 小程序售后页支持复制客服微信和直接拨打服务热线
- 首页 Banner 与精选内容已支持后台配置驱动
- 提供一份可直接继续细化开发的产品与技术设计文档

## 启动方式

### 0. 初始化数据库

首次启动前先执行：

```bash
cd backend
powershell -ExecutionPolicy Bypass -File scripts/init-db.ps1
```

默认会连接：

- `DB_HOST=127.0.0.1`
- `DB_PORT=3306`
- `DB_NAME=housekeeping_platform`
- `DB_USERNAME=root`
- `DB_PASSWORD=yjlikes123`

SQL 初始化脚本在 `backend/sql/init-mysql.sql:1`。

### 1. 后端

```bash
cd backend
mvn spring-boot:run
```

默认地址：`http://localhost:8080/api`

当前已接入真实 MySQL 数据的接口包括：

- `POST /api/admin/auth/login`
- `GET /api/admin/auth/me`
- `PUT /api/admin/auth/password`
- `GET /api/home/landing`
- `GET /api/profile/summary`
- `GET /api/profile/support`
- `GET /api/services`
- `GET /api/orders`
- `GET /api/orders/detail?orderNo=xxx`
- `GET /api/orders/status-logs?orderNo=xxx`
- `POST /api/orders`
- `PUT /api/orders/cancel`
- `POST /api/orders/review`
- `GET /api/addresses`
- `POST /api/addresses`
- `DELETE /api/addresses?id=xxx`
- `GET /api/marketing/coupons`
- `GET /api/marketing/activities`
- `GET /api/admin/dashboard`
- `GET /api/admin/orders`
- `GET /api/admin/orders/page?keyword=...&statusKey=...&pageNo=1&pageSize=10`
- `GET /api/admin/dashboard?days=7|15|30`
- `GET /api/admin/orders/candidates?orderNo=xxx`
- `GET /api/admin/orders/detail?orderNo=xxx`
- `GET /api/admin/orders/dispatch-logs?orderNo=xxx`
- `GET /api/admin/orders/status-logs?orderNo=xxx`
- `POST /api/admin/orders/dispatch`
- `PUT /api/admin/orders/status`
- `GET /api/admin/workers`
- `GET /api/admin/users`
- `GET /api/admin/users/roles`
- `POST /api/admin/users`
- `PUT /api/admin/users/status`
- `PUT /api/admin/users/password/reset`
- `GET /api/admin/users/logs`
- `GET /api/admin/content/banners`
- `POST /api/admin/content/banners`
- `PUT /api/admin/content/banners/status`
- `GET /api/admin/content/articles`
- `POST /api/admin/content/articles`
- `PUT /api/admin/content/articles/status`
- `GET /api/admin/marketing/coupons`
- `POST /api/admin/marketing/coupons`
- `PUT /api/admin/marketing/coupons/status`
- `GET /api/admin/marketing/activities`
- `POST /api/admin/marketing/activities`
- `PUT /api/admin/marketing/activities/status`
- `GET /api/admin/services`
- `POST /api/admin/services`
- `PUT /api/admin/services/status`
- `GET /api/admin/workers/applications`
- `PUT /api/admin/workers/applications/audit`
- `POST /api/worker/auth/login`
- `GET /api/worker/auth/me`
- `POST /api/worker/apply`
- `GET /api/worker/apply/status?mobile=xxx`
- `GET /api/worker/orders`
- `GET /api/worker/orders/{orderNo}`
- `GET /api/worker/orders/status-logs?orderNo=xxx`
- `PUT /api/worker/orders/confirm-onsite`
- `PUT /api/worker/orders/start-service`
- `PUT /api/worker/orders/submit-finish`
- `PUT /api/worker/orders/exception`
- `GET /api/worker/schedule`
- `GET /api/worker/income`
- `GET /api/worker/messages`
- `PUT /api/worker/messages/read-all`

阿姨端公开接口为 `POST /api/worker/auth/login`、`POST /api/worker/apply`、`GET /api/worker/apply/status?mobile=xxx`；其余 `/api/worker/**` 接口需携带阿姨端 JWT。

### 2. 管理后台

```bash
cd admin-web
npm install
npm run dev
```

默认地址：`http://localhost:5173`

### 3. 小程序

```bash
cd miniapp
npm install
npm run dev:h5
```

说明：当前小程序端接口地址写在 `miniapp/src/utils/api.ts:1`，本地开发默认请求 `http://127.0.0.1:8080/api`。

如果本机 `8080` 端口被占用，可在启动后端时改端口，例如：

```bash
cd backend
mvn spring-boot:run -Dspring-boot.run.arguments=--server.port=18080
```

如需微信小程序构建，可执行：

```bash
cd miniapp
npm run dev:mp-weixin
```

## Docker 部署

当前仓库已提供基于 Docker 的部署方案，默认部署：

- `mysql`：MySQL 8
- `backend`：Spring Boot API
- `admin-web`：Vue 后台，使用 Nginx 提供静态资源并反代 `/api`

部署步骤：

```bash
cp .env.example .env
# 按需修改 .env 中的密码与 JWT_SECRET

docker compose up -d --build
```

默认访问方式：

- 后台前端：`http://服务器IP/`
- 后台接口：`http://服务器IP/api/...`

说明：

- 当前 Docker 部署默认不包含 `miniapp` 的 H5/小程序构建。
- 数据库初始化脚本会在 MySQL 首次启动时自动执行：`backend/sql/init-mysql.sql`
- 生产部署与维护手册见：`docs/server-deployment.md:1`

## 说明

- 当前机器环境是 `Java 8`，所以后端骨架使用 `Spring Boot 2.7.x`。
- 如果后续升级到 `JDK 17+`，建议再升级到 Spring Boot 3.x。
- 目前后端数据以示例数据为主，适合先推进页面联调与业务建模。

## 文档

- 总体方案：`docs/platform-design.md:1`
- 三端实施说明：`docs/three-end-implementation-spec.md:1`
- 数据库初始化脚本：`backend/sql/init-mysql.sql:1`
- 三端升级草案：`backend/sql/upgrade-v2-three-end.sql:1`

## 新增业务能力

- 阿姨资源与档期表：`worker_schedule`
- 派单日志表：`order_dispatch_log`
- 订单新增派单字段：`assigned_worker_id`、`assigned_worker_name`、`dispatch_time`
- 后台订单页支持查询候选阿姨并完成派单
- 后台订单页支持查看订单详情抽屉与派单记录
- 后台订单页支持状态流转：确认上门、开始服务、完成服务、取消订单
- 后台订单页已支持关键词搜索、状态筛选和分页
- 后台仪表盘已支持 ECharts 图表化与时间范围筛选（7 / 15 / 30 天）

## 仪表盘能力

- 看板页：`admin-web/src/views/DashboardView.vue:1`
- 支持时间范围筛选：7天 / 15天 / 30天
- 已接入 ECharts 折线趋势图和服务构成饼图
- 看板接口可按 `days` 参数动态返回趋势与热门服务数据
- 后台阿姨页支持查看今日已派单量与近三天可用档期数

## 后台认证

- 已接入后台登录页、JWT 鉴权和基础角色权限控制
- 登录页文件：`admin-web/src/views/LoginView.vue:1`
- JWT 拦截器：`backend/src/main/java/com/housekeeping/config/AdminAuthInterceptor.java:1`
- 登录接口：`backend/src/main/java/com/housekeeping/controller/AdminAuthController.java:1`
- 默认账号会在后端首次启动时自动创建
- 当前登录人支持修改自己的密码：`PUT /api/admin/auth/password`

### 默认账号

- 超级管理员：`admin / Admin@123`
- 运营人员：`operator / Operator@123`

### 当前角色策略

- `SUPER_ADMIN`：可访问全部菜单
- `OPERATOR`：可访问看板、订单、服务、阿姨模块
- 后台 `用户管理` 页面当前仅 `SUPER_ADMIN` 可见
- 后端也已增加基础角色校验：用户管理接口仅 `SUPER_ADMIN` 可调用；看板、订单、服务调度相关接口仅 `SUPER_ADMIN` 和 `OPERATOR` 可调用

## 用户管理能力

- 后台用户管理页：`admin-web/src/views/UsersView.vue:1`
- 支持查看后台账号列表
- 支持查看角色列表
- 支持新增后台账号
- 支持启用/禁用账号
- 支持重置后台账号密码
- 支持查看最近后台账号操作日志
- 当前限制：不能禁用正在登录的自己

## 权限前端能力

- 已增加按钮级权限指令：`admin-web/src/directives/permission.ts:1`
- 当前用户页中的“新增账号 / 启停账号 / 重置密码”等操作已按角色做前端控制
- 后端同时保留接口级角色校验，避免仅靠前端控制带来绕过风险

## 内容管理能力

- 后台内容管理页：`admin-web/src/views/ContentView.vue:1`
- 支持维护首页 Banner 的新增、编辑、删除与启停
- 支持维护首页精选内容文章的新增、编辑、删除与启停
- 小程序首页与 H5 首页会读取启用中的 Banner 与文章配置

## 营销管理能力

- 后台营销管理页：`admin-web/src/views/MarketingView.vue:1`
- 支持维护优惠券的新增、编辑、删除与启停
- 支持维护营销活动的新增、编辑、删除与启停
- 小程序首页会读取启用中的活动内容
- 小程序“我的”页已接入优惠券中心入口：`miniapp/src/pages/mine/coupon.vue:1`

## 服务管理能力

- 后台服务管理页：`admin-web/src/views/ServicesView.vue:1`
- 支持新增、编辑、删除服务项目
- 支持编辑服务名称、标语、简介、价格、标签、时长与排序
- 支持启用/停用服务，前台首页与小程序首页只读取启用中的服务项目
- 已接入后台服务管理接口：`GET /api/admin/services`、`POST /api/admin/services`、`PUT /api/admin/services/status`