# 酒店数据管理系统 API 操作说明书

## 概述

本文档详细描述了酒店数据管理系统中 `hotel_positions`（酒店职位）和 `hotel_group_brands`（酒店集团品牌）两个数据表的完整CRUD操作API接口。

### 基础信息
- **API基础URL**: `/api/data-parse`
- **数据格式**: JSON
- **字符编码**: UTF-8
- **时间格式**: `YYYY-MM-DD HH:MM:SS`

### 通用返回格式
所有API接口都遵循统一的返回格式：
```json
{
    "code": 200,
    "success": true,
    "message": "操作成功信息",
    "data": "具体数据内容"
}
```

### HTTP状态码说明
| 状态码 | 含义 | 说明 |
|--------|------|------|
| 200 | OK | 请求成功 |
| 201 | Created | 资源创建成功 |
| 400 | Bad Request | 请求参数错误 |
| 404 | Not Found | 资源不存在 |
| 409 | Conflict | 资源冲突（重复） |
| 500 | Internal Server Error | 服务器内部错误 |

---

## 一、酒店职位管理 API (hotel_positions)

### 1.1 获取所有职位记录

#### 基本信息
- **URL**: `/get-hotel-positions-list`
- **方法**: `GET`
- **功能**: 获取酒店职位数据表的全部记录

#### 请求参数
无需请求参数

#### 响应参数
| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | integer | 响应状态码 |
| success | boolean | 操作是否成功 |
| message | string | 响应消息 |
| data | array | 职位记录数组 |
| count | integer | 记录总数 |

#### 职位记录字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | integer | 主键ID |
| department_zh | string | 部门中文名称 |
| department_en | string | 部门英文名称 |
| position_zh | string | 职位中文名称 |
| position_en | string | 职位英文名称 |
| position_abbr | string | 职位英文缩写（可为null） |
| level_zh | string | 职级中文名称 |
| level_en | string | 职级英文名称 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
| created_by | string | 创建者 |
| updated_by | string | 更新者 |
| status | string | 状态（active/inactive） |

#### 测试样例

**请求示例:**
```bash
GET /api/data-parse/get-hotel-positions-list
```

**成功响应示例:**
```json
{
    "code": 200,
    "success": true,
    "message": "获取酒店职位列表成功",
    "data": [
        {
            "id": 1,
            "department_zh": "餐饮部",
            "department_en": "Food & Beverage Department",
            "position_zh": "总经理",
            "position_en": "General Manager",
            "position_abbr": "GM",
            "level_zh": "总经理级",
            "level_en": "General Manager Level",
            "created_at": "2025-01-19 10:00:00",
            "updated_at": "2025-01-19 10:00:00",
            "created_by": "system",
            "updated_by": "system",
            "status": "active"
        }
    ],
    "count": 1
}
```

### 1.2 新增职位记录

#### 基本信息
- **URL**: `/add-hotel-positions`
- **方法**: `POST`
- **功能**: 新增酒店职位记录

#### 请求参数
| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| department_zh | string | 是 | 部门中文名称 |
| department_en | string | 是 | 部门英文名称 |
| position_zh | string | 是 | 职位中文名称 |
| position_en | string | 是 | 职位英文名称 |
| position_abbr | string | 否 | 职位英文缩写 |
| level_zh | string | 是 | 职级中文名称 |
| level_en | string | 是 | 职级英文名称 |
| created_by | string | 否 | 创建者（默认system） |
| updated_by | string | 否 | 更新者（默认system） |
| status | string | 否 | 状态（默认active） |

#### 响应参数
同职位记录字段说明

#### 测试样例

**请求示例:**
```bash
POST /api/data-parse/add-hotel-positions
Content-Type: application/json

{
    "department_zh": "餐饮部",
    "department_en": "Food & Beverage Department",
    "position_zh": "副总经理",
    "position_en": "Deputy General Manager",
    "position_abbr": "DGM",
    "level_zh": "总监级",
    "level_en": "Director Level",
    "created_by": "admin"
}
```

**成功响应示例:**
```json
{
    "code": 200,
    "success": true,
    "message": "酒店职位记录创建成功",
    "data": {
        "id": 151,
        "department_zh": "餐饮部",
        "department_en": "Food & Beverage Department",
        "position_zh": "副总经理",
        "position_en": "Deputy General Manager",
        "position_abbr": "DGM",
        "level_zh": "总监级",
        "level_en": "Director Level",
        "created_at": "2025-01-19 15:30:00",
        "updated_at": "2025-01-19 15:30:00",
        "created_by": "admin",
        "updated_by": "admin",
        "status": "active"
    }
}
```

**重复记录错误响应:**
```json
{
    "code": 409,
    "success": false,
    "message": "职位记录已存在：餐饮部 - 副总经理",
    "data": {
        "id": 100,
        "department_zh": "餐饮部",
        "position_zh": "副总经理",
        "..."
    }
}
```

### 1.3 更新职位记录

#### 基本信息
- **URL**: `/update-hotel-positions/<int:position_id>`
- **方法**: `PUT`
- **功能**: 更新指定ID的职位记录

#### 路径参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| position_id | integer | 职位记录ID |

#### 请求参数
| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| department_zh | string | 否 | 部门中文名称 |
| department_en | string | 否 | 部门英文名称 |
| position_zh | string | 否 | 职位中文名称 |
| position_en | string | 否 | 职位英文名称 |
| position_abbr | string | 否 | 职位英文缩写 |
| level_zh | string | 否 | 职级中文名称 |
| level_en | string | 否 | 职级英文名称 |
| updated_by | string | 否 | 更新者 |
| status | string | 否 | 状态 |

#### 测试样例

**请求示例:**
```bash
PUT /api/data-parse/update-hotel-positions/1
Content-Type: application/json

{
    "position_abbr": "AGM",
    "updated_by": "admin"
}
```

**成功响应示例:**
```json
{
    "code": 200,
    "success": true,
    "message": "酒店职位记录更新成功",
    "data": {
        "id": 1,
        "department_zh": "餐饮部",
        "department_en": "Food & Beverage Department",
        "position_zh": "总经理",
        "position_en": "General Manager",
        "position_abbr": "AGM",
        "level_zh": "总经理级",
        "level_en": "General Manager Level",
        "created_at": "2025-01-19 10:00:00",
        "updated_at": "2025-01-19 16:00:00",
        "created_by": "system",
        "updated_by": "admin",
        "status": "active"
    }
}
```

### 1.4 查询指定职位记录

#### 基本信息
- **URL**: `/query-hotel-positions/<int:position_id>`
- **方法**: `GET`
- **功能**: 根据ID查询指定职位记录

#### 路径参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| position_id | integer | 职位记录ID |

#### 测试样例

**请求示例:**
```bash
GET /api/data-parse/query-hotel-positions/1
```

**成功响应示例:**
```json
{
    "code": 200,
    "success": true,
    "message": "查找职位记录成功",
    "data": {
        "id": 1,
        "department_zh": "餐饮部",
        "department_en": "Food & Beverage Department",
        "position_zh": "总经理",
        "position_en": "General Manager",
        "position_abbr": "GM",
        "level_zh": "总经理级",
        "level_en": "General Manager Level",
        "created_at": "2025-01-19 10:00:00",
        "updated_at": "2025-01-19 15:45:00",
        "created_by": "system",
        "updated_by": "admin",
        "status": "active"
    }
}
```

**记录不存在响应:**
```json
{
    "code": 404,
    "success": false,
    "message": "未找到ID为999的职位记录",
    "data": null
}
```

### 1.5 删除职位记录

#### 基本信息
- **URL**: `/delete-hotel-positions/<int:position_id>`
- **方法**: `DELETE`
- **功能**: 删除指定ID的职位记录

#### 路径参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| position_id | integer | 职位记录ID |

#### 测试样例

**请求示例:**
```bash
DELETE /api/data-parse/delete-hotel-positions/1
```

**成功响应示例:**
```json
{
    "code": 200,
    "success": true,
    "message": "职位记录删除成功",
    "data": {
        "id": 1,
        "department_zh": "餐饮部",
        "department_en": "Food & Beverage Department",
        "position_zh": "总经理",
        "position_en": "General Manager",
        "position_abbr": "GM",
        "level_zh": "总经理级",
        "level_en": "General Manager Level",
        "created_at": "2025-01-19 10:00:00",
        "updated_at": "2025-01-19 15:45:00",
        "created_by": "system",
        "updated_by": "admin",
        "status": "active"
    }
}
```

---

## 二、酒店集团品牌管理 API (hotel_group_brands)

### 2.1 获取所有品牌记录

#### 基本信息
- **URL**: `/get-hotel-group-brands-list`
- **方法**: `GET`
- **功能**: 获取酒店集团品牌数据表的全部记录

#### 请求参数
无需请求参数

#### 响应参数
| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | integer | 响应状态码 |
| success | boolean | 操作是否成功 |
| message | string | 响应消息 |
| data | array | 品牌记录数组 |
| count | integer | 记录总数 |

#### 品牌记录字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | integer | 主键ID |
| group_name_en | string | 集团英文名称 |
| group_name_zh | string | 集团中文名称 |
| brand_name_en | string | 品牌英文名称 |
| brand_name_zh | string | 品牌中文名称 |
| positioning_level_en | string | 定位级别英文名称 |
| positioning_level_zh | string | 定位级别中文名称 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
| created_by | string | 创建者 |
| updated_by | string | 更新者 |
| status | string | 状态（active/inactive） |

#### 测试样例

**请求示例:**
```bash
GET /api/data-parse/get-hotel-group-brands-list
```

**成功响应示例:**
```json
{
    "code": 200,
    "success": true,
    "message": "获取酒店集团品牌列表成功",
    "data": [
        {
            "id": 1,
            "group_name_en": "IHG Hotels & Resorts",
            "group_name_zh": "洲际酒店集团",
            "brand_name_en": "InterContinental",
            "brand_name_zh": "洲际酒店及度假村",
            "positioning_level_en": "Upper Upscale",
            "positioning_level_zh": "超高端",
            "created_at": "2025-01-19 10:00:00",
            "updated_at": "2025-01-19 10:00:00",
            "created_by": "system",
            "updated_by": "system",
            "status": "active"
        }
    ],
    "count": 1
}
```

### 2.2 新增品牌记录

#### 基本信息
- **URL**: `/add-hotel-group-brands`
- **方法**: `POST`
- **功能**: 新增酒店集团品牌记录

#### 请求参数
| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| group_name_en | string | 是 | 集团英文名称 |
| group_name_zh | string | 是 | 集团中文名称 |
| brand_name_en | string | 是 | 品牌英文名称 |
| brand_name_zh | string | 是 | 品牌中文名称 |
| positioning_level_en | string | 是 | 定位级别英文名称 |
| positioning_level_zh | string | 是 | 定位级别中文名称 |
| created_by | string | 否 | 创建者（默认system） |
| updated_by | string | 否 | 更新者（默认system） |
| status | string | 否 | 状态（默认active） |

#### 测试样例

**请求示例:**
```bash
POST /api/data-parse/add-hotel-group-brands
Content-Type: application/json

{
    "group_name_en": "Marriott International",
    "group_name_zh": "万豪国际",
    "brand_name_en": "The Ritz-Carlton",
    "brand_name_zh": "丽思卡尔顿",
    "positioning_level_en": "Luxury",
    "positioning_level_zh": "奢华型",
    "created_by": "admin"
}
```

**成功响应示例:**
```json
{
    "code": 200,
    "success": true,
    "message": "酒店集团品牌记录创建成功",
    "data": {
        "id": 296,
        "group_name_en": "Marriott International",
        "group_name_zh": "万豪国际",
        "brand_name_en": "The Ritz-Carlton",
        "brand_name_zh": "丽思卡尔顿",
        "positioning_level_en": "Luxury",
        "positioning_level_zh": "奢华型",
        "created_at": "2025-01-19 16:00:00",
        "updated_at": "2025-01-19 16:00:00",
        "created_by": "admin",
        "updated_by": "admin",
        "status": "active"
    }
}
```

**重复记录错误响应:**
```json
{
    "code": 409,
    "success": false,
    "message": "品牌记录已存在：万豪国际 - 丽思卡尔顿",
    "data": {
        "id": 200,
        "group_name_zh": "万豪国际",
        "brand_name_zh": "丽思卡尔顿",
        "..."
    }
}
```

### 2.3 更新品牌记录

#### 基本信息
- **URL**: `/update-hotel-group-brands/<int:brand_id>`
- **方法**: `PUT`
- **功能**: 更新指定ID的品牌记录

#### 路径参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| brand_id | integer | 品牌记录ID |

#### 请求参数
| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| group_name_en | string | 否 | 集团英文名称 |
| group_name_zh | string | 否 | 集团中文名称 |
| brand_name_en | string | 否 | 品牌英文名称 |
| brand_name_zh | string | 否 | 品牌中文名称 |
| positioning_level_en | string | 否 | 定位级别英文名称 |
| positioning_level_zh | string | 否 | 定位级别中文名称 |
| updated_by | string | 否 | 更新者 |
| status | string | 否 | 状态 |

#### 测试样例

**请求示例:**
```bash
PUT /api/data-parse/update-hotel-group-brands/1
Content-Type: application/json

{
    "positioning_level_en": "Luxury",
    "positioning_level_zh": "奢华型",
    "updated_by": "admin"
}
```

**成功响应示例:**
```json
{
    "code": 200,
    "success": true,
    "message": "酒店集团品牌记录更新成功",
    "data": {
        "id": 1,
        "group_name_en": "IHG Hotels & Resorts",
        "group_name_zh": "洲际酒店集团",
        "brand_name_en": "InterContinental",
        "brand_name_zh": "洲际酒店及度假村",
        "positioning_level_en": "Luxury",
        "positioning_level_zh": "奢华型",
        "created_at": "2025-01-19 10:00:00",
        "updated_at": "2025-01-19 16:30:00",
        "created_by": "system",
        "updated_by": "admin",
        "status": "active"
    }
}
```

### 2.4 查询指定品牌记录

#### 基本信息
- **URL**: `/query-hotel-group-brands/<int:brand_id>`
- **方法**: `GET`
- **功能**: 根据ID查询指定品牌记录

#### 路径参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| brand_id | integer | 品牌记录ID |

#### 测试样例

**请求示例:**
```bash
GET /api/data-parse/query-hotel-group-brands/1
```

**成功响应示例:**
```json
{
    "code": 200,
    "success": true,
    "message": "查找品牌记录成功",
    "data": {
        "id": 1,
        "group_name_en": "IHG Hotels & Resorts",
        "group_name_zh": "洲际酒店集团",
        "brand_name_en": "InterContinental",
        "brand_name_zh": "洲际酒店及度假村",
        "positioning_level_en": "Upper Upscale",
        "positioning_level_zh": "超高端",
        "created_at": "2025-01-19 10:00:00",
        "updated_at": "2025-01-19 16:30:00",
        "created_by": "system",
        "updated_by": "admin",
        "status": "active"
    }
}
```

**记录不存在响应:**
```json
{
    "code": 404,
    "success": false,
    "message": "未找到ID为999的品牌记录",
    "data": null
}
```

### 2.5 删除品牌记录

#### 基本信息
- **URL**: `/delete-hotel-group-brands/<int:brand_id>`
- **方法**: `DELETE`
- **功能**: 删除指定ID的品牌记录

#### 路径参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| brand_id | integer | 品牌记录ID |

#### 测试样例

**请求示例:**
```bash
DELETE /api/data-parse/delete-hotel-group-brands/1
```

**成功响应示例:**
```json
{
    "code": 200,
    "success": true,
    "message": "品牌记录删除成功",
    "data": {
        "id": 1,
        "group_name_en": "IHG Hotels & Resorts",
        "group_name_zh": "洲际酒店集团",
        "brand_name_en": "InterContinental",
        "brand_name_zh": "洲际酒店及度假村",
        "positioning_level_en": "Upper Upscale",
        "positioning_level_zh": "超高端",
        "created_at": "2025-01-19 10:00:00",
        "updated_at": "2025-01-19 16:30:00",
        "created_by": "system",
        "updated_by": "admin",
        "status": "active"
    }
}
```

---

## 三、错误处理

### 3.1 常见错误场景

#### 缺少必填字段
```json
{
    "code": 400,
    "success": false,
    "message": "缺少必填字段: department_zh, position_zh",
    "data": null
}
```

#### 记录不存在
```json
{
    "code": 404,
    "success": false,
    "message": "未找到ID为999的职位记录",
    "data": null
}
```

#### 记录重复冲突
```json
{
    "code": 409,
    "success": false,
    "message": "职位记录已存在：餐饮部 - 总经理",
    "data": {
        "id": 1,
        "department_zh": "餐饮部",
        "position_zh": "总经理",
        "..."
    }
}
```

#### 服务器内部错误
```json
{
    "code": 500,
    "success": false,
    "message": "创建酒店职位记录失败: 数据库连接超时",
    "data": null
}
```

### 3.2 错误处理建议

1. **检查HTTP状态码**: 首先检查HTTP响应状态码
2. **解析响应JSON**: 获取详细的错误信息
3. **根据code字段处理**: 根据响应中的code字段进行相应处理
4. **显示用户友好错误信息**: 将技术错误转换为用户可理解的提示

---

## 四、最佳实践

### 4.1 API调用建议

1. **设置合适的超时时间**: 建议设置30秒的请求超时
2. **处理网络异常**: 实现重试机制，最多重试3次
3. **验证输入参数**: 在发送请求前验证必填字段
4. **缓存查询结果**: 对于列表查询，可以实现客户端缓存

### 4.2 数据处理建议

1. **字符串去除空格**: 所有字符串字段会自动去除前后空格
2. **唯一性检查**: 
   - 职位表：基于部门中文名称+职位中文名称
   - 品牌表：基于集团中文名称+品牌中文名称
3. **状态管理**: 记录状态默认为"active"，可设置为"inactive"进行软删除

### 4.3 安全建议

1. **输入验证**: 所有输入都会进行服务端验证
2. **SQL注入防护**: 使用ORM框架防止SQL注入
3. **日志记录**: 所有操作都会记录详细日志
4. **权限控制**: 建议在业务层实现用户权限验证

---

## 五、测试工具推荐

### 5.1 Postman测试集合

可以导入以下Postman集合来快速测试所有API接口：

```json
{
    "info": {
        "name": "酒店数据管理API",
        "description": "酒店职位和集团品牌管理API测试集合"
    },
    "item": [
        {
            "name": "获取所有职位",
            "request": {
                "method": "GET",
                "url": "{{baseUrl}}/api/data-parse/get-hotel-positions-list"
            }
        },
        {
            "name": "新增职位",
            "request": {
                "method": "POST",
                "url": "{{baseUrl}}/api/data-parse/add-hotel-positions",
                "header": [
                    {
                        "key": "Content-Type",
                        "value": "application/json"
                    }
                ],
                "body": {
                    "raw": "{\n    \"department_zh\": \"餐饮部\",\n    \"department_en\": \"Food & Beverage Department\",\n    \"position_zh\": \"副总经理\",\n    \"position_en\": \"Deputy General Manager\",\n    \"position_abbr\": \"DGM\",\n    \"level_zh\": \"总监级\",\n    \"level_en\": \"Director Level\"\n}"
                }
            }
        }
    ]
}
```

### 5.2 cURL命令示例

#### 获取职位列表
```bash
curl -X GET "http://localhost:5000/api/data-parse/get-hotel-positions-list" \
  -H "Content-Type: application/json"
```

#### 新增职位记录
```bash
curl -X POST "http://localhost:5000/api/data-parse/add-hotel-positions" \
  -H "Content-Type: application/json" \
  -d '{
    "department_zh": "餐饮部",
    "department_en": "Food & Beverage Department",
    "position_zh": "副总经理",
    "position_en": "Deputy General Manager",
    "position_abbr": "DGM",
    "level_zh": "总监级",
    "level_en": "Director Level"
  }'
```

---

## 附录

### A. 数据字典

#### A.1 部门列表（参考）
- 餐饮部 / Food & Beverage Department
- 房务部 / Housekeeping Department
- 市场销售部 / Sales & Marketing Department
- 人力资源部 / Human Resources Department
- 财务部 / Finance Department
- 行政办公室 / Administrative Office
- 工程部 / Engineering Department
- 水疗部 / Spa Department
- 保安部 / Security Department

#### A.2 职级列表（参考）
- 经理级 / Manager Level
- 总监级 / Director Level
- 总经理级 / General Manager Level

#### A.3 定位级别列表（参考）
- 奢华型 / Luxury
- 超高端 / Upper Upscale
- 高端 / Upscale
- 中高端 / Upper Midscale
- 中端 / Midscale
- 经济型 / Economy

### B. 版本历史

| 版本 | 日期 | 修改内容 | 作者 |
|------|------|----------|------|
| 1.0 | 2025-01-19 | 初始版本，包含完整CRUD API | 系统 |

---

**文档结束**

> 如有疑问或需要技术支持，请联系开发团队。