灵工坊 (LingGongFang)

灵活接单，高效清洁 — 连接酒店与清洁工人的智能服务平台

项目简介

灵工坊是一个专为酒店行业打造的清洁服务撮合平台，通过数字化手段连接酒店与专业清洁工人，实现：

• 酒店端：快速发布清洁需求，实时追踪订单状态，在线验收与支付
• 工人端：灵活接单，就近服务，收入透明可提现
• 平台端：智能派单，资质审核，数据分析，全流程管控

核心功能

模块	功能描述
用户管理	微信登录、实名认证、多角色权限
酒店管理	酒店入驻、房型配置、价格设置
订单系统	订单创建、状态流转、取消退款
支付系统	微信支付、余额充值、工人提现
资质管理	工人资质认证、等级评定
区域管理	虚拟区域划分、功能授权

技术栈

• 后端框架: Spring Boot 3.5 + MyBatis-Flex
• 数据库: MySQL / MariaDB
• 缓存: Spring Cache
• 支付: 微信支付 V3 API
• 存储: 阿里云 OSS
• 地图: 腾讯地图 API
• 文档: SpringDoc OpenAPI (Swagger)
• 工具库: Hutool, Lombok

快速开始

环境要求

• JDK 21+
• Maven 3.8+
• MySQL 8.0+

安装步骤

1. 克隆项目

git clone https://github.com/your-repo/linggongfang.git
cd linggongfang

2. 配置数据库

# 创建数据库
mysql -u root -p -e "CREATE DATABASE linggongfang CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

3. 修改配置

复制配置模板并填入实际值：

cp application.yml.template src/main/resources/application.yml

需要配置的环境变量：

export WECHAT_APP_ID=your_app_id
export WECHAT_APP_SECRET=your_app_secret
export WECHAT_MCH_ID=your_merchant_id
export WECHAT_API_V3_KEY=your_api_v3_key
export ALIYUN_OSS_KEY_ID=your_oss_key_id
export ALIYUN_OSS_KEY_SECRET=your_oss_key_secret
export TENCENT_MAP_KEY=your_map_key

4. 启动项目

./mvnw spring-boot:run

5. 访问服务

• API 服务: http://localhost:8123
• Swagger 文档: http://localhost:8123/swagger-ui.html

项目结构

src/main/java/com/sakurapuare/linggongfang/
├── annotation/        # 自定义注解 (@Require 权限控制)
├── common/            # 通用类 (Response, AuthInfo, Params)
├── config/            # 配置类 (JWT, WeChat, OSS, CORS)
├── constant/          # 常量定义 (角色, 状态枚举)
├── context/           # 上下文 (用户认证信息 ThreadLocal)
├── controller/        # REST 控制器
│   ├── admin/        # 管理端接口
│   ├── hotel/        # 酒店端接口
│   ├── user/         # 用户端接口
│   └── business/     # 业务接口 (清洁订单等)
├── exception/         # 异常处理
├── handler/           # 全局处理器
├── interceptor/       # 拦截器 (认证, 权限, 租户)
├── mapper/            # MyBatis Mapper
├── pojo/              # 数据对象
│   ├── entity/       # 数据库实体
│   ├── dto/          # 数据传输对象
│   └── vo/           # 视图对象
├── service/           # 服务层
│   ├── base/         # 基础 CRUD 服务
│   ├── business/     # 业务服务
│   └── payment/      # 支付服务
└── utils/             # 工具类

API 文档

启动项目后访问 Swagger UI 查看完整 API 文档：

http://localhost:8123/swagger-ui.html

主要接口分组：

• /auth/* - 认证相关
• /admin/* - 管理端接口
• /hotel/* - 酒店端接口
• /user/* - 用户端接口
• /cleaning/* - 清洁订单接口
• /payment/* - 支付接口

订单状态流转

[未支付] → [待接单] → [已接单] → [已签到] → [待验收] → [已完成]
    ↓         ↓          ↓                        ↓
 [已取消]  [已取消]   [已取消]                 [不合格] → [售后中]
                                                           ↓
                                              [退款中] → [已退款]

角色说明

角色	标识	权限范围
管理员	admin	全部功能
区域经理	area_manager	管辖区域内功能
酒店	hotel	酒店管理、订单发布
清洁工人	cleaning	接单、签到、提交验收
普通用户	user	基础功能

开发指南

详细开发指南请参阅 CLAUDE.md，包含：

• 代码规范与命名约定
• 代码生成规则
• Service/Controller 编写规范
• 数据库设计规范

贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'feat: Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 提交 Pull Request

Commit 规范

使用约定式提交：

• feat: 新功能
• fix: 修复 Bug
• docs: 文档更新
• refactor: 代码重构
• test: 测试相关
• chore: 构建/工具变动

许可证

本项目采用 MIT 许可证。

联系我们

• 开发者: SakuraPuare
• 邮箱: sakurapuare@sakurapuare.com

---

_{用技术连接服务，让清洁更简单}