# 阳光村务

**Repository Path**: hackloop/village-governance

## Basic Information

- **Project Name**: 阳光村务
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-19
- **Last Updated**: 2026-10-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Village Governance System

**村务管理系统** - 体现阳光村务，建设数字乡村

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Go Version](https://img.shields.io/badge/Go-1.24-00ADD8?logo=go)](https://go.dev/)
[![Vue Version](https://img.shields.io/badge/Vue-3.4-4FC08D?logo=vue.js)](https://vuejs.org/)

一个现代化的村务管理系统，提供人口档案、村组户层级、党务/村务/财务管理、用户权限等功能，助力乡村数字化建设。

## ✨ 特性

- 🏘️ **村组户层级管理** - 树形结构展示村/组/户/人关系
- 👥 **人口档案管理** - 完整的居民信息管理，支持导入导出、疑似重复检测
- 💰 **财务管理** - 收入支出管理、审批流程、资产管理、合同管理、财务报表
- 📋 **党务村务管理** - 党务和村务事项管理看板
- 🔐 **权限管理** - 基于 RBAC 的细粒度权限控制
- 📊 **统计分析** - 人口统计、财务统计、图表可视化
- 📝 **操作日志** - 完整的操作审计追踪
- 💾 **数据备份** - 支持数据库备份导出与恢复
- 🎨 **现代化 UI** - 基于 Element Plus 的美观界面

## 🛠️ 技术栈

### 后端
- **语言**: Go 1.24
- **Web 框架**: Gin
- **ORM**: GORM + 原生 SQL
- **数据库**: MySQL 8.0
- **缓存**: Redis 7.4
- **对象存储**: MinIO
- **认证**: JWT

### 前端
- **框架**: Vue 3.4 (Composition API)
- **语言**: TypeScript 5.4
- **构建工具**: Vite 5.2
- **UI 组件库**: Element Plus 2.14
- **状态管理**: Pinia 2.1
- **路由**: Vue Router 4.3
- **图表**: ECharts 6.1

### 部署
- **容器**: Docker + Docker Compose
- **Web 服务器**: Nginx
- **桌面客户端**: Electron

## 📦 快速开始

### 使用 Docker Compose（推荐）

```bash
# 克隆仓库
git clone https://github.com/yourusername/village-governance.git
cd village-governance

# 启动所有服务（MySQL + Redis + MinIO + Backend + Frontend）
./start.sh
```

启动成功后访问：
- **前端**: http://localhost:8032
- **后端 API**: http://localhost:8031/api/v1/health

默认账号：
- 超级管理员：`superadmin` / `123456`
- 村干部：`cadre` / `123456`

### 本地开发

**前置条件**：
- Go 1.24+
- Node.js 20+
- MySQL 8.0+
- Redis 7.4+ (可选)
- MinIO (可选)

#### 1. 启动基础设施

```bash
docker compose up -d mysql redis minio
```

#### 2. 启动后端

```bash
cd backend
go mod download

# 设置环境变量
export MYSQL_HOST=127.0.0.1
export MYSQL_PORT=3306
export MYSQL_USER=village
export MYSQL_PASSWORD=village
export MYSQL_DB=village_governance
export REDIS_ADDR=127.0.0.1:6379
export JWT_SECRET=dev-secret-change-me

# 运行
go run cmd/server/main.go
```

后端将运行在 http://localhost:8031

#### 3. 启动前端

```bash
cd frontend
npm install
npm run dev
```

前端将运行在 http://localhost:8032

### 使用本地开发脚本

项目提供了便捷的开发脚本：

```bash
# 启动本地开发环境（需要先启动 MySQL/Redis/MinIO）
./dev-start.sh

# 停止本地开发环境
./dev-stop.sh
```

日志输出到 `logs/backend.log` 和 `logs/frontend.log`。

## 📚 功能模块

### 1. 人口档案管理
- ✅ 居民信息 CRUD（30+ 字段）
- ✅ 多维度筛选（姓名、性别、年龄、村组、政治面貌、特殊身份等）
- ✅ 身份证号自动校验
- ✅ 批量导入/导出 Excel
- ✅ 疑似重复档案检测
- ✅ 出生登记、死亡注销
- ✅ 迁入迁出登记
- ✅ 家庭户调整

### 2. 村组户层级管理
- ✅ 树形结构展示（村 → 组 → 户 → 人）
- ✅ 村/组/户的新增、编辑、删除
- ✅ 户主变更
- ✅ 家庭成员管理
- ✅ 户籍关系维护

### 3. 财务管理
- ✅ **收入管理**：登记、确认、驳回
- ✅ **支出管理**：提交、多级审批、支付
- ✅ **资产管理**：固定资产、资产变动记录
- ✅ **合同管理**：合同登记、到期预警
- ✅ **资源管理**：村集体资源登记
- ✅ **账户管理**：多账户管理
- ✅ **统计报表**：收支统计、资产负债表、财务导出

### 4. 党务/村务管理
- ✅ 党务事项看板
- ✅ 村务事项看板
- ✅ 状态流转管理

### 5. 用户与权限
- ✅ 用户管理（新增、编辑、删除）
- ✅ 角色管理（权限配置）
- ✅ 基于 RBAC 的权限控制
- ✅ JWT 认证
- ✅ 会话管理

### 6. 系统管理
- ✅ 操作日志查询（审计追踪）
- ✅ 数据备份导出（支持全库或选表）
- ✅ 数据恢复（SQL 文件导入）
- ✅ 人口统计仪表盘

## 🏗️ 项目结构

```
village-governance/
├── backend/                 # Go 后端
│   ├── cmd/
│   │   └── server/         # 应用入口
│   ├── internal/
│   │   ├── handler/        # HTTP 处理器
│   │   ├── service/        # 业务逻辑层
│   │   ├── repository/     # 数据访问层
│   │   ├── model/          # 数据模型
│   │   ├── middleware/     # 中间件
│   │   └── response/       # 统一响应
│   └── pkg/                # 公共包
│       ├── database/       # 数据库工具
│       ├── logger/         # 日志工具
│       ├── jwt/            # JWT 工具
│       └── storage/        # 文件存储
├── frontend/               # Vue 3 前端
│   ├── src/
│   │   ├── api/           # API 接口
│   │   ├── components/    # 组件
│   │   ├── views/         # 页面
│   │   ├── router/        # 路由
│   │   ├── store/         # 状态管理
│   │   └── constants/     # 常量定义
│   └── public/            # 静态资源
├── desktop/               # Electron 桌面客户端
├── deploy/                # 部署脚本和配置
├── scripts/               # 工具脚本
├── docs/                  # 文档
├── docker-compose.yml     # Docker Compose 配置
├── .env.example           # 环境变量示例
├── start.sh               # 快速启动脚本
├── stop.sh                # 停止脚本
├── dev-start.sh           # 本地开发启动
└── dev-stop.sh            # 本地开发停止
```

## 📖 文档

- [后端 README](backend/README.md) - Go 后端架构、API 文档、开发指南
- [前端 README](frontend/README.md) - Vue 3 前端架构、组件使用、开发规范
- [项目架构文档](docs/architecture.md) - 整体架构设计
- [开发规范](docs/development-standards.md) - 编码规范和最佳实践
- [CLAUDE.md](CLAUDE.md) - AI 助手开发指引

## 🚀 部署

### Docker 部署（生产环境）

```bash
# 1. 配置环境变量
cp .env.example .env
vim .env  # 修改数据库密码、JWT Secret 等

# 2. 启动服务
./start.sh

# 3. 停止服务
./stop.sh
```

### 云端部署（非 Docker）

适用于已有 MySQL/Redis/Nginx 的云服务器：

```bash
# 配置部署参数
cp .env.deploy.example .env.deploy
vim .env.deploy  # 修改远端数据库配置

# 部署到远端服务器
./scripts/deploy-cloud.sh
```

详见 [部署文档](docs/deployment.md)。

### 独立安装包

生成跨平台安装包：

```bash
./scripts/package.sh
```

安装包输出到 `dist/installer/`，支持：
- Windows (amd64)
- macOS (Apple Silicon arm64)
- Linux (amd64)

### 桌面客户端

打包 Electron 桌面客户端：

```bash
./scripts/package-desktop.sh
```

支持：
- macOS (Apple Silicon / Intel)
- Windows (x64)

## 🔐 权限系统

系统采用基于角色的访问控制（RBAC），权限格式为 `resource:action`。

### 预设角色

| 角色 | 标识 | 权限 | 说明 |
|-----|------|------|------|
| 超级管理员 | `super_admin` | `*` | 所有权限 |
| 村干部 | `village_admin` | 人口、层级、党务、村务、财务 | 日常村务管理 |

### 权限点示例

```
dashboard:view              # 查看仪表盘
population:view             # 查看人口档案
population:manage           # 管理人口档案
hierarchy:view              # 查看村组户层级
hierarchy:manage            # 管理村组户层级
finance_affair:view         # 查看财务
finance_affair:manage       # 管理财务
user:manage                 # 管理用户
system:role:manage          # 管理角色
system:backup               # 数据备份
system:log:view             # 查看操作日志
```

详见 [权限配置文档](docs/permissions.md)。

## 🧪 测试

```bash
# 后端测试
cd backend
go test ./...
go test -cover ./...

# 前端测试（待实现）
cd frontend
npm run test
```

## 🤝 贡献

欢迎贡献代码！请遵循以下流程：

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

提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范。

## 📝 更新日志

见 [CHANGELOG.md](CHANGELOG.md)

## 🐛 问题反馈

如遇到问题，请：
1. 查看 [常见问题文档](docs/FAQ.md)
2. 搜索 [Issues](https://github.com/yourusername/village-governance/issues)
3. 提交新 Issue（请提供详细的复现步骤）

## 📄 开源协议

本项目基于 [MIT License](LICENSE) 开源。

## 👥 贡献者

感谢所有为本项目做出贡献的开发者！

## 🙏 致谢

- [Gin](https://github.com/gin-gonic/gin) - Go Web 框架
- [GORM](https://gorm.io/) - Go ORM 库
- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
- [Element Plus](https://element-plus.org/) - Vue 3 UI 组件库
- [ECharts](https://echarts.apache.org/) - 数据可视化图表库

## 📧 联系方式

- 项目主页: https://github.com/yourusername/village-governance
- 问题反馈: https://github.com/yourusername/village-governance/issues
- 邮箱: your.email@example.com

---

⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！