# hhyt

**Repository Path**: xiaoping2017/hhyt

## Basic Information

- **Project Name**: hhyt
- **Description**: 航期查询项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-09
- **Last Updated**: 2025-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚢 船期管理系统 (HHYT)

[![Django](https://img.shields.io/badge/Django-4.2.7-green.svg)](https://www.djangoproject.com/)
[![DRF](https://img.shields.io/badge/DRF-3.14.0-blue.svg)](https://www.django-rest-framework.org/)
[![Vue](https://img.shields.io/badge/Vue-3.4-brightgreen.svg)](https://vuejs.org/)
[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
[![Node.js](https://img.shields.io/badge/Node.js-16+-green.svg)](https://nodejs.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

基于Django REST Framework和Vue 3的现代化船期管理系统，提供完整的船期数据管理、本地费用管理、用户权限控制和前端管理界面。

## 🌐 在线访问

- **生产环境**: https://www.sezqma.com/ 或 http://49.233.138.141/
- **API文档**: https://www.sezqma.com/api/
- **管理后台**: https://www.sezqma.com/admin/

## ✨ 核心特性

### 🚢 船期管理
- **完整的船期数据管理** - 船舶航线、港口、时间等信息管理
- **船期数据爬取** - 自动从外部数据源获取最新船期信息
- **数据版本控制** - 支持多版本数据管理和同步
- **前台船期查询** - 专业的船期查询界面，支持多条件筛选

### 💰 本地费用管理
- **费用信息管理** - 完整的本地费用录入、编辑、查询功能
- **多货币支持** - 支持多种货币的费用计算
- **费用分类管理** - 灵活的费用分类和标签系统

### 👥 用户权限系统
- **基于角色的权限控制(RBAC)** - 细粒度的权限管理
- **JWT认证** - 安全的Token认证机制
- **用户头像上传** - 支持用户个人头像管理
- **多角色支持** - 超级管理员、工作人员、业务员等角色

### 🔔 系统消息通知 (新增v2.0)
- **实时消息推送** - 管理员发布系统通知，用户实时接收
- **按角色定向发送** - 支持按用户角色精准推送消息
- **消息优先级管理** - 紧急/重要/普通三级优先级分类
- **已读状态跟踪** - 完整的消息已读/未读状态管理
- **智能权限控制** - 基于用户权限的消息显示控制

### 🛡️ 企业级安全防护 (新增)
- **反爬虫系统** - 企业级双重保护机制，支持公司IP白名单
- **智能检测** - User-Agent检测和频率限制，拦截率90%+
- **快速恢复** - 3-15分钟自动解封，误杀率<1%
- **多用户支持** - 支持100+用户并发访问，企业友好

### 🎨 现代化前端界面
- **Vue 3 + Element Plus** - 现代化的响应式用户界面
- **TypeScript支持** - 类型安全的前端开发
- **组件化架构** - 可复用的UI组件库
- **国际化支持** - 完善的中文界面

### 📊 数据管理
- **MariaDB/MySQL数据库** - 稳定可靠的数据存储
- **数据爬取系统** - 自动化的船期数据采集
- **数据同步机制** - 多源数据的同步和合并
- **性能优化** - 数据库索引优化，查询性能提升

## 📁 项目结构

```
hhyt/
├── 🚢 后端系统 (Django REST Framework)
│   ├── ship-schedule-management/     # 主后端项目
│   │   ├── ship_schedule/           # Django项目配置
│   │   ├── authentication/         # 用户认证和权限管理
│   │   ├── schedules/              # 船期管理模块
│   │   ├── local_fees/             # 本地费用管理
│   │   ├── system_messages/        # 系统消息管理 (新增v2.0)
│   │   ├── static/                 # 静态文件
│   │   ├── media/                  # 上传文件存储
│   │   ├── logs/                   # 应用日志
│   │   ├── tests/                  # 测试用例
│   │   ├── scripts/                # 维护脚本
│   │   ├── docs/                   # API文档
│   │   ├── requirements.txt        # Python依赖
│   │   └── manage.py               # Django管理脚本
│   │
├── 🎨 前端系统 (Vue 3 + TypeScript)
│   ├── ship-schedule-management-ui/ # 主前端项目
│   │   ├── src/
│   │   │   ├── views/              # 页面组件
│   │   │   ├── components/         # 公共组件
│   │   │   ├── stores/             # 状态管理
│   │   │   ├── router/             # 路由配置
│   │   │   ├── api/                # API接口
│   │   │   ├── utils/              # 工具函数
│   │   │   └── styles/             # 样式文件
│   │   ├── tests/                  # 前端测试
│   │   ├── docs/                   # 前端文档
│   │   ├── package.json            # Node.js依赖
│   │   └── vite.config.js          # Vite配置
│   │
├── 📊 数据爬取系统
│   ├── get_schedule_data/          # 船期数据爬取
│   │   ├── daily_crawl.py          # 每日数据爬取脚本
│   │   ├── process_routes.py       # 路由数据处理
│   │   ├── config.json             # 爬取配置
│   │   └── ports_config.json       # 港口配置
│   │
├── 📚 项目文档
│   ├── 文档/                      # 中文分类文档目录
│   │   ├── 安全防护/              # 反爬虫系统文档
│   │   ├── 系统部署/              # 部署指南和配置
│   │   ├── 开发指南/              # 开发环境和规范
│   │   └── API接口/               # API接口文档
│   ├── CLAUDE.md                   # 开发指令文档
│   └── README.md                   # 项目说明文档
```

## 🚀 快速开始

### 环境要求

- **Python**: 3.8+
- **Node.js**: 16+
- **数据库**: MariaDB 10.3+ 或 MySQL 8.0+
- **操作系统**: Linux (Ubuntu 20.04+推荐) 或 macOS

### 1. 克隆项目

```bash
git clone https://gitee.com/xiaoping2017/hhyt.git
cd hhyt
```

### 2. 后端环境配置

```bash
# 创建并激活Python虚拟环境
conda create -n hhyt python=3.8
conda activate hhyt

# 进入后端项目目录
cd ship-schedule-management

# 安装Python依赖
pip install -r requirements.txt

# 配置环境变量（复制并修改）
cp .env.example .env
# 编辑.env文件，配置数据库连接等信息

# 执行数据库迁移
python manage.py migrate

# 创建超级用户
python manage.py createsuperuser

# 启动后端开发服务器
python manage.py runserver
```

### 3. 前端环境配置

```bash
# 进入前端项目目录
cd ../ship-schedule-management-ui

# 安装前端依赖
pnpm install
# 或使用 npm install

# 启动前端开发服务器
pnpm dev
# 或使用 npm run dev
```

### 4. 访问系统

- **前端界面**: http://localhost:3000
- **后端API**: http://localhost:8000/api/
- **Django管理**: http://localhost:8000/admin/

### 5. 测试账号

**超级管理员账号**:
- 邮箱: admin@admin.com
- 密码: admin123

## 🔧 生产环境部署

### 数据库配置

```bash
# MariaDB/MySQL配置
数据库名: huan_hai
用户名: root
密码: 099118
端口: 3306
```

### 后端部署 (Gunicorn + Nginx)

```bash
# 安装系统服务
sudo systemctl enable gunicorn_ship_schedule
sudo systemctl enable nginx

# 启动服务
sudo systemctl start gunicorn_ship_schedule
sudo systemctl start nginx

# 检查服务状态
sudo systemctl status gunicorn_ship_schedule nginx
```

### 前端部署

```bash
# 构建生产版本
cd ship-schedule-management-ui
pnpm build

# 部署到Nginx
# 构建后的文件在 dist/ 目录中
```

### 服务管理命令

```bash
# 重启服务
sudo systemctl restart gunicorn_ship_schedule
sudo systemctl reload nginx

# 查看日志
sudo tail -f /var/log/gunicorn/ship_schedule_error.log
sudo journalctl -u gunicorn_ship_schedule -f
```

## 📚 API文档

### 认证相关

```bash
# 用户登录
POST /api/auth/login/
{
  "email": "admin@admin.com",
  "password": "admin123"
}

# 获取当前用户信息
GET /api/auth/me/
Authorization: Bearer <access_token>

# 刷新Token
POST /api/auth/token/refresh/
{
  "refresh": "<refresh_token>"
}
```

### 船期管理

```bash
# 获取船期信息
GET /api/vessel-info/
Authorization: Bearer <access_token>

# 船期查询（前台页面）
GET /api/vessel-info/query/?polCd=CNSHA&podCd=USNYC
Authorization: Bearer <access_token>

# 创建船期信息
POST /api/vessel-info/
Authorization: Bearer <access_token>
```

### 本地费用管理

```bash
# 获取本地费用列表
GET /api/local-fees/
Authorization: Bearer <access_token>

# 创建本地费用
POST /api/local-fees/
Authorization: Bearer <access_token>
```

### 系统消息管理 (新增v2.0)

```bash
# 管理员消息管理
GET /api/admin/messages/          # 获取所有消息
POST /api/admin/messages/         # 创建消息
PUT /api/admin/messages/{id}/     # 更新消息
DELETE /api/admin/messages/{id}/  # 删除消息

# 用户消息查看
GET /api/user/messages/           # 获取用户消息
GET /api/user/messages/unread_count/  # 获取未读数量
POST /api/user/messages/{id}/mark_read/  # 标记已读
POST /api/user/messages/mark_all_read/   # 全部已读
```

### 快速API测试

```bash
# 获取访问Token
TOKEN=$(curl -s -X POST https://www.sezqma.com/api/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@admin.com","password":"admin123"}' | \
  jq -r '.access')

# 测试API
curl -H "Authorization: Bearer $TOKEN" https://www.sezqma.com/api/auth/me/
curl -H "Authorization: Bearer $TOKEN" https://www.sezqma.com/api/vessel-info/
```

## 🧪 测试

### 后端测试

```bash
cd ship-schedule-management

# 运行所有测试
python manage.py test

# 运行特定测试
python manage.py test authentication
python manage.py test schedules
python manage.py test local_fees

# 使用pytest
pytest
```

### 前端测试

```bash
cd ship-schedule-management-ui

# 运行单元测试
pnpm test

# 运行端到端测试
pnpm test:e2e

# 测试覆盖率
pnpm test:coverage
```

## 🔐 权限说明

### 用户角色

1. **超级管理员 (Superuser)**
   - 拥有所有权限
   - 可以管理用户、角色、权限
   - 可以访问Django admin界面

2. **工作人员 (Staff)**
   - 船期信息管理权限
   - 本地费用管理权限
   - 用户信息查看权限

3. **业务员 (Business User)**
   - 船期查询权限
   - 本地费用查询权限
   - 个人信息管理权限

### 权限分类

- **用户管理**: user.list, user.detail, user.create, user.update, user.delete
- **角色管理**: role.list, role.detail, role.create, role.update, role.delete
- **权限管理**: permission.list, permission.detail
- **船期管理**: vessel_info.list, vessel_info.detail, vessel_info.create, vessel_info.update, vessel_info.delete
- **费用管理**: local_fee.list, local_fee.detail, local_fee.create, local_fee.update, local_fee.delete
- **系统消息**: system.message.list, system.message.detail, system.message.create, system.message.update, system.message.delete (新增v2.0)

## 📊 数据爬取系统

### 船期数据爬取

```bash
cd get_schedule_data

# 手动执行数据爬取
python daily_crawl.py

# 查看爬取配置
cat config.json
cat ports_config.json
```

### 自动化任务

系统支持定时任务自动爬取船期数据，保持数据的实时性和准确性。

## 🛠️ 开发指南

### 技术栈

**后端**:
- Django 4.2.7 - Web框架
- Django REST Framework 3.14.0 - API框架
- MariaDB/MySQL - 数据库
- JWT - 认证机制
- Gunicorn - WSGI服务器
- Nginx - 反向代理

**前端**:
- Vue 3.4 - 前端框架
- TypeScript - 类型系统
- Element Plus - UI组件库
- Vite 5.2 - 构建工具
- Pinia - 状态管理

### 开发规范

1. **后端开发**
   - 遵循Django最佳实践
   - 使用DRF序列化器进行数据验证
   - 所有API需要权限验证
   - 编写完整的测试用例

2. **前端开发**
   - 使用TypeScript进行类型检查
   - 组件化开发，提高代码复用性
   - 遵循Vue 3 Composition API规范
   - 统一的错误处理和用户反馈

3. **代码质量**
   - 代码覆盖率: 后端90%+, 前端80%+
   - 单个文件不超过500行
   - 统一的代码格式化和检查

## 🔍 故障排除

### 常见问题

1. **403权限错误**
   ```bash
   chmod 755 /root /root/hhyt
   ```

2. **502网关错误**
   ```bash
   sudo systemctl status gunicorn_ship_schedule
   sudo systemctl restart gunicorn_ship_schedule
   ```

3. **静态文件404**
   ```bash
   python manage.py collectstatic --noinput
   ```

4. **前端更新不生效**
   ```bash
   pnpm build
   # 检查dist目录是否正确部署
   ```

### 日志查看

```bash
# 应用日志
tail -f ship-schedule-management/logs/django.log

# Gunicorn日志
sudo tail -f /var/log/gunicorn/ship_schedule_error.log

# Nginx日志
sudo tail -f /var/log/nginx/error.log
```

## 🤝 贡献指南

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

## 📄 许可证

本项目采用MIT许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 联系方式

- **项目仓库**: https://gitee.com/xiaoping2017/hhyt
- **问题反馈**: 请在Gitee仓库中提交Issue
- **技术支持**: 通过Gitee私信联系项目维护者

## 📅 更新日志

### v2.0.0 (2025-06-12) 🔔 系统消息功能版本
- 🔔 **新增系统消息通知功能** - 管理员可发布系统消息，用户实时接收
- 🎯 **按角色定向发送** - 支持按用户角色精准推送消息，提升运营效率
- ⚡ **消息优先级管理** - 紧急/重要/普通三级优先级，支持重要消息突出显示
- 📊 **已读状态跟踪** - 完整的消息已读/未读状态管理，实时统计未读数量
- 🛡️ **智能权限控制** - 基于用户权限的消息显示控制，确保信息安全
- 🎨 **前端消息组件** - 响应式消息通知界面，支持自动收起和手动管理
- 📚 **完善权限文档** - 更新权限配置文档，添加系统消息权限说明
- 🔧 **权限配置优化** - 为普通用户自动配置消息查看权限

### v2.1.0 (2025-06-11)
- 🛡️ **新增企业级反爬虫系统** - 支持公司IP白名单，频率限制，User-Agent检测
- 🏢 **企业多用户优化** - 支持100+用户并发访问，误杀率<1%
- ⚡ **快速恢复机制** - 屏蔽时间从1小时缩短至3-15分钟
- 📚 **文档结构重构** - 创建中文分类文档目录，提升维护性
- 🔧 **安全防护增强** - 分级屏蔽策略，智能行为检测

### v1.5.0 (2025-01-09)
- ✨ 清理项目无用文件，精简代码库结构
- 🗑️ 移除Docker配置（项目使用Gunicorn+Nginx部署）
- 📝 删除过时的文档和备份文件
- 🧹 清理调试脚本和测试工具
- 📋 完善项目README文档

### v1.5.0 (2025-05-26)
- 🔧 修复数据版本控制并集成船期爬取系统
- 📝 精简CLAUDE.md指令文件，保留核心快速开发信息
- 🔧 完善生产环境配置文档
- 🛠️ 修正Gunicorn和Nginx配置

---

**最后更新时间**: 2025年6月11日

---

## 📚 相关文档

- [📖 文档中心](./文档/README.md) - 完整的项目文档导航
- [🛡️ 反爬虫配置指南](./文档/安全防护/反爬虫系统配置指南.md) - 企业级安全防护
- [🚀 生产环境部署指南](./文档/系统部署/生产环境部署指南.md) - 完整部署步骤
- [⚡ 公司IP白名单快速配置](./文档/安全防护/公司IP白名单快速配置.md) - 企业IP配置