# hotel

**Repository Path**: zui216/hotel

## Basic Information

- **Project Name**: hotel
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-26
- **Last Updated**: 2026-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 酒店管理系统

一个企业级酒店管理系统，基于 Django + Vue3 + MySQL 构建，支持多角色权限控制。

## 技术栈

- **后端**：Python 3.10+ / Django 4.2 / Django REST Framework 3.14 / SimpleJWT
- **前端**：Vue 3.4 / Vite 5 / Ant Design Vue 4 / Pinia / ECharts
- **数据库**：MySQL 8.0+

## 环境要求

- Python 3.10+
- Node.js 18+
- MySQL 8.0+

## 一键初始化（setup.sh）

根目录 `setup.sh` 覆盖依赖检查、`.env` 生成（含随机 `SECRET_KEY`）、后端依赖 + `migrate` + `sql/data.sql` 载入 + `init_default_users`、前端与根 `npm install`。可重复执行（幂等）。

```bash
./setup.sh                       # 首次完整初始化
./setup.sh --skip-db             # 只装依赖，不动数据库
./setup.sh --skip-frontend       # 跳过前端 npm install
./setup.sh --recreate-env        # 备份并重新生成 .env
```

前提：MySQL 已启动、目标数据库已创建、`.env`（首次生成后）中的 `DB_*` 与 `DEFAULT_*_PASSWORD` 已按本地环境填写；`python` / `pip` 已在 PATH 中（若使用 conda，请先 `conda activate xiangmu` 再执行 `setup.sh`）。首次运行会生成 `.env` 并中止，让你先填占位符，再次运行即可完成剩余步骤。

## 后端启动步骤

1. 进入后端目录：
   ```bash
   cd backend
   ```

2. 激活 conda 环境：
   ```bash
   conda activate xiangmu
   ```

3. 安装依赖：
   ```bash
   pip install -r requirements.txt
   ```

4. 配置本地环境变量：
   ```bash
   cp ../.env.example ../.env
   ```
   按本地环境填写 `SECRET_KEY`、数据库连接和默认用户密码。也可以通过 `ENV_PATH` 指定其他 `.env` 文件。

5. 执行数据库迁移：
   ```bash
   python manage.py migrate
   ```

   > 数据库表结构以 Django migrations 为准（`backend/apps/*/migrations/`）。`sql/data.sql` 仅存放房型/服务项目等业务初始数据；不再维护 `sql/schema.sql`，避免与 migrations 漂移。

6. 初始化默认账号和权限数据：
   ```bash
   python manage.py init_default_users
   ```

7. 启动开发服务器：
   ```bash
   python manage.py runserver
   ```

后端将在 http://localhost:8000 启动。

`DEBUG` / `ENABLE_API_DOCS` 现均默认 `False`。仅当在 `.env` 显式打开 `DEBUG=True` 或 `ENABLE_API_DOCS=True` 时,API 文档入口才会注册：
- Swagger UI: http://localhost:8000/swagger/
- ReDoc: http://localhost:8000/redoc/

## 管理命令（数据回填）

P0 修复引入的两条一次性回填命令，建议按顺序执行：

```bash
# 为历史退房记录补齐 room_charge 类型的 Bill
python manage.py backfill_room_charge_bills --dry-run   # 预览
python manage.py backfill_room_charge_bills             # 正式写入

# 基于 Checkin.customer_phone 重算 Customer.total_spent / stay_count / membership_level
python manage.py rebuild_customer_stats --dry-run       # 预览
python manage.py rebuild_customer_stats                 # 正式写入
```

两条命令均包裹在 `transaction.atomic()` 内,支持 `--dry-run`,可反复执行。

## 前端启动步骤

1. 进入前端目录：
   ```bash
   cd frontend
   ```

2. 安装依赖：
   ```bash
   npm install
   ```

3. 启动开发服务器：
   ```bash
   npm run dev
   ```

前端将在 http://localhost:5173 启动，API 请求自动代理到后端 8000 端口。

## 一键启动（start.sh）

根目录 `start.sh` 用于本地开发一键拉起前后端，自动激活 conda 环境、探活后端、前台跟踪日志。

```bash
./start.sh            # 启动（默认前台，Ctrl+C 停止）
./start.sh start      # 同上
./start.sh stop       # 停止
./start.sh restart    # 重启
./start.sh status     # 查看运行状态
```

支持的环境变量覆盖：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `HOTEL_CONDA_ENV` | `xiangmu` | 后端使用的 conda 环境名 |
| `HOTEL_RUNTIME_DIR` | `<repo>/.runtime` | 存放 PID / 日志文件的目录 |
| `BACKEND_PORT` | `8000` | 后端监听端口 |
| `FRONTEND_PORT` | `5173` | 前端监听端口 |

示例：`HOTEL_CONDA_ENV=my-env FRONTEND_PORT=5174 ./start.sh`

## 数据库管理模块（dbadmin）

内置只读的 DBA 视图，仅供管理员在应用内查看表结构、样本数据、执行受限的 SELECT 查询，避免直连生产 MySQL。

- **入口**：前端「数据库管理」菜单（管理员可见）。
- **权限**：需要 `dbadmin_access` 权限；普通角色不放通，最小权限。
- **只读**：SQL 控制台仅接受 SELECT 白名单语句，敏感列（如身份证、手机号）自动脱敏。
- **审计**：所有操作写入 `dbadmin_audit_log` 表，含操作人、SQL、影响行数、命中的脱敏规则。
- **导出**：默认关闭全表导出；触发导出会被审计并做二次防护（脱敏 + 行数截断）。

## 测试

后端测试专用配置在 [backend/hotel/settings_test.py](backend/hotel/settings_test.py)：sqlite in-memory + LocMem 缓存，不会连生产 MySQL。

```bash
# 后端
conda activate xiangmu && cd backend && pytest -q

# 前端
cd frontend && npm test
```

`backend/pytest.ini` 已默认指向 `hotel.settings_test`。前端 `npm test` 走 vitest，`test:watch` 为守护模式。

## 持续集成（CI）

GitHub Actions 配置见 [.github/workflows/ci.yml](.github/workflows/ci.yml)。

- **backend job**：ruff check + ruff format --check + pip-audit（不阻断）+ `manage.py check` + `pytest -q`
- **frontend job**：`npm ci` + eslint + vitest + `npm run build`

任何 PR 均会跑上述两条流水线；本地可用 `ruff check backend/` / `ruff format backend/` 提前对齐。

## 提交规范与 pre-commit（P2 B7）

根目录 `package.json` 承载 monorepo 级 hook：

```bash
npm install                    # 根目录一次即可，自动触发 husky
```

`prepare` 脚本会安装 `.husky/` 下的 hook。之后：

- **`.husky/pre-commit`**：跑 `lint-staged`
  - `backend/**/*.py` → `conda run -n xiangmu ruff check --fix` + `ruff format`
  - `frontend/**/*.{js,vue}` → `eslint --fix` + `prettier --write`
  - `frontend/**/*.{json,css,less,md}` → `prettier --write`
- **`.husky/commit-msg`**：跑 `commitlint --edit`，强制 Conventional Commits（`feat:` / `fix:` / `refactor:` / `chore:` / `docs:` / `test:` / `perf:` / `build:` / `ci:` / `style:` / `revert:`），`header-max-length: 100`。

绕过 hook 需 `git commit --no-verify`（仅应急）。

## 前端国际化（P2 B7）

前端已接入 `vue-i18n@9`（Composition API 模式）。

- 骨架：[frontend/src/i18n/index.js](frontend/src/i18n/index.js)
- 中英文文案：[frontend/src/i18n/locales/zh-CN.json](frontend/src/i18n/locales/zh-CN.json)、[frontend/src/i18n/locales/en-US.json](frontend/src/i18n/locales/en-US.json)
- 语言检测顺序：`localStorage.locale` → `navigator.language` → `zh-CN`
- 语言切换：右上角 HeaderBar 的地球图标下拉

首批已抽文案的 5 个页面：登录、Dashboard、预订列表 + 表单 + 筛选、入住列表、退房列表。其余页面文案后续按 P3 节奏推进。

## 生产部署硬化（P2 B2）

`backend/hotel/settings.py` 已把生产安全头挂上开关，默认取值随 `DEBUG` 反转：

| 设置 | 默认（DEBUG=False 时） | 说明 |
|---|---|---|
| `SECURE_SSL_REDIRECT` | `True` | 需 nginx 传 `X-Forwarded-Proto: https` |
| `SECURE_HSTS_SECONDS` | `31536000` | 灰度期建议先设 300，稳定 3~7 天再放大 |
| `SECURE_HSTS_INCLUDE_SUBDOMAINS` | `True` | |
| `SECURE_HSTS_PRELOAD` | `True` | |
| `SESSION_COOKIE_SECURE` | `True` | |
| `CSRF_COOKIE_SECURE` | `True` | |
| `SECURE_PROXY_SSL_HEADER` | `('HTTP_X_FORWARDED_PROTO', 'https')` | 反代前一定要传 |

`SECRET_KEY` 在 `DEBUG=False` 下强制 ≥50 字符（[hotel/settings.py:22-23](backend/hotel/settings.py#L22-L23)）。

生产口令下：

```bash
conda activate xiangmu && cd backend && DEBUG=False python manage.py check --deploy
# System check identified no issues (0 silenced).
```

若浏览器 HTTPS 前反代未传 `X-Forwarded-Proto` 会陷入重定向死循环——先在 nginx 侧确认再放开 `SECURE_SSL_REDIRECT`。

## 默认账号

| 角色 | 用户名 | 密码来源 |
|------|--------|----------|
| 管理员 | admin | `DEFAULT_ADMIN_PASSWORD` |
| 经理 | manager | `DEFAULT_MANAGER_PASSWORD` |
| 前台 | receptionist | `DEFAULT_RECEPTIONIST_PASSWORD` |

## 跨域配置

- 后端已配置 django-cors-headers，允许 http://localhost:5173 跨域访问
- 前端通过 Vite 代理将 /api 请求转发到 http://localhost:8000
- JWT Token 通过 Authorization: Bearer <token> 传递

## 功能模块

- **用户与权限管理**：多角色（管理员/经理/前台）、细粒度权限控制
- **客房管理**：房型管理、房间管理、房间状态流转
- **预订管理**：预订创建/确认/取消、可用房间查询
- **入住管理**：预订入住/散客入住、押金管理
- **退房管理**：自动费用计算、多种支付方式
- **财务管理**：账单明细、收款记录、日/月报表
- **客户管理**：客户信息、会员等级、入住历史、反馈评价
- **服务管理**：服务项目管理、服务请求处理
- **通知公告**：公告发布与管理

## 项目结构

```
hotel-management/
├── backend/                    # Django 后端
│   ├── hotel/                  # 项目配置
│   ├── apps/                   # 业务应用
│   │   ├── users/              # 用户与权限
│   │   ├── rooms/              # 客房管理
│   │   ├── reservations/       # 预订管理
│   │   ├── checkin/            # 入住管理
│   │   ├── checkout/           # 退房管理
│   │   ├── finance/            # 财务管理
│   │   ├── customers/          # 客户管理
│   │   ├── services/           # 服务管理
│   │   └── notifications/      # 通知公告
│   ├── utils/                  # 公共工具
│   └── requirements.txt
├── frontend/                   # Vue3 前端
│   ├── src/
│   │   ├── api/                # API 封装
│   │   ├── assets/             # 静态资源
│   │   ├── components/         # 公共组件
│   │   ├── layouts/            # 布局组件
│   │   ├── router/             # 路由配置
│   │   ├── stores/             # 状态管理
│   │   ├── views/              # 页面视图
│   │   └── utils/              # 工具函数
│   └── package.json
├── sql/
│   └── data.sql                # 初始数据（房型/服务/权限；表结构以 Django migrations 为准）
└── README.md
```