# cwgk **Repository Path**: xycs1/cwgk ## Basic Information - **Project Name**: cwgk - **Description**: 社区/乡村数字服务平台 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-02-16 - **Last Updated**: 2026-02-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 村务公开管理系统 (CWGK) > 社区/乡村数字服务平台 - 面向农村社区的综合管理平台 **版本**: v1.2.0 **更新日期**: 2026-02-23 --- ## 目录 - [项目简介](#项目简介) - [技术栈](#技术栈) - [功能模块](#功能模块) - [项目结构](#项目结构) - [数据库设计](#数据库设计) - [API接口文档](#api接口文档) - [前端路由](#前端路由) - [快速开始](#快速开始) - [配置说明](#配置说明) - [Docker部署](#docker部署) - [开发指南](#开发指南) - [安全设计](#安全设计) --- ## 项目简介 村务公开管理系统是一个面向农村社区的综合管理平台，提供村务公开、事件上报、缴费管理、政策发布等功能，实现村务管理的数字化、透明化。系统采用前后端分离架构，支持多级区域管理（市/县/乡/村四级），为基层治理提供数字化解决方案。 ### 核心特性 - 多级区域管理：支持市、县、乡、村四级区域架构 - 角色权限控制：基于 RBAC 的权限管理 - 数据可视化：ECharts 数据大屏展示 - 响应式设计：适配 PC 端和移动端 - 容器化部署：Docker Compose 一键部署 --- ## 技术栈 ### 后端技术 | 技术 | 版本 | 说明 | |------|------|------| | Spring Boot | 2.7.18 | 基础框架 | | Spring Security | 5.7.11 | 安全框架，JWT认证 | | Spring Data Redis | - | 缓存支持 | | Spring Cache | - | 缓存抽象 | | Spring AOP | - | 切面编程 | | MyBatis-Plus | 3.5.5 | ORM框架，代码生成 | | MySQL | 8.0 | 主数据库 | | Redis | 7.x | 缓存、会话存储 | | JWT (jjwt) | 0.11.5 | 身份认证令牌 | | Knife4j | 3.0.3 | API文档增强 | | Hutool | 5.8.24 | Java工具库 | | Apache POI | 5.2.3 | Excel导入导出 | | Lombok | - | 代码简化 | | Jackson | - | JSON序列化 | ### 前端技术 | 技术 | 版本 | 说明 | |------|------|------| | Vue.js | 3.4.x | 渐进式JavaScript框架 | | TypeScript | 5.3.x | 类型安全的JavaScript超集 | | Vite | 5.0.x | 下一代前端构建工具 | | Vue Router | 4.2.x | 官方路由管理器 | | Element Plus | 2.4.x | Vue 3 组件库 | | ECharts | 5.4.x | 数据可视化图表库 | | Vue-ECharts | 6.6.x | Vue 3 ECharts封装 | | Axios | 1.6.x | HTTP客户端 | | XLSX | 0.18.x | Excel文件处理 | ### 运维技术 | 技术 | 说明 | |------|------| | Docker | 容器化部署 | | Docker Compose | 多容器编排 | | Nginx | 反向代理、静态资源服务 | --- ## 功能模块 ### 一、核心业务模块 #### 1. 用户管理 | 功能 | 说明 | |------|------| | 用户注册 | 手机号注册，支持身份证、真实姓名等信息 | | 用户登录 | JWT Token认证，支持记住登录 | | 个人中心 | 查看/修改个人信息、头像上传 | | 密码管理 | 密码修改、重置 | | 管理员管理 | 创建/编辑/禁用管理员账号 | | 角色分配 | 按区域级别分配管理员权限 | #### 2. 区域管理 | 功能 | 说明 | |------|------| | 多级区域 | 市-县-乡-村四级区域树形结构 | | 区域CRUD | 新增、编辑、删除区域 | | 批量导入 | Excel批量导入区域数据 | | 区域编码 | 支持行政区划代码 | #### 3. 村务公开 | 功能 | 说明 | |------|------| | 通知公告 | 村务公告发布、浏览、置顶 | | 村务动态 | 村内新闻动态发布 | | 财务公开 | 村财务收支情况公开 | | 政策文件 | 政策法规文件发布 | #### 4. 事件上报 | 功能 | 说明 | |------|------| | 事件上报 | 居民上报问题（求助/投诉/建议/咨询） | | 图片上传 | 支持多图片上传 | | 事件处理 | 管理员分配、处理事件 | | 状态跟踪 | 实时查看事件处理进度 | | 处理结果 | 记录处理结果和反馈 | #### 5. 缴费管理 | 功能 | 说明 | |------|------| | 缴费户号 | 绑定水电气等缴费户号 | | 账单查询 | 查看待缴费账单 | | 在线缴费 | 模拟在线支付 | | 缴费记录 | 历史缴费记录查询 | #### 6. 家庭档案 | 功能 | 说明 | |------|------| | 家庭信息 | 户主信息、家庭住址 | | 成员管理 | 家庭成员信息维护 | | 特殊标签 | 低保、残疾等标签标记 | | 档案导出 | 家庭信息Excel导出 | ### 二、扩展服务模块 #### 7. 农业服务 | 功能 | 说明 | |------|------| | 农产品发布 | 发布农产品销售信息 | | 产品分类 | 粮食、蔬菜、畜禽、水产等 | | 订单管理 | 农产品订单创建、发货、收货 | | 收货地址 | 用户收货地址管理 | #### 8. 医疗服务 | 功能 | 说明 | |------|------| | 医院列表 | 查看医院信息 | | 科室医生 | 查看科室和医生排班 | | 预约挂号 | 在线预约挂号 | | 挂号记录 | 查看挂号历史 | | 健康档案 | 个人健康信息记录 | #### 9. 教育培训 | 功能 | 说明 | |------|------| | 在线课程 | 农业技术、电商培训等视频课程 | | 培训报名 | 线下培训班报名 | | 学习记录 | 课程学习进度跟踪 | #### 10. 养老服务 | 功能 | 说明 | |------|------| | 养老院查询 | 查看养老院信息、床位 | | 服务预约 | 居家养老服务预约 | | 健康档案 | 老年人健康信息管理 | #### 11. 就业服务 | 功能 | 说明 | |------|------| | 招聘信息 | 查看本地招聘信息 | | 简历管理 | 创建和管理个人简历 | | 职位搜索 | 按条件搜索职位 | #### 12. 下沉基层 | 功能 | 说明 | |------|------| | 服务申请 | 申请政务服务 | | 进度查询 | 查看申请处理进度 | | 服务指南 | 办事指南查询 | #### 13. 投诉建议 | 功能 | 说明 | |------|------| | 提交投诉 | 提交投诉或建议 | | 处理反馈 | 管理员回复处理 | ### 三、系统管理模块 #### 14. 系统管理（管理员） | 功能 | 说明 | |------|------| | 用户管理 | 用户列表、禁用/启用 | | 角色管理 | 角色CRUD、权限分配 | | 菜单管理 | 菜单配置、权限标识 | | 字典管理 | 数据字典维护 | | 配置管理 | 系统参数配置 | | 操作日志 | 系统操作日志查询 | #### 15. 数据大屏 | 功能 | 说明 | |------|------| | 数据概览 | 用户、事件、服务等统计 | | 区域排名 | 各区域数据排名 | | 趋势图表 | 数据趋势分析 | | 数据导出 | 统计数据Excel导出 | --- ## 项目结构 ``` cwgk/ ├── server/ # 后端项目 │ ├── pom.xml # Maven配置 │ ├── Dockerfile # Docker构建文件 │ └── src/main/ │ ├── java/com/cwgk/ │ │ ├── CwgkApplication.java # 启动类 │ │ ├── annotation/ # 自定义注解 │ │ │ └── OperationLog.java # 操作日志注解 │ │ ├── aspect/ # 切面 │ │ │ └── OperationLogAspect.java # 日志切面 │ │ ├── common/ # 公共类 │ │ │ ├── Result.java # 统一响应 │ │ │ ├── ResultCode.java # 响应码枚举 │ │ │ └── BusinessException.java # 业务异常 │ │ ├── config/ # 配置类 │ │ │ ├── SecurityConfig.java # 安全配置 │ │ │ ├── RedisConfig.java # Redis配置 │ │ │ ├── MybatisPlusConfig.java # MP配置 │ │ │ └── Knife4jConfig.java # API文档配置 │ │ ├── controller/ # 控制器 (37个) │ │ │ ├── UserController.java # 用户管理 │ │ │ ├── RegionController.java # 区域管理 │ │ │ ├── NoticeController.java # 公告管理 │ │ │ ├── EventReportController.java# 事件上报 │ │ │ ├── BillController.java # 缴费管理 │ │ │ ├── FamilyController.java # 家庭档案 │ │ │ ├── MedicalController.java # 医疗服务 │ │ │ ├── ElderlyController.java # 养老服务 │ │ │ ├── EducationController.java # 教育培训 │ │ │ ├── EmploymentController.java # 就业服务 │ │ │ ├── AgricultureController.java# 农业服务 │ │ │ ├── StatisticsController.java # 数据统计 │ │ │ └── ... # 其他控制器 │ │ ├── dto/ # 数据传输对象 │ │ ├── entity/ # 实体类 (38个) │ │ ├── mapper/ # MyBatis Mapper │ │ ├── security/ # 安全相关 │ │ │ ├── JwtTokenProvider.java # JWT提供者 │ │ │ ├── JwtAuthenticationFilter.java │ │ │ └── UserDetailsServiceImpl.java │ │ ├── service/ # 服务接口 │ │ │ ├── UserService.java │ │ │ ├── RegionService.java │ │ │ └── impl/ # 服务实现 │ │ ├── util/ # 工具类 │ │ └── vo/ # 视图对象 │ └── resources/ │ ├── application.yml # 应用配置 │ └── db/ # 数据库脚本 │ ├── init_database.sql # 初始化脚本 │ ├── index_optimize.sql # 索引优化 │ └── multi_level.sql # 多级区域 │ ├── src/ # 前端项目 │ ├── main.ts # 入口文件 │ ├── App.vue # 根组件 │ ├── api/ # API接口 (32个文件) │ │ ├── request.ts # Axios封装 │ │ ├── user.ts # 用户接口 │ │ ├── region.ts # 区域接口 │ │ ├── notice.ts # 公告接口 │ │ ├── event.ts # 事件接口 │ │ ├── bill.ts # 账单接口 │ │ ├── family.ts # 家庭接口 │ │ ├── medical.ts # 医疗接口 │ │ ├── elderly.ts # 养老接口 │ │ ├── course.ts # 课程接口 │ │ ├── job.ts # 招聘接口 │ │ ├── product.ts # 农产品接口 │ │ ├── statistics.ts # 统计接口 │ │ └── ... │ ├── assets/ # 静态资源 │ ├── components/ # 公共组件 │ ├── layout/ # 布局组件 │ │ └── index.vue # 主布局 │ ├── router/ # 路由配置 │ │ └── index.ts # 路由定义 │ ├── stores/ # Pinia状态管理 │ ├── styles/ # 样式文件 │ ├── utils/ # 工具函数 │ └── views/ # 页面组件 (15个模块) │ ├── login/index.vue # 登录页 │ ├── register/index.vue # 注册页 │ ├── home/index.vue # 首页 │ ├── village/index.vue # 村务公开 │ ├── event/index.vue # 事件上报 │ ├── payment/index.vue # 便民缴费 │ ├── agriculture/index.vue # 农产品上行 │ ├── medical/index.vue # 医疗服务 │ ├── elderly/index.vue # 养老服务 │ ├── education/index.vue # 教育服务 │ ├── employment/index.vue # 就业服务 │ ├── service/index.vue # 下沉基层 │ ├── personal/index.vue # 个人中心 │ ├── admin/index.vue # 系统管理 │ └── dashboard/index.vue # 数据大屏 │ ├── dist/ # 前端构建产物 ├── docker-compose.yml # Docker编排 ├── nginx.conf # Nginx配置 ├── vite.config.ts # Vite配置 ├── tsconfig.json # TypeScript配置 ├── package.json # 前端依赖 └── TECHNICAL_DOC.md # 技术文档 ``` --- ## 数据库设计 ### 数据库概览 - **数据库**: MySQL 8.0 - **字符集**: utf8mb4 - **排序规则**: utf8mb4_unicode_ci - **表数量**: 38张表 ### 表分类 #### 一、系统管理表 (12张) | 表名 | 说明 | |------|------| | sys_user | 用户表 - 存储用户基本信息 | | sys_region | 区域表 - 四级行政区划 | | sys_role | 角色表 - 角色定义 | | sys_menu | 菜单表 - 系统菜单配置 | | sys_role_menu | 角色菜单关联表 | | sys_user_role | 用户角色关联表 | | sys_log | 操作日志表 | | sys_login_log | 登录日志表 | | sys_config | 系统配置表 | | sys_dict_type | 字典类型表 | | sys_dict_data | 字典数据表 | | sys_message | 系统消息表 | #### 二、业务管理表 (15张) | 表名 | 说明 | |------|------| | biz_notice | 公告表 | | biz_family | 家庭表 | | biz_family_member | 家庭成员表 | | biz_policy | 政策文件表 | | biz_finance | 财务公开表 | | biz_dynamic | 村务动态表 | | biz_event_report | 事件上报表 | | biz_service_apply | 服务申请表 | | biz_product | 农产品表 | | agri_order | 农产品订单表 | | biz_address | 收货地址表 | | biz_job | 招聘信息表 | | emp_resume | 简历表 | | service_complaint | 投诉建议表 | | service_guide | 服务指南表 | #### 三、医疗服务表 (4张) | 表名 | 说明 | |------|------| | med_hospital | 医院表 | | med_department | 科室表 | | med_doctor | 医生表 | | biz_medical_registration | 医疗挂号表 | #### 四、养老服务表 (3张) | 表名 | 说明 | |------|------| | biz_elderly_service | 养老服务预约表 | | biz_health_record | 健康档案表 | | elderly_nursing_home | 养老院表 | #### 五、教育培训表 (3张) | 表名 | 说明 | |------|------| | edu_course | 课程表 | | edu_training | 培训班表 | | edu_enrollment | 培训报名表 | #### 六、缴费服务表 (1张) | 表名 | 说明 | |------|------| | pay_bill | 账单表 | ### 核心表结构 #### 用户表 (sys_user) | 字段 | 类型 | 说明 | |------|------|------| | id | BIGINT | 主键ID | | username | VARCHAR(50) | 用户名，唯一 | | password | VARCHAR(100) | 密码（BCrypt加密） | | real_name | VARCHAR(50) | 真实姓名 | | phone | VARCHAR(20) | 手机号 | | id_card | VARCHAR(18) | 身份证号 | | avatar | VARCHAR(200) | 头像URL | | gender | VARCHAR(10) | 性别 | | birthday | DATE | 出生日期 | | address | VARCHAR(200) | 地址 | | region_id | BIGINT | 所属区域ID | | role | VARCHAR(20) | 角色：ADMIN/USER | | level | VARCHAR(20) | 级别：CITY/COUNTY/TOWN/VILLAGE | | status | TINYINT | 状态：1正常 0禁用 | | create_time | DATETIME | 创建时间 | | update_time | DATETIME | 更新时间 | | deleted | TINYINT | 逻辑删除标记 | #### 区域表 (sys_region) | 字段 | 类型 | 说明 | |------|------|------| | id | BIGINT | 主键ID | | parent_id | BIGINT | 父级ID | | name | VARCHAR(50) | 区域名称 | | code | VARCHAR(20) | 区划代码 | | level | INT | 层级：1市 2县 3乡 4村 | | sort | INT | 排序 | | status | TINYINT | 状态：1正常 0禁用 | #### 事件上报表 (biz_event_report) | 字段 | 类型 | 说明 | |------|------|------| | id | BIGINT | 主键ID | | user_id | BIGINT | 上报用户ID | | region_id | BIGINT | 区域ID | | type | VARCHAR(20) | 类型：help/complaint/suggestion/consult | | title | VARCHAR(100) | 标题 | | content | TEXT | 内容 | | images | VARCHAR(1000) | 图片URL | | location | VARCHAR(200) | 地点 | | contact | VARCHAR(50) | 联系方式 | | status | TINYINT | 状态：0待处理 1处理中 2已解决 3已关闭 | | handler_id | BIGINT | 处理人ID | | handle_time | DATETIME | 处理时间 | | handle_result | TEXT | 处理结果 | --- ## API接口文档 ### 接口规范 - **基础路径**: `/api` - **认证方式**: Bearer Token (JWT) - **请求格式**: JSON - **响应格式**: `{"code": 200, "message": "success", "data": {}}` ### 认证接口 ``` POST /api/user/login # 用户登录 请求: { username, password } 响应: { token, user: { id, username, realName, role, level, regionId } } POST /api/user/register # 用户注册 请求: { username, password, realName, phone, idCard, regionId } POST /api/user/logout # 退出登录 GET /api/user/info # 获取当前用户信息 POST /api/user/update # 更新用户信息 POST /api/user/changePassword # 修改密码 请求: { oldPassword, newPassword } ``` ### 区域管理接口 ``` GET /api/region/tree # 获取区域树形结构 GET /api/region/children/{parentId} # 获取子区域 GET /api/region/{id} # 获取区域详情 POST /api/region # 新增区域 PUT /api/region # 更新区域 DELETE /api/region/{id} # 删除区域 POST /api/region/import # 批量导入区域 (Excel) ``` ### 公告管理接口 ``` GET /api/notice/page # 公告分页列表 参数: page, size, type, keyword GET /api/notice/{id} # 公告详情 POST /api/notice # 新增公告 PUT /api/notice # 更新公告 DELETE /api/notice/{id} # 删除公告 DELETE /api/notice/batch # 批量删除 ``` ### 事件上报接口 ``` GET /api/event/page # 事件分页列表 GET /api/event/list # 我的上报记录 GET /api/event/region # 区域事件列表 GET /api/event/{id} # 事件详情 POST /api/event # 上报事件 请求: { type, title, content, images, location, contactName, contactPhone } POST /api/event/handle/{id} # 处理事件 请求: { handleResult, status } PUT /api/event # 更新事件 DELETE /api/event/{id} # 删除事件 ``` ### 缴费管理接口 ``` GET /api/payAccount/list # 缴费户号列表 POST /api/payAccount # 新增缴费户号 DELETE /api/payAccount/{id} # 删除缴费户号 GET /api/bill/list # 账单列表 GET /api/bill/{id} # 账单详情 POST /api/bill/create # 创建账单（管理员） POST /api/bill/pay/{id} # 支付账单 ``` ### 医疗服务接口 ``` GET /api/hospital/list # 医院列表 GET /api/hospital/{id} # 医院详情 GET /api/medical/doctors # 医生列表 GET /api/medical/registration # 我的挂号记录 POST /api/medical/register # 预约挂号 请求: { hospitalId, department, doctorId, appointmentDate, timeSlot, patientName, phone, symptoms } PUT /api/medical/cancel/{id} # 取消挂号 GET /api/medical/healthRecord # 健康档案 POST /api/medical/healthRecord # 创建健康档案 ``` ### 农业服务接口 ``` GET /api/product/list # 农产品列表 GET /api/product/{id} # 农产品详情 POST /api/product # 发布农产品 PUT /api/product # 更新产品 DELETE /api/product/{id} # 删除产品 GET /api/agriOrder/list # 订单列表 POST /api/agriOrder # 创建订单 PUT /api/agriOrder/{id}/status # 更新订单状态 ``` ### 就业服务接口 ``` GET /api/job/list # 招聘信息列表 GET /api/job/{id} # 招聘详情 POST /api/job # 发布招聘（管理员） GET /api/resume/list # 我的简历列表 POST /api/resume # 创建简历 ``` ### 教育培训接口 ``` GET /api/course/list # 课程列表 GET /api/course/{id} # 课程详情 GET /api/training/list # 培训班列表 POST /api/training/enroll/{id} # 报名培训 ``` ### 数据统计接口 ``` GET /api/statistics/city # 市级统计数据 GET /api/statistics/county # 县级统计列表 GET /api/statistics/region/{id} # 区域统计 GET /api/statistics/rank # 区域排名 GET /api/statistics/trend # 趋势数据 GET /api/statistics/dashboard # 大屏数据 GET /api/statistics/export/excel # 导出Excel ``` ### 系统管理接口 ``` # 菜单管理 GET /api/system/menu/tree # 菜单树 POST /api/system/menu # 新增菜单 PUT /api/system/menu # 更新菜单 DELETE /api/system/menu/{id} # 删除菜单 # 角色管理 GET /api/system/role/list # 角色列表 POST /api/system/role # 新增角色 PUT /api/system/role # 更新角色 DELETE /api/system/role/{id} # 删除角色 # 字典管理 GET /api/system/dict/type/list # 字典类型列表 GET /api/system/dict/data/{type} # 字典数据 POST /api/system/dict/type # 新增字典类型 POST /api/system/dict/data # 新增字典数据 # 日志管理 GET /api/log/page # 操作日志分页 ``` --- ## 前端路由 ### 路由配置 | 路径 | 名称 | 组件 | 权限 | 说明 | |------|------|------|------|------| | /login | Login | login/index.vue | 公开 | 登录页 | | /register | Register | register/index.vue | 公开 | 注册页 | | / | Layout | layout/index.vue | - | 主布局 | | /home | Home | home/index.vue | 登录 | 首页 | | /village | Village | village/index.vue | 公开 | 村务公开 | | /event | Event | event/index.vue | 登录 | 事件上报 | | /payment | Payment | payment/index.vue | 登录 | 便民缴费 | | /agriculture | Agriculture | agriculture/index.vue | 登录 | 农产品上行 | | /medical | Medical | medical/index.vue | 登录 | 医疗服务 | | /elderly | Elderly | elderly/index.vue | 登录 | 养老服务 | | /education | Education | education/index.vue | 登录 | 教育服务 | | /employment | Employment | employment/index.vue | 登录 | 就业服务 | | /service | Service | service/index.vue | 登录 | 下沉基层 | | /personal | Personal | personal/index.vue | 登录 | 个人中心 | | /admin | Admin | admin/index.vue | ADMIN | 系统管理 | | /dashboard | Dashboard | dashboard/index.vue | ADMIN | 数据大屏 | ### 路由守卫 ```typescript // 路由守卫逻辑 1. 公开页面：/login, /register, /village 可直接访问 2. 需登录页面：检查 localStorage 中的 token 3. 权限页面：检查用户角色是否满足路由 meta.roles 要求 4. 未授权时：重定向到 /home 或 /login ``` --- ## 快速开始 ### 环境要求 | 环境 | 版本要求 | |------|---------| | JDK | 11+ | | Node.js | 16+ | | MySQL | 8.0+ | | Redis | 6.0+ | | Maven | 3.6+ | ### 本地开发 #### 1. 克隆项目 ```bash git clone cd cwgk ``` #### 2. 数据库初始化 ```bash # 创建数据库并导入初始数据 mysql -u root -p < server/src/main/resources/db/init_database.sql ``` #### 3. 启动后端 ```bash cd server # 方式一：Maven 运行 mvn spring-boot:run # 方式二：打包运行 mvn clean package -DskipTests java -jar target/cwgk-server-1.0.0.jar ``` 后端服务：`http://localhost:8080` API文档：`http://localhost:8080/doc.html` #### 4. 启动前端 ```bash # 安装依赖 npm install # 开发模式 npm run dev ``` 前端服务：`http://localhost:3000` #### 5. 默认账号 | 账号 | 密码 | 角色 | |------|------|------| | admin | admin123 | 超级管理员 | --- ## 配置说明 ### 后端配置 (application.yml) ```yaml # 服务端口 server: port: 8080 # 数据库配置 spring: datasource: url: jdbc:mysql://localhost:3306/cwgk?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai username: root password: 123456 hikari: maximum-pool-size: 20 # 最大连接数 minimum-idle: 5 # 最小空闲连接 # Redis配置 redis: host: localhost port: 6379 database: 0 # JWT配置 jwt: secret: your-secret-key # JWT密钥 expiration: 86400000 # 有效期(毫秒)，默认24小时 # 日志配置 logging: level: com.cwgk: debug file: name: logs/cwgk.log max-size: 10MB max-history: 30 ``` ### 前端配置 (vite.config.ts) ```typescript export default defineConfig({ plugins: [vue()], resolve: { alias: { '@': resolve(__dirname, 'src') // @别名 } }, server: { port: 3000, // 开发服务器端口 proxy: { '/api': { target: 'http://localhost:8080', // 后端地址 changeOrigin: true } } } }) ``` ### 环境变量 创建 `.env.development` 文件： ```env VITE_API_BASE_URL=/api ``` 创建 `.env.production` 文件： ```env VITE_API_BASE_URL=/api ``` --- ## Docker部署 ### 使用 Docker Compose 一键部署 ```bash # 构建并启动所有服务 docker-compose up -d # 查看服务状态 docker-compose ps # 查看日志 docker-compose logs -f backend # 停止服务 docker-compose down # 停止并删除数据卷 docker-compose down -v ``` ### 服务架构 ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Nginx │────▶│ Backend │────▶│ MySQL │ │ :80 │ │ :8080 │ │ :3306 │ └─────────────┘ └─────────────┘ └─────────────┘ │ ▼ ┌─────────────┐ │ Redis │ │ :6379 │ └─────────────┘ ``` ### 服务配置 | 服务 | 容器名 | 端口 | 说明 | |------|--------|------|------| | frontend | cwgk-frontend | 80 | Nginx静态资源服务 | | backend | cwgk-backend | 8080 | Spring Boot应用 | | mysql | cwgk-mysql | 3306 | MySQL 8.0 | | redis | cwgk-redis | 6379 | Redis 7 | ### 数据持久化 ```yaml volumes: mysql_data: # MySQL数据持久化 redis_data: # Redis数据持久化 ``` ### 健康检查 - MySQL: `mysqladmin ping -h localhost` - Redis: `redis-cli ping` - Backend: `curl -f http://localhost:8080/actuator/health` --- ## 开发指南 ### 代码规范 - **Java**: 遵循阿里巴巴 Java 开发规范 - **TypeScript**: ESLint + Prettier - **命名规范**: - 类名: PascalCase (如 `UserController`) - 方法名: camelCase (如 `getUserById`) - 常量: UPPER_SNAKE_CASE (如 `MAX_SIZE`) - 数据库表: lower_snake_case (如 `sys_user`) ### 分支管理 ``` master # 主分支，稳定版本 develop # 开发分支 feature/* # 功能分支 hotfix/* # 热修复分支 ``` ### 提交规范 ``` feat: 新功能 fix: 修复bug docs: 文档更新 style: 代码格式 refactor: 重构 test: 测试 chore: 构建/工具 ``` ### 代码质量工具 ```bash # Java代码检查 mvn checkstyle:check # 代码规范检查 mvn spotbugs:check # 静态分析 mvn test jacoco:report # 测试覆盖率报告 # 前端代码检查 npm run lint # ESLint检查 npm run format # Prettier格式化 ``` ### 单元测试 ```bash # 后端测试 mvn test # 运行所有测试 mvn test -Dtest=UserServiceTest # 运行指定测试类 # 测试覆盖率 mvn jacoco:report # 报告位置: target/site/jacoco/index.html ``` --- ## 安全设计 ### 认证机制 - **JWT Token**: 无状态认证 - **有效期**: 24小时 - **存储**: 前端 localStorage - **传输**: Authorization Header (Bearer Token) ### 权限控制 ``` 权限模型: RBAC (基于角色的访问控制) 用户 ──▶ 用户角色关联 ──▶ 角色 ──▶ 角色菜单关联 ──▶ 菜单/权限 ``` ### 角色体系 | 角色 | 编码 | 数据范围 | |------|------|---------| | 超级管理员 | SUPER_ADMIN | 全部数据 | | 市级管理员 | CITY_ADMIN | 本市数据 | | 县级管理员 | COUNTY_ADMIN | 本县数据 | | 乡镇管理员 | TOWN_ADMIN | 本乡镇数据 | | 村级管理员 | VILLAGE_ADMIN | 本村数据 | | 普通用户 | USER | 个人数据 | ### 密码安全 - **加密算法**: BCrypt - **密码强度**: 6-20位字符 - **密码校验**: 前后端双重校验 ### 安全配置 ```java // Spring Security 配置 - 禁用 CSRF (使用 JWT) - 开启 CORS - 接口权限拦截 - 匿名访问白名单 ``` ### 敏感信息 - 数据库密码、JWT密钥等通过环境变量配置 - 生产环境禁止使用默认密码 - 日志中过滤敏感字段 --- ## 常见问题 ### Q1: 启动后端报数据库连接失败？ 检查 MySQL 是否启动，数据库是否创建，用户名密码是否正确。 ### Q2: 前端请求后端跨域？ 开发环境 Vite 已配置代理，生产环境 Nginx 已配置反向代理。 ### Q3: 登录后 Token 失效？ Token 有效期 24 小时，检查系统时间是否正确，检查 Redis 是否正常。 ### Q4: 文件上传失败？ 检查文件大小限制（默认 10MB），检查文件类型是否允许。 --- ## 版本历史 | 版本 | 日期 | 说明 | |------|------|------| | 1.0.0 | 2026-02-16 | 初始版本，基础功能 | | 1.1.0 | 2026-02-16 | 添加统一异常处理、单元测试、参数校验 | | 1.2.0 | 2026-02-23 | 完善功能模块，优化部署配置 | --- ## 许可证 本项目仅供学习交流使用。 --- ## 联系方式 如有问题，请联系开发团队。QQ交流群：1063516859