xinyin025/RuoYi-Vue-Plus
1
0
Fork 0
mirror of https://github.com/dromara/RuoYi-Vue-Plus.git synced 2025-11-16 14:13:45 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

更新子模块 ruoyi-plus-soybean 的路径和远程仓库地址。

Browse Source
This commit is contained in:
Xuhf
2025-05-23 10:11:42 +08:00
parent eed5a226f9
commit 049934932d
775 changed files with 84371 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
docs/GIT_MANUAL.md Normal file
View File

@@ -0,0 +1,107 @@
# RuoYi-Vue-Plus 多仓库 Git 管理手册
## 目录
1. [项目架构说明](#项目架构说明)
2. [初始化设置](#初始化设置)
3. [日常操作流程](#日常操作流程)
4. [冲突处理](#冲突处理)
5. [命令速查表](#命令速查表)
6. [注意事项](#注意事项)
## 项目架构说明
- **主仓库**：`ruoyi-vue-plus`
- 同步源：`https://github.com/dromara/RuoYi-Vue-Plus`
- 推送目标：`https://github.com/figo990/RuoYi-Vue-Plus`
- **子模块**：`ruoyi-plus-soybean`
- 同步源：`https://gitee.com/xlsea/ruoyi-plus-soybean`
- 与主仓库一起推送到 `figo990/RuoYi-Vue-Plus`
## 初始化设置
```bash
# 1. 克隆主仓库
git clone https://github.com/figo990/RuoYi-Vue-Plus.git ruoyi-vue-plus
cd ruoyi-vue-plus
# 2. 添加官方仓库为上游源
git remote add upstream https://github.com/dromara/RuoYi-Vue-Plus.git
# 3. 初始化子模块
git submodule add https://gitee.com/xlsea/ruoyi-plus-soybean.git ruoyi-plus-soybean
```
## 日常操作流程
### 同步主仓库更新
```bash
git fetch upstream
git merge upstream/main
git push origin main
```
### 同步子模块更新
```bash
cd ruoyi-plus-soybean
git pull origin main
cd ..
git add ruoyi-plus-soybean
git commit -m "Update submodule"
git push origin main
```
### 提交本地修改
```bash
# 修改主仓库
git add .
git commit -m "修改说明"
git push origin main
# 修改子模块
cd ruoyi-plus-soybean
git add .
git commit -m "子模块修改说明"
git push origin main
cd ..
git add ruoyi-plus-soybean
git commit -m "更新子模块引用"
git push origin main
```
## 冲突处理
### 主仓库冲突
```bash
git fetch upstream
git merge upstream/main
# 手动解决冲突后
git add .
git commit -m "解决冲突"
git push origin main
```
### 子模块冲突
```bash
cd ruoyi-plus-soybean
git pull origin main
# 手动解决冲突后
git add .
git commit -m "解决子模块冲突"
git push origin main
cd ..
git add ruoyi-plus-soybean
git commit -m "更新子模块引用"
git push origin main
```
## 命令速查表
| 操作 | 命令 |
| -------------- | ----------------------------------------------------------------------------------- |
| 拉取官方更新 | `git fetch upstream && git merge upstream/main` |
| 推送主仓库修改 | `git add . && git commit -m "msg" && git push origin main` |
| 更新子模块 | `cd ruoyi-plus-soybean && git pull origin main` |
| 提交子模块修改 | `cd ruoyi-plus-soybean && git add . && git commit -m "msg" && git push origin main` |
## 注意事项
1. 首次克隆后需初始化子模块：
```bash
git submodule update --init --recursive
```
2. 子模块修改需单独提交到其仓库
3. 保持主仓库和子模块分支一致（推荐使用`main`分支）

754
docs/basic/PMS数据模型.md Normal file
View File

@@ -0,0 +1,754 @@
## 云宿居 PMS 系统 - PMS核心数据模型 (最终版 v_ry_final_4.0)
**快速导航：**
- [1. 引言](#1-引言)
- [2. PMS 核心E-R图 (最终版 - 简化)](#2-pms-核心er图-最终版---简化)
- [3. 表结构定义](#3-表结构定义)
- [3.1 SaaS平台与系统基础表 (源自若依)](#31-saas平台与系统基础表-源自若依)
- [3.2 PMS核心业务表](#32-pms核心业务表)
- [3.3 公共数据模型 (PMS相关)](#33-公共数据模型-pms相关)
- [4. 主要业务实体状态流转](#4-主要业务实体状态流转)
- [5. 核心业务枚举值定义 (PMS主要部分)](#5-核心业务枚举值定义-pms主要部分)
- [6. 索引命名与规范建议](#6-索引命名与规范建议)
## 1. 引言
### 1.1 文档目的与范围
本文档详细定义了"云宿居"民宿 Property Management System (PMS) 的数据库逻辑模型，并与其依赖的若依框架的基础表（如租户、用户、部门等）进行了整合。本文档旨在为数据库的物理实现和后端开发提供具体指导。
**核心原则：**
1. 若依框架的基础实体（用户、租户、角色、部门等）及其字段规范固定不变。
2. PMS新增的核心业务表主键统一采用 `BIGINT` 自增ID。
3. **PMS业务表只关联部门(`dept_id`)，不直接关联租户(`tenant_id`)。部门代表实际的门店/分店，通过部门可以查询到其所属租户信息。** 这使得"一个租户下有多个门店"的业务模型更加清晰，同时减少数据冗余。
4. **特例：`pms_tenant_settings`和`pms_mp_settings`表保留tenant_id字段，通过dept_id为NULL来表示租户全局设置，通过具体的dept_id值表示部门/门店特定设置。**
5. PMS业务表中的枚举字段，统一使用 `VARCHAR(50)` 存储描述性字符串以增强可读性和扩展性。这与若依常用的 `CHAR(1)` 枚举在交互时需注意API层面的适配。
### 1.2 命名与设计约定 (PMS新增表部分)
* **表命名:** `pms_` (PMS核心业务表)，`cmn_` (公共模块)。若依表使用其原生 `sys_` 前缀。
* **字段命名:** `snake_case` (小写下划线)。
* **主键 (PK):**
* PMS核心业务实体: **`BIGINT` AUTO_INCREMENT**。
* 日志类高频写入表: `BIGINT` AUTO_INCREMENT。
* **部门ID `dept_id`:** `bigint(20)` (同 `sys_dept.dept_id`)，在PMS业务表中非空，用于标识数据归属于哪个门店。
* **外键 (FK):** 类型与关联表主键一致。`COMMENT '关联 table_name.column_name'`。
* **通用审计字段 (对齐若依):**
* `create_by` (BIGINT(20) NULLABLE, COMMENT '创建者，关联 sys_user.user_id')
* `create_time` (DATETIME NULLABLE, COMMENT '创建时间')
* `update_by` (BIGINT(20) NULLABLE, COMMENT '更新者，关联 sys_user.user_id')
* `update_time` (DATETIME NULLABLE, COMMENT '更新时间')
* `create_dept_id` (BIGINT(20) NULLABLE, COMMENT '创建记录的操作员所属部门，关联 sys_dept.dept_id')
* **软删除策略 (对齐若依):**
* `del_flag` (CHAR(1) DEFAULT '0' NOT NULL, COMMENT '删除标志（0代表存在 1代表删除）')。
* **状态与枚举字段 (PMS优化):**
* PMS业务表中的枚举字段，统一使用 `VARCHAR(50)` 存储描述性枚举字符串。
## 2. PMS 核心E-R图 (最终版 - 简化)
```mermaid
erDiagram
%% --- 若依基础表 (关键部分) ---
sys_tenant {
varchar(20) tenant_id PK "租户编号 (业务主键)"
bigint id "物理主键, 若依内部使用"
varchar(255) company_name "企业/民宿名称"
}
sys_dept {
bigint dept_id PK "部门ID"
varchar(20) tenant_id FK "关联 sys_tenant.tenant_id"
varchar(30) dept_name "部门名称"
}
sys_user {
bigint user_id PK "用户ID (PMS员工)"
varchar(20) tenant_id FK "用户初始归属租户"
bigint dept_id FK "用户所属部门"
varchar(30) user_name "用户名, 全局唯一"
}
sys_role {
bigint role_id PK "角色ID"
varchar(20) tenant_id FK "角色定义所属租户 (或平台)"
varchar(30) role_name "角色名称"
}
%% --- Common Contact Table ---
cmn_contacts {
BIGINT contact_id PK "联系人ID (自增)"
BIGINT dept_id FK "所属部门ID"
VARCHAR(255) full_name "姓名"
}
%% --- PMS Core Business Tables (主键改为BIGINT) ---
pms_room_types {
BIGINT room_type_id PK "房型ID (自增)"
BIGINT dept_id FK "部门ID"
VARCHAR(255) name "房型名称"
}
pms_room_rooms {
BIGINT room_id PK "房间ID (自增)"
BIGINT dept_id FK "部门ID"
BIGINT room_type_id FK "房型ID"
VARCHAR(255) room_number "房间号"
VARCHAR(50) room_status "物理状态"
VARCHAR(50) cleaning_status "清洁状态"
}
pms_room_locks {
BIGINT lock_id PK "锁定ID (自增)"
BIGINT dept_id FK "部门ID"
BIGINT room_id FK "房间ID"
}
pms_core_orders {
BIGINT order_id PK "订单ID (自增)"
BIGINT dept_id FK "部门ID"
BIGINT contact_id FK "联系人ID"
BIGINT room_type_id FK "房型ID"
BIGINT pms_room_id FK "房间ID(可空)"
VARCHAR(50) order_status "订单状态"
VARCHAR(50) order_source "订单来源"
}
pms_core_order_items {
BIGINT order_item_id PK "订单项ID (自增)"
BIGINT order_id FK "订单ID"
BIGINT dept_id FK "部门ID"
VARCHAR(50) product_type "产品类型"
}
pms_core_channels {
BIGINT channel_id PK "渠道ID (自增)"
BIGINT dept_id FK "部门ID(可空)"
VARCHAR(50) channel_type "渠道类型"
}
pms_finance_folios {
BIGINT folio_id PK "账单ID (自增)"
BIGINT dept_id FK "部门ID"
BIGINT order_id FK "订单ID(UNIQUE)"
VARCHAR(50) folio_status "账单状态"
}
pms_finance_transactions {
BIGINT transaction_id PK "交易ID (自增)"
BIGINT folio_id FK "账单ID"
BIGINT dept_id FK "部门ID"
VARCHAR(50) transaction_type "交易类型"
}
pms_finance_payment_methods {
BIGINT payment_method_id PK "支付方式ID (自增)"
BIGINT dept_id FK "部门ID"
VARCHAR(50) method_type "支付方式类型"
}
pms_finance_extra_charge_items {
BIGINT item_id PK "附加费用项ID (自增)"
BIGINT dept_id FK "部门ID"
}
pms_room_pricing_rules {
BIGINT rule_id PK "价格规则ID (自增)"
BIGINT dept_id FK "部门ID"
BIGINT room_type_id FK "房型ID(可空)"
}
pms_tenant_settings {
BIGINT setting_id PK "设置ID (自增)"
BIGINT dept_id FK "部门ID"
VARCHAR(100) setting_group "设置分组"
VARCHAR(100) setting_key "设置键名"
}
pms_mp_settings {
BIGINT setting_id PK "小程序设置ID (自增)"
BIGINT dept_id FK "部门ID"
VARCHAR(100) setting_key "设置键名"
}
pms_tenant_user_devices {
BIGINT id PK "设备记录ID (自增)"
BIGINT user_id FK "用户ID"
}
cmn_contact_tags {
BIGINT tag_id PK "标签ID (自增)"
BIGINT dept_id FK "部门ID"
}
cmn_contact_tag_relations {
BIGINT relation_id PK "关联ID (自增)"
BIGINT contact_id FK "联系人ID"
BIGINT tag_id FK "标签ID"
}
%% --- 若依基础表关联 ---
sys_tenant ||--o{ sys_dept : "包含门店/部门"
sys_tenant ||--o{ sys_user : "的主要租户"
sys_tenant ||--o{ sys_role : "定义角色归属"
sys_dept ||--o{ sys_user : "员工属于门店"
%% --- PMS 表关联到若依基础表 ---
sys_dept ||--o{ pms_room_types : "定义房型"
sys_dept ||--o{ pms_room_rooms : "拥有房间"
sys_dept ||--o{ pms_core_orders : "拥有订单"
sys_dept ||--o{ cmn_contacts : "拥有联系人"
sys_dept ||--o{ pms_tenant_settings : "拥有PMS配置"
sys_dept ||--o{ pms_mp_settings : "拥有小程序配置"
sys_dept ||--o{ cmn_contact_tags : "定义联系人标签"
sys_user ||--o{ pms_tenant_user_devices : "注册设备"
%% --- PMS 内部表关联 ---
pms_room_types ||--o{ pms_room_rooms : "有具体房间"
pms_room_types ||--o{ pms_core_orders : "被预订类型"
pms_room_types o|--o{ pms_room_pricing_rules : "规则适用房型"
pms_room_rooms ||--o{ pms_room_locks : "可被锁定"
pms_room_rooms o|--o{ pms_core_orders : "被分配房间"
pms_room_rooms o|--o{ pms_core_order_items : "关联房晚项目"
pms_core_orders ||--o{ pms_core_order_items : "包含项目"
pms_core_orders ||--|| pms_finance_folios : "生成账单"
cmn_contacts o|--o{ pms_core_orders : "是主要联系人"
pms_core_channels o|--o{ pms_core_orders : "是来源渠道"
pms_finance_folios ||--o{ pms_finance_transactions : "记录交易"
pms_finance_payment_methods o|--o{ pms_finance_transactions : "使用支付方式"
pms_finance_extra_charge_items o|--o{ pms_core_order_items : "可以是附加项"
cmn_contacts ||--o{ cmn_contact_tag_relations : "关联标签"
cmn_contact_tags ||--o{ cmn_contact_tag_relations : "被应用于"
```
*注：E-R图中部分表的字段为简化表示，详细字段请参照下文。*
## 3. 表结构定义
### 3.1 SaaS平台与系统基础表 (源自若依)
这些表结构直接采用或参考附件 `ry_vue_5.X - 副本.txt` 中的定义，关键表包括：
* `sys_tenant`: 租户表 (业务主键 `tenant_id varchar(20)`)
* `sys_dept`: 部门表 (主键 `dept_id bigint(20)`)，在本系统中将作为门店/分店使用
* `sys_user`: 用户信息表 (主键 `user_id bigint(20)`)
* `sys_role`: 角色信息表 (主键 `role_id bigint(20)`)
* `sys_user_role`: 用户角色关联表
* `sys_config`: 参数配置表
* `sys_logininfor`: 系统访问记录（登录日志）
* `sys_dict_type`, `sys_dict_data`: 字典表 (PMS枚举值优先在PMS表中使用 `VARCHAR(50)`，但若依系统本身的字典可按其规范使用)
**PMS系统将直接使用或关联这些若依表中的记录，例如PMS订单的 `dept_id` 将关联到 `sys_dept.dept_id`，`create_by` 将关联到 `sys_user.user_id`。部门进一步通过 `sys_dept.tenant_id` 关联到租户。**
### 3.2 PMS核心业务表
#### 3.2.1 `pms_room_types` - 房型表
* 业务描述: 存储各部门(门店)定义的房型信息。
* 主键: `room_type_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `room_type_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '房型唯一ID'): 主键。
* `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID(门店), 关联 sys_dept.dept_id')。
* `name` (VARCHAR(255), NOT NULL, COMMENT '房型名称 (例如: 豪华大床房)')。
* `default_price` (DECIMAL(10,2), NOT NULL, COMMENT '房型默认价格 (每晚)')。
* `capacity` (INT, NOT NULL, COMMENT '标准入住人数')。
* `amenities` (JSON, NULLABLE, COMMENT '房型设施标签。JSON数组，例如 [\"wifi\", \"空调\"]')。
* `description` (TEXT, NULLABLE, COMMENT '房型描述')。
* `images_json` (JSON, NULLABLE, COMMENT '房型图片。JSON数组')。
* `sort_order` (INT, DEFAULT 0, COMMENT '显示排序值')。
* `status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '状态。枚举: active (启用), inactive (禁用)')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 索引: `idx_pms_rt_dept_name` (dept_id, name), `idx_pms_rt_dept_status` (dept_id, status)
#### 3.2.2 `pms_room_rooms` - 房间表
* 业务描述: 存储各部门(门店)的具体房间信息。
* 主键: `room_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `room_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '房间唯一ID')。
* `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID(门店), 关联 sys_dept.dept_id')。
* `room_type_id` (BIGINT, FK, NOT NULL, COMMENT '所属房型ID, 关联 pms_room_types.room_type_id')。
* `room_number` (VARCHAR(50), NOT NULL, COMMENT '房间号 (在门店内应唯一)')。
* `floor` (VARCHAR(50), NULLABLE, COMMENT '楼层')。
* `room_status` (VARCHAR(50), NOT NULL, DEFAULT 'available', COMMENT '物理状态。枚举: available (可用), occupied (占用中), maintenance (维护中), out_of_service (停用服务)')。
* `cleaning_status` (VARCHAR(50), NOT NULL, DEFAULT 'clean', COMMENT '清洁状态。枚举: clean (已清洁), dirty (待清洁), cleaning_in_progress (清洁中), inspected (已查房)')。
* `description` (TEXT, NULLABLE, COMMENT '房间描述或备注')。
* `status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '记录状态。枚举: active (启用), inactive (禁用)')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 唯一约束: `unq_pms_r_dept_room_number` (dept_id, room_number, del_flag)
* 索引: `idx_pms_r_dept_rt` (dept_id, room_type_id), `idx_pms_r_dept_room_status` (dept_id, room_status), `idx_pms_r_dept_cleaning_status` (dept_id, cleaning_status)
#### 3.2.3 `pms_room_locks` - 房间锁定记录表
* 业务描述: 记录房间因维护、手动操作等原因被锁定的情况。
* 主键: `lock_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `lock_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '锁定记录唯一ID')。
* `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID, 关联 sys_dept.dept_id')。
* `room_id` (BIGINT, FK, NOT NULL, COMMENT '被锁定的房间ID, 关联 pms_room_rooms.room_id')。
* `start_datetime` (DATETIME, NOT NULL, COMMENT '锁定开始时间')。
* `end_datetime` (DATETIME, NOT NULL, COMMENT '锁定结束时间')。
* `reason` (TEXT, NULLABLE, COMMENT '锁定原因')。
* `lock_type` (VARCHAR(50), NOT NULL, DEFAULT 'manual_lock', COMMENT '锁定类型。枚举: manual_lock (手动锁定), maintenance (维护), auto_block (自动锁定), staff_use (员工自用)')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 索引: `idx_pms_rl_tenant_dept_room_time` (tenant_id, dept_id, room_id, start_datetime, end_datetime), `idx_pms_rl_tenant_dept_lock_type` (tenant_id, dept_id, lock_type)
#### 3.2.4 `pms_core_orders` - 核心订单表
* 业务描述: 存储所有来源的预订订单核心信息。
* 主键: `order_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `order_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '订单唯一ID')。
* `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID, 关联 sys_dept.dept_id')。
* `contact_id` (BIGINT, FK, NULLABLE, COMMENT '主要联系人ID, 关联 cmn_contacts.contact_id')。
* `primary_contact_name` (VARCHAR(100), NOT NULL, COMMENT '主要联系人姓名 (冗余)')。
* `primary_contact_phone` (VARCHAR(50), NOT NULL, COMMENT '主要联系人电话 (冗余)')。
* `pms_room_id` (BIGINT, FK, NULLABLE, COMMENT '分配的房间ID, 关联 pms_room_rooms.room_id, 入住时分配')。
* `room_type_id` (BIGINT, FK, NOT NULL, COMMENT '预订的房型ID, 关联 pms_room_types.room_type_id')。
* `channel_id` (BIGINT, FK, NULLABLE, COMMENT '订单来源渠道ID, 关联 pms_core_channels.channel_id')。
* `check_in_date` (DATE, NOT NULL, COMMENT '计划入住日期')。
* `check_out_date` (DATE, NOT NULL, COMMENT '计划离店日期')。
* `num_adults` (INT, NOT NULL, DEFAULT 1, COMMENT '成人数')。
* `num_children` (INT, DEFAULT 0, COMMENT '儿童数')。
* `estimated_arrival_time` (TIME, NULLABLE, COMMENT '预计抵达时间')。
* `total_amount` (DECIMAL(10,2), NOT NULL, COMMENT '订单总金额')。
* `paid_amount` (DECIMAL(10,2), DEFAULT 0.00, COMMENT '已付金额')。
* `due_amount` (DECIMAL(10,2), AS (`total_amount` - `paid_amount`)) STORED COMMENT '应付金额 (计算列)'。
* `currency` (VARCHAR(3), NOT NULL, DEFAULT 'CNY', COMMENT '货币代码')。
* `order_status` (VARCHAR(50), NOT NULL, COMMENT '订单状态。枚举: pending_confirmation, confirmed, checked_in, checked_out, cancelled, no_show, extended, waitlist')。
* `order_source` (VARCHAR(50), NOT NULL, COMMENT '订单来源。枚举: direct_walk_in, direct_phone, direct_website, direct_mall_h5, ota_channel_manager, travel_agency, corporate, other')。
* `notes` (TEXT, NULLABLE, COMMENT '订单备注')。
* `cancelled_at` (DATETIME, NULLABLE, COMMENT '取消时间')。
* `cancellation_reason` (TEXT, NULLABLE, COMMENT '取消原因')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 索引: `idx_pms_o_tenant_dept_status_dates` (tenant_id, dept_id, order_status, check_in_date, check_out_date), `idx_pms_o_tenant_dept_contact_phone` (tenant_id, dept_id, primary_contact_phone), `idx_pms_o_tenant_dept_source` (tenant_id, dept_id, order_source)
#### 3.2.5 `pms_core_order_items` - 核心订单项目表
* 业务描述: 记录订单中包含的具体商品或服务项目。
* 主键: `order_item_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `order_item_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '订单项目唯一ID')。
* `order_id` (BIGINT, FK, NOT NULL, COMMENT '所属订单ID, 关联 pms_core_orders.order_id')。
* `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID, 关联 sys_dept.dept_id (冗余)')。
* `pms_room_id` (BIGINT, FK, NULLABLE, COMMENT '关联房间ID (如房晚项目), 关联 pms_room_rooms.room_id')。
* `product_id` (BIGINT, FK, NULLABLE, COMMENT '关联产品ID (多态), 如 pms_finance_extra_charge_items.item_id')。
* `product_type` (VARCHAR(50), NOT NULL, COMMENT '产品类型。枚举: room_night (房晚), extra_charge_item (附加收费项目), package_component (套餐子项), service_fee (服务费), discount_adjustment (折扣调整)')。
* `description` (VARCHAR(255), NOT NULL, COMMENT '项目描述 (例如: 豪华大床房住宿, 额外早餐)')。
* `quantity` (INT, NOT NULL, DEFAULT 1, COMMENT '数量')。
* `unit_price` (DECIMAL(10,2), NOT NULL, COMMENT '单价')。
* `total_price` (DECIMAL(10,2), AS (`quantity` * `unit_price`)) STORED COMMENT '总价 (计算列)'。
* `service_date` (DATE, NULLABLE, COMMENT '服务发生日期 (例如房晚对应的日期)')。
* `notes` (TEXT, NULLABLE, COMMENT '项目备注')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 索引: `idx_pms_oi_order_id` (order_id), `idx_pms_oi_tenant_dept_product_type` (tenant_id, dept_id, product_type)
#### 3.2.6 `pms_core_channels` - 订单来源渠道表
* 业务描述: 管理订单的来源渠道。
* 主键: `channel_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `channel_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '渠道唯一ID')。
* `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, 若渠道归属特定部门')。
* `name` (VARCHAR(100), NOT NULL, COMMENT '渠道名称 (例如: 携程, 官网直订)')。
* `channel_type` (VARCHAR(50), NOT NULL, COMMENT '渠道类型。枚举: ota, direct_booking (官网/电话/前台), gds (全球分销系统), wholesaler (批发商), corporate (公司协议), internal_use (内部使用), other')。
* `description` (TEXT, NULLABLE, COMMENT '渠道描述')。
* `status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '状态。枚举: active (激活), inactive (停用), deprecated (弃用)')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 索引: `idx_pms_ch_tenant_dept_name` (tenant_id, dept_id, name), `idx_pms_ch_type` (channel_type), `idx_pms_ch_status` (status)
#### 3.2.7 `pms_finance_folios` - 客户账单(Folio)表
* 业务描述: 记录与订单关联的客户账单核心信息。
* 主键: `folio_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `folio_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '账单唯一ID')。
* `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID, 关联 sys_dept.dept_id')。
* `order_id` (BIGINT, UNIQUE, FK, NOT NULL, COMMENT '关联的订单ID, 关联 pms_core_orders.order_id')。
* `total_charges` (DECIMAL(10,2), NOT NULL, DEFAULT 0.00, COMMENT '总应收费用')。
* `total_payments` (DECIMAL(10,2), NOT NULL, DEFAULT 0.00, COMMENT '总已收付款')。
* `total_refunds` (DECIMAL(10,2), NOT NULL, DEFAULT 0.00, COMMENT '总已退款')。
* `balance` (DECIMAL(10,2), AS (`total_charges` - `total_payments` + `total_refunds`)) STORED COMMENT '当前余额 (计算列)'。
* `folio_status` (VARCHAR(50), NOT NULL, DEFAULT 'open', COMMENT '账单状态。枚举: open (开放/未结清), closed (已结清/关闭), void (作废), pending_settlement (待结算)')。
* `notes` (TEXT, NULLABLE, COMMENT '账单备注')。
* `closed_at` (DATETIME, NULLABLE, COMMENT '账单关闭时间')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 索引: `idx_pms_f_tenant_dept_order_id` (tenant_id, dept_id, order_id), `idx_pms_f_tenant_dept_status` (tenant_id, dept_id, folio_status)
#### 3.2.8 `pms_finance_transactions` - 财务交易流水表
* 业务描述: 记录在Folio中的每一笔财务交易。
* 主键: `transaction_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `transaction_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '交易唯一ID')。
* `folio_id` (BIGINT, FK, NOT NULL, COMMENT '所属账单ID, 关联 pms_finance_folios.folio_id')。
* `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID, 关联 sys_dept.dept_id (冗余)')。
* `transaction_type` (VARCHAR(50), NOT NULL, COMMENT '交易类型。枚举: charge (应收费用), payment (客人付款), refund (退款给客人), deposit (押金), deposit_refund (押金退还), adjustment_positive (正调整), adjustment_negative (负调整)')。
* `amount` (DECIMAL(10,2), NOT NULL, COMMENT '交易金额')。
* `description` (VARCHAR(255), NOT NULL, COMMENT '交易描述')。
* `payment_method_id` (BIGINT, FK, NULLABLE, COMMENT '支付方式ID, 关联 pms_finance_payment_methods.payment_method_id')。
* `payment_gateway_txn_id` (VARCHAR(255), NULLABLE, COMMENT '支付网关交易号')。
* `transaction_time` (DATETIME, NOT NULL, COMMENT '交易实际发生时间')。
* `related_order_item_id` (BIGINT, FK, NULLABLE, COMMENT '关联的订单项ID, 关联 pms_core_order_items.order_item_id')。
* `notes` (TEXT, NULLABLE, COMMENT '交易备注')。
* `is_void` (BOOLEAN, NOT NULL, DEFAULT FALSE, COMMENT '是否已作废冲销')。
* `voided_at` (DATETIME, NULLABLE, COMMENT '作废时间')。
* `voided_reason` (TEXT, NULLABLE, COMMENT '作废原因')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 索引: `idx_pms_ft_folio_id` (folio_id), `idx_pms_ft_tenant_dept_type_time` (tenant_id, dept_id, transaction_type, transaction_time), `idx_pms_ft_payment_gateway_txn_id` (payment_gateway_txn_id)
#### 3.2.9 `pms_finance_payment_methods` - 支付方式表
* 业务描述: 存储租户可定义的支付方式。
* 主键: `payment_method_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `payment_method_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '支付方式唯一ID')。
* `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, 若支付方式归属特定部门')。
* `name` (VARCHAR(100), NOT NULL, COMMENT '支付方式名称 (例如: 现金, 微信支付)')。
* `method_type` (VARCHAR(50), NOT NULL, COMMENT '支付方式类型。枚举: cash, credit_card_visa, credit_card_mastercard, credit_card_amex, alipay, wechat_pay, bank_transfer, company_account, voucher, points, other_online_payment, mobile_payment, other')。
* `details_json` (JSON, NULLABLE, COMMENT '支付方式附加配置。例如支付网关参数等')。
* `status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '状态。枚举: active (激活), inactive (停用)')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 索引: `idx_pms_fpm_tenant_dept_name` (tenant_id, dept_id, name), `idx_pms_fpm_tenant_dept_type` (tenant_id, dept_id, method_type), `idx_pms_fpm_tenant_dept_status` (tenant_id, dept_id, status)
#### 3.2.10 `pms_finance_extra_charge_items` - 附加费用项目表
* 业务描述: 存储租户可预定义的附加消费项目，如额外早餐、加床费等。
* 主键: `item_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `item_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '附加费用项目唯一ID')。
* `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, 若项目归属特定部门')。
* `name` (VARCHAR(255), NOT NULL, COMMENT '项目名称')。
* `default_price` (DECIMAL(10,2), NOT NULL, COMMENT '默认单价')。
* `category` (VARCHAR(100), NULLABLE, COMMENT '费用类别，如餐饮、服务、商品等')。
* `is_taxable` (BOOLEAN, NOT NULL, DEFAULT TRUE, COMMENT '是否应税')。
* `description` (TEXT, NULLABLE, COMMENT '项目描述')。
* `status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '状态。枚举: active (激活), inactive (停用)')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 索引: `idx_pms_feci_tenant_dept_name` (tenant_id, dept_id, name), `idx_pms_feci_tenant_dept_category` (tenant_id, dept_id, category), `idx_pms_feci_tenant_dept_status` (tenant_id, dept_id, status)
#### 3.2.11 `pms_room_pricing_rules` - 房间价格规则表
* 业务描述: 为特定房型在特定日期范围或特定条件下设置价格调整规则。
* 主键: `rule_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `rule_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '价格规则唯一ID')。
* `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, 若规则归属特定部门')。
* `name` (VARCHAR(255), NOT NULL, COMMENT '规则名称 (例如: 周末特价, 连住优惠)')。
* `room_type_id` (BIGINT, FK, NULLABLE, COMMENT '适用的房型ID, 关联 pms_room_types.room_type_id, NULL表示适用于所有房型')。
* `date_range_start` (DATE, NULLABLE, COMMENT '规则适用开始日期')。
* `date_range_end` (DATE, NULLABLE, COMMENT '规则适用结束日期')。
* `days_of_week_json` (JSON, NULLABLE, COMMENT 'JSON数组，数字代表星期几, e.g., [1,2,7] (1-Mon, 7-Sun)')。
* `min_length_of_stay` (INT, NULLABLE, COMMENT '最小入住天数要求')。
* `max_length_of_stay` (INT, NULLABLE, COMMENT '最大入住天数限制')。
* `price_adjustment_type` (VARCHAR(50), NOT NULL, COMMENT '调整类型。枚举: fixed_amount_override (固定价格覆盖), percentage_discount_from_base (基价百分比折扣), fixed_amount_increase_on_base (基价固定金额上浮), fixed_amount_decrease_from_base (基价固定金额下调), set_to_value (设置为特定值)')。
* `adjustment_value` (DECIMAL(10,2), NOT NULL, COMMENT '调整值 (具体金额或百分比，如50.00或0.1代表10%)')。
* `priority` (INT, NOT NULL, DEFAULT 0, COMMENT '规则优先级，数字越大优先级越高')。
* `status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '状态。枚举: active (激活), inactive (停用), scheduled (计划中)')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 索引: `idx_pms_rpr_tenant_dept_dates` (tenant_id, dept_id, date_range_start, date_range_end), `idx_pms_rpr_tenant_dept_status_priority` (tenant_id, dept_id, status, priority)
#### 3.2.12 `pms_tenant_user_devices` - 租户用户设备表
* 业务描述: 用于存储租户用户（员工）登录过的设备信息，主要用于推送通知。
* 主键: `id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '设备记录唯一ID')。
* `user_id` (BIGINT(20), FK, NOT NULL, COMMENT '关联的用户ID, 关联 sys_user.user_id')。
* `device_type` (VARCHAR(50), NOT NULL, COMMENT '设备类型，例如: ios_app, android_app, wechat_miniprogram, web_push_browser')。
* `device_token` (VARCHAR(512), NOT NULL, COMMENT '设备推送令牌')。
* `app_version` (VARCHAR(50), NULLABLE, COMMENT '客户端应用版本')。
* `last_login_at` (DATETIME, NOT NULL, COMMENT '此设备最后登录时间')。
* `status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '状态。枚举: active (激活), inactive (停用), token_expired (令牌过期)')。
* `create_time` (DATETIME, NOT NULL, COMMENT '记录创建时间')。
* `update_time` (DATETIME, NOT NULL, COMMENT '记录更新时间')。
* 唯一约束: `unq_pms_ud_user_device_token_type` (user_id, device_token, device_type)
* 索引: `idx_pms_ud_tenant_user_token` (tenant_id, user_id, device_token), `idx_pms_ud_user_status` (user_id, status)
#### 3.2.13 `pms_tenant_settings` - 租户级PMS特定设置表
* 业务描述: 存储租户或部门级别的PMS特定业务配置项。与若依的 `sys_config` 互补。
* 主键: `setting_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `setting_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '设置唯一ID')。
* `tenant_id` (VARCHAR(20), NOT NULL, COMMENT '租户编号, 关联 sys_tenant.tenant_id')。
* `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, NULL表示租户全局PMS设置')。
* `setting_group` (VARCHAR(100), NOT NULL, COMMENT '设置分组，例如: pms_booking_rules, pms_financial_params, pms_ui_appearance')。
* `setting_key` (VARCHAR(100), NOT NULL, COMMENT '设置项的唯一键 (在tenant_id, dept_id, setting_group下唯一)')。
* `setting_value` (TEXT, NOT NULL, COMMENT '设置项的值 (根据需要可存储JSON字符串)')。
* `value_type` (VARCHAR(50), NOT NULL, DEFAULT 'string', COMMENT '值类型，如 string, integer, boolean, json，方便解析')。
* `description` (TEXT, NULLABLE, COMMENT '设置项描述')。
* `is_sensitive` (BOOLEAN, NOT NULL, DEFAULT FALSE, COMMENT '是否为敏感设置')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 唯一约束: `unq_pms_ts_tenant_dept_group_key` (tenant_id, dept_id, setting_group, setting_key, del_flag)
* 索引: `idx_pms_ts_tenant_dept_group_key` (tenant_id, dept_id, setting_group, setting_key)
#### 3.2.14 `pms_mp_settings` - 民宿管理小程序配置表
* 业务描述: 存储租户或部门级别针对民宿员工管理小程序的特定配置项。
* 主键: `setting_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `setting_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '小程序设置唯一ID')。
* `tenant_id` (VARCHAR(20), NOT NULL, COMMENT '租户编号, 关联 sys_tenant.tenant_id')。
* `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, NULL表示租户全局小程序设置')。
* `setting_key` (VARCHAR(100), NOT NULL, COMMENT '小程序配置项的唯一键。例如: mp_theme_color, mp_enable_feature_xyz')。
* `setting_value` (TEXT, NOT NULL, COMMENT '配置项的值 (可存储JSON字符串)')。
* `value_type` (VARCHAR(50), NOT NULL, DEFAULT 'string', COMMENT '值类型，如 string, integer, boolean, json')。
* `description` (TEXT, NULLABLE, COMMENT '配置项描述')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 唯一约束: `unq_pms_mps_tenant_dept_key` (tenant_id, dept_id, setting_key, del_flag)
* 索引: `idx_pms_mps_tenant_dept_key` (tenant_id, dept_id, setting_key)
### 3.3 公共数据模型 (PMS相关)
#### 3.3.1 `cmn_contacts` - 联系人表
* 业务描述: 存储系统中所有类型的联系人信息，主要是PMS的住客。
* 主键: `contact_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `contact_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '联系人唯一ID')。
* `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, 若联系人主要归属某部门')。
* `contact_type` (VARCHAR(50), NOT NULL, COMMENT '联系人类型。枚举: guest_individual (散客), guest_group_contact (团队联系人), corporate_contact (公司协议联系人), travel_agent_contact (旅行社联系人), company_profile (公司档案), supplier_contact (供应商联系人), employee_profile (员工档案关联), other (其他)')。
* `full_name` (VARCHAR(255), NULLABLE, COMMENT '姓名')。
* `phone_number` (VARCHAR(50), NULLABLE, COMMENT '主要联系电话')。
* `email` (VARCHAR(255), NULLABLE, COMMENT '电子邮件地址')。
* `wechat_openid` (VARCHAR(100), NULLABLE, COMMENT '微信OpenID (特定于单个微信公众号或小程序)')。
* `wechat_unionid` (VARCHAR(100), NULLABLE, COMMENT '微信UnionID (跨多个微信应用的用户唯一标识)')。
* `related_user_id` (BIGINT(20), FK, NULLABLE, COMMENT '关联的系统用户ID, 关联 sys_user.user_id, 如员工档案关联')。
* `gender` (VARCHAR(20), NULLABLE, COMMENT '性别。枚举: male (男), female (女), non_binary (非二元), prefer_not_to_say (不愿透露), unknown (未知)')。
* `date_of_birth` (DATE, NULLABLE, COMMENT '出生日期')。
* `id_type` (VARCHAR(50), NULLABLE, COMMENT '证件类型，如身份证、护照等。可关联sys_dict_data')。
* `id_number_encrypted` (VARCHAR(255), NULLABLE, COMMENT '证件号码 (加密存储)')。
* `nationality_country_code` (VARCHAR(10), NULLABLE, COMMENT '国籍代码 (ISO 3166-1 alpha-2)')。
* `preferred_language` (VARCHAR(10), NULLABLE, COMMENT '偏好语言代码 (e.g., en, zh-CN)')。
* `address_street` (VARCHAR(255), NULLABLE, COMMENT '街道地址')。
* `address_city` (VARCHAR(100), NULLABLE, COMMENT '城市')。
* `address_state_province` (VARCHAR(100), NULLABLE, COMMENT '省/州')。
* `address_postal_code` (VARCHAR(50), NULLABLE, COMMENT '邮政编码')。
* `address_country_code` (VARCHAR(10), NULLABLE, COMMENT '国家代码 (ISO 3166-1 alpha-2)')。
* `contact_status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '联系人状态。枚举: active (活跃), inactive (不活跃), prospect (潜在客户), blacklisted (黑名单), pending_verification (待验证), merged_duplicate (已合并重复)')。
* `remarks` (TEXT, NULLABLE, COMMENT '备注信息')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 唯一约束 (建议，考虑 `del_flag`):
* `unq_cmn_c_tenant_dept_phone` (tenant_id, dept_id, phone_number, del_flag) (如果电话在部门内唯一)
* `unq_cmn_c_tenant_dept_email` (tenant_id, dept_id, email, del_flag) (如果邮箱在部门内唯一)
* 索引: `idx_cmn_c_tenant_dept_fname` (tenant_id, dept_id, full_name), `idx_cmn_c_tenant_dept_status_type` (tenant_id, dept_id, contact_status, contact_type), `idx_cmn_c_related_user` (related_user_id)
#### 3.3.2 `cmn_contact_tags` - 联系人标签表
* 业务描述: 定义可用于分类和标记联系人的标签。
* 主键: `tag_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `tag_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '标签唯一ID')。
* `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, 若标签归属特定部门或全局')。
* `name` (VARCHAR(100), NOT NULL, COMMENT '标签名称')。
* `color` (VARCHAR(20), NULLABLE, COMMENT '标签显示颜色，如十六进制色值 #FF5733')。
* `category` (VARCHAR(50), NULLABLE, COMMENT '标签分类，如兴趣、客户级别、来源等')。
* `description` (TEXT, NULLABLE, COMMENT '标签描述')。
* `is_system` (BOOLEAN, NOT NULL, DEFAULT FALSE, COMMENT '是否为系统预设标签 (不可删除)')。
* `sort_order` (INT, NOT NULL, DEFAULT 0, COMMENT '排序值')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
* `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
* `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
* `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
* `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志（0存在 1删除）')。
* 唯一约束: `unq_cmn_ct_tenant_dept_name_category` (tenant_id, dept_id, name, category, del_flag)
* 索引: `idx_cmn_ct_category` (category), `idx_cmn_ct_is_system` (is_system)
#### 3.3.3 `cmn_contact_tag_relations` - 联系人标签关联表
* 业务描述: 实现联系人与标签的多对多关系。
* 主键: `relation_id` (BIGINT AUTO_INCREMENT)
* 字段定义:
* `relation_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '关联唯一ID')。
* `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID, 关联 sys_dept.dept_id (冗余, 以联系人所属部门为准)')。
* `contact_id` (BIGINT, FK, NOT NULL, COMMENT '联系人ID, 关联 cmn_contacts.contact_id')。
* `tag_id` (BIGINT, FK, NOT NULL, COMMENT '标签ID, 关联 cmn_contact_tags.tag_id')。
* `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
* `create_time` (DATETIME, NOT NULL, COMMENT '创建时间')。
* 唯一约束: `unq_cmn_ctr_tenant_dept_contact_tag` (tenant_id, dept_id, contact_id, tag_id)
* 索引: `idx_cmn_ctr_contact_id` (contact_id), `idx_cmn_ctr_tag_id` (tag_id)
## 4. 主要业务实体状态流转
#### 4.1 订单 (`pms_core_orders`) 状态流转
```mermaid
stateDiagram-v2
[*] --> pending_confirmation: 创建订单
pending_confirmation --> confirmed: 确认订单
pending_confirmation --> cancelled: 取消订单
confirmed --> checked_in: 办理入住
confirmed --> cancelled: 取消订单
confirmed --> no_show: 未按时入住
checked_in --> checked_out: 办理退房
checked_in --> extended: 延长入住
extended --> checked_out: 办理退房
checked_out --> [*] : 订单完成
cancelled --> [*] : 订单取消
no_show --> [*] : 订单标记为No Show
```
* **订单状态 (`order_status` VARCHAR(50)) 枚举值示例:**
* `pending_confirmation` (待确认)
* `confirmed` (已确认)
* `checked_in` (已入住)
* `checked_out` (已退房)
* `cancelled` (已取消)
* `no_show` (未到店)
* `extended` (已延期)
* `waitlist` (等候名单)
#### 4.2 房间 (`pms_room_rooms`) 状态流转 (物理状态 & 清洁状态)
**物理状态 (`room_status` VARCHAR(50))**
```mermaid
stateDiagram-v2
[*] --> available: 房间空闲可用
available --> occupied: 客人入住 / 预留占用
available --> maintenance: 安排维护 / 维修
available --> out_of_service: 暂停服务 (其他原因)
occupied --> available: 客人退房 (且房间已清洁完成)
maintenance --> available: 维护完成 (房间恢复可用)
out_of_service --> available: 恢复服务
```
* **物理状态枚举值示例:**
* `available` (可用)
* `occupied` (占用中)
* `maintenance` (维护中)
* `out_of_service` (暂停服务)
**清洁状态 (`cleaning_status` VARCHAR(50))**
```mermaid
stateDiagram-v2
[*] --> clean: 初始状态 / 清洁完成
clean --> dirty: 客人使用后 / 退房后标记
dirty --> cleaning_in_progress: 客房服务员开始清洁
cleaning_in_progress --> inspected: 清洁完成待查房
inspected --> clean: 查房通过
inspected --> cleaning_in_progress: 查房未通过，返工
clean --> cleaning_in_progress: 客中打扫 (客人仍在住，但安排了打扫)
```
* **清洁状态枚举值示例:**
* `clean` (已清洁)
* `dirty` (待清洁)
* `cleaning_in_progress` (清洁中)
* `inspected` (已查房/待检)
#### 4.3 账单 (`pms_finance_folios`) 状态流转
```mermaid
stateDiagram-v2
[*] --> open: 订单创建时自动生成 / 手动创建
open --> closed: 账务结清 (所有费用付清)
open --> void: 作废账单 (如错误创建)
open --> pending_settlement: 等待结算 (如对公转账)
pending_settlement --> closed: 结算完成
pending_settlement --> open: 取消结算，返回开放
closed --> open: 重新打开 (特殊情况，需权限，如补充入账或退款)
void --> [*] : 账单作废
closed --> [*] : 账单关闭
```
* **账单状态 (`folio_status` VARCHAR(50)) 枚举值示例:**
* `open` (开放/未结清)
* `closed` (已结清/关闭)
* `void` (作废)
* `pending_settlement` (待结算)
## 5. 核心业务枚举值定义 (PMS主要部分)
以下列出PMS核心业务表中 `VARCHAR(50)` 类型枚举字段的建议值，具体值可根据业务细化调整。
* **`pms_room_types.status`**: `active` (启用), `inactive` (禁用)
* **`pms_room_rooms.room_status`**: `available` (可用), `occupied` (占用中), `maintenance` (维护中), `out_of_service` (暂停服务)
* **`pms_room_rooms.cleaning_status`**: `clean` (已清洁), `dirty` (待清洁), `cleaning_in_progress` (清洁中), `inspected` (已查房/待检)
* **`pms_room_rooms.status` (记录状态)**: `active` (启用), `inactive` (禁用)
* **`pms_room_locks.lock_type`**: `manual_lock` (手动锁定), `maintenance` (维护), `auto_block` (自动锁定，如欠费), `staff_use` (员工自用), `cleaning_block` (清洁锁定)
* **`pms_core_orders.order_status`**: `pending_confirmation` (待确认), `confirmed` (已确认), `checked_in` (已入住), `checked_out` (已退房), `cancelled` (已取消), `no_show` (未到店), `extended` (已延期), `waitlist` (等候名单), `provisional` (暂定预订)
* **`pms_core_orders.order_source`**: `direct_walk_in` (现场步入), `direct_phone` (电话预订), `direct_website` (官网预订), `direct_mall_h5` (H5商城), `ota_channel_manager` (OTA渠道管理), `travel_agency` (旅行社), `corporate_account` (公司协议), `internal_booking` (内部预订), `other` (其他)
* **`pms_core_order_items.product_type`**: `room_night` (房晚), `extra_charge_item` (附加收费项目), `package_component` (套餐子项), `service_fee` (服务费), `discount_adjustment` (折扣调整), `cancellation_fee` (取消费)
* **`pms_core_channels.channel_type`**: `ota` (在线旅行社), `direct_booking` (直接预订-官网/电话/前台), `gds` (全球分销系统), `wholesaler` (批发商), `corporate` (公司协议), `internal_use` (内部使用), `meta_search` (元搜索), `other` (其他)
* **`pms_core_channels.status`**: `active` (激活), `inactive` (停用), `deprecated` (弃用)
* **`pms_finance_folios.folio_status`**: `open` (开放/未结清), `closed` (已结清/关闭), `void` (作废), `pending_settlement` (待结算)
* **`pms_finance_transactions.transaction_type`**: `charge` (应收费用), `payment` (客人付款), `refund` (退款给客人), `deposit` (押金收款), `deposit_refund` (押金退还), `adjustment_positive` (正调整), `adjustment_negative` (负调整), `folio_transfer_out` (转出), `folio_transfer_in` (转入)
* **`pms_finance_payment_methods.method_type`**: `cash` (现金), `credit_card_visa` (VISA卡), `credit_card_mastercard` (万事达卡), `credit_card_amex` (运通卡), `credit_card_unionpay` (银联卡), `alipay` (支付宝), `wechat_pay` (微信支付), `bank_transfer` (银行转账), `company_account` (公司账户/挂账), `voucher` (代金券), `points_redemption` (积分兑换), `other_online_payment` (其他在线支付), `mobile_payment` (其他移动支付), `other` (其他)
* **`pms_finance_payment_methods.status`**: `active` (激活), `inactive` (停用)
* **`pms_finance_extra_charge_items.status`**: `active` (激活), `inactive` (停用)
* **`pms_room_pricing_rules.price_adjustment_type`**: `fixed_amount_override` (固定价格覆盖), `percentage_discount_from_base` (基价百分比折扣), `fixed_amount_increase_on_base` (基价固定金额上浮), `fixed_amount_decrease_from_base` (基价固定金额下调), `set_to_value` (设置为特定值)
* **`pms_room_pricing_rules.status`**: `active` (激活), `inactive` (停用), `scheduled` (计划中/待生效)
* **`pms_tenant_user_devices.status`**: `active` (激活), `inactive` (停用), `token_expired` (令牌过期)
* **`cmn_contacts.contact_type`**: `guest_individual` (散客), `guest_group_contact` (团队联系人), `corporate_contact` (公司协议联系人), `travel_agent_contact` (旅行社联系人), `company_profile` (公司档案), `supplier_contact` (供应商联系人), `employee_profile` (员工档案关联), `other` (其他)
* **`cmn_contacts.gender`**: `male` (男), `female` (女), `non_binary` (非二元性别), `prefer_not_to_say` (不愿透露), `unknown` (未知)
* **`cmn_contacts.contact_status`**: `active` (活跃), `inactive` (不活跃), `prospect` (潜在客户), `blacklisted` (黑名单), `pending_verification` (待验证), `merged_duplicate` (已合并重复档案)
## 6. 索引命名与规范建议
* **唯一索引：** `unq_[子系统前缀]_[表名简写]_[字段1]_[字段2]`，例如：`unq_pms_r_tdrn` 代表 `pms_room_rooms` 表上 `tenant_id, dept_id, room_number` 的唯一索引。
* **普通索引：** `idx_[子系统前缀]_[表名简写]_[字段1]_[字段2]`，例如：`idx_pms_o_tds` 代表 `pms_core_orders` 表上 `tenant_id, dept_id, order_status` 的普通索引。
* **租户和部门优先：** 对于所有包含 `tenant_id` 和 `dept_id` 的PMS业务表，查询相关的索引应优先考虑这两个字段，顺序通常为 `(tenant_id, dept_id, ...其他条件字段)`。
* **覆盖索引：** 尽量设计覆盖索引以减少回表，提高查询性能。
* **避免过多索引：** 每个表的索引数量不宜过多，以免影响写入性能。
---
**(文档末尾)**
**重要提示：**
* 本文档中的主键类型已统一为 `BIGINT AUTO_INCREMENT` (用于PMS新增业务表) 或遵循若依原有的 `BIGINT` (用于若依系统表)。
* PMS业务表中的枚举字段统一为 `VARCHAR(50)`，这与若依的 `CHAR(1)` 不同，在系统集成和前端交互时，可能需要在API层或逻辑层进行适配和转换。
* 所有PMS业务表已添加 `dept_id` 字段，用于数据归属和统计。确保所有相关查询和业务逻辑都考虑到 `dept_id`。
* 审计字段和软删除标记已尽量对齐若依规范。
请仔细审查此最终方案，确保其满足所有业务需求和技术约束。

328
docs/basic/PMS需求.md Normal file
View File

@@ -0,0 +1,328 @@
# 云宿居 PMS 系统 - 核心功能需求 (PMS内部聚焦)
## 1. 引言
### 1.1 文档目的与范围
本文档定义了"云宿居"民宿 Property Management System (PMS) 的核心功能需求，**重点聚焦于PMS租户核心业务子系统（以下简称PMS核心模块）的内部功能**。它旨在明确该子系统的核心功能范围和关键业务流程。
本文档是PMS核心模块后续详细设计和开发工作的基础。
### 1.2 目标读者
产品经理、架构师、开发工程师、测试工程师。
### 1.4 术语表
| 术语 | 全称 | 描述 |
| ------- | -------------------------- | ------------------------------------------------------------- |
| PMS | Property Management System | 民宿/酒店属性管理系统，管理房间、预订、联系人、账务等核心业务 |
| Folio | Folio | 客户账单，用于记录联系人在店期间所有费用和付款的详细清单 |
| Tenant | Tenant | 租户，指使用本SaaS化PMS系统的单个民宿运营方 |
| Dept | Department | 部门，在本系统中表示租户下的门店/分店 |
| Contact | Contact | 联系人，指系统中统一管理的客户信息，包括预订人、实际入住人等 |
### 1.5 优先级定义
* **[P0]**: MVP 阶段必须实现的核心功能。
* **[P1]**: 重要功能，MVP 后第一个主要版本包含。
* **[P2]**: 次要或完善性功能，后续迭代实现。
* **[P3]**: 未来规划或可选功能。
## 2. 核心设计原则 (适用于PMS内部)
1. **核心稳固**: 保持PMS核心功能（房态、订单、账务、联系人）的极简和稳定。
2. **数据为基**: 确保PMS核心数据结构设计合理，易于内部功能扩展。
3. **安全隐私**: PMS内部数据处理需考虑数据安全和隐私保护。
4. **门店为中心**: 所有业务数据以门店（部门）为归属单位，支持一个租户下多个门店的业务模型。
## 3. 系统架构概览 (PMS视角)
PMS租户核心业务子系统是整个云宿居平台的核心，负责处理民宿日常运营的核心业务流程。
```mermaid
flowchart TD
subgraph PMSCore["PMS核心业务子系统"]
PMS["PMS租户<br>核心业务子系统"]:::coreSystem
end
subgraph ExternalSystems["外部关联系统"]
SaaSPlat[SaaS平台管理]:::system
WCDSMM[商城与商品管理]:::system
end
PMSAdmin[PMS核心后台]:::app
OwnerApp[民宿管理小程序]:::app
UserB([民宿主/前台]):::user
SaaSPlat -- "租户配置" --> PMS
WCDSMM -- "预订数据" --> PMS
PMS -- "房态/价格" --> WCDSMM
PMSAdmin --> PMS
OwnerApp --> PMS
UserB -.-> PMSAdmin
UserB -.-> OwnerApp
classDef system fill:#f0f8ff,stroke:#1890ff,stroke-width:1px
classDef coreSystem fill:#f6ffed,stroke:#52c41a,stroke-width:3px,color:#135200,font-weight:bold
classDef app fill:#d9f7be,stroke:#52c41a,stroke-width:1px
classDef user fill:#fff7e6,stroke:#fa8c16,stroke-width:1px,shape:person
```
## 4. PMS租户核心业务子系统 (PMSTenantCoreSubsystem)
**目标:** 为民宿租户提供稳定、高效的核心运营管理能力。
**主要用户:** 民宿主/管理员、前台员工。
#### 4.2.1 房态管理 [P0]
* **功能:**
* **网格日历视图:** 直观展示房间占用情况（已预订、已入住、清洁中、维护锁定）。
* **今日状态列表:** 按预抵、在住、预离分类展示当日订单/房间。
* **清洁状态管理:** 手动标记房间清洁状态 (待清洁/清洁中/已干净)。
* **快捷操作:** 在房态图上可快速创建预订、登记入住/退房、标记房间清洁状态、设置房间临时锁定/解锁。支持拖动修改预订的入住日期或房间。
* **关键数据:**
* `pms_room_types` (room_type_id:BIGINT:pk, dept_id:BIGINT, name:VARCHAR(255), default_price:DECIMAL(10,2), capacity:INT, amenities:JSON, description:TEXT, images_json:JSON, status:VARCHAR(50))
* `pms_room_rooms` (room_id:BIGINT:pk, dept_id:BIGINT, room_type_id:BIGINT, room_number:VARCHAR(50), floor:VARCHAR(50), room_status:VARCHAR(50), cleaning_status:VARCHAR(50), description:TEXT, status:VARCHAR(50))
* `pms_room_locks` (lock_id:BIGINT:pk, dept_id:BIGINT, room_id:BIGINT, start_datetime:DATETIME, end_datetime:DATETIME, reason:TEXT, lock_type:VARCHAR(50))
#### 4.2.2 订单管理 [P0, P1, P2]
* **目标:** 高效、准确地管理所有来源的预订订单。
* **[P0] 核心订单生命周期管理:**
* 功能: 手动创建订单、接收外部系统订单、订单详情查看与编辑、核心状态管理（待确认、已确认、已入住、已退房、已取消、未入住）、关联联系人与房间、生成账单基础、房态联动。
* 库存策略: `pending_confirmation` 状态不锁硬库存。`confirmed` 状态锁定库存。
* 关键数据:
* `pms_core_orders` (order_id:BIGINT:pk, dept_id:BIGINT, contact_id:BIGINT, primary_contact_name:VARCHAR(100), primary_contact_phone:VARCHAR(50), pms_room_id:BIGINT, room_type_id:BIGINT, channel_id:BIGINT, check_in_date:DATE, check_out_date:DATE, num_adults:INT, num_children:INT, estimated_arrival_time:TIME, total_amount:DECIMAL(10,2), paid_amount:DECIMAL(10,2), due_amount:DECIMAL(10,2), currency:VARCHAR(3), order_status:VARCHAR(50), order_source:VARCHAR(50), notes:TEXT, cancelled_at:DATETIME, cancellation_reason:TEXT)
* `pms_core_order_items` (order_item_id:BIGINT:pk, order_id:BIGINT, dept_id:BIGINT, pms_room_id:BIGINT, product_id:BIGINT, product_type:VARCHAR(50), description:VARCHAR(255), quantity:INT, unit_price:DECIMAL(10,2), total_price:DECIMAL(10,2), service_date:DATE, notes:TEXT)
* `pms_core_channels` (channel_id:BIGINT:pk, dept_id:BIGINT, name:VARCHAR(100), channel_type:VARCHAR(50), description:TEXT, status:VARCHAR(50))
* 状态流转图:
```mermaid
stateDiagram-v2
[*] --> pending_confirmation: 创建订单
pending_confirmation --> confirmed: 确认订单
pending_confirmation --> cancelled: 取消订单
confirmed --> checked_in: 办理入住
confirmed --> cancelled: 取消订单
confirmed --> no_show: 未按时入住
checked_in --> checked_out: 办理退房
checked_in --> extended: 延长入住
extended --> checked_out: 办理退房
checked_out --> [*] : 订单完成
cancelled --> [*] : 订单取消
no_show --> [*] : 订单标记为No Show
```
* **[P1] 增强功能:** 订单修改（日期、房型等）、款项管理（预付款、押金）、取消与退款细则、基础支付记录（如手动录入）、自动化通知（预订成功、入住提醒）、订单备注与标签。
* **[P2] 实用订单工具:** 简版团体预订、等候名单、订单报表、发票管理。
#### 4.2.3 财务与支付 (Folio Management) [P0]
* **功能:** 账单管理(Folio)、交易流水、附加消费管理、收款方式与记录、退款处理、账单生成与查询。
* **关键数据:**
* `pms_finance_folios` (folio_id:BIGINT:pk, dept_id:BIGINT, order_id:BIGINT, total_charges:DECIMAL(10,2), total_payments:DECIMAL(10,2), total_refunds:DECIMAL(10,2), balance:DECIMAL(10,2), folio_status:VARCHAR(50), notes:TEXT, closed_at:DATETIME)
* `pms_finance_transactions` (transaction_id:BIGINT:pk, folio_id:BIGINT, dept_id:BIGINT, transaction_type:VARCHAR(50), amount:DECIMAL(10,2), description:VARCHAR(255), payment_method_id:BIGINT, payment_gateway_txn_id:VARCHAR(255), transaction_time:DATETIME, related_order_item_id:BIGINT, notes:TEXT, is_void:BOOLEAN, voided_at:DATETIME, voided_reason:TEXT)
* `pms_finance_payment_methods` (payment_method_id:BIGINT:pk, dept_id:BIGINT, name:VARCHAR(100), method_type:VARCHAR(50), details_json:JSON, status:VARCHAR(50))
* `pms_finance_extra_charge_items` (item_id:BIGINT:pk, dept_id:BIGINT, name:VARCHAR(255), default_price:DECIMAL(10,2), category:VARCHAR(100), is_taxable:BOOLEAN, description:TEXT, status:VARCHAR(50))
#### 4.2.4 联系人与会员管理 [P1] (P0阶段依赖`cmn_contacts`部分字段)
* **功能 (P0涉及):** 订单关联联系人时，使用/创建`cmn_contacts`记录。
* **关键数据 (P0使用部分):**
* `cmn_contacts` (contact_id:BIGINT:pk, dept_id:BIGINT, contact_type:VARCHAR(50), full_name:VARCHAR(255), phone_number:VARCHAR(50), email:VARCHAR(255), id_type:VARCHAR(50), id_number_encrypted:VARCHAR(255), gender:VARCHAR(20), contact_status:VARCHAR(50))
* **[P1] 功能:** 统一联系人档案、证件管理、联系人标签[P2]、联系人偏好[P2]、会员信息管理。
#### 4.2.5 会员营销 (储值、等级、权益) [P2]
* **功能:** 储值管理、会员等级定义与升级、会员权益定义与关联。
#### 4.2.6 租户级系统管理 [P0]
* **功能:**
* **员工管理:** 租户管理员管理内部员工账号。
* **角色与权限:** 租户管理员定义内部角色 [MVP: 预设固定角色]。
* **基础设置:** 民宿信息、Logo等；房型管理；房间管理；基础定价策略 (`pms_room_types.default_price`, `pms_room_pricing_rules`表)；支付方式管理 (`pms_finance_payment_methods`)；附加消费项目 (`pms_finance_extra_charge_items`)。
* **门店管理:** 在一个租户下管理多个门店，每个门店对应一个sys_dept记录。
* **租户特定配置:** 管理租户全局及各门店特定的配置。
* **关键数据:**
* `pms_tenant_settings` (setting_id:BIGINT:pk, tenant_id:VARCHAR(20), dept_id:BIGINT, setting_group:VARCHAR(100), setting_key:VARCHAR(100), setting_value:TEXT, value_type:VARCHAR(50), description:TEXT, is_sensitive:BOOLEAN)
* 特殊说明: 保留tenant_id字段，当dept_id为NULL时表示租户全局配置，当dept_id有值时表示特定门店配置。主要存储PMS业务相关的配置项。
* `pms_mp_settings` (setting_id:BIGINT:pk, tenant_id:VARCHAR(20), dept_id:BIGINT, setting_key:VARCHAR(100), setting_value:TEXT, value_type:VARCHAR(50), description:TEXT)
* 特殊说明: 保留tenant_id字段，当dept_id为NULL时表示租户级小程序配置，当dept_id有值时表示特定门店的小程序配置。主要存储民宿管理小程序的界面和功能配置。
* `pms_tenant_user_devices` (id:BIGINT:pk, user_id:BIGINT, device_type:VARCHAR(50), device_token:VARCHAR(512), app_version:VARCHAR(50), last_login_at:DATETIME, status:VARCHAR(50))
* `pms_room_pricing_rules` (rule_id:BIGINT:pk, dept_id:BIGINT, name:VARCHAR(255), room_type_id:BIGINT, date_range_start:DATE, date_range_end:DATE, days_of_week_json:JSON, min_length_of_stay:INT, max_length_of_stay:INT, price_adjustment_type:VARCHAR(50), adjustment_value:DECIMAL(10,2), priority:INT, status:VARCHAR(50))
##### 4.2.6.1 员工管理
* **功能:** 民宿租户管理员管理本民宿的员工账号、分配角色。用户登录后，若关联多个租户或部门，提供切换租户和部门(门店)功能。
#### 4.2.7 简易报表与分析 [P1]
* **功能:** 核心运营报表 (总营收、入住率、ADR、RevPAR)、渠道来源分析、会员统计、消费分析。
* **特点:** 支持门店级和租户级统计分析。
#### 4.2.8 民宿管理小程序 (Owner We App) [P0]
* **技术:** 前端使用 Uni-App
* **功能:** 房态查看、订单提醒、日程查看（今日预抵/预离）、状态处理 (简单入住/退房操作)、数据概览（核心收支数据）。
* **特点:** 支持门店切换功能。
#### 4.2.9 PMS核心管理后台 [P0]
* **描述:** 提供独立的Web管理后台界面，完成所有PMS核心业务操作。
## 5. 关键业务场景模型图 (PMS内部)
### 5.1 订单状态图 - 房间预订生命周期
```mermaid
stateDiagram-v2
[*] --> 待确认: 用户创建预订
待确认 --> 已确认: 预付款成功/人工确认
待确认 --> 已取消: 超时未确认/用户取消
已确认 --> 已取消: 申请取消并退款
已确认 --> 已入住: 办理入住手续
已入住 --> 已退房: 办理退房手续
已退房 --> 已完成: 完成结算
已取消 --> [*]
已完成 --> [*]
```
### 5.2 PMS核心业务状态图
```mermaid
stateDiagram-v2
state 房间状态 {
[*] --> 空闲
空闲 --> 已预订: 创建预订
空闲 --> 维护中: 设置维护
已预订 --> 已入住: 办理入住
已预订 --> 空闲: 取消预订
已入住 --> 待清洁: 办理退房
待清洁 --> 清洁中: 开始清洁
清洁中 --> 空闲: 完成清洁
维护中 --> 空闲: 完成维护
}
state 财务状态 {
[*] --> 未结账
未结账 --> 部分支付: 收取定金/押金
部分支付 --> 部分支付: 增加消费
部分支付 --> 已结清: 支付尾款
部分支付 --> 退款中: 申请退款
退款中 --> 已退款: 确认退款
已结清 --> [*]
已退款 --> [*]
}
```
### 5.3 PMS租户核心业务子系统组件图
```mermaid
flowchart TD
subgraph PMS["PMS租户核心业务子系统"]
direction TB
APILayer["API层 (内部)"]:::internal --> |请求分发| BusinessModules
subgraph BusinessModules["核心业务模块"]
direction TB
Room["房态管理"]:::internal
Booking["订单管理"]:::internal
Finance["财务与支付"]:::internal
Guest["联系人与会员 (P1核心)"]:::internal
Settings["系统管理 (含门店管理)"]:::internal
Reports["报表分析 (P1+)"]:::internal
Room <--> Booking
Booking <--> Finance
Booking --> Guest
end
end
subgraph AccessLayer["应用访问层 (PMS用户)"]
direction LR
MiniApp["民宿管理小程序"]:::external
WebAdmin["PMS Web管理后台"]:::external
end
AccessLayer --> APILayer
classDef internal fill:#f0f8ff,stroke:#1890ff,stroke-width:1px
classDef external fill:#f5f5f5,stroke:#d9d9d9,stroke-width:1px
```
## 6. 系统角色与权限概述 (PMS相关用户)
1. **民宿租户管理员 (Tenant Admin):**
* 用户实体: 关联到 `sys_user` 表。
* 关联: 通过 `sys_user_role` 表关联到租户及相关角色。
* 操作平台: PMS核心后台 (Web), 民宿管理小程序 (Uni-App)。
* 核心职责: 管理其名下一个或多个民宿门店的完整运营，包括房型房间、订单、财务、员工、租户级系统设置等。
2. **门店管理员 (Store Manager):**
* 用户实体: 关联到 `sys_user` 表。
* 关联: 通过 `sys_user_role` 表和 `sys_dept` 表关联到特定门店与角色。
* 操作平台: PMS核心后台 (Web), 民宿管理小程序 (Uni-App)。
* 核心职责: 管理特定门店的日常运营。
3. **民宿前台/员工 (Tenant Staff):**
* 用户实体: 关联到 `sys_user` 表。
* 关联: 通过 `sys_user_role` 表和 `sys_dept` 表关联到门店及相关角色。
* 操作平台: PMS核心后台 (Web), 民宿管理小程序 (Uni-App)。
* 核心职责: 根据分配的权限执行日常操作，如订单处理、房态更新、联系人入住退房、账务录入等。
## 7. 实施策略与演进路径 (PMS P0重点)
### 7.1 MVP阶段 (PMS核心功能)
- **房态管理:** 基础房型、房间定义和日历视图。
- **订单管理:** 手动录单、接收外部订单（简化接口）、入住、退房基本流程。
- **财务与支付:** 基础账单 (Folio)、交易流水、手动收款/支付记录。
- **租户级系统管理:** 员工账号、门店管理、基础设置（房型、房间、基础价格、支付方式、附加消费项目）。
- **民宿管理小程序:** 房态查看和简单操作（入住/退房）。
## 8. 版本历史
- v2.8 (原始文档版本) - 本文档基于此裁剪和聚焦。
- v3.0 (最新版本) - 修改为"部门作为门店"的数据模型，业务表只关联sys_dept。
## 附录 (PMS内部核心实体)
### 附录A 概念性 E-R 图 (PMS核心)
```mermaid
graph LR
sys_tenant(sys_tenant) -->|1..N| sys_dept(Department)
sys_dept -->|1..N| pms_core_orders(Order)
sys_dept -->|1..N| pms_room_rooms(Room)
sys_dept -->|1..N| sys_user(User)
sys_dept -->|1..N| pms_tenant_settings(Settings)
pms_core_orders -->|0..1| cmn_contacts(Contact)
pms_core_orders -->|1..N| pms_core_order_items(OrderItem)
pms_core_orders -->|1..1| pms_finance_folios(Folio)
pms_room_rooms -->|1..1| pms_room_types(RoomType)
pms_finance_folios -->|1..N| pms_finance_transactions(Transaction)
```
### 附录B 实体关系图 (PMS核心及关联)
```mermaid
graph LR
sys_tenant("sys_tenant") -->|1..N| sys_dept("sys_dept (门店)")
sys_dept -->|1..N| pms_core_orders
sys_dept -->|1..N| pms_room_rooms
sys_dept -->|1..N| sys_user
sys_user -->|1..N| pms_tenant_user_devices
sys_user -->|1..N| sys_user_role
sys_dept -->|1..N| pms_tenant_settings
sys_dept -->|1..N| pms_mp_settings
sys_dept -->|1..N| cmn_contacts
sys_dept -->|1..N| pms_room_types
pms_core_orders -->|0..1| cmn_contacts
pms_core_orders -->|1..N| pms_core_order_items
pms_core_orders -->|1..1| pms_finance_folios
pms_room_rooms -->|1..1| pms_room_types
pms_room_types -->|1..N| pms_room_pricing_rules
pms_core_order_items -->|0..1| pms_finance_extra_charge_items
pms_core_order_items -->|0..1| pms_room_rooms
pms_finance_folios -->|1..N| pms_finance_transactions
pms_finance_transactions -->|0..1| pms_finance_payment_methods
```

288
docs/二开todolist.md Normal file
View File

@@ -0,0 +1,288 @@
# PMS 模块二次开发 ToDoList
## 阶段 0: 项目初始化与理解
- [x] **阅读核心文档:**
- [x] 仔细阅读《PMS数据模型.md》，完全理解PMS核心表的结构、字段定义、关系以及主键/外键/索引规范。
- [x] 仔细阅读《PMS需求.md》，明确PMS核心模块 [P0] 阶段必须实现的功能需求（房态、订单核心生命周期、基础财务支付、租户级系统管理基础）。
- [x] 通读《RuoYi-Vue-Plus二次开发最佳实践.md》，重点关注以下章节：
- Chapter 1: 引言 (文档目的, 模块化特性, **二次开发核心原则**, **Cursor使用优势**)
- Chapter 2: 环境准备与项目结构 (前后端环境, **前后端项目结构**, **代码生成器与Cursor协同**)
- Chapter 3: 模块深入分析 (用户管理模块的启示)
- Chapter 4: 后端开发最佳实践 (Cursor辅助技巧, 模块设计, 分层约定, Domain对象规范)
- Chapter 5: 前端开发最佳实践 (Cursor辅助技巧, 项目结构, 功能模块开发规范, 组件案例, 前后端交互)
- Chapter 6: 前后端协作规范
- Chapter 7: 代码规范与风格
- Chapter 8: 新模块添加流程与实践
- [x] **环境与工具准备:**
- [x] 确保后端开发环境 (JDK, Maven, Redis, MySQL) 符合《最佳实践》Chapter 2.1 要求。
- [x] 确保前端开发环境 (Node.js, pnpm) 符合《最佳实践》Chapter 2.1 要求。
- [x] 安装并配置好 Cursor IDE，将整个 `ruoyi-vue-plus` 项目导入工作区。
- [x] （可选）在 Cursor 中为项目设置特定上下文，如关键模块路径、技术栈等，以便更好地辅助开发。
## 阶段 1: 后端开发 - 模块搭建与核心表结构
- [ ] **创建后端Maven子模块 `ruoyi-pms`** (参考《最佳实践》Chapter 2.2, 4.2, 8.3):
- [ ] 在 `ruoyi-vue-plus/ruoyi-modules` 目录下创建新的 Maven 子模块 `ruoyi-pms`。
- [ ] 配置 `ruoyi-pms/pom.xml`：
- [ ] 设置 `<parent>` 指向 `ruoyi-modules`。
- [ ] 添加必要的公共模块依赖 (如: `ruoyi-common-core`, `ruoyi-common-mybatis`, `ruoyi-common-web`, `ruoyi-common-satoken`, `ruoyi-common-excel`, `ruoyi-common-translate`, `ruoyi-common-tenant`)。
- [ ] 在项目根目录 `pom.xml` 和 `ruoyi-modules/pom.xml` 的 `<modules>` 部分注册 `ruoyi-pms`。
- [ ] **创建后端基础包结构** (参考《最佳实践》Chapter 4.2):
- [ ] 在 `ruoyi-pms/src/main/java/` 下创建基础包，例如 `org.dromara.pms`。
- [ ] 在 `org.dromara.pms` 下创建标准分层包：`controller`, `service`, `service.impl`, `mapper`, `domain` (包含 `entity`, `bo`, `vo`)。
- [ ] **数据库表创建与初始化**:
- [ ] **执行SQL脚本**: 确保已在开发数据库中执行 `script/sql/pms_tables.sql` 文件，创建所有PMS相关的表。
- [ ] **验证表结构**: 对照《PMS数据模型.md》仔细检查已创建的表结构、字段类型、约束、索引是否正确。
- [ ] **验证基础数据**: 确认 `pms_core_channels` 和 `pms_finance_payment_methods` 表的基础数据已按 `pms_tables.sql` 中的`INSERT`语句正确插入。
- [ ] **集成新模块到系统**:
- [ ] (如果需要)在 `ruoyi-admin` 模块的 `application.yml` 中，确保新模块的包路径 (如 `org.dromara.pms`) 被扫描到。
- [ ] (如果需要)配置MyBatis Plus扫描新模块的Mapper XML文件路径。
- [ ] **后端国际化资源文件**:
- [ ] 在 `ruoyi-pms/src/main/resources/` 下创建 `i18n` 目录。
- [ ] 在 `i18n` 目录下创建基础的国际化属性文件，如 `messages_zh_CN.properties` 和 `messages_en_US.properties`。
## 阶段 2: 后端开发 - 核心业务功能 [P0]
**通用后端开发规范 (参考《最佳实践》Chapter 4 & 7.1):**
- [ ] 遵循分层架构约定 (Controller -> Service -> Mapper)。
- [ ] 严格区分 Entity, BO, VO 的职责和使用场景。
- [ ] 使用 MapStruct Plus (`@AutoMapper`) 进行对象转换。
- [ ] Service 层实现类的方法应添加 `@Transactional` 注解。
- [ ] Controller 层方法应添加 `@Log` 操作日志注解和 `@SaCheckPermission` 权限注解。
- [ ] BO 对象字段使用 JSR 303/380 注解进行参数校验。
- [ ] VO 对象字段按需使用 `@Translation` 和 `@Sensitive` 注解。
- [ ] 编写清晰的 Javadoc 注释和行内注释。
- [ ] 使用 Cursor 辅助生成代码、分析逻辑、优化代码。
**具体功能模块开发:**
- [ ] **代码生成器应用 (可选但推荐)** (参考《最佳实践》Chapter 2.4):
- [ ] 针对《PMS数据模型.md》中定义的核心表 (如 `pms_room_types`, `pms_room_rooms`, `pms_core_orders` 等)，使用若依代码生成器生成初始的 Entity, Mapper, Service, Controller, BO, VO。
- [ ] **Cursor辅助**: "请Cursor分析代码生成器为 `pms_room_types` 表生成的后端代码，并指出哪些部分需要根据《PMS需求.md》和《最佳实践》进行调整。"
- [ ] **1. 房型管理 (`pms_room_types`)**:
- [ ] **Domain**: 创建/调整 `PmsRoomType`, `PmsRoomTypeBo`, `PmsRoomTypeVo`。
- [ ] **Mapper**: 创建/调整 `PmsRoomTypeMapper.java` 和对应的 `PmsRoomTypeMapper.xml`。
- [ ] **Service**: 创建/调整 `IPmsRoomTypeService.java` 和 `PmsRoomTypeServiceImpl.java` (实现CRUD逻辑)。
- [ ] **Controller**: 创建/调整 `PmsRoomTypeController.java` (暴露RESTful API)。
- [ ] **2. 房间管理 (`pms_room_rooms`)**:
- [ ] **Domain**: `PmsRoomRoom`, `PmsRoomRoomBo`, `PmsRoomRoomVo`.
- [ ] **Mapper**: `PmsRoomRoomMapper.java` & XML.
- [ ] **Service**: `IPmsRoomRoomService.java` & Impl (CRUD, 更新房间状态/清洁状态逻辑).
- [ ] **Controller**: `PmsRoomRoomController.java`.
- [ ] **3. 房间锁定 (`pms_room_locks`)**:
- [ ] **Domain**: `PmsRoomLock`, `PmsRoomLockBo`, `PmsRoomLockVo`.
- [ ] **Mapper**: `PmsRoomLockMapper.java` & XML.
- [ ] **Service**: `IPmsRoomLockService.java` & Impl (CRUD).
- [ ] **Controller**: `PmsRoomLockController.java`.
- [ ] **4. 核心订单管理 (`pms_core_orders`, `pms_core_order_items`)** (参考《PMS需求.md》4.2.2 [P0]):
- [ ] **Domain**:
- `PmsCoreOrder`, `PmsCoreOrderBo`, `PmsCoreOrderVo` (应包含订单项列表).
- `PmsCoreOrderItem`, `PmsCoreOrderItemBo`, `PmsCoreOrderItemVo`.
- [ ] **Mapper**: `PmsCoreOrderMapper`, `PmsCoreOrderItemMapper` & XMLs.
- [ ] **Service**: `IPmsCoreOrderService`, `IPmsCoreOrderItemService` & Impls (实现订单创建、查询、修改、取消、状态流转核心逻辑；订单项增删改查).
- [ ] 实现订单状态转换逻辑 (pending_confirmation -> confirmed -> checked_in -> checked_out / cancelled / no_show).
- [ ] 订单创建时关联/创建 `cmn_contacts` (基础字段)。
- [ ] 订单创建时关联 `pms_core_channels`。
- [ ] 订单创建/确认时，自动创建或关联 `pms_finance_folios`。
- [ ] **Controller**: `PmsCoreOrderController`.
- [ ] **5. 订单来源渠道 (`pms_core_channels`)**:
- [ ] **Domain**: `PmsCoreChannel`, `PmsCoreChannelBo`, `PmsCoreChannelVo`.
- [ ] **Mapper**: `PmsCoreChannelMapper` & XML.
- [ ] **Service**: `IPmsCoreChannelService` & Impl (CRUD).
- [ ] **Controller**: `PmsCoreChannelController`.
- [ ] **6. 财务-账单管理 (`pms_finance_folios`)** (参考《PMS需求.md》4.2.3 [P0]):
- [ ] **Domain**: `PmsFinanceFolio`, `PmsFinanceFolioBo`, `PmsFinanceFolioVo` (应包含交易流水列表).
- [ ] **Mapper**: `PmsFinanceFolioMapper` & XML.
- [ ] **Service**: `IPmsFinanceFolioService` & Impl (CRUD, 更新账单状态, 计算余额逻辑 - 应用层计算).
- [ ] **Controller**: `PmsFinanceFolioController`.
- [ ] **7. 财务-交易流水 (`pms_finance_transactions`)**:
- [ ] **Domain**: `PmsFinanceTransaction`, `PmsFinanceTransactionBo`, `PmsFinanceTransactionVo`.
- [ ] **Mapper**: `PmsFinanceTransactionMapper` & XML.
- [ ] **Service**: `IPmsFinanceTransactionService` & Impl (CRUD, 关联 `pms_finance_payment_methods`).
- [ ] **Controller**: `PmsFinanceTransactionController`.
- [ ] **8. 财务-支付方式 (`pms_finance_payment_methods`)**:
- [ ] **Domain**: `PmsFinancePaymentMethod`, `PmsFinancePaymentMethodBo`, `PmsFinancePaymentMethodVo`.
- [ ] **Mapper**: `PmsFinancePaymentMethodMapper` & XML.
- [ ] **Service**: `IPmsFinancePaymentMethodService` & Impl (CRUD).
- [ ] **Controller**: `PmsFinancePaymentMethodController`.
- [ ] **9. 财务-附加费用项目 (`pms_finance_extra_charge_items`)**:
- [ ] **Domain**: `PmsFinanceExtraChargeItem`, `PmsFinanceExtraChargeItemBo`, `PmsFinanceExtraChargeItemVo`.
- [ ] **Mapper**: `PmsFinanceExtraChargeItemMapper` & XML.
- [ ] **Service**: `IPmsFinanceExtraChargeItemService` & Impl (CRUD).
- [ ] **Controller**: `PmsFinanceExtraChargeItemController`.
- [ ] **10. 价格规则 (`pms_room_pricing_rules`)**:
- [ ] **Domain**: `PmsRoomPricingRule`, `PmsRoomPricingRuleBo`, `PmsRoomPricingRuleVo`.
- [ ] **Mapper**: `PmsRoomPricingRuleMapper` & XML.
- [ ] **Service**: `IPmsRoomPricingRuleService` & Impl (CRUD).
- [ ] **Controller**: `PmsRoomPricingRuleController`.
- [ ] **11. 联系人基础 (`cmn_contacts`)** (P0阶段主要为订单关联所需字段):
- [ ] **Domain**: `CmnContact`, `CmnContactBo`, `CmnContactVo` (仅包含P0阶段所需字段，如姓名、电话).
- [ ] **Mapper**: `CmnContactMapper` & XML.
- [ ] **Service**: `ICmnContactService` & Impl (提供基础的联系人查询、创建接口供订单模块调用).
- [ ] **Controller**: (P0阶段可能不需要完整独立的Controller，主要通过订单业务间接操作).
- [ ] **12. 租户/部门特定配置 (`pms_tenant_settings`, `pms_mp_settings`)**:
- [ ] **Domain**: `PmsTenantSetting`, `PmsTenantSettingBo`, `PmsTenantSettingVo` & 类似的 `PmsMpSetting` 对象.
- [ ] **Mapper**: `PmsTenantSettingMapper`, `PmsMpSettingMapper` & XMLs.
- [ ] **Service**: `IPmsTenantSettingService`, `IPmsMpSettingService` & Impls (CRUD, 按 group/key 查询).
- [ ] **Controller**: `PmsTenantSettingController`, `PmsMpSettingController`.
- [ ] **13. 租户用户设备 (`pms_tenant_user_devices`)**: (用于民宿管理小程序推送等)
- [ ] **Domain**: `PmsTenantUserDevice`, `PmsTenantUserDeviceBo`, `PmsTenantUserDeviceVo`.
- [ ] **Mapper**: `PmsTenantUserDeviceMapper` & XML.
- [ ] **Service**: `IPmsTenantUserDeviceService` & Impl (CRUD, 设备注册/更新逻辑).
- [ ] **Controller**: `PmsTenantUserDeviceController`.
- [ ] **API文档**:
- [ ] 为所有Controller和DTO添加清晰的Swagger/Knife4j注解 (参考《最佳实践》Chapter 8.3)。
## 阶段 3: 前端开发 - 核心管理界面 [P0] (Soybean Admin Pro)
**通用前端开发规范 (参考《最佳实践》Chapter 5 & 7.2):**
- [ ] 遵循 Soybean Admin Pro 的项目结构和编码规范。
- [ ] 使用 Vue 3 Composition API + `<script setup>`。
- [ ] 为 props, emits, reactive state, methods 提供 TypeScript 类型。
- [ ] 优先使用框架提供的 Hooks (`useTable`, `useForm` 等) 和 Naive UI 组件。
- [ ] 组件样式使用 scoped CSS 或 CSS Modules。
- [ ] 使用 Cursor 辅助生成组件、分析代码、实现逻辑。
**具体功能模块开发:**
- [ ] **前端项目结构搭建** (参考《最佳实践》Chapter 5.2):
- [ ] 在 `src/views/`下创建 `pms` 目录，并为各管理功能创建子目录 (如 `room-type`, `room`, `order`, `folio` 等)。
- [ ] 在 `src/service/api/` 下创建 `pms` 目录，并为各后端Controller创建对应的 `ts` 服务文件 (如 `roomType.ts`, `order.ts`)。
- [ ] 在 `src/typings/api/` 下创建 `pms` 目录，定义与后端BO/VO对应的TypeScript接口。
- [ ] 创建 `src/router/routes/modules/pms.ts` 路由配置文件。
- [ ] (可选) 在 `src/store/modules/` 下创建 `pms` 目录，用于存放PMS相关的Pinia store。
- [ ] **Cursor辅助**: "请Cursor根据《最佳实践》前端项目结构，为PMS模块生成基础的目录和文件占位符。"
- [ ] **1. 房型管理界面 (`src/views/pms/room-type/`)**:
- [ ] **API服务**: `src/service/api/pms/roomType.ts` (实现对后端 `PmsRoomTypeController` 的调用)。
- [ ] **类型定义**: `src/typings/api/pms/roomType.ts` (定义 `PmsRoomTypeVo` 等接口)。
- [ ] **列表页**: `index.vue` (表格展示房型列表，支持搜索、分页、新增、编辑、删除按钮)。
- [ ] **表单组件**: `components/RoomTypeForm.vue` (用于新增/编辑房型的弹窗或抽屉表单，包含字段校验)。
- [ ] **2. 房间管理界面 (`src/views/pms/room/`)**:
- [ ] **API服务**: `src/service/api/pms/room.ts`.
- [ ] **类型定义**: `src/typings/api/pms/room.ts`.
- [ ] **列表页**: `index.vue` (展示房间列表，支持按房型、状态等搜索，操作按钮)。
- [ ] **表单组件**: `components/RoomForm.vue`.
- [ ] **房态图/日历视图基础**: (《PMS需求.md》4.2.1 [P0] 网格日历视图 - 此为复杂功能，P0阶段可能先实现基础列表和状态管理)
- [ ] **3. 订单管理界面 (`src/views/pms/order/`)**:
- [ ] **API服务**: `src/service/api/pms/order.ts`.
- [ ] **类型定义**: `src/typings/api/pms/order.ts`.
- [ ] **列表页**: `index.vue` (展示订单列表，支持按日期、状态、联系人等搜索)。
- [ ] **详情页/表单**: `detail.vue` 或 `components/OrderForm.vue` (用于创建/编辑/查看订单详情，包含订单项管理)。
- [ ] 实现订单状态变更操作。
- [ ] 关联联系人选择/创建。
- [ ] 关联房型/房间选择。
- [ ] **4. 财务-账单管理界面 (`src/views/pms/folio/`)**:
- [ ] **API服务**: `src/service/api/pms/folio.ts`.
- [ ] **类型定义**: `src/typings/api/pms/folio.ts`.
- [ ] **列表页/详情页**: (展示账单列表，点击可查看账单详情及交易流水)。
- [ ] **5. 财务-支付方式管理界面 (`src/views/pms/payment-method/`)**:
- [ ] **API服务**: `src/service/api/pms/paymentMethod.ts`.
- [ ] **类型定义**: `src/typings/api/pms/paymentMethod.ts`.
- [ ] **列表页**: `index.vue` (管理支付方式)。
- [ ] **表单组件**: `components/PaymentMethodForm.vue`.
- [ ] **6. 财务-附加费用项目管理界面 (`src/views/pms/extra-charge-item/`)**:
- [ ] **API服务**: `src/service/api/pms/extraChargeItem.ts`.
- [ ] **类型定义**: `src/typings/api/pms/extraChargeItem.ts`.
- [ ] **列表页**: `index.vue`.
- [ ] **表单组件**: `components/ExtraChargeItemForm.vue`.
- [ ] **7. 价格规则管理界面 (`src/views/pms/pricing-rule/`)**:
- [ ] **API服务**: `src/service/api/pms/pricingRule.ts`.
- [ ] **类型定义**: `src/typings/api/pms/pricingRule.ts`.
- [ ] **列表页**: `index.vue`.
- [ ] **表单组件**: `components/PricingRuleForm.vue`.
- [ ] **8. 租户/部门特定配置界面 (`src/views/pms/settings/`)**:
- [ ] (按需实现，可能集成到系统现有配置管理或单独页面)
- [ ] **路由配置 (`src/router/routes/modules/pms.ts`)**:
- [ ] 为以上所有PMS管理页面配置路由。
- [ ] 配置菜单项 (名称、图标、排序、权限标识) (参考《最佳实践》Chapter 5.3)。
- [ ] **Cursor辅助**: "请Cursor根据已创建的PMS前端页面，生成对应的 `pms.ts` 路由配置文件，并包含菜单定义。"
- [ ] **前端国际化**:
- [ ] 将所有界面上的文本添加到 `src/locales/langs/zh-CN.ts` 和 `en-US.ts` 中。
- [ ] **权限控制**:
- [ ] 使用 `useAuth` Hook 和权限指令，根据后端返回的权限标识控制按钮的显示/隐藏和页面的访问。
## 阶段 4: 民宿管理小程序 (Owner We App) [P0] - 基础功能
**技术栈**: Uni-App (参考《PMS需求.md》4.2.8)
- [ ] **项目搭建**: 创建 Uni-App 项目。
- [ ] **API对接**:
- [ ] 封装调用后端PMS接口的请求函数 (复用或参考前端Web的API服务)。
- [ ] 处理用户认证和token。
- [ ] **核心功能实现**:
- [ ] **房态查看**:
- [ ] 调用后端接口获取房态数据。
- [ ] 以列表或简化日历形式展示房间状态。
- [ ] **订单提醒**: (P0阶段可能为简单的订单列表，按预抵/预离排序)
- [ ] 调用后端接口获取订单列表。
- [ ] **日程查看 (今日预抵/预离)**:
- [ ] 筛选并展示当日预抵和预离的订单。
- [ ] **状态处理 (简单入住/退房操作)**:
- [ ] 提供按钮或操作，调用后端接口更新订单状态为 `checked_in` 或 `checked_out`。
- [ ] **数据概览 (核心收支数据)**: (P0阶段可简化，如当日收款总额)
- [ ] **门店切换功能**: 如果用户关联多个门店，允许切换当前操作的门店上下文。
- [ ] **UI/UX设计**: 简洁易用，符合移动端操作习惯。
- [ ] **打包与测试**: 在微信开发者工具和真机上进行测试。
## 阶段 5: 集成、测试与部署
- [ ] **后端单元测试**:
- [ ] 为核心Service层方法编写JUnit单元测试。
- [ ] **前后端联调** (参考《最佳实践》Chapter 6, 8.5):
- [ ] 逐个功能模块进行前后端接口联调，确保数据交互正确。
- [ ] **Cursor辅助**: "后端 `PmsOrderController` 的 `getOrderById` 接口返回数据格式与前端期望不一致，请Cursor分析可能的原因。"
- [ ] **系统集成测试**:
- [ ] 测试PMS模块与若依基础模块 (用户、部门、租户、权限、字典等) 的集成情况。
- [ ] 测试多租户、多部门数据隔离是否正确。
- [ ] **[P0] 功能验收测试 (UAT)**:
- [ ] 根据《PMS需求.md》中[P0]功能点，逐一进行业务场景测试。
- [ ] **Bug修复与回归测试**:
- [ ] **数据库菜单与权限SQL**:
- [ ] 编写将PMS模块前端路由配置的菜单信息插入到 `sys_menu` 表的SQL脚本。
- [ ] (如果需要新的权限标识) 编写插入到 `sys_permission` (或其他权限相关表) 的SQL脚本，并关联到角色。
- [ ] **文档完善**:
- [ ] 更新/创建PMS模块相关的开发文档、API文档 (确保Swagger/Knife4j是最新的)。
- [ ] **部署准备** (参考《最佳实践》Chapter 8.5):
- [ ] 后端打包 (如 `mvn package -DskipTests`)。
- [ ] 前端打包 (`pnpm build`)。
- [ ] 小程序打包。
- [ ] **部署到测试/生产环境并验证**。
## 阶段 6: 持续迭代与优化 [P1+]
- [ ] 根据《PMS需求.md》中的 [P1], [P2] 优先级，规划后续迭代功能。
- [ ] **订单管理[P1]**: 订单修改、款项管理、取消退款细则、自动化通知等。
- [ ] **联系人与会员管理[P1]**: 统一联系人档案、证件管理。
- [ ] **简易报表与分析[P1]**: 核心运营报表。
- [ ] 性能优化。
- [ ] 用户体验改进。
- [ ] 安全加固。
---
**注意**: 此ToDoList仅为初步计划，具体执行时需根据实际情况灵活调整。请频繁使用Cursor进行代码生成、分析、重构和问题排查，以提高开发效率和代码质量。