🏘️ 小区业主自治管理系统

项目背景

在《民法典》框架下，小区业委会的成立和运作涉及大量流程：业主身份认证、筹备组组建、业主大会召开、投票表决、日常事务公示、财务管理等。传统线下方式效率低、不透明，容易引发纠纷。本系统将全流程线上化，服务三端用户。

核心流程

用户角色与权限

技术栈

分层架构

项目结构

# ===== 后端 (Spring Boot 多模块) =====
src/backend/
├── ruoyi-admin/        # 启动模块 + Controller 层
│   └── controller/
│       ├── system/      # RuoYi 内置：用户/角色/菜单/部门
│       └── biz/         # ★ 业务模块：小区/楼栋/公告/工单/业委会/大会/财务/认证
├── ruoyi-common/        # 公共工具：BaseEntity、AjaxResult、注解
├── ruoyi-framework/     # 框架层：Security 配置、AOP 切面、过滤器
├── ruoyi-system/        # 业务层：Domain + Mapper + Service
│   ├── domain/          # RuoYi 内置领域模型
│   ├── biz/domain/      # ★ 业务领域模型
│   ├── biz/mapper/      # ★ 业务 Mapper 接口
│   └── biz/service/     # ★ 业务 Service
├── ruoyi-generator/     # 代码生成器
└── ruoyi-quartz/        # 定时任务

# ===== 前端 (Vue2 SPA) =====
src/admin-pc/
├── src/
│   ├── api/biz/          # ★ 业务 API 层 (8 个模块)
│   ├── views/biz/        # ★ 业务 Vue 页面 (8 个模块)
│   ├── router/           # 路由配置
│   └── utils/request.js  # Axios 封装 (Token 拦截)
└── vue.config.js         # 代理 /dev-api → 后端 :8080

# ===== 小程序 + 手机端 =====
src/miniapp/             # 微信小程序 (原生框架)
src/admin-mobile/        # 手机 H5 管理端 (React)

ER 关系概要

                   ┌──────────────┐
                   │  community   │  小区信息
                   └──────┬───────┘
                          │ 1:N
                   ┌──────▼───────┐
                   │   building   │  楼栋
                   └──────┬───────┘
                          │ 1:N
                   ┌──────▼───────┐     ┌──────────────┐     ┌──────────────┐
                   │    house     │     │   sys_user   │     │   sys_role   │
                   └──────┬───────┘     └──────┬───────┘     └──────┬───────┘
                          │                    │                    │
                          └──────┬─────────────┘                    │
                                 │ N:M                              │
                          ┌──────▼───────┐                          │
                          │ owner_house  │  业主-房产绑定            │
                          └──────┬───────┘                          │
                                 │                                  │
                    ┌────────────┼────────────┐                     │
                    │            │            │                     │
             ┌──────▼──┐  ┌──────▼──┐  ┌──────▼──────┐             │
             │ meeting │  │complaint│  │announcement │             │
             │ 业主大会 │  │ 诉求工单 │  │  公示公告   │             │
             └──────┬──┘  └─────────┘  └─────────────┘             │
                    │                                               │
       ┌────────────┼────────────┐                                  │
  ┌────▼─────┐ ┌────▼─────┐ ┌───▼──────┐                            │
  │  vote    │ │ vote_    │ │ sign_in  │                            │
  │ _config  │ │ record   │ │  签到    │                            │
  └──────────┘ └──────────┘ └──────────┘                            │
                                                                    │
  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
  │  committee   │  │  financial_  │  │ preparation  │              │
  │   业委会     │  │    record    │  │   筹备记录   │              │
  └──────────────┘  └──────────────┘  └──────────────┘              │

RuoYi 系统表 (20 张)

由 RuoYi 框架提供，处理认证、权限、日志等通用功能

业务表 — 小区与房产

业务表 — 业委会与大会

业务表 — 投票

业务表 — 运营管理

关键设计决策

代码分层规范

每个业务模块遵循统一的分层结构（以 Community 为例）：

// 1. Domain — 数据模型，继承 RuoYi 的 BaseEntity
public class Community extends BaseEntity {
    private Long id;
    private String name;
    private String address;
    // ... getter / setter
}

// 2. Mapper 接口 — MyBatis 数据访问
public interface CommunityMapper {
    List<Community> selectCommunityList(Community c);
    Community selectCommunityById(Long id);
    int insertCommunity(Community c);
    int updateCommunity(Community c);
    int deleteCommunityByIds(Long[] ids);
}

// 3. Mapper XML — SQL 映射，支持动态条件查询
<!-- CommunityMapper.xml -->
<!-- 使用 <include refid="selectVo"/> 复用字段列表 -->
<!-- <if test="..."> 实现动态 WHERE 条件 -->

// 4. Service 接口 + 实现
public interface ICommunityService { ... }
// CommunityServiceImpl — 注入 Mapper，委托调用

// 5. Controller — RESTful API，继承 BaseController
@RestController
@RequestMapping("/biz/community")
public class CommunityController extends BaseController {
    @Autowired private ICommunityService service;

    @GetMapping("/list")
    public TableDataInfo list(Community c) {
        startPage();                     // PageHelper 分页
        List<Community> list = service.selectCommunityList(c);
        return getDataTable(list);        // 统一分页响应体
    }

    @PostMapping
    @PreAuthorize("@ss.hasPermi('biz:community:add')")  // 按钮级权限
    public AjaxResult add(@RequestBody Community c) {
        return toAjax(service.insertCommunity(c));
    }
}

统一响应规范

API 全量清单

权限控制体系

基于 Spring Security + RBAC 的三级权限控制：

PC 管理端 (Vue2 + Element UI)

基于 RuoYi-Vue 前端框架，所有业务页面遵循统一模板：

1. 搜索区 — el-form :inline 内联搜索表单，支持条件筛选 + 重置
2. 工具栏 — 新增/修改/删除按钮，用 v-hasPermi 指令控制显隐
3. 数据表格 — el-table + pagination 分页组件，多选支持批量删除
4. 弹窗表单 — el-dialog 内嵌 el-form，新增/编辑复用同一组件
5. API 调用 — 统一通过 @/api/biz/xxx.js 模块封装，自动携带 Token

前端 API 层示例

// src/api/biz/community.js
import request from '@/utils/request'

export function listCommunity(query) {
  return request({ url: '/biz/community/list', method: 'get', params: query })
}
export function getCommunity(id) {
  return request({ url: '/biz/community/' + id, method: 'get' })
}
export function addCommunity(data) {
  return request({ url: '/biz/community', method: 'post', data })
}
export function updateCommunity(data) {
  return request({ url: '/biz/community', method: 'put', data })
}
export function delCommunity(ids) {
  return request({ url: '/biz/community/' + ids, method: 'delete' })
}

菜单配置

业务菜单存储在 sys_menu 表中，通过数据库动态配置（无需重启前端）：

小程序端 (微信原生)

使用 wx.login 获取 code → 后端换取 openid → JWT Token 认证

手机管理端 (React H5)

环境要求

启动步骤

1. 数据库初始化

# 导入 RuoYi 系统表
mysql -h host -u user -p lianyue < src/backend/sql/ry_20260417.sql
mysql -h host -u user -p lianyue < src/backend/sql/quartz.sql

# 业务表已通过 application.yml 自动建表（MyBatis）
# 如需手动创建，执行 src/backend/wuye-server/.../sql/init.sql

2. 修改配置

# 编辑 src/backend/ruoyi-admin/src/main/resources/application-druid.yml
datasource:
  druid:
    master:
      url: jdbc:mysql://YOUR_HOST:PORT/lianyue?...   # 修改数据库连接
      username: YOUR_USER                              # 修改用户名
      password: YOUR_PASSWORD                          # 修改密码

3. 启动后端

cd src/backend
mvn clean package -DskipTests     # 编译打包
java -jar ruoyi-admin/target/ruoyi-admin.jar   # 启动 (端口 8080)

4. 启动前端

cd src/admin-pc
npm install                        # 安装依赖
npm run dev                        # 启动开发服务器 (默认端口 1024)

# 访问 http://localhost:1024
# 默认账号: admin / admin123

当前运行状态