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

概述

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

基础信息

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

通用返回格式

所有API接口都遵循统一的返回格式：

{
    "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）

测试样例

请求示例:

GET /api/data-parse/get-hotel-positions-list

成功响应示例:

{
    "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）

响应参数

同职位记录字段说明

测试样例

请求示例:

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"
}

成功响应示例:

{
    "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"
    }
}

重复记录错误响应:

{
    "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	否	状态

测试样例

请求示例:

PUT /api/data-parse/update-hotel-positions/1
Content-Type: application/json

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

成功响应示例:

{
    "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

测试样例

请求示例:

GET /api/data-parse/query-hotel-positions/1

成功响应示例:

{
    "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"
    }
}

记录不存在响应:

{
    "code": 404,
    "success": false,
    "message": "未找到ID为999的职位记录",
    "data": null
}

1.5 删除职位记录

基本信息

URL: /delete-hotel-positions/<int:position_id>
方法: DELETE
功能: 删除指定ID的职位记录

路径参数

参数名	类型	说明
position_id	integer	职位记录ID

测试样例

请求示例:

DELETE /api/data-parse/delete-hotel-positions/1

成功响应示例:

{
    "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）

测试样例

请求示例:

GET /api/data-parse/get-hotel-group-brands-list

成功响应示例:

{
    "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）

测试样例

请求示例:

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"
}

成功响应示例:

{
    "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"
    }
}

重复记录错误响应:

{
    "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	否	状态

测试样例

请求示例:

PUT /api/data-parse/update-hotel-group-brands/1
Content-Type: application/json

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

成功响应示例:

{
    "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

测试样例

请求示例:

GET /api/data-parse/query-hotel-group-brands/1

成功响应示例:

{
    "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"
    }
}

记录不存在响应:

{
    "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

测试样例

请求示例:

DELETE /api/data-parse/delete-hotel-group-brands/1

成功响应示例:

{
    "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 常见错误场景

缺少必填字段

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

记录不存在

{
    "code": 404,
    "success": false,
    "message": "未找到ID为999的职位记录",
    "data": null
}

记录重复冲突

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

服务器内部错误

{
    "code": 500,
    "success": false,
    "message": "创建酒店职位记录失败: 数据库连接超时",
    "data": null
}

3.2 错误处理建议

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

四、最佳实践

4.1 API调用建议

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

4.2 数据处理建议

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

4.3 安全建议

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

五、测试工具推荐

5.1 Postman测试集合

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

{
    "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命令示例

获取职位列表

curl -X GET "http://localhost:5000/api/data-parse/get-hotel-positions-list" \
  -H "Content-Type: application/json"

新增职位记录

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	系统

文档结束

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

酒店职位和品牌_API使用手册.md 21 KB Cronologia Originale

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

概述

基础信息

通用返回格式

HTTP状态码说明

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

1.1 获取所有职位记录

基本信息

请求参数

响应参数

职位记录字段说明

测试样例

1.2 新增职位记录

基本信息

请求参数

响应参数

测试样例

1.3 更新职位记录

基本信息

路径参数

请求参数

测试样例

1.4 查询指定职位记录

基本信息

路径参数

测试样例

1.5 删除职位记录

基本信息

路径参数

测试样例

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

2.1 获取所有品牌记录

基本信息

请求参数

响应参数

品牌记录字段说明

测试样例

2.2 新增品牌记录

基本信息

请求参数

测试样例

2.3 更新品牌记录

基本信息

路径参数

请求参数

测试样例

2.4 查询指定品牌记录

基本信息

路径参数

测试样例

2.5 删除品牌记录

基本信息

路径参数

测试样例

三、错误处理

3.1 常见错误场景

缺少必填字段

记录不存在

记录重复冲突

服务器内部错误

3.2 错误处理建议

四、最佳实践

4.1 API调用建议

4.2 数据处理建议

4.3 安全建议

五、测试工具推荐

5.1 Postman测试集合

5.2 cURL命令示例

获取职位列表

新增职位记录

附录

A. 数据字典

A.1 部门列表（参考）

A.2 职级列表（参考）

A.3 定位级别列表（参考）

B. 版本历史

酒店职位和品牌_API使用手册.md 21 KB

Cronologia Originale