diff --git a/.cursor/settings.json b/.cursor/settings.json new file mode 100644 index 000000000..29c2d0319 --- /dev/null +++ b/.cursor/settings.json @@ -0,0 +1,22 @@ +{ + "cursor.cpp.intelliSenseEngine": "disabled", + "cursor.python.analysis.autoImportCompletions": false, + "cursor.java.completion.enabled": true, + "cursor.java.completion.maxResults": 50, + "cursor.indexing.excludePatterns": [ + "**/target/**", + "**/node_modules/**", + "**/.git/**", + "**/logs/**", + "**/temp/**", + "**/*.jar", + "**/.flattened-pom.xml", + "**/ruoyi-plus-soybean/node_modules/**", + "**/ruoyi-plus-soybean/dist/**", + "**/ruoyi-plus-soybean/.temp/**" + ], + "cursor.indexing.maxFileSize": "1MB", + "cursor.indexing.maxFiles": 10000, + "cursor.chat.maxTokens": 4000, + "cursor.general.enableLogging": false +} \ No newline at end of file diff --git a/.gitignore b/.gitignore index fa3ee9749..da2511950 100644 --- a/.gitignore +++ b/.gitignore @@ -40,9 +40,44 @@ nbdist/ *.log *.xml.versionsBackup *.swp +*.md +*.ps1 +*.mdc !*/build/*.java !*/build/*.html !*/build/*.xml .flattened-pom.xml + +###################################################################### +# Cursor优化 - 排除索引文件 +*.jar +*.war +*.ear +*.class +*.pyc +*.pyo +__pycache__/ +.DS_Store +Thumbs.db + +# 前端构建产物 +**/node_modules/ +**/dist/ +**/.temp/ +**/.nuxt/ +**/.next/ +**/.vuepress/dist/ + +# 日志和临时文件 +logs/ +temp/ +*.tmp +*.temp + +# 开发环境文件 +.env.local +.env.development.local +.env.test.local +.env.production.local diff --git a/.mvn/jvm.config b/.mvn/jvm.config new file mode 100644 index 000000000..2cbf0d6b4 --- /dev/null +++ b/.mvn/jvm.config @@ -0,0 +1,6 @@ +-Xmx6g +-Xms3g +-XX:+UseG1GC +-XX:+UnlockExperimentalVMOptions +-Dmaven.artifact.threads=12 +-Dmaven.compile.fork=true diff --git a/.mvn/maven.config b/.mvn/maven.config new file mode 100644 index 000000000..1d81156dd --- /dev/null +++ b/.mvn/maven.config @@ -0,0 +1,6 @@ +-T 2C +-DskipTests=true +-Dmaven.compile.fork=true +-Dmaven.javadoc.skip=true +-Dmaven.source.skip=true +-Dmaven.test.skip=true diff --git a/.vscode/keybindings.json b/.vscode/keybindings.json new file mode 100644 index 000000000..35fe29e38 --- /dev/null +++ b/.vscode/keybindings.json @@ -0,0 +1,22 @@ +[ + { + "key": "f5", + "command": "workbench.action.tasks.runTask", + "args": "🧠 智能启动 (推荐)" + }, + { + "key": "ctrl+f6", + "command": "workbench.action.tasks.runTask", + "args": "⚡ 零编译启动" + }, + { + "key": "ctrl+alt+x", + "command": "workbench.action.tasks.runTask", + "args": "🛑 停止后台编译" + }, + { + "key": "ctrl+alt+b", + "command": "workbench.action.tasks.runTask", + "args": "📦 PMS快速编译" + } +] diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 000000000..6765c3f68 --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,59 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "type": "java", + "name": "DromaraApplication", + "request": "launch", + "mainClass": "org.dromara.DromaraApplication", + "projectName": "ruoyi-admin" + }, + { + "type": "java", + "name": "RuoYi Application", + "request": "launch", + "mainClass": "org.dromara.DromaraApplication", + "projectName": "ruoyi-admin", + "args": "", + "vmArgs": "-Xmx2g -Xms1g -XX:+UseG1GC -Dspring.profiles.active=dev -Dfile.encoding=UTF-8", + "env": { + "JAVA_TOOL_OPTIONS": "-Dfile.encoding=UTF-8 -Duser.timezone=Asia/Shanghai" + }, + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen" + }, + { + "type": "java", + "name": "RuoYi Debug", + "request": "launch", + "mainClass": "org.dromara.DromaraApplication", + "projectName": "ruoyi-admin", + "args": "", + "vmArgs": "-Xmx2g -Xms1g -XX:+UseG1GC -Dspring.profiles.active=dev -Dfile.encoding=UTF-8 -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005", + "env": { + "JAVA_TOOL_OPTIONS": "-Dfile.encoding=UTF-8 -Duser.timezone=Asia/Shanghai" + }, + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen" + }, + { + "type": "java", + "name": "Remote Debug", + "request": "attach", + "hostName": "localhost", + "port": 5005, + "projectName": "ruoyi-admin" + }, + { + "type": "java", + "name": "JUnit Tests", + "request": "launch", + "mainClass": "", + "projectName": "ruoyi-pms", + "args": "", + "vmArgs": "-Dspring.profiles.active=test", + "env": {}, + "console": "integratedTerminal" + } + ] +} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json index d53ecaf3d..5b46556d9 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,4 +1,119 @@ { - "java.compile.nullAnalysis.mode": "automatic", - "java.configuration.updateBuildConfiguration": "automatic" + "java.configuration.runtimes": [ + { + "name": "JavaSE-21", + "path": "D:\\jdk", + "default": true + } + ], + "java.compile.nullAnalysis.mode": "disabled", + "java.autobuild.enabled": false, + "java.maxConcurrentBuilds": 1, + "java.import.maven.enabled": false, + "java.import.gradle.enabled": false, + "maven.executable.path": "D:\\maven3.9\\bin\\mvn.cmd", + "maven.terminal.useJavaHome": true, + "maven.terminal.customEnv": [ + { + "environmentVariable": "MAVEN_OPTS", + "value": "-Xmx6g -XX:+UseG1GC -Dmaven.artifact.threads=12" + }, + { + "environmentVariable": "JAVA_TOOL_OPTIONS", + "value": "-Dfile.encoding=UTF-8 -Duser.timezone=Asia/Shanghai -XX:+UseG1GC" + } + ], + "java.jdt.ls.vmargs": "-XX:+UseG1GC -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -Dsun.zip.disableMemoryMapping=true -Xmx6g -Xms2g -XX:+UnlockExperimentalVMOptions", + "java.import.maven.offline": true, + "java.maven.downloadSources": false, + "java.maven.downloadJavadoc": false, + "java.referencesCodeLens.enabled": false, + "java.implementationsCodeLens.enabled": false, + "java.signatureHelp.enabled": true, + "java.contentProvider.preferred": "fernflower", + "java.server.launchMode": "Standard", + "java.sources.organizeImports.starThreshold": 99, + "java.sources.organizeImports.staticStarThreshold": 99, + "java.saveActions.organizeImports": false, + "java.completion.maxResults": 50, + "java.completion.enabled": true, + "java.configuration.updateBuildConfiguration": "disabled", + "java.configuration.checkProjectSettingsExclusions": false, + "java.project.referencedLibraries": [], + "java.project.sourcePaths": [], + "java.project.outputPath": "", + "java.dependency.autoRefresh": false, + "java.dependency.refreshDelay": 2000, + "java.dependency.packagePresentation": "flat", + "java.project.importOnFirstTimeStartup": "disabled", + "java.project.importHint": false, + "java.workspace.filter": false, + "java.clean.workspace": false, + "java.format.enabled": false, + "java.codeGeneration.hashCodeEquals.useJava7Objects": true, + "java.codeGeneration.useBlocks": true, + "java.progressReports.enabled": false, + "java.recommendations.enabled": false, + "java.references.includeAccessors": false, + "java.references.includeDecompiledSources": false, + "java.typeHierarchy.lazyLoad": true, + "java.selectionRange.enabled": false, + "java.showBuildStatusOnStart.enabled": false, + "java.silentNotification": true, + "files.exclude": { + "**/target": true, + "**/.idea": true, + "**/node_modules": true, + "**/logs": true, + "**/temp": true, + "**/.git": true, + "**/ruoyi-plus-soybean/node_modules": true, + "**/ruoyi-plus-soybean/dist": true, + "**/ruoyi-plus-soybean/.temp": true, + "**/*.jar": true, + "**/.flattened-pom.xml": true, + "**/.classpath": true, + "**/.project": true, + "**/.settings": true, + "**/bin": true + }, + "search.exclude": { + "**/target": true, + "**/node_modules": true, + "**/logs": true, + "**/.git": true, + "**/ruoyi-plus-soybean/node_modules": true, + "**/*.jar": true, + "**/.flattened-pom.xml": true, + "**/.classpath": true, + "**/.project": true, + "**/.settings": true, + "**/bin": true + }, + "files.watcherExclude": { + "**/target/**": true, + "**/node_modules/**": true, + "**/.git/objects/**": true, + "**/.git/subtree-cache/**": true, + "**/logs/**": true, + "**/temp/**": true, + "**/ruoyi-plus-soybean/node_modules/**": true, + "**/ruoyi-plus-soybean/dist/**": true, + "**/*.jar": true, + "**/.flattened-pom.xml": true, + "**/.classpath": true, + "**/.project": true, + "**/.settings/**": true, + "**/bin/**": true + }, + "java.debug.settings.onBuildFailureProceed": true, + "java.eclipse.downloadSources": false, + "java.maven.updateSnapshots": false, + "java.import.maven.disableTestClasspathFlag": true, + "files.autoSave": "off", + "editor.formatOnSave": false, + "editor.codeActionsOnSave": {}, + "extensions.autoUpdate": false, + "extensions.autoCheckUpdates": false, + "update.mode": "none" } \ No newline at end of file diff --git a/.vscode/snippets/java.json b/.vscode/snippets/java.json new file mode 100644 index 000000000..100d702f6 --- /dev/null +++ b/.vscode/snippets/java.json @@ -0,0 +1,177 @@ +{ + "RuoYi Controller": { + "prefix": "rycontroller", + "body": [ + "@Api(tags = \"${1:模块}管理\")", + "@RestController", + "@RequestMapping(\"/${2:module}/${3:entity}\")", + "@RequiredArgsConstructor", + "public class ${4:Entity}Controller {", + "", + " private final I${4:Entity}Service ${5:entity}Service;", + "", + " @GetMapping(\"/list\")", + " @ApiOperation(\"查询${1:模块}列表\")", + " @SaCheckPermission(\"${2:module}:${3:entity}:list\")", + " public TableDataInfo<${4:Entity}Vo> list(${4:Entity}Bo bo, PageQuery pageQuery) {", + " return ${5:entity}Service.queryPageList(bo, pageQuery);", + " }", + "", + " @GetMapping(\"/{${6:id}}\")", + " @ApiOperation(\"获取${1:模块}详细信息\")", + " @SaCheckPermission(\"${2:module}:${3:entity}:query\")", + " public R<${4:Entity}Vo> getInfo(@PathVariable Long ${6:id}) {", + " return R.ok(${5:entity}Service.queryById(${6:id}));", + " }", + "", + " @PostMapping", + " @ApiOperation(\"新增${1:模块}\")", + " @SaCheckPermission(\"${2:module}:${3:entity}:add\")", + " @Log(title = \"${1:模块}管理\", businessType = BusinessType.INSERT)", + " public R add(@Validated(AddGroup.class) @RequestBody ${4:Entity}Bo bo) {", + " return toAjax(${5:entity}Service.insertByBo(bo));", + " }", + "", + " @PutMapping", + " @ApiOperation(\"修改${1:模块}\")", + " @SaCheckPermission(\"${2:module}:${3:entity}:edit\")", + " @Log(title = \"${1:模块}管理\", businessType = BusinessType.UPDATE)", + " public R edit(@Validated(EditGroup.class) @RequestBody ${4:Entity}Bo bo) {", + " return toAjax(${5:entity}Service.updateByBo(bo));", + " }", + "", + " @DeleteMapping(\"/{${6:id}s}\")", + " @ApiOperation(\"删除${1:模块}\")", + " @SaCheckPermission(\"${2:module}:${3:entity}:remove\")", + " @Log(title = \"${1:模块}管理\", businessType = BusinessType.DELETE)", + " public R remove(@PathVariable Long[] ${6:id}s) {", + " return toAjax(${5:entity}Service.deleteWithValidByIds(List.of(${6:id}s), true));", + " }", + "", + " $0", + "}" + ], + "description": "创建RuoYi Controller模板" + }, + "RuoYi Service": { + "prefix": "ryservice", + "body": [ + "@Service", + "@RequiredArgsConstructor", + "public class ${1:Entity}ServiceImpl implements I${1:Entity}Service {", + "", + " private final ${1:Entity}Mapper baseMapper;", + "", + " @Override", + " public TableDataInfo<${1:Entity}Vo> queryPageList(${1:Entity}Bo bo, PageQuery pageQuery) {", + " LambdaQueryWrapper<${1:Entity}> lqw = buildQueryWrapper(bo);", + " Page<${1:Entity}Vo> result = baseMapper.selectVoPage(pageQuery.build(), lqw);", + " return TableDataInfo.build(result);", + " }", + "", + " @Override", + " public ${1:Entity}Vo queryById(Long ${2:id}) {", + " return baseMapper.selectVoById(${2:id});", + " }", + "", + " @Override", + " @Transactional(rollbackFor = Exception.class)", + " public Boolean insertByBo(${1:Entity}Bo bo) {", + " ${1:Entity} add = MapstructUtils.convert(bo, ${1:Entity}.class);", + " validEntityBeforeSave(add);", + " boolean flag = baseMapper.insert(add) > 0;", + " if (flag) {", + " bo.set${3:Id}(add.get${3:Id}());", + " }", + " return flag;", + " }", + "", + " @Override", + " @Transactional(rollbackFor = Exception.class)", + " public Boolean updateByBo(${1:Entity}Bo bo) {", + " ${1:Entity} update = MapstructUtils.convert(bo, ${1:Entity}.class);", + " validEntityBeforeSave(update);", + " return baseMapper.updateById(update) > 0;", + " }", + "", + " @Override", + " @Transactional(rollbackFor = Exception.class)", + " public Boolean deleteWithValidByIds(Collection ids, Boolean isValid) {", + " if (isValid) {", + " // 做一些业务上的校验,判断是否需要校验", + " }", + " return baseMapper.deleteByIds(ids) > 0;", + " }", + "", + " private LambdaQueryWrapper<${1:Entity}> buildQueryWrapper(${1:Entity}Bo bo) {", + " Map params = bo.getParams();", + " LambdaQueryWrapper<${1:Entity}> lqw = Wrappers.lambdaQuery();", + " // 添加查询条件", + " return lqw;", + " }", + "", + " private void validEntityBeforeSave(${1:Entity} entity) {", + " // 做一些数据校验,如唯一约束", + " }", + "", + " $0", + "}" + ], + "description": "创建RuoYi Service实现类模板" + }, + "RuoYi Entity": { + "prefix": "ryentity", + "body": [ + "@Data", + "@EqualsAndHashCode(callSuper = true)", + "@TableName(\"${1:table_name}\")", + "public class ${2:Entity} extends TenantEntity {", + "", + " /**", + " * ${3:主键ID}", + " */", + " @TableId(type = IdType.ASSIGN_ID)", + " private Long ${4:id};", + "", + " $0", + "}" + ], + "description": "创建RuoYi Entity模板" + }, + "RuoYi BO": { + "prefix": "rybo", + "body": [ + "@Data", + "@EqualsAndHashCode(callSuper = true)", + "@AutoMapper(target = ${1:Entity}.class, reverseConvertGenerate = false)", + "public class ${1:Entity}Bo extends BaseEntity {", + "", + " /**", + " * ${2:主键ID}", + " */", + " @NotNull(message = \"${2:主键ID}不能为空\", groups = { EditGroup.class })", + " private Long ${3:id};", + "", + " $0", + "}" + ], + "description": "创建RuoYi BO模板" + }, + "RuoYi VO": { + "prefix": "ryvo", + "body": [ + "@Data", + "@AutoMapper(target = ${1:Entity}.class)", + "public class ${1:Entity}Vo {", + "", + " /**", + " * ${2:主键ID}", + " */", + " private Long ${3:id};", + "", + " $0", + "}" + ], + "description": "创建RuoYi VO模板" + } +} \ No newline at end of file diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 000000000..03bb13262 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,88 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "🧠 智能启动 (推荐)", + "type": "shell", + "command": ".\\dev-start.ps1", + "group": "build", + "presentation": { + "echo": true, + "reveal": "always", + "focus": false, + "panel": "dedicated" + }, + "isBackground": true, + "problemMatcher": { + "pattern": { + "regexp": "^.*$", + "file": 1, + "location": 2, + "message": 3 + }, + "background": { + "activeOnStart": true, + "beginsPattern": "^.*启动应用.*", + "endsPattern": "^.*Started.*in.*seconds.*" + } + } + }, + { + "label": "⚡ 零编译启动", + "type": "shell", + "command": ".\\quick-start.ps1", + "group": "build", + "presentation": { + "echo": true, + "reveal": "always", + "focus": false, + "panel": "dedicated" + }, + "isBackground": true, + "problemMatcher": { + "pattern": { + "regexp": "^.*$", + "file": 1, + "location": 2, + "message": 3 + }, + "background": { + "activeOnStart": true, + "beginsPattern": "^.*启动应用.*", + "endsPattern": "^.*Started.*in.*seconds.*" + } + } + }, + { + "label": "🛑 停止后台编译", + "type": "shell", + "command": ".\\stop-background-compile.ps1", + "group": "build", + "presentation": { + "echo": true, + "reveal": "always", + "focus": false, + "panel": "shared", + "showReuseMessage": true, + "clear": false + } + }, + { + "label": "📦 PMS快速编译", + "type": "shell", + "command": ".\\pms-compile.ps1", + "group": "build", + "presentation": { + "echo": true, + "reveal": "always", + "focus": false, + "panel": "shared", + "showReuseMessage": true, + "clear": false + }, + "problemMatcher": [ + "$maven-compiler-java" + ] + } + ] +} diff --git a/docs/basic/PMS数据模型.md b/docs/basic/PMS数据模型.md index 0a7d2539a..ef8c08998 100644 --- a/docs/basic/PMS数据模型.md +++ b/docs/basic/PMS数据模型.md @@ -1,15 +1,21 @@ -## 云宿居 PMS 系统 - PMS核心数据模型 (最终版 v_ry_final_4.0) +## 云宿居 PMS 系统 - PMS核心数据模型 (最终版 v5.7) **快速导航：** - [1. 引言](#1-引言) -- [2. PMS 核心E-R图 (最终版 - 简化)](#2-pms-核心er图-最终版---简化) +- [2. PMS 核心E-R图 (最终版)](#2-pms-核心er图-最终版) - [3. 表结构定义](#3-表结构定义) - [3.1 SaaS平台与系统基础表 (源自若依)](#31-saas平台与系统基础表-源自若依) - - [3.2 PMS核心业务表](#32-pms核心业务表) - - [3.3 公共数据模型 (PMS相关)](#33-公共数据模型-pms相关) + - [3.2 客户管理表 (租户级共享/门店级)](#32-客户管理表-租户级共享门店级) + - [3.3 房间管理表 (门店级隔离)](#33-房间管理表-门店级隔离) + - [3.4 价格管理表 (门店级隔离)](#34-价格管理表-门店级隔离) + - [3.5 订单管理表 (门店级隔离)](#35-订单管理表-门店级隔离) + - [3.6 财务管理表 (门店级隔离)](#36-财务管理表-门店级隔离) + - [3.7 合作方管理表 (全局共享/租户级)](#37-合作方管理表-全局共享租户级) + - [3.8 系统配置表 (租户级/门店级)](#38-系统配置表-租户级门店级) - [4. 主要业务实体状态流转](#4-主要业务实体状态流转) -- [5. 核心业务枚举值定义 (PMS主要部分)](#5-核心业务枚举值定义-pms主要部分) -- [6. 索引命名与规范建议](#6-索引命名与规范建议) +- [5. 核心业务枚举值定义](#5-核心业务枚举值定义) +- [6. 数据权限控制与索引设计](#6-数据权限控制与索引设计) +- [7. 版本变更记录](#7-版本变更记录) ## 1. 引言 @@ -19,186 +25,100 @@ **核心原则：** 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层面的适配。 +3. **所有PMS业务表都包含 `tenant_id` 字段，支持标准多租户拦截器自动过滤。** +4. **数据隔离层级:** + - 租户级隔离：客户信息在租户内共享，使用 `tenant_id` 标准多租户拦截器 + - 门店级隔离：订单、房间、财务等核心业务数据按门店隔离，包含 `dept_id` 字段 + - 门店级共享：客户标签使用 `dept_id`，可设为NULL实现租户级共享 +5. **多租户拦截器排除原则：仅排除系统级全局表和特殊处理表** +6. PMS业务表中的枚举字段，统一使用 `VARCHAR(50)` 存储描述性字符串以增强可读性和扩展性。 -### 1.2 命名与设计约定 (PMS新增表部分) -* **表命名:** `pms_` (PMS核心业务表)，`cmn_` (公共模块)。若依表使用其原生 `sys_` 前缀。 +### 1.2 命名与设计约定 +* **表命名:** `pms_` (PMS核心业务表)。若依表使用其原生 `sys_` 前缀。 * **字段命名:** `snake_case` (小写下划线)。 * **主键 (PK):** - * PMS核心业务实体: **`BIGINT` AUTO_INCREMENT**。 - * 日志类高频写入表: `BIGINT` AUTO_INCREMENT。 -* **部门ID `dept_id`:** `bigint(20)` (同 `sys_dept.dept_id`)，在PMS业务表中非空，用于标识数据归属于哪个门店。 + * PMS核心业务实体: `BIGINT AUTO_INCREMENT`。 + * 日志类高频写入表: `BIGINT AUTO_INCREMENT`。 +* **租户ID `tenant_id`:** `VARCHAR(20)` (同 `sys_tenant.tenant_id`)，在PMS业务表中非空。 +* **部门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') + * `create_dept` (BIGINT(20) NULLABLE, COMMENT '创建记录的操作员所属部门，关联 sys_dept.dept_id') * **软删除策略 (对齐若依):** - * `del_flag` (CHAR(1) DEFAULT '0' NOT NULL, COMMENT '删除标志（0代表存在 1代表删除）')。 + * `del_flag` (`CHAR(1) DEFAULT '0' NOT NULL`, COMMENT '删除标志（0代表存在 1代表删除）')。 * **状态与枚举字段 (PMS优化):** * PMS业务表中的枚举字段，统一使用 `VARCHAR(50)` 存储描述性枚举字符串。 -## 2. PMS 核心E-R图 (最终版 - 简化) +## 2. PMS 核心E-R图 (最终版) ```mermaid erDiagram %% --- 若依基础表 (关键部分) --- - sys_tenant { - varchar(20) tenant_id PK "租户编号 (业务主键)" - bigint id "物理主键, 若依内部使用" - varchar(255) company_name "企业/民宿名称" - } + sys_tenant {} + sys_dept {} + sys_user {} - sys_dept { - bigint dept_id PK "部门ID" - varchar(20) tenant_id FK "关联 sys_tenant.tenant_id" - varchar(30) dept_name "部门名称" - } + %% --- 客户与合作方表 --- + pms_customer_contacts {} + pms_contact_tags {} + pms_contact_tag_relations {} + pms_suppliers {} + pms_partners {} - 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 "角色名称" - } + %% --- PMS Core Business Tables (门店级隔离) --- + pms_room_types {} + pms_room_rooms {} + pms_room_locks {} + pms_core_orders {} + pms_order_status_history {} + pms_order_guests {} + pms_core_order_items {} + pms_core_channels {} + pms_finance_folios {} + pms_finance_transactions {} + pms_finance_payment_methods {} + pms_finance_extra_charge_items {} + pms_room_pricing_rules {} + pms_pricing_calculations {} + pms_special_date_pricing {} + pms_room_inventory_snapshot {} - %% --- 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" - } + %% --- 系统配置相关表 --- + pms_tenant_settings {} + pms_mp_settings {} + pms_tenant_user_devices {} %% --- 若依基础表关联 --- sys_tenant ||--o{ sys_dept : "包含门店/部门" sys_tenant ||--o{ sys_user : "的主要租户" - sys_tenant ||--o{ sys_role : "定义角色归属" sys_dept ||--o{ sys_user : "员工属于门店" + %% --- 客户相关表关联 --- + sys_tenant ||--o{ pms_customer_contacts : "拥有客户联系人" + pms_customer_contacts ||--o{ pms_contact_tag_relations : "联系人标签关联" + pms_contact_tags ||--o{ pms_contact_tag_relations : "标签关联联系人" + sys_tenant ||--o{ pms_contact_tags : "拥有标签" + sys_dept ||--o{ pms_contact_tags : "门店级标签" + + %% --- 供应商合作伙伴关联 --- + sys_tenant ||--o{ pms_suppliers : "拥有供应商" + sys_tenant ||--o{ pms_partners : "拥有合作伙伴" + %% --- 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_tenant ||--o{ pms_room_types : "定义房型" + sys_tenant ||--o{ pms_core_orders : "拥有订单" + sys_tenant ||--o{ pms_finance_folios : "拥有账单" + + sys_dept ||--o{ pms_room_types : "门店房型" + sys_dept ||--o{ pms_room_rooms : "门店房间" + sys_dept ||--o{ pms_core_orders : "门店订单" + sys_dept ||--o{ pms_tenant_settings : "门店配置" + sys_dept ||--o{ pms_mp_settings : "门店小程序配置" sys_user ||--o{ pms_tenant_user_devices : "注册设备" @@ -206,6 +126,9 @@ erDiagram 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_types ||--o{ pms_pricing_calculations : "价格计算记录" + pms_room_types o|--o{ pms_special_date_pricing : "特殊日期价格" + pms_room_types ||--o{ pms_room_inventory_snapshot : "库存快照" pms_room_rooms ||--o{ pms_room_locks : "可被锁定" pms_room_rooms o|--o{ pms_core_orders : "被分配房间" @@ -213,420 +136,646 @@ erDiagram pms_core_orders ||--o{ pms_core_order_items : "包含项目" pms_core_orders ||--|| pms_finance_folios : "生成账单" - cmn_contacts o|--o{ pms_core_orders : "是主要联系人" + pms_core_orders ||--o{ pms_order_status_history : "状态变更历史" + pms_core_orders ||--o{ pms_order_guests : "入住客人信息" + pms_customer_contacts o|--o{ pms_core_orders : "是主要客户" pms_core_channels o|--o{ pms_core_orders : "是来源渠道" + pms_core_channels o|--o{ pms_pricing_calculations : "价格计算渠道" 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_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 客户管理表 (租户级共享/门店级) -### 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的住客。 +#### 3.2.1 `pms_customer_contacts` - 客户联系人表 +* 业务描述: 存储租户级共享的客户联系人信息，包括个人客户、团队联系人、企业客户、会员等。 +* 数据隔离: **租户级共享，使用标准多租户拦截器，租户内所有门店可见** * 主键: `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) +* 核心字段: + * `contact_id` - 联系人唯一ID + * `tenant_id` - 租户ID (多租户拦截器自动过滤) + * `contact_type` - 联系人类型 (individual_guest/group_leader/corporate_contact/vip_member/repeat_guest/marketing_tag/behavior_tag) + * `full_name` - 联系人姓名 + * `phone_number` - 主要联系电话 + * `email` - 电子邮件地址 + * `wechat_openid` - 微信OpenID + * `wechat_unionid` - 微信UnionID + * `gender` - 性别 + * `date_of_birth` - 出生日期 + * `id_type` - 证件类型 + * `id_number_encrypted` - 证件号码 (加密存储) + * `nationality_country_code` - 国籍代码 + * `address_province` - 地址-省份 + * `address_city` - 地址-城市 + * `address_district` - 地址-区县 + * `address_detail` - 地址-详细地址 + * `postal_code` - 邮政编码 + * `contact_status` - 联系人状态 (active/inactive/blacklisted/pending_verification) + * `member_level` - 会员等级 + * `total_stays` - 总入住次数 + * `total_amount` - 总消费金额 (DECIMAL(10,2)) + * `last_stay_date` - 最后入住日期 + * `remarks` - 备注信息 + * `create_dept` - 创建部门 (BIGINT, 关联sys_dept.dept_id) + * `create_by` - 创建者 (BIGINT) + * `create_time` - 创建时间 (DATETIME) + * `update_by` - 更新者 (BIGINT) + * `update_time` - 更新时间 (DATETIME) + * `del_flag` - 删除标志 (CHAR(1) DEFAULT '0' NOT NULL) +* 索引设计: + * `idx_pms_cc_tenant` (tenant_id) + * `idx_pms_cc_tenant_name` (tenant_id, full_name) + * `idx_pms_cc_tenant_phone` (tenant_id, phone_number) + * `idx_pms_cc_tenant_status_type` (tenant_id, contact_status, contact_type) -#### 3.3.2 `cmn_contact_tags` - 联系人标签表 -* 业务描述: 定义可用于分类和标记联系人的标签。 +#### 3.2.2 `pms_contact_tags` - 联系人标签表 +* 业务描述: 存储客户联系人标签信息，支持门店级或租户级标签。 +* 数据隔离: **使用标准多租户拦截器，dept_id为NULL时表示租户级标签** * 主键: `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) +* 核心字段: + * `tag_id` - 标签唯一ID + * `tenant_id` - 租户ID (多租户拦截器自动过滤) + * `dept_id` - 部门ID (NULL表示租户级标签，非NULL表示门店级标签) + * `name` - 标签名称 + * `color` - 标签显示颜色 + * `category` - 标签分类 (contact_level/contact_source/contact_preference/service_record/marketing_tag/behavior_tag) + * `description` - 标签描述 + * `is_system` - 是否为系统预设标签 + * `sort_order` - 排序值 + * `create_dept` - 创建部门 (BIGINT, 关联sys_dept.dept_id) + * `create_by` - 创建者 (BIGINT) + * `create_time` - 创建时间 (DATETIME) + * `update_by` - 更新者 (BIGINT) + * `update_time` - 更新时间 (DATETIME) + * `del_flag` - 删除标志 (CHAR(1) DEFAULT '0' NOT NULL) +* 索引设计: + * `idx_pms_ct_tenant_dept` (tenant_id, dept_id) + * `idx_pms_ct_tenant_dept_name_category` (tenant_id, dept_id, name, category) + * `idx_pms_ct_category` (category) -#### 3.3.3 `cmn_contact_tag_relations` - 联系人标签关联表 -* 业务描述: 实现联系人与标签的多对多关系。 +#### 3.2.3 `pms_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) +* 核心字段: + * `relation_id` - 关联唯一ID + * `tenant_id` - 租户ID (多租户拦截器自动过滤) + * `contact_id` - 联系人ID (关联 pms_customer_contacts.contact_id) + * `tag_id` - 标签ID (关联 pms_contact_tags.tag_id) + * `create_dept` - 创建部门 (BIGINT, 关联sys_dept.dept_id) + * `create_by` - 创建者 (BIGINT) + * `create_time` - 创建时间 (DATETIME) + * `del_flag` - 删除标志 (CHAR(1) DEFAULT '0' NOT NULL) +* 索引设计: + * `idx_pms_ctr_tenant_contact` (tenant_id, contact_id) + * `idx_pms_ctr_tenant_tag` (tenant_id, tag_id) + * `idx_pms_ctr_contact_id` (contact_id) + * `idx_pms_ctr_tag_id` (tag_id) + * UNIQUE KEY `unq_pms_ctr_tenant_contact_tag` (tenant_id, contact_id, tag_id, del_flag) + +### 3.3 房间管理表 (门店级隔离) + +#### 3.3.1 `pms_room_types` - 房型表 +* 业务描述: 存储各门店定义的房型信息。 +* 数据隔离: 门店级隔离，使用多租户拦截器 +* 主键: `room_type_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `room_type_id` - 房型唯一ID + * `tenant_id` - 租户ID (多租户拦截器使用) + * `dept_id` - 部门ID (门店级权限控制, 关联 sys_dept.dept_id) + * `type_name` - 房型名称 + * `type_code` - 房型代码 + * `description` - 房型描述 + * `standard_occupancy` - 标准入住人数 + * `max_occupancy` - 最大入住人数 + * `room_area` - 房间面积(平方米) (DECIMAL(8,2)) + * `bed_configuration` - 床型配置 + * `amenities` - 房间设施 + * `default_price` - 默认价格 (DECIMAL(10,2)) + * `status` - 房型状态 (active/inactive/maintenance) + * `sort_order` - 排序值 + * `images` - 房型图片 + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 +* 索引设计: + * `idx_room_type_tenant` (tenant_id) + * `idx_room_type_dept` (dept_id) + * `idx_room_type_status` (status) + * `uk_room_type_code_dept` (type_code, dept_id, del_flag) -- 唯一约束 + +#### 3.3.2 `pms_room_rooms` - 房间表 +* 业务描述: 存储各门店的具体房间信息。 +* 数据隔离: 门店级隔离，使用多租户拦截器 +* 主键: `room_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `room_id` - 房间唯一ID + * `tenant_id` - 租户ID (多租户拦截器使用) + * `dept_id` - 部门ID (门店级权限控制, 关联 sys_dept.dept_id) + * `room_type_id` - 房型ID (关联 pms_room_types.room_type_id) + * `room_number` - 房间号 + * `floor` - 楼层 + * `room_status` - 房间物理状态 (available/occupied/maintenance/out_of_order) + * `cleaning_status` - 清洁状态 (clean/dirty/cleaning/inspecting) + * `description` - 房间描述 + * `special_amenities` - 房间特殊设施 + * `last_cleaning_time` - 最后清洁时间 + * `last_maintenance_time` - 最后维护时间 + * `status_remarks` - 房间状态备注 + * `sort_order` - 排序值 + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 +* 索引设计: + * `idx_room_tenant` (tenant_id) + * `idx_room_dept` (dept_id) + * `idx_room_type` (room_type_id) + * `idx_room_status` (room_status) + * `idx_room_cleaning` (cleaning_status) + * `uk_room_number_dept` (room_number, dept_id, del_flag) -- 同门店房间号唯一 +* 外键约束: + * `fk_room_room_type` FOREIGN KEY (room_type_id) REFERENCES pms_room_types(room_type_id) + +#### 3.3.3 `pms_room_locks` - 房间锁定表 +* 业务描述: 存储房间锁定记录，支持维护、清洁、管理等多种锁定类型。 +* 数据隔离: 门店级隔离，使用多租户拦截器 +* 主键: `lock_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `lock_id` - 锁定记录唯一ID + * `tenant_id` - 租户ID (多租户拦截器使用) + * `dept_id` - 部门ID (门店级权限控制, 关联 sys_dept.dept_id) + * `room_id` - 房间ID (关联 pms_room_rooms.room_id) + * `lock_type` - 锁定类型 (maintenance/cleaning/management/malfunction) + * `lock_start_time` - 锁定开始时间 + * `lock_end_time` - 锁定结束时间 + * `lock_reason` - 锁定原因 + * `lock_status` - 锁定状态 (active/unlocked/expired) + * `unlock_time` - 解锁时间 + * `unlock_by` - 解锁操作人 + * `unlock_reason` - 解锁原因 + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 +* 索引设计: + * `idx_room_lock_tenant` (tenant_id) + * `idx_room_lock_dept` (dept_id) + * `idx_room_lock_room` (room_id) + * `idx_room_lock_status` (lock_status) + * `idx_room_lock_time` (lock_start_time, lock_end_time) +* 外键约束: + * `fk_room_lock_room` FOREIGN KEY (room_id) REFERENCES pms_room_rooms(room_id) + +### 3.4 价格管理表 (门店级隔离) + +#### 3.4.1 `pms_room_pricing_rules` - 价格规则表 +* 业务描述: 存储动态定价规则。 +* 数据隔离: 门店级隔离 (dept_id可空表示租户级通用规则，具体以业务为准，当前ER图定义是门店级) +* 主键: `rule_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `rule_id` - 价格规则唯一ID + * `tenant_id` - 租户ID + * `dept_id` - 部门ID (门店，可空，关联 sys_dept.dept_id) + * `name` - 规则名称 + * `room_type_id` - 房型ID (可空, 关联 pms_room_types.room_type_id) + * `date_range_start` - 适用开始日期 + * `date_range_end` - 适用结束日期 + * `days_of_week_json` - 适用星期 (JSON, e.g., [1,2,7]) + * `min_length_of_stay` - 最小入住天数 + * `max_length_of_stay` - 最大入住天数 + * `price_adjustment_type` - 调整类型 + * `adjustment_value` - 调整值 (DECIMAL(10,2)) + * `priority` - 规则优先级 + * `status` - 状态 (active/inactive) + * `channel_restrictions_json` - 渠道限制 (JSON数组) + * `guest_count_min` - 最小客人数 (INT) + * `guest_count_max` - 最大客人数 (INT) + * `advance_booking_days_min` - 最小提前预订天数 (INT) + * `advance_booking_days_max` - 最大提前预订天数 (INT) + * `rule_description` - 规则描述 (VARCHAR(500)) + * `is_combinable` - 是否可与其他规则叠加 (BOOLEAN, DEFAULT TRUE) + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 +* 索引设计: + * `idx_pms_rpr_tenant_dept_status_priority` (tenant_id, dept_id, status, priority) + * `idx_pms_rpr_tenant_dept_rt_dates` (tenant_id, dept_id, room_type_id, date_range_start, date_range_end) + * `idx_pms_rpr_tenant_dept_combinable` (tenant_id, dept_id, is_combinable, status) + +#### 3.4.2 `pms_pricing_calculations` - 价格计算历史表 +* 业务描述: 记录每次价格计算的详细过程和结果，支持价格审计和趋势分析。 +* 数据隔离: 门店级隔离，使用多租户拦截器 +* 主键: `calculation_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `calculation_id` - 计算记录唯一ID + * `tenant_id` - 租户ID + * `dept_id` - 部门ID (门店, 关联 sys_dept.dept_id) + * `room_type_id` - 房型ID (关联 pms_room_types.room_type_id) + * `check_in_date` - 入住日期 (DATE, 非空) + * `check_out_date` - 离店日期 (DATE, 非空) + * `base_price` - 基础价格 (DECIMAL(10,2), 非空) + * `final_price` - 最终价格 (DECIMAL(10,2), 非空) + * `applied_rules_json` - 应用的规则详情 (JSON) + * `calculation_time` - 计算时间 (DATETIME, 非空) + * `channel_id` - 渠道ID (BIGINT, 关联 pms_core_channels.channel_id) + * `guest_count` - 客人数量 (INT) + * `advance_booking_days` - 提前预订天数 (INT) + * `calculation_context` - 计算上下文 (JSON, 如促销活动、会员等级等) +* 索引设计: + * `idx_pms_pc_tenant_dept_rt_dates` (tenant_id, dept_id, room_type_id, check_in_date, check_out_date) + * `idx_pms_pc_calculation_time` (calculation_time) + * `idx_pms_pc_tenant_dept_channel` (tenant_id, dept_id, channel_id) +* 外键约束: + * `fk_pricing_calc_room_type` FOREIGN KEY (room_type_id) REFERENCES pms_room_types(room_type_id) + +#### 3.4.3 `pms_special_date_pricing` - 特殊日期价格表 +* 业务描述: 存储特殊日期（节假日、活动日等）的价格设置，具有高优先级。 +* 数据隔离: 门店级隔离，使用多租户拦截器 +* 主键: `special_date_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `special_date_id` - 特殊日期唯一ID + * `tenant_id` - 租户ID + * `dept_id` - 部门ID (门店，可空表示租户级，关联 sys_dept.dept_id) + * `name` - 特殊日期名称 (VARCHAR(100), 非空) + * `date_type` - 日期类型 (VARCHAR(50), 如 holiday/festival/event/promotion) + * `specific_date` - 具体日期 (DATE, 可空) + * `date_range_start` - 日期范围开始 (DATE, 可空) + * `date_range_end` - 日期范围结束 (DATE, 可空) + * `room_type_id` - 房型ID (可空表示全部房型, 关联 pms_room_types.room_type_id) + * `price_adjustment_type` - 调整类型 (VARCHAR(50), 非空) + * `adjustment_value` - 调整值 (DECIMAL(10,2), 非空) + * `fixed_price` - 固定价格 (DECIMAL(10,2), 可空) + * `priority` - 优先级 (INT, DEFAULT 100) + * `status` - 状态 (VARCHAR(50), DEFAULT 'active') + * `description` - 描述 (VARCHAR(500)) + * `is_recurring_yearly` - 是否每年重复 (TINYINT, DEFAULT 0) + * `min_length_of_stay` - 最小入住天数 (INT, 可空) + * `max_length_of_stay` - 最大入住天数 (INT, 可空) + * `channel_restrictions_json` - 渠道限制 (JSON数组) + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 +* 索引设计: + * `idx_pms_sdp_tenant_dept_date` (tenant_id, dept_id, specific_date) + * `idx_pms_sdp_tenant_dept_rt` (tenant_id, dept_id, room_type_id) + * `idx_pms_sdp_tenant_dept_type_status` (tenant_id, dept_id, date_type, status) + * `idx_pms_sdp_date_range` (specific_date, status) +* 外键约束: + * `fk_special_date_room_type` FOREIGN KEY (room_type_id) REFERENCES pms_room_types(room_type_id) + +### 3.5 订单管理表 (门店级隔离) + +#### 3.5.1 `pms_core_orders` - 核心订单表 +* 业务描述: 存储客户预订的核心订单信息，包括预订详情、客户信息、房间分配、订单状态等。 +* 数据隔离: **门店级隔离，包含 `dept_id` 字段** +* 主键: `order_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `order_id` - 订单唯一ID + * `tenant_id` - 租户ID (多租户拦截器自动过滤) + * `dept_id` - 部门ID (门店) + * `contact_id` - 联系人ID (关联 pms_customer_contacts.contact_id) + * `pms_room_id` - 分配的房间ID (关联 pms_room_rooms.room_id) + * `room_type_id` - 预订的房型ID (关联 pms_room_types.room_type_id) + * `channel_id` - 订单来源渠道ID (关联 pms_core_channels.channel_id) + * `check_in_date` - 计划入住日期 + * `check_out_date` - 计划离店日期 + * `num_adults` - 成人数 + * `num_children` - 儿童数 + * `total_amount` - 订单总金额 (DECIMAL(10,2)) + * `paid_amount` - 已付金额 (DECIMAL(10,2)) + * `order_status` - 订单状态 + * `order_source` - 订单来源 + * `notes` - 订单备注 + * `actual_check_in_time` - 实际入住时间 + * `actual_check_out_time` - 实际退房时间 + * `confirmed_time` - 订单确认时间 + * `cancelled_time` - 订单取消时间 + * `expected_arrival_time` - 预计到达时间 + * `special_requests` - 特殊要求 + * `create_dept` - 创建部门 (BIGINT) + * `create_by` - 创建者 (BIGINT) + * `create_time` - 创建时间 (DATETIME) + * `update_by` - 更新者 (BIGINT) + * `update_time` - 更新时间 (DATETIME) + * `del_flag` - 删除标志 (CHAR(1) DEFAULT '0' NOT NULL) +* 索引设计: + * `idx_pms_o_tenant_dept` (tenant_id, dept_id) + * `idx_pms_o_tenant_dept_status` (tenant_id, dept_id, order_status) + * `idx_pms_o_tenant_dept_dates` (tenant_id, dept_id, check_in_date, check_out_date) + * `idx_pms_o_tenant_dept_contact` (tenant_id, dept_id, contact_id) + * `idx_pms_o_tenant_dept_room_dates` (tenant_id, dept_id, pms_room_id, check_in_date, check_out_date) + +#### 3.5.2 `pms_order_guests` - 订单入住客人表 +* 业务描述: 记录订单的实际入住客人信息，支持多人入住登记，与客户档案灵活关联。 +* 数据隔离: **门店级隔离，包含 `dept_id` 字段** +* 主键: `guest_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `guest_id` - 客人记录唯一ID + * `tenant_id` - 租户ID (多租户拦截器自动过滤) + * `order_id` - 订单ID (关联 pms_core_orders.order_id) + * `dept_id` - 部门ID (门店) + * `contact_id` - 关联客户联系人ID (关联 pms_customer_contacts.contact_id，可空) + * `guest_type` - 客人类型 (primary/additional) + * `is_primary_contact` - 是否为订单主联系人 (TINYINT(1) DEFAULT '0') + * `full_name` - 客人姓名 + * `id_type` - 证件类型 + * `id_number_encrypted` - 证件号码(加密) + * `phone_number` - 联系电话 + * `age_group` - 年龄组 (adult/child/infant) + * `create_time` - 创建时间 (DATETIME) + * `create_by` - 创建者 (BIGINT) + * `del_flag` - 删除标志 (CHAR(1) DEFAULT '0' NOT NULL) +* 业务规则: + * 每个订单必须有且仅有一个 `guest_type='primary'` 的主客人 + * 主客人的 `contact_id` 应与订单的 `contact_id` 保持一致 + * 同行客人可选择关联现有客户档案或不关联 + * 客人信息变更时可选择同步更新客户档案 +* 索引设计: + * `idx_pms_og_tenant_order` (tenant_id, order_id) + * `idx_pms_og_tenant_dept` (tenant_id, dept_id) + * `idx_pms_og_order_guest_type` (order_id, guest_type) + * `idx_pms_og_tenant_contact` (tenant_id, contact_id) + * `idx_pms_og_order_primary` (order_id, is_primary_contact) + +#### 3.5.3 `pms_order_status_history` - 订单状态变更历史表 +* 业务描述: 记录订单状态的每次变更历史，支持操作审计和状态追踪。 +* 数据隔离: 门店级隔离，使用多租户拦截器 +* 主键: `history_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `history_id` - 历史记录唯一ID + * `tenant_id` - 租户ID + * `order_id` - 订单ID (关联 pms_core_orders.order_id) + * `dept_id` - 部门ID (门店, 关联 sys_dept.dept_id) + * `from_status` - 原状态 (VARCHAR(50), 可空) + * `to_status` - 新状态 (VARCHAR(50), 非空) + * `change_reason` - 状态变更原因 (VARCHAR(500)) + * `change_time` - 变更时间 (DATETIME, 非空) + * `change_by` - 操作人 (BIGINT, 关联 sys_user.user_id) + * `notes` - 备注 (TEXT) + * `del_flag` - 删除标志 (CHAR(1) DEFAULT '0' NOT NULL) +* 索引设计: + * `idx_pms_osh_tenant_order` (tenant_id, order_id) + * `idx_pms_osh_tenant_dept_time` (tenant_id, dept_id, change_time) + * `idx_pms_osh_order_time` (order_id, change_time) +* 外键约束: + * `fk_order_status_history_order` FOREIGN KEY (order_id) REFERENCES pms_core_orders(order_id) + +#### 3.5.4 `pms_core_order_items` - 订单项目表 +* 业务描述: 存储订单中的具体项目，如房费、附加服务等。 +* 数据隔离: 门店级隔离，使用多租户拦截器 +* 主键: `order_item_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `order_item_id` - 订单项唯一ID + * `tenant_id` - 租户ID + * `order_id` - 所属订单ID (关联 pms_core_orders.order_id) + * `dept_id` - 部门ID (门店, 关联 sys_dept.dept_id) + * `pms_room_id` - 关联房间ID (可空, 如房晚项目, 关联 pms_room_rooms.room_id) + * `product_id` - 产品ID (可空, 如关联 pms_finance_extra_charge_items.item_id) + * `product_type` - 产品类型 (room_fee/extra_service/package_item) + * `description` - 项目描述 + * `quantity` - 数量 + * `unit_price` - 单价 (DECIMAL(10,2)) + * `service_date` - 服务日期 (针对非房晚类项目) + * `notes` - 项目备注 + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 +* 索引设计: + * `idx_pms_oi_tenant_order` (tenant_id, order_id) + * `idx_pms_oi_tenant_dept_product` (tenant_id, dept_id, product_type, product_id) + +#### 3.5.5 `pms_core_channels` - 订单渠道表 +* 业务描述: 存储订单来源渠道信息。 +* 数据隔离: 门店级隔离 (dept_id可空表示租户级通用渠道) +* 主键: `channel_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `channel_id` - 渠道唯一ID + * `tenant_id` - 租户ID + * `dept_id` - 部门ID (门店，可空，关联 sys_dept.dept_id) + * `name` - 渠道名称 + * `channel_type` - 渠道类型 + * `description` - 渠道描述 + * `status` - 状态 (active/inactive) + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 +* 索引设计: + * `idx_pms_ch_tenant_dept_status` (tenant_id, dept_id, status) + * `idx_pms_ch_tenant_dept_type` (tenant_id, dept_id, channel_type) + +#### 3.5.6 `pms_room_inventory_snapshot` - 房型库存快照表 +* 业务描述: 存储房型库存的快照数据，用于快速查询可用性和性能优化。 +* 数据隔离: 门店级隔离，使用多租户拦截器 +* 主键: `snapshot_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `snapshot_id` - 快照唯一ID + * `tenant_id` - 租户ID + * `dept_id` - 部门ID (门店, 关联 sys_dept.dept_id) + * `room_type_id` - 房型ID (关联 pms_room_types.room_type_id) + * `snapshot_date` - 快照日期 (DATE, 非空) + * `total_rooms` - 总房间数 (INT, 非空) + * `available_rooms` - 可用房间数 (INT, 非空) + * `occupied_rooms` - 已占用房间数 (INT, 非空) + * `maintenance_rooms` - 维护中房间数 (INT, 非空) + * `locked_rooms` - 锁定房间数 (INT, 非空) + * `last_updated` - 最后更新时间 (DATETIME, 非空) +* 索引设计: + * `unq_pms_ris_tenant_dept_rt_date` (tenant_id, dept_id, room_type_id, snapshot_date) -- 唯一约束 + * `idx_pms_ris_tenant_dept_date` (tenant_id, dept_id, snapshot_date) + * `idx_pms_ris_last_updated` (last_updated) +* 外键约束: + * `fk_room_inventory_room_type` FOREIGN KEY (room_type_id) REFERENCES pms_room_types(room_type_id) + +### 3.6 财务管理表 (门店级隔离) + +#### 3.6.1 `pms_finance_folios` - 客户账单表 +* 业务描述: 存储客户在店期间的所有费用和支付记录。 +* 数据隔离: 门店级隔离，使用多租户拦截器 +* 主键: `folio_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `folio_id` - 账单唯一ID + * `tenant_id` - 租户ID + * `dept_id` - 部门ID (门店, 关联 sys_dept.dept_id) + * `order_id` - 关联订单ID (UNIQUE, 关联 pms_core_orders.order_id) + * `total_charges` - 总应收费用 (DECIMAL(10,2)) + * `total_payments` - 总已收付款 (DECIMAL(10,2)) + * `total_refunds` - 总已退款 (DECIMAL(10,2)) + * `balance` AS (`total_charges` - `total_payments` + `total_refunds`) COMMENT '计算列：余额' + * `folio_status` - 账单状态 + * `notes` - 账单备注 + * `closed_at` - 账单关闭时间 + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 +* 索引设计: + * `idx_pms_ff_tenant_dept_order` (tenant_id, dept_id, order_id) + * `idx_pms_ff_tenant_dept_status` (tenant_id, dept_id, folio_status) + +#### 3.6.2 `pms_finance_transactions` - 财务交易流水表 +* 业务描述: 记录每一笔财务交易明细。 +* 数据隔离: 门店级隔离，使用多租户拦截器 +* 主键: `transaction_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `transaction_id` - 交易唯一ID + * `tenant_id` - 租户ID + * `folio_id` - 所属账单ID (关联 pms_finance_folios.folio_id) + * `dept_id` - 部门ID (门店, 关联 sys_dept.dept_id) + * `transaction_type` - 交易类型 + * `amount` - 交易金额 (DECIMAL(10,2)) + * `description` - 交易描述 + * `payment_method_id` - 支付方式ID (关联 pms_finance_payment_methods.payment_method_id) + * `payment_gateway_txn_id` - 支付网关交易号 + * `transaction_time` - 交易时间 + * `related_order_item_id` - 关联订单项ID (可空, 关联 pms_core_order_items.order_item_id) + * `notes` - 交易备注 + * `is_void` - 是否已作废 (BOOLEAN) + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 +* 索引设计: + * `idx_pms_ft_tenant_folio` (tenant_id, folio_id) + * `idx_pms_ft_tenant_dept_type_time` (tenant_id, dept_id, transaction_type, transaction_time) + +#### 3.6.3 `pms_finance_payment_methods` - 支付方式表 +* 业务描述: 存储系统支持的支付方式。 +* 数据隔离: 门店级隔离 (dept_id可空表示租户级通用支付方式) +* 主键: `payment_method_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `payment_method_id` - 支付方式唯一ID + * `tenant_id` - 租户ID + * `dept_id` - 部门ID (门店，可空，关联 sys_dept.dept_id) + * `name` - 支付方式名称 + * `method_type` - 支付方式类型 + * `details_json` - 附加配置 (JSON, 如银行账号，终端号等) + * `status` - 状态 (active/inactive) + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 +* 索引设计: + * `idx_pms_fpm_tenant_dept_status` (tenant_id, dept_id, status) + * `idx_pms_fpm_tenant_dept_type` (tenant_id, dept_id, method_type) + +#### 3.6.4 `pms_finance_extra_charge_items` - 附加费用项目表 +* 业务描述: 存储可供订单选择的附加费用项目。 +* 数据隔离: 门店级隔离 (dept_id可空表示租户级通用项目) +* 主键: `item_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `item_id` - 附加费用项唯一ID + * `tenant_id` - 租户ID + * `dept_id` - 部门ID (门店，可空，关联 sys_dept.dept_id) + * `name` - 项目名称 + * `default_price` - 默认单价 (DECIMAL(10,2)) + * `category` - 费用类别 + * `is_taxable` - 是否应税 (BOOLEAN) + * `description` - 项目描述 + * `status` - 状态 (active/inactive) + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 +* 索引设计: + * `idx_pms_feci_tenant_dept_status` (tenant_id, dept_id, status) + * `idx_pms_feci_tenant_dept_category` (tenant_id, dept_id, category) + +### 3.7 合作方管理表 (全局共享/租户级) + +#### 3.7.1 `pms_suppliers` - 供应商表 +* 业务描述: 存储供应商信息，如清洁、维护、物料等供应商。 +* 数据隔离: **支持全局共享 (tenant_id IS NULL) 和租户级隔离 (tenant_id IS NOT NULL)**。已从多租户拦截器排除，业务层处理。 +* 主键: `supplier_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `supplier_id` - 供应商唯一ID + * `tenant_id` - 租户ID (可空，NULL表示全局供应商) + * `supplier_type` - 供应商类型 + * `company_name` - 公司名称 + * `contact_person` - 联系人姓名 + * `phone_number` - 联系电话 + * `email` - 邮箱地址 + * `business_scope` - 业务范围描述 + * `service_area` - 服务区域 + * `contract_info` - 合同信息 + * `status` - 供应商状态 (active/inactive) + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 (对于全局数据，create_dept可能为NULL) +* 索引设计: + * `idx_pms_s_tenant_type` (tenant_id, supplier_type) + * `idx_pms_s_tenant_name` (tenant_id, company_name) + * `idx_pms_s_tenant_status` (tenant_id, status) + +#### 3.7.2 `pms_partners` - 合作伙伴表 +* 业务描述: 存储合作伙伴信息，如旅行社、代理商等，支持佣金设置。 +* 数据隔离: **支持全局共享 (tenant_id IS NULL) 和租户级隔离 (tenant_id IS NOT NULL)**。已从多租户拦截器排除，业务层处理。 +* 主键: `partner_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `partner_id` - 合作伙伴唯一ID + * `tenant_id` - 租户ID (可空，NULL表示全局合作伙伴) + * `partner_type` - 合作伙伴类型 + * `company_name` - 公司名称 + * `contact_person` - 联系人姓名 + * `phone_number` - 联系电话 + * `email` - 邮箱地址 + * `website_url` - 网站地址 + * `commission_rate` - 佣金比例 (DECIMAL(5,2), 如 5.50 表示5.5%) + * `payment_terms` - 付款条件 + * `cooperation_level` - 合作等级 + * `contract_start_date` - 合同开始日期 + * `contract_end_date` - 合同结束日期 + * `status` - 合作伙伴状态 (active/inactive) + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 (对于全局数据，create_dept可能为NULL) +* 索引设计: + * `idx_pms_p_tenant_type` (tenant_id, partner_type) + * `idx_pms_p_tenant_name` (tenant_id, company_name) + * `idx_pms_p_tenant_status` (tenant_id, status) + +### 3.8 系统配置表 (租户级/门店级) + +#### 3.8.1 `pms_tenant_settings` - 租户/门店配置表 +* 业务描述: 存储租户级或门店级的各项配置参数。 +* 数据隔离: **通过dept_id区分。dept_id为NULL表示租户级配置，非NULL表示特定门店的配置。** 标准多租户拦截器处理tenant_id。 +* 主键: `setting_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `setting_id` - 设置唯一ID + * `tenant_id` - 租户ID + * `dept_id` - 部门ID (门店，NULL=租户级，关联 sys_dept.dept_id) + * `setting_group` - 设置分组 (e.g., booking_rules, finance_params) + * `setting_key` - 设置键名 (e.g., max_advance_booking_days) + * `setting_value` - 设置值 (TEXT) + * `value_type` - 值类型 (string/integer/boolean/json) + * `description` - 设置描述 + * `is_sensitive` - 是否敏感设置 (BOOLEAN) + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 +* 索引设计: + * `unq_pms_ts_tenant_dept_group_key` (tenant_id, dept_id, setting_group, setting_key, del_flag) + * `idx_pms_ts_tenant_dept_group` (tenant_id, dept_id, setting_group) + +#### 3.8.2 `pms_mp_settings` - 小程序配置表 +* 业务描述: 存储小程序相关的配置。 +* 数据隔离: **通过dept_id区分。dept_id为NULL表示租户级通用小程序配置，非NULL表示特定门店的小程序配置。** 标准多租户拦截器处理tenant_id。 +* 主键: `setting_id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `setting_id` - 小程序设置唯一ID + * `tenant_id` - 租户ID + * `dept_id` - 部门ID (门店，NULL=租户级，关联 sys_dept.dept_id) + * `setting_key` - 设置键名 (e.g., theme_color, app_id) + * `setting_value` - 设置值 (TEXT) + * `value_type` - 值类型 (string/integer/boolean/json) + * `description` - 设置描述 + * `create_dept`, `create_by`, `create_time`, `update_by`, `update_time`, `del_flag` -- 标准审计字段 +* 索引设计: + * `unq_pms_mps_tenant_dept_key` (tenant_id, dept_id, setting_key, del_flag) + +#### 3.8.3 `pms_tenant_user_devices` - 用户设备表 +* 业务描述: 存储用户登录过的设备信息，用于消息推送等。 +* 数据隔离: **租户用户级别，通过user_id关联，间接关联到租户。** 标准多租户拦截器处理tenant_id。 +* 主键: `id` (BIGINT AUTO_INCREMENT) +* 核心字段: + * `id` - 设备记录唯一ID + * `tenant_id` - 租户ID (冗余，通过user_id可查，但便于直接过滤) + * `user_id` - 用户ID (关联 sys_user.user_id) + * `device_type` - 设备类型 (iOS/Android/Web/MiniProgram) + * `device_token` - 设备令牌 (用于推送) + * `app_version` - 应用版本 + * `last_login_at` - 最后登录时间 + * `status` - 状态 (active/inactive/expired) + * `create_time` - 创建时间 (DATETIME) + * `update_time` - 更新时间 (DATETIME) + * (*注: 此表通常不包含create_by, update_by, del_flag, create_dept，因为是用户设备自动注册行为*) +* 索引设计: + * `idx_pms_tud_tenant_user_device` (tenant_id, user_id, device_type) + * `idx_pms_tud_tenant_user_status` (tenant_id, user_id, status) + * `idx_pms_tud_device_token` (device_token) + ## 4. 主要业务实体状态流转 -#### 4.1 订单 (`pms_core_orders`) 状态流转 - +### 4.1 订单状态流转 ```mermaid stateDiagram-v2 [*] --> pending_confirmation: 创建订单 @@ -642,113 +791,607 @@ stateDiagram-v2 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`) 状态流转 (物理状态 & 清洁状态) +**订单状态枚举值:** +- `pending_confirmation` (待确认) +- `confirmed` (已确认) +- `checked_in` (已入住) +- `checked_out` (已退房) +- `cancelled` (已取消) +- `no_show` (未到店) +- `extended` (已延期) +- `waitlist` (等候名单) -**物理状态 (`room_status` VARCHAR(50))** +### 4.2 房间状态流转 + +**物理状态流转:** ```mermaid stateDiagram-v2 [*] --> available: 房间空闲可用 - available --> occupied: 客人入住 / 预留占用 - available --> maintenance: 安排维护 / 维修 - available --> out_of_service: 暂停服务 (其他原因) - occupied --> available: 客人退房 (且房间已清洁完成) - maintenance --> 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: 客房服务员开始清洁 + [*] --> clean: 初始状态 + clean --> dirty: 客人使用后 + dirty --> cleaning_in_progress: 开始清洁 cleaning_in_progress --> inspected: 清洁完成待查房 inspected --> clean: 查房通过 - inspected --> cleaning_in_progress: 查房未通过，返工 - clean --> cleaning_in_progress: 客中打扫 (客人仍在住，但安排了打扫) + inspected --> cleaning_in_progress: 查房未通过 ``` -* **清洁状态枚举值示例:** - * `clean` (已清洁) - * `dirty` (待清洁) - * `cleaning_in_progress` (清洁中) - * `inspected` (已查房/待检) - -#### 4.3 账单 (`pms_finance_folios`) 状态流转 +### 4.3 账单状态流转 ```mermaid stateDiagram-v2 - [*] --> open: 订单创建时自动生成 / 手动创建 - open --> closed: 账务结清 (所有费用付清) - open --> void: 作废账单 (如错误创建) - open --> pending_settlement: 等待结算 (如对公转账) + [*] --> open: 订单创建时生成 + open --> closed: 账务结清 + open --> void: 作废账单 + open --> pending_settlement: 等待结算 pending_settlement --> closed: 结算完成 - pending_settlement --> open: 取消结算，返回开放 - closed --> open: 重新打开 (特殊情况，需权限，如补充入账或退款) + pending_settlement --> open: 取消结算 + closed --> open: 重新打开 (特殊情况) void --> [*] : 账单作废 closed --> [*] : 账单关闭 ``` -* **账单状态 (`folio_status` VARCHAR(50)) 枚举值示例:** - * `open` (开放/未结清) - * `closed` (已结清/关闭) - * `void` (作废) - * `pending_settlement` (待结算) -## 5. 核心业务枚举值定义 (PMS主要部分) +## 5. 核心业务枚举值定义 -以下列出PMS核心业务表中 `VARCHAR(50)` 类型枚举字段的建议值，具体值可根据业务细化调整。 +### 5.1 客户联系人相关枚举 +```sql +-- pms_customer_contacts.contact_type +'individual_guest' -- 散客 +'group_leader' -- 团队负责人 +'corporate_contact' -- 企业联系人 +'vip_member' -- VIP会员 +'repeat_guest' -- 回头客 +'marketing_tag' -- 营销标签 +'behavior_tag' -- 行为标签 +'other' -- 其他 -* **`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` (已合并重复档案) +-- pms_customer_contacts.contact_status +'active' -- 活跃 +'inactive' -- 不活跃 +'blacklisted' -- 黑名单 +'pending_verification' -- 待验证 +'merged_duplicate' -- 已合并重复档案 -## 6. 索引命名与规范建议 +-- pms_customer_contacts.gender +'male' -- 男 +'female' -- 女 +'non_binary' -- 非二元性别 +'prefer_not_to_say' -- 不愿透露 +'unknown' -- 未知 -* **唯一索引：** `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, ...其他条件字段)`。 -* **覆盖索引：** 尽量设计覆盖索引以减少回表，提高查询性能。 -* **避免过多索引：** 每个表的索引数量不宜过多，以免影响写入性能。 +-- pms_customer_contacts.member_level +'bronze' -- 铜牌会员 +'silver' -- 银牌会员 +'gold' -- 金牌会员 +'platinum' -- 白金会员 +'diamond' -- 钻石会员 + +-- pms_contact_tags.category +'contact_level' -- 联系人等级 +'contact_source' -- 联系人来源 +'contact_preference' -- 偏好标签 +'service_record' -- 服务记录 +'marketing_tag' -- 营销标签 +'behavior_tag' -- 行为标签 +``` + +### 5.2 供应商相关枚举 +```sql +-- pms_suppliers.supplier_type +'cleaning_service' -- 清洁服务 +'maintenance_repair' -- 维护维修 +'laundry_service' -- 洗涤服务 +'food_beverage' -- 餐饮供应 +'amenities_supplies' -- 用品供应 +'technology_service' -- 技术服务 +'other' -- 其他 + +-- pms_suppliers.status +'active' -- 活跃 +'inactive' -- 不活跃 +``` + +### 5.3 合作伙伴相关枚举 +```sql +-- pms_partners.partner_type +'travel_agency' -- 旅行社 +'ota_platform' -- OTA平台 +'corporate_client' -- 企业客户 +'booking_agent' -- 预订代理 +'tour_operator' -- 旅游运营商 +'other' -- 其他 + +-- pms_partners.cooperation_level +'standard' -- 标准 +'preferred' -- 优选 +'strategic' -- 战略 +'exclusive' -- 独家 + +-- pms_partners.status +'active' -- 活跃 +'inactive' -- 不活跃 +``` + +### 5.4 房间相关枚举 +```sql +-- pms_room_rooms.room_status (物理状态) +'available' -- 可用 +'occupied' -- 占用中 +'maintenance' -- 维护中 +'out_of_service' -- 暂停服务 + +-- pms_room_rooms.cleaning_status (清洁状态) +'clean' -- 已清洁 +'dirty' -- 待清洁 +'cleaning_in_progress' -- 清洁中 +'inspected' -- 已查房 + +-- pms_room_locks.lock_type (锁定类型) +'maintenance' -- 维护锁定 +'cleaning' -- 清洁锁定 +'management' -- 管理锁定 +'malfunction' -- 故障锁定 + +-- pms_room_locks.lock_status (锁定状态) +'active' -- 锁定中 +'unlocked' -- 已解锁 +'expired' -- 已过期 +``` + +### 5.5 价格相关枚举 +```sql +-- 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' -- 设置为特定值 +``` + +### 5.6 订单相关枚举 +```sql +-- pms_core_orders.order_status (订单状态) +'pending_confirmation' -- 待确认 +'confirmed' -- 已确认 +'checked_in' -- 已入住 +'checked_out' -- 已退房 +'cancelled' -- 已取消 +'no_show' -- 未到店 +'extended' -- 已延期 +'waitlist' -- 等候名单 + +-- 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_channels.channel_type +'ota' -- OTA平台 +'direct_booking' -- 直接预订 +'gds' -- 全球分销系统 +'wholesaler' -- 批发商 +'corporate' -- 企业协议 +'internal_use' -- 内部使用 + +-- pms_order_guests.guest_type (客人类型) +'primary' -- 主客人 +'additional' -- 同行客人 +'child' -- 儿童 +'infant' -- 婴儿 +'senior' -- 老人 + +-- pms_order_guests.age_group (年龄组) +'adult' -- 成人 +'child' -- 儿童 +'infant' -- 婴儿 +'senior' -- 老人 + +-- pms_order_guests.id_type (证件类型) +'ID_CARD' -- 身份证 +'PASSPORT' -- 护照 +'DRIVER_LICENSE' -- 驾驶证 +'MILITARY_ID' -- 军官证 +'STUDENT_ID' -- 学生证 +'OTHER' -- 其他 + +-- pms_order_status_history.change_reason (状态变更原因) +'guest_request' -- 客人要求 +'system_auto' -- 系统自动 +'staff_operation' -- 员工操作 +'payment_received' -- 收到付款 +'payment_failed' -- 付款失败 +'room_ready' -- 房间准备就绪 +'guest_arrived' -- 客人到达 +'guest_departed' -- 客人离店 +'cancellation_policy' -- 取消政策 +'no_show_timeout' -- 未到店超时 +'maintenance_required' -- 需要维护 +'other' -- 其他原因 +``` + +### 5.7 财务相关枚举 +```sql +-- 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_unionpay' -- 银联卡 +'alipay' -- 支付宝 +'wechat_pay' -- 微信支付 +'bank_transfer' -- 银行转账 +'company_account' -- 公司账户/挂账 +'voucher' -- 代金券 +'points_redemption' -- 积分兑换 +'other' -- 其他 + +-- pms_finance_extra_charge_items.category (附加费用项目类别) +'room_charge' -- 房费相关 +'food_beverage' -- 餐饮 +'laundry' -- 洗衣 +'parking' -- 停车 +'damages' -- 损坏赔偿 +'other_service' -- 其他服务 +'retail' -- 商品销售 +'telephone' -- 电话费 +'business_center' -- 商务中心 +'spa_services' -- SPA服务 + +-- pms_special_date_pricing.date_type (特殊日期类型) +'holiday' -- 法定节假日 +'festival' -- 传统节日 +'event' -- 特殊活动 +'promotion' -- 促销活动 +'conference' -- 会议会展 +'sports' -- 体育赛事 +'local_event' -- 本地活动 + +-- pms_special_date_pricing.price_adjustment_type +'fixed_amount_override' -- 固定价格覆盖 +'percentage_increase_from_base' -- 基价百分比上浮 +'percentage_discount_from_base' -- 基价百分比折扣 +'fixed_amount_increase_on_base' -- 基价固定金额上浮 +'fixed_amount_decrease_from_base' -- 基价固定金额下调 + +-- pms_pricing_calculations.calculation_context (计算上下文) +-- JSON格式示例: +{ + "promotion_code": "SUMMER2024", -- 促销代码 + "member_level": "gold", -- 会员等级 + "booking_channel": "direct", -- 预订渠道 + "advance_days": 30, -- 提前预订天数 + "guest_count": 2, -- 客人数量 + "special_events": ["local_festival"], -- 特殊事件 + "weather_factor": "good", -- 天气因素 + "occupancy_rate": 0.85 -- 入住率 +} +``` + +## 6. 数据权限控制与索引设计 + +### 6.1 索引命名与设计规范 + +#### 6.1.1 索引命名约定 +为确保索引名称的规范性和可读性，建议遵循以下命名约定： + +* **唯一索引 (Unique Index):** + * 格式: `unq_[子系统前缀]_[表名简写]_[字段1缩写]_[字段2缩写]...` + * 示例: `unq_pms_r_tdrn` 代表 `pms_room_rooms` 表上 `tenant_id`, `dept_id`, `room_number` 的唯一索引。 + * 说明: 表名简写和字段缩写应尽量简洁并能表达其含义。 + +* **普通索引 (Non-Unique Index):** + * 格式: `idx_[子系统前缀]_[表名简写]_[字段1缩写]_[字段2缩写]...` + * 示例: `idx_pms_o_tds` 代表 `pms_core_orders` 表上 `tenant_id`, `dept_id`, `order_status` 的普通索引。 + +* **表名简写建议**：在项目内部可约定一套表名简写规则，例如 `pms_customer_contacts` -> `cc` or `cust`, `pms_room_rooms` -> `rr` or `room`。 + +* **现有索引兼容性**: 本文档中现有的索引名称（如 `idx_pms_o_tenant_dept_status`）已具备良好的可读性并遵循了前缀和字段组合的原则。新开发的索引可考虑采用上述更简洁的缩写约定，现有索引可逐步过渡或在可读性要求较高时保留描述性更强的名称。 + +#### 6.1.2 索引设计原则 +* **租户和部门优先**: 对于所有包含 `tenant_id` 和 `dept_id` 的PMS业务表，查询相关的索引应优先考虑这两个字段，顺序通常为 `(tenant_id, dept_id, ...其他条件字段)`，以充分利用多租户和门店级数据隔离的特性。 +* **覆盖索引 (Covering Index)**: 尽量设计覆盖索引以减少回表查询（即索引包含查询所需的所有列），从而提高查询性能。 +* **选择性高的列优先**: 索引列的选择应优先考虑那些具有高区分度的列（即列中唯一值较多）。 +* **避免过多索引**: 每个表的索引数量不宜过多（通常建议不超过5-7个），过多的索引会增加写操作（INSERT, UPDATE, DELETE）的开销，并占用额外的存储空间。 +* **避免在索引列上使用函数或表达式**: 这可能导致索引失效。 +* **定期审查和优化**: 应定期监控索引的使用情况（如未使用索引、低效索引），并进行相应的调整和优化。 + +### 6.2 数据隔离策略 + +#### 6.2.1 多租户拦截器配置 +```yaml +# application.yml +tenant: + enable: true + excludes: + # 若依系统表 + - sys_menu + - sys_tenant + - sys_tenant_package + - sys_role_dept + - sys_role_menu + - sys_user_post + - sys_user_role + - sys_client + - sys_oss_config + # PMS供应商合作伙伴表 (支持全局共享，排除多租户拦截器) + - pms_suppliers # 供应商信息 + - pms_partners # 合作伙伴信息 +``` + +**重要说明**: +- **`pms_customer_contacts`** 表**不在排除列表中**，因为该表有 `tenant_id` 字段且需要租户间隔离 +- **`pms_contact_tags`** 和 **`pms_contact_tag_relations`** 表**不在排除列表中**，使用标准多租户拦截器 +- **`pms_suppliers`** 和 **`pms_partners`** 表在排除列表中，因为它们支持全局共享 (`tenant_id` 可为 NULL) + +#### 6.2.2 数据权限控制层级 + +**Level 1: 多租户拦截器 (自动)** +- 适用表：所有含 `tenant_id` 且不在排除列表的表 +- 自动添加：`WHERE tenant_id = #{currentTenantId}` +- 确保：租户间数据完全隔离 + +**Level 2: 门店级权限控制 (业务层)** +- 适用表：门店级PMS业务表 (含 `dept_id` 字段) +- 业务层添加：`AND dept_id = #{currentDeptId}` +- 确保：同租户不同门店数据隔离 + +**Level 3: 租户级共享 (标准拦截器)** +- 适用表：客户信息、客户标签 +- 拦截器自动添加：`WHERE tenant_id = #{currentTenantId}` +- 确保：租户内所有门店可见，租户间隔离 + +**Level 4: 全局共享 (排除拦截器)** +- 适用表：供应商、合作伙伴 (`tenant_id` 可为 NULL) +- 业务层手动添加：`WHERE tenant_id IS NULL OR tenant_id = #{currentTenantId}` +- 确保：全局数据和租户数据都可见 + +### 6.3 核心索引设计 + +#### 6.3.1 租户级共享表索引 (使用多租户拦截器) +```sql +-- 客户联系人查询索引 +CREATE INDEX idx_pms_cc_tenant_name ON pms_customer_contacts + (tenant_id, full_name); +CREATE INDEX idx_pms_cc_tenant_phone ON pms_customer_contacts + (tenant_id, phone_number); +CREATE INDEX idx_pms_cc_tenant_status_type ON pms_customer_contacts + (tenant_id, contact_status, contact_type); + +-- 联系人标签查询索引 +CREATE INDEX idx_pms_ct_tenant_dept ON pms_contact_tags + (tenant_id, dept_id); +CREATE INDEX idx_pms_ct_tenant_dept_name_category ON pms_contact_tags + (tenant_id, dept_id, name, category); + +-- 标签关联查询索引 +CREATE INDEX idx_pms_ctr_tenant_contact ON pms_contact_tag_relations + (tenant_id, contact_id); +CREATE INDEX idx_pms_ctr_tenant_tag ON pms_contact_tag_relations + (tenant_id, tag_id); +``` + +#### 6.3.2 门店级业务表索引 (使用多租户拦截器) +```sql +-- 核心查询复合索引 (tenant_id + dept_id + 业务字段) +CREATE INDEX idx_pms_o_tenant_dept_status ON pms_core_orders + (tenant_id, dept_id, order_status); + +CREATE INDEX idx_pms_o_tenant_dept_dates ON pms_core_orders + (tenant_id, dept_id, check_in_date, check_out_date); + +CREATE INDEX idx_pms_r_tenant_dept_status ON pms_room_rooms + (tenant_id, dept_id, room_status, cleaning_status); + +-- 关联查询索引 +CREATE INDEX idx_pms_o_tenant_dept_contact ON pms_core_orders + (tenant_id, dept_id, contact_id); +``` + +#### 6.3.3 全局共享表索引 (排除多租户拦截器) +```sql +-- 供应商查询索引 (支持 tenant_id 为 NULL) +CREATE INDEX idx_pms_s_tenant_type ON pms_suppliers + (tenant_id, supplier_type); +CREATE INDEX idx_pms_s_tenant_name ON pms_suppliers + (tenant_id, company_name); + +-- 合作伙伴查询索引 (支持 tenant_id 为 NULL) +CREATE INDEX idx_pms_p_tenant_type ON pms_partners + (tenant_id, partner_type); +CREATE INDEX idx_pms_p_tenant_name ON pms_partners + (tenant_id, company_name); +``` + +### 6.4 典型查询模式 + +#### 6.4.1 租户级共享查询 (多租户拦截器自动处理) +```sql +-- 客户联系人查询 (拦截器自动添加 tenant_id 条件) +SELECT * FROM pms_customer_contacts +WHERE tenant_id = '100000' -- 拦截器自动添加 + AND contact_status = 'active' + AND full_name LIKE '%张%' +ORDER BY create_time DESC; + +-- 联系人标签查询 (支持门店级和租户级标签) +SELECT * FROM pms_contact_tags +WHERE tenant_id = '100000' -- 拦截器自动添加 + AND (dept_id = 103 OR dept_id IS NULL) -- 业务层添加 + AND category = 'contact_level' +ORDER BY sort_order; +``` + +#### 6.4.2 门店级查询 (多租户拦截器 + 业务层门店过滤) +```sql +-- 门店订单查询 +SELECT * FROM pms_core_orders +WHERE tenant_id = '100000' -- 拦截器自动添加 + AND dept_id = 103 -- 业务层添加 + AND order_status = 'confirmed' +ORDER BY check_in_date DESC; +``` + +#### 6.4.3 全局共享查询 (业务层手动处理) +```sql +-- 供应商查询 (包含全局和租户级供应商) +SELECT * FROM pms_suppliers +WHERE (tenant_id IS NULL OR tenant_id = '100000') -- 业务层手动添加 + AND supplier_type = 'cleaning_service' + AND status = 'active' +ORDER BY company_name; +``` + +### 6.5 实施建议 + +#### 6.5.1 开发规范 +1. **客户联系人查询**: 直接查询，让多租户拦截器自动处理租户隔离 +2. **联系人标签查询**: 业务层添加 `(dept_id = #{currentDeptId} OR dept_id IS NULL)` 实现门店和租户级标签 +3. **订单等门店数据**: 多租户拦截器 + 业务层 `dept_id` 过滤 +4. **供应商合作伙伴**: 业务层手动添加 `(tenant_id IS NULL OR tenant_id = #{currentTenantId})` + +#### 6.5.2 性能优化 +1. **复合索引优先**: 按 `(tenant_id, dept_id, 业务字段)` 顺序设计 +2. **标签查询优化**: `pms_contact_tags` 的 `(tenant_id, dept_id)` 复合索引支持门店和租户级查询 +3. **关联查询优化**: 客户联系人与订单关联时，优先使用 `tenant_id` 过滤 --- -**(文档末尾)** -**重要提示：** -* 本文档中的主键类型已统一为 `BIGINT AUTO_INCREMENT` (用于PMS新增业务表) 或遵循若依原有的 `BIGINT` (用于若依系统表)。 -* PMS业务表中的枚举字段统一为 `VARCHAR(50)`，这与若依的 `CHAR(1)` 不同，在系统集成和前端交互时，可能需要在API层或逻辑层进行适配和转换。 -* 所有PMS业务表已添加 `dept_id` 字段，用于数据归属和统计。确保所有相关查询和业务逻辑都考虑到 `dept_id`。 -* 审计字段和软删除标记已尽量对齐若依规范。 +## 版本历史 +- v5.1 (上一版本) - 修正多租户拦截器配置，恢复遗漏的标签表，优化表名一致性 +- v5.2 (上一版本) - 表名标准化优化，使用民宿行业标准术语，完善客户管理数据模型 +- v5.3 (上一版本) - 全面同步需求文档v4.0：补充核心表审计字段、del_flag；统一ER图与表定义；对齐所有枚举值；明确供应商/合作伙伴的全局共享处理方式。 +- v5.4 (上一版本) - 更新"命名与设计约定"；重组第3节表结构定义，使其按业务模块划分，与需求文档结构对齐；确保所有表定义包含完整核心字段、审计字段和外键注释。 +- v5.5 (当前版本) - 订单管理和价格管理数据模型优化：新增订单状态历史追踪、订单客人信息管理、价格计算历史记录、特殊日期价格管理、库存快照等功能支持。 -请仔细审查此最终方案，确保其满足所有业务需求和技术约束。 \ No newline at end of file +**重要变更说明 (v5.5):** +- **订单管理增强**: 新增 `pms_order_status_history` 表支持订单状态变更历史追踪；新增 `pms_order_guests` 表支持多人入住客人信息管理；优化 `pms_core_orders` 表增加关键时间字段和特殊要求字段。 +- **价格管理完善**: 新增 `pms_pricing_calculations` 表记录价格计算历史和审计轨迹；新增 `pms_special_date_pricing` 表支持节假日和特殊活动的价格管理；优化 `pms_room_pricing_rules` 表增加渠道限制、客人数量、提前预订等高级规则字段。 +- **库存管理支持**: 新增 `pms_room_inventory_snapshot` 表提供房型库存快照功能，提升查询性能和支持库存分析。 +- **枚举值补充**: 新增订单客人类型、年龄组、特殊日期类型等枚举值定义。 +- **索引优化**: 为新增表设计了完整的索引策略，优化查询性能和支持业务场景。 +- **ER图更新**: 更新实体关系图，反映新增表和关联关系。 + +### v5.6 (当前版本) - 客人信息管理优化 +**发布日期**: 2024年12月 + +**主要变更**: +1. **订单客人表优化** (`pms_order_guests`): + - 新增 `contact_id` 字段，支持与客户档案关联 + - 新增 `is_primary_contact` 字段，标识订单主联系人 + - 完善索引设计，提升查询性能 + +2. **订单表结构优化** (`pms_core_orders`): + - 移除冗余字段 `primary_contact_name` 和 `primary_contact_phone` + - 通过关联查询获取联系人信息，避免数据不一致 + +3. **价格规则表增强** (`pms_room_pricing_rules`): + - 新增 `advance_booking_days_max` 字段 + - 新增 `member_level_restrictions_json` 字段，支持会员等级限制 + - 重命名 `rule_description` 为 `description`，保持命名一致性 + +4. **库存快照表完善** (`pms_room_inventory_snapshot`): + - 新增 `dirty_rooms` 字段，统计脏房数量 + - 新增 `out_of_order_rooms` 字段，统计停用房间数 + - 新增 `reserved_rooms` 字段，统计预留房间数 + +5. **枚举值补充**: + - 完善客人证件类型枚举 + - 新增订单状态变更原因枚举 + - 补充特殊日期类型枚举 + - 增加价格计算上下文示例 + +6. **外键约束完善**: + - 新增 `pms_order_guests` 与 `pms_customer_contacts` 的外键关联 + - 新增 `pms_order_guests` 与 `pms_core_orders` 的外键关联 + - 优化索引设计，支持高效的关联查询 + +7. **业务流程优化**: + - 完善入住登记流程，支持智能档案匹配和新档案创建 + - 优化客户档案维护流程，实现信息同步和统计更新 + - 增强订单与客人信息的关联管理 + +### v5.7 (当前版本) - 系统配置管理模块完善 +**发布日期**: 2024年12月 + +**主要变更**: +1. **系统配置管理表新增**: + - 新增 `pms_tenant_settings` 表，支持租户级和门店级配置管理 + - 新增 `pms_mp_settings` 表，支持小程序配置管理 + - 新增 `pms_tenant_user_devices` 表，支持用户设备管理和安全审计 + +2. **配置管理功能增强**: + - 支持配置分组管理（预订规则、财务参数、界面外观、业务流程） + - 支持配置继承机制（租户级配置、门店级覆盖） + - 支持敏感配置加密存储和访问控制 + - 支持配置项类型验证（string/integer/boolean/json/decimal） + +3. **小程序配置支持**: + - 主题配置（颜色、图标、名称） + - 功能开关（在线预订、支付、客房服务、反馈） + - 支付配置（微信支付、支付宝、超时设置） + - 通知配置（预订通知、入住提醒、退房提醒） + +4. **用户设备管理**: + - 多设备类型支持（iOS/Android/Web/MiniProgram） + - 设备状态跟踪（活跃、不活跃、过期、阻止） + - 推送令牌管理和推送开关控制 + - 登录历史和安全审计功能 + +5. **预定义配置项**: + - 预订规则：最大/最小提前预订时间、当日预订、自动确认等 + - 财务参数：默认货币、税率、押金比例、取消费率等 + - 界面外观：主题色、品牌标识、欢迎语、页脚文本等 + - 业务流程：自动分房、身份验证、确认信息、客人评价等 + +6. **系统配置枚举值**: + - 配置值类型：`string`, `integer`, `boolean`, `json`, `decimal` + - 配置状态：`active`, `inactive` + - 设备类型：`iOS`, `Android`, `Web`, `MiniProgram` + - 设备状态：`active`, `inactive`, `expired`, `blocked` + - 小程序配置分类：`theme`, `payment`, `notification`, `function`, `security` + - 配置分组：`booking_rules`, `finance_params`, `ui_appearance`, `business_process` + +7. **索引优化**: + - 租户配置表：`(tenant_id, dept_id, setting_group, setting_key)` 唯一索引 + - 小程序配置表：`(tenant_id, dept_id, setting_key)` 唯一索引 + - 用户设备表：`(tenant_id, user_id, device_id)` 唯一索引 + - 查询性能优化索引：按租户、部门、分组、状态等维度 + +8. **菜单权限体系**: + - 系统配置管理主菜单及6个子菜单 + - 完整权限控制：查询、新增、修改、删除、导入、导出、批量操作 + - 特殊权限：配置继承、覆盖、重置、模板应用、系统监控等 + +### v5.5 (历史版本) - 订单管理和价格管理数据模型优化 \ No newline at end of file diff --git a/docs/basic/PMS需求.md b/docs/basic/PMS需求.md index a74535433..ee7e31e2a 100644 --- a/docs/basic/PMS需求.md +++ b/docs/basic/PMS需求.md @@ -1,328 +1,1787 @@ -# 云宿居 PMS 系统 - 核心功能需求 (PMS内部聚焦) +# 云宿居 PMS 系统需求规格说明书 (完整版 v4.3) -## 1. 引言 +**快速导航：** +- [1. 项目概述](#1-项目概述) +- [2. 术语表](#2-术语表) +- [3. 系统架构](#3-系统架构) +- [4. 数据模型设计](#4-数据模型设计) +- [5. 核心功能模块](#5-核心功能模块) +- [6. 联系人管理](#6-联系人管理) +- [7. 房态管理](#7-房态管理) +- [8. 价格管理](#8-价格管理) +- [9. 订单管理](#9-订单管理) +- [10. 财务管理](#10-财务管理) +- [11. 系统配置管理](#11-系统配置管理) +- [12. 业务流程设计](#12-业务流程设计) +- [13. 接口设计规范](#13-接口设计规范) +- [14. 用户界面设计](#14-用户界面设计) +- [15. 非功能性需求](#15-非功能性需求) +- [16. 技术实现要求](#16-技术实现要求) +- [17. 部署与运维](#17-部署与运维) -### 1.1 文档目的与范围 +## 1. 项目概述 -本文档定义了"云宿居"民宿 Property Management System (PMS) 的核心功能需求，**重点聚焦于PMS租户核心业务子系统（以下简称PMS核心模块）的内部功能**。它旨在明确该子系统的核心功能范围和关键业务流程。 +### 1.1 项目背景 +"云宿居"是一个面向中小型民宿经营者的 SaaS PMS（Property Management System）解决方案。基于若依框架构建，支持多租户架构，为民宿业主提供房间管理、订单处理、客户管理、财务结算等核心功能。 -本文档是PMS核心模块后续详细设计和开发工作的基础。 +### 1.2 核心特色 +- **多租户架构**: 单实例支持多个民宿品牌或经营者 +- **门店级权限**: 支持连锁民宿的分店管理 +- **客户信息共享**: 租户内客户信息在各门店间共享，提升服务体验 +- **移动优先**: 支持小程序和H5，适配民宿日常运营场景 -### 1.2 目标读者 +### 1.3 系统目标 +- **提升运营效率**: 自动化房态管理、动态定价、智能配置 +- **优化客户体验**: 租户级客户档案共享、个性化服务 +- **增强收益管理**: 动态定价策略、多渠道管理、收益分析 +- **保障数据安全**: 多层级权限控制、数据加密、审计追踪 -产品经理、架构师、开发工程师、测试工程师。 +### 1.4 适用范围 +- **目标用户**: 中小型民宿经营者、连锁民宿品牌、民宿管理公司 +- **业务规模**: 支持1-1000间房的民宿运营管理 +- **地域范围**: 主要面向中国大陆地区，支持多语言扩展 -### 1.4 术语表 +### 1.5 核心用户角色 +- **民宿主/管理员**: 系统的主要管理者，负责整体运营决策和系统配置 +- **前台员工**: 日常操作人员，负责订单处理、入住退房、客户服务等 -| 术语 | 全称 | 描述 | -| ------- | -------------------------- | ------------------------------------------------------------- | -| PMS | Property Management System | 民宿/酒店属性管理系统，管理房间、预订、联系人、账务等核心业务 | -| Folio | Folio | 客户账单，用于记录联系人在店期间所有费用和付款的详细清单 | -| Tenant | Tenant | 租户，指使用本SaaS化PMS系统的单个民宿运营方 | -| Dept | Department | 部门，在本系统中表示租户下的门店/分店 | -| Contact | Contact | 联系人，指系统中统一管理的客户信息，包括预订人、实际入住人等 | +### 1.6 功能优先级策略 +本系统采用分阶段开发策略，按优先级划分功能实现： +- **P0 (核心功能)**: 系统基础运营必需功能，第一阶段实现 +- **P1 (重要功能)**: 提升运营效率的重要功能，第二阶段实现 +- **P2 (增强功能)**: 优化用户体验的增强功能，第三阶段实现 +- **P3 (扩展功能)**: 面向未来的扩展功能，后续版本实现 -### 1.5 优先级定义 +## 2. 术语表 -* **[P0]**: MVP 阶段必须实现的核心功能。 -* **[P1]**: 重要功能，MVP 后第一个主要版本包含。 -* **[P2]**: 次要或完善性功能，后续迭代实现。 -* **[P3]**: 未来规划或可选功能。 +| 术语 | 定义 | 说明 | +| -------------------------- | ---------------------- | ------------------------------------------ | +| **租户(Tenant)** | SaaS平台的独立客户单位 | 通常是一个民宿品牌或管理公司 | +| **门店(Department/Store)** | 租户下的具体经营场所 | 在系统中对应sys_dept表，表示具体的民宿分店 | +| **联系人(Contact)** | 客户联系人信息 | 包括个人客人、企业联系人、代理商联系人等 | +| **客人(Guest)** | 实际入住的客户 | 是联系人的一种类型，特指入住客户 | +| **房型(Room Type)** | 标准化的房间类型定义 | 如标准间、豪华间、套房等 | +| **房间(Room)** | 具体的物理房间 | 有唯一房间号，属于某个房型 | +| **订单(Order)** | 预订记录 | 包含入住信息、客户信息、房间信息等 | +| **账单(Folio)** | 财务账单 | 记录订单的费用明细和支付情况 | +| **渠道(Channel)** | 订单来源渠道 | 如官网、OTA平台、电话预订等 | -## 2. 核心设计原则 (适用于PMS内部) +**重要说明**: 在PMS系统中，`sys_dept` 表的记录代表**门店/分店**，而非传统意义上的部门。这是基于民宿行业的业务特点做出的设计决策。 -1. **核心稳固**: 保持PMS核心功能（房态、订单、账务、联系人）的极简和稳定。 -2. **数据为基**: 确保PMS核心数据结构设计合理，易于内部功能扩展。 -3. **安全隐私**: PMS内部数据处理需考虑数据安全和隐私保护。 -4. **门店为中心**: 所有业务数据以门店（部门）为归属单位，支持一个租户下多个门店的业务模型。 +## 3. 系统架构 -## 3. 系统架构概览 (PMS视角) +### 4.1 总体架构 -PMS租户核心业务子系统是整个云宿居平台的核心，负责处理民宿日常运营的核心业务流程。 +```mermaid +graph TB + subgraph "外部系统" + E1[第三方支付] + E2[OTA平台] + E3[短信/邮件服务] + E4[文件存储OSS] + end + + subgraph "客户端层" + A1[管理后台 Web] + A2[小程序端管理] + A4[开放API] + end + + subgraph "应用网关层" + G1[API网关] + G2[负载均衡] + G3[安全认证] + end + + subgraph "应用服务层" + B1[用户权限服务] + BS_Core[核心业务服务 订单 房态 财务 联系人 价格] + B7[系统配置服务] + B8[消息通知服务] + B9[报表统计服务] + end + + subgraph "数据访问与基础设施层" + C_DataAccess[数据访问 ORM 多租户与权限] + C_Infra[基础设施 缓存Redis 连接池 消息队列MQ] + end + + subgraph "数据存储层" + D1[MySQL主库] + D2[MySQL从库] + D3[Redis缓存] + D5[日志存储] + end + + %% 外部系统连接 + BS_Core -- "支付处理" --> E1 + BS_Core -- "订单同步" --> E2 + B8 -- "消息发送" --> E3 + BS_Core -- "文件存取" --> E4 + + %% 客户端到网关 + A1 --> G1 + A2 --> G1 + A4 --> G1 + + %% 网关到服务 (Primary routing and direct access) + G1 --> G2 + G2 --> G3 + G3 -- "分发/认证" --> B1 + G3 -- "分发/认证" --> BS_Core + G3 -- "分发/认证" --> B7 + G3 -- "分发/认证" --> B8 + G3 -- "分发/认证" --> B9 + + %% 应用服务层内部依赖 (Refined logic for BS_Core operations) + BS_Core -- "权限校验" --> B1 + BS_Core -- "获取配置" --> B7 + BS_Core -- "发送通知" --> B8 + + %% 服务到数据访问与基础设施 + B1 -- "数据操作" --> C_DataAccess + BS_Core -- "数据操作" --> C_DataAccess + B7 -- "数据操作" --> C_DataAccess + B8 -- "消息队列" --> C_Infra + %% MQ is part of Infra + B9 -- "数据查询" --> C_DataAccess + %% Reports from DB + B9 -- "缓存读取" --> C_Infra + %% Reports might use Cache + + %% 数据访问与基础设施到存储 + C_DataAccess -- "读/写" --> D1 + C_DataAccess -- "读" --> D2 + C_Infra -- "缓存操作" --> D3 + %% Redis Cache + C_Infra -- "日志写入" --> D5 + %% MQ for logs or async tasks, or direct logging + + %% 存储层内部连接 + D1 -.-> D2 + + style E1 fill:#e1f5fe + style E2 fill:#e1f5fe + style E3 fill:#e1f5fe + style E4 fill:#e1f5fe + style G1 fill:#f3e5f5 + style G2 fill:#f3e5f5 + style G3 fill:#f3e5f5 + style BS_Core fill:#e8f5e9 + style B1 fill:#e8f5e9 + style B7 fill:#e8f5e9 + style B8 fill:#e8f5e9 + style B9 fill:#e8f5e9 +``` + +### 4.2 技术架构 +- **后端框架**: Spring Boot + MyBatis-Plus + 若依框架 +- **前端技术**: Vue3 + Element Plus + TypeScript +- **数据库**: MySQL 8.0 + Redis 6.0 +- **消息队列**: RabbitMQ (可选) +- **文件存储**: 阿里云OSS / 本地存储 +- **部署方式**: Docker + Kubernetes + +### 4.3 多租户架构设计 + +#### 4.3.1 多层级权限控制 +``` +Level 1: 多租户拦截器 (自动) +├── 自动添加: WHERE tenant_id = #{currentTenantId} +└── 确保: 租户间数据完全隔离 + +Level 2: 门店级权限控制 (业务层) +├── 业务层添加: AND dept_id = #{currentDeptId} +└── 确保: 同租户不同门店数据隔离 + +Level 3: 租户级共享 (标准拦截器) +├── 适用表: 联系人信息、联系人标签 +├── 拦截器自动添加: WHERE tenant_id = #{currentTenantId} +└── 确保: 租户内所有门店可见，租户间隔离 + +Level 4: 全局共享 (特殊处理) +├── 适用表: 系统配置、字典数据等 +└── 确保: 全局数据对所有租户可见 +``` + +#### 4.3.2 数据隔离策略 +- **租户级隔离**: 联系人信息在租户内共享，所有门店都可以查看和使用 +- **门店级隔离**: 订单、房间、财务等核心业务数据按门店隔离 +- **标签灵活性**: 联系人标签支持门店级和租户级两种模式 + +## 4. 数据模型设计 + +### 5.1 核心实体关系图 (E-R图) + +```mermaid +erDiagram + %% --- 若依基础实体 --- + sys_tenant { + varchar(20) tenant_id PK "租户编号 (业务主键)" + bigint id "物理主键" + varchar(255) company_name "企业/民宿名称" + varchar(50) status "租户状态" + } + + sys_dept { + bigint dept_id PK "部门ID (门店)" + varchar(20) tenant_id FK "关联租户" + varchar(30) dept_name "部门名称 (门店名称)" + varchar(50) status "部门状态" + } + + sys_user { + bigint user_id PK "用户ID (PMS员工)" + varchar(20) tenant_id FK "用户归属租户" + bigint dept_id FK "用户所属部门" + varchar(30) user_name "用户名" + varchar(50) status "用户状态" + } + + %% --- 客户管理实体 --- + pms_customer_contacts { + bigint contact_id PK "联系人ID" + varchar(20) tenant_id FK "所属租户ID" + varchar(255) full_name "联系人姓名" + varchar(50) phone_number "联系电话" + varchar(255) email "邮箱地址" + varchar(50) contact_type "联系人类型" + varchar(50) contact_status "联系人状态" + varchar(50) member_level "会员等级" + int total_stays "总入住次数" + decimal total_amount "总消费金额 (12,2)" + } + + pms_contact_tags { + bigint tag_id PK "标签ID" + varchar(20) tenant_id FK "所属租户ID" + bigint dept_id FK "部门ID (可空)" + varchar(100) name "标签名称" + varchar(20) color "标签颜色" + varchar(50) category "标签分类" + } + + pms_contact_tag_relations { + bigint relation_id PK "关联ID" + varchar(20) tenant_id FK "所属租户ID" + bigint contact_id FK "联系人ID" + bigint tag_id FK "标签ID" + } + + %% --- 房间管理实体 --- + pms_room_types { + bigint room_type_id PK "房型ID" + varchar(20) tenant_id FK "租户ID" + bigint dept_id FK "部门ID (门店)" + varchar(255) name "房型名称" + decimal default_price "默认价格 (10,2)" + int capacity "标准入住人数" + json amenities "房型设施" + varchar(50) status "状态" + } + + pms_room_rooms { + bigint room_id PK "房间ID" + varchar(20) tenant_id FK "租户ID" + bigint dept_id FK "部门ID (门店)" + bigint room_type_id FK "房型ID" + varchar(50) room_number "房间号" + varchar(50) floor "楼层" + varchar(50) room_status "物理状态" + varchar(50) cleaning_status "清洁状态" + } + + %% --- 订单管理实体 --- + pms_core_orders { + bigint order_id PK "订单ID" + varchar(20) tenant_id FK "所属租户ID" + bigint dept_id FK "所属门店ID" + varchar(50) order_status "订单状态" + decimal total_amount "订单总金额 (15,2)" + } + + pms_core_order_items { + bigint order_item_id PK "订单项ID" + varchar(20) tenant_id FK "租户ID" + bigint order_id FK "订单ID" + bigint dept_id FK "部门ID (门店)" + varchar(50) product_type "产品类型 (房费, 服务等)" + varchar(255) description "项目描述" + int quantity "数量" + decimal unit_price "单价 (10,2)" + date service_date "服务日期" + } + + %% --- 财务管理实体 --- + pms_finance_folios { + bigint folio_id PK "账单ID" + varchar(20) tenant_id FK "所属租户ID" + bigint dept_id FK "所属门店ID" + bigint order_id FK "关联订单ID" + decimal total_charges "总费用 (15,2)" + decimal total_payments "总支付 (15,2)" + decimal balance "余额 (15,2)" + } + + pms_finance_transactions { + bigint transaction_id PK "交易ID" + varchar(20) tenant_id FK "租户ID" + bigint folio_id FK "账单ID" + bigint dept_id FK "部门ID (门店)" + varchar(50) transaction_type "交易类型" + decimal amount "交易金额 (10,2)" + varchar(255) description "交易描述" + varchar(100) payment_method_details "支付方式详情 (文本描述)" + datetime transaction_time "交易时间" + } + + %% --- 合作方管理实体 --- + pms_suppliers { + bigint supplier_id PK "供应商ID" + varchar(20) tenant_id FK "所属租户ID (可空, 平台级则为空)" + varchar(50) supplier_type "供应商类型" + varchar(255) company_name "公司名称" + varchar(100) contact_person "联系人" + varchar(50) phone_number "联系电话" + varchar(50) status "供应商状态" + } + + pms_partners { + bigint partner_id PK "合作伙伴ID" + varchar(20) tenant_id FK "所属租户ID (可空, 平台级则为空)" + varchar(50) partner_type "合作伙伴类型" + varchar(255) company_name "公司名称" + varchar(100) contact_person "联系人" + decimal commission_rate "佣金比例 (5,2)" + varchar(50) cooperation_level "合作等级" + varchar(50) status "合作伙伴状态" + } + + %% --- 实体关系定义 --- + sys_tenant ||--o{ sys_dept : "包含门店/部门" + sys_tenant ||--o{ sys_user : "拥有用户" + sys_dept ||--o{ sys_user : "员工属于门店" + + sys_tenant ||--o{ pms_customer_contacts : "拥有客户" + sys_tenant ||--o{ pms_contact_tags : "拥有标签 (租户级)" + sys_dept ||--o{ pms_contact_tags : "拥有标签 (门店级)" + pms_customer_contacts ||--o{ pms_contact_tag_relations : "客户标签关联" + pms_contact_tags ||--o{ pms_contact_tag_relations : "标签关联客户" + + sys_tenant ||--o{ pms_room_types : "定义房型" + sys_dept ||--o{ pms_room_types : "门店房型" + pms_room_types ||--o{ pms_room_rooms : "有具体房间" + + sys_tenant ||--o{ pms_core_orders : "拥有订单" + sys_dept ||--o{ pms_core_orders : "门店订单" + pms_customer_contacts ||--o{ pms_core_orders : "是主要客户" + pms_room_types ||--o{ pms_core_orders : "被预订类型" + pms_room_rooms ||--o{ pms_core_orders : "被分配房间 (可空)" + pms_core_orders ||--o{ pms_core_order_items : "包含项目" + + pms_core_orders |o--|| pms_finance_folios : "生成账单" + pms_finance_folios ||--o{ pms_finance_transactions : "记录交易" + + sys_tenant ||--o{ pms_suppliers : "(管理租户级供应商)" + sys_tenant ||--o{ pms_partners : "(管理租户级合作伙伴)" + %% 平台级供应商/合作伙伴通过 tenant_id IS NULL 实现，不直接在图上显示对平台的FK + %% The pms_tenant_settings relationship to sys_dept, IF pms_tenant_settings were in this diagram, + %% would be: sys_dept ||--o{ pms_tenant_settings : "门店配置" + %% Make sure this line is manually corrected if pms_tenant_settings is re-added elsewhere or if the diagram is less simplified. +``` +*注意：此E-R图为核心业务实体的概览。详细的表结构、字段定义、约束及索引设计，请参考最新的《PMS数据模型设计文档》。* + +### 5.2 数据表分类 + +以下为PMS系统核心业务相关的数据表分类。详细的表结构和字段定义请参考《PMS数据模型设计文档》。 + +#### 5.2.1 若依基础表 (继承) +| 表名 | 说明 | 数据隔离 | +| ---------- | ---------------------------------------- | -------- | +| sys_tenant | 租户信息表 | 全局 | +| sys_dept | 部门表 (在本系统中作为**门店/分店**使用) | 租户级 | +| sys_user | 用户信息表 (PMS系统员工) | 租户级 | +| sys_role | 角色信息表 | 租户级 | +*其他若依基础表按原框架定义使用。* + +#### 5.2.2 客户管理表 +| 表名 | 说明 | 数据隔离 | +| ------------------------- | -------------------------------- | ------------- | +| pms_customer_contacts | 存储客户核心档案信息 | 租户级共享 | +| pms_contact_tags | 定义客户标签，支持租户级和门店级 | 租户级/门店级 | +| pms_contact_tag_relations | 客户与标签的关联关系 | 租户级 | + +#### 5.2.3 房间管理表 +| 表名 | 说明 | 数据隔离 | +| -------------- | -------------------------------------- | -------- | +| pms_room_types | 定义房型基础信息、价格、设施等 | 门店级 | +| pms_room_rooms | 管理具体的物理房间及其当前状态 | 门店级 | +| pms_room_locks | 记录房间的临时锁定信息（如维护、清洁） | 门店级 | + +#### 5.2.4 价格管理表 +| 表名 | 说明 | 数据隔离 | +| ---------------------- | ---------------------------- | -------- | +| pms_room_pricing_rules | 定义房价的动态调整规则和策略 | 门店级 | + +#### 5.2.5 订单管理表 +| 表名 | 说明 | 数据隔离 | +| -------------------- | ------------------------------------ | -------- | +| pms_core_orders | 存储客户预订的核心订单信息 | 门店级 | +| pms_core_order_items | 存储订单中的具体项目，如房费、服务费 | 门店级 | +| pms_core_channels | 定义订单的来源渠道信息 | 门店级 | + +#### 5.2.6 财务管理表 +| 表名 | 说明 | 数据隔离 | +| ------------------------------ | ---------------------------------- | -------- | +| pms_finance_folios | 管理客户在店期间的账务信息（账单） | 门店级 | +| pms_finance_transactions | 记录所有财务相关的交易流水明细 | 门店级 | +| pms_finance_payment_methods | 定义系统支持的支付方式 | 门店级 | +| pms_finance_extra_charge_items | 定义订单中可添加的附加费用项目 | 门店级 | + +#### 5.2.7 合作方管理表 +| 表名 | 说明 | 数据隔离 | +| ------------- | ------------------------------------- | ------------ | +| pms_suppliers | 存储供应商信息 (如清洁服务、物料供应) | 全局或租户级 | +| pms_partners | 存储合作伙伴信息 (如旅行社、OTA平台) | 全局或租户级 | +*全局共享数据通过 `tenant_id IS NULL` 实现，租户级数据则记录对应 `tenant_id`。* + +#### 5.2.8 系统配置表 +| 表名 | 说明 | 数据隔离 | +| ----------------------- | ---------------------------------------- | ------------- | +| pms_tenant_settings | 存储租户级或门店级的各项业务配置参数 | 租户级/门店级 | +| pms_mp_settings | 存储小程序相关的配置信息 | 租户级/门店级 | +| pms_tenant_user_devices | 存储用户登录过的设备信息，用于消息推送等 | 租户级 | + +### 5.3 核心枚举值定义 + +系统中使用的各类业务状态和类型枚举值（例如：订单状态、客户类型、房间清洁状态等），其详细定义、可选值及完整列表请参考最新的《PMS数据模型设计文档》中的相应章节（通常在第5节"核心业务枚举值定义"）。 + +在本文档后续的功能描述中，会根据上下文需要提及关键的枚举值及其业务含义，但《PMS数据模型设计文档》是枚举定义的唯一权威来源，以确保信息的一致性和准确性。 + +## 6. 联系人管理 + +### 6.1 业务背景 +联系人管理是PMS系统的核心模块，负责管理所有与业务相关的联系人信息，包括客户、供应商、合作伙伴等。采用租户级共享模式，确保租户内所有门店都能访问和使用客户联系人信息。 + +### 6.2 客户联系人核心功能 +#### 6.2.1 基础联系人管理 [P0] +- **联系人档案**: 创建和维护客户基本信息（姓名、电话、邮箱等）。 +- **订单关联**: 将联系人与其历史订单关联。 +- **简单搜索**: 支持按姓名、电话等关键信息搜索联系人。 + +#### 6.2.2 会员体系 [P1] +- **会员等级**: 建立基础的会员等级体系。 +- **积分系统**: 实现积分累积和兑换机制。 +- **会员权益**: 为不同等级会员提供差异化权益。 + +#### 6.2.3 高级会员功能 [P2] +- **个性化服务**: 记录客户偏好，提供个性化服务。 +- **会员营销**: 针对不同会员群体进行精准营销。 +- **客户分析**: 提供客户价值分析和行为分析。 + +### 6.3 客户联系人数据模型与规则 + +#### 6.3.1 功能概述 +- **关联数据表**: `pms_customer_contacts` (主表), `pms_contact_tags`, `pms_contact_tag_relations` +- **数据权限**: 客户联系人信息（`pms_customer_contacts`）为租户级共享，使用标准多租户拦截器。标签（`pms_contact_tags`）支持租户级和门店级。 +- **业务范围**: 管理所有类型的客户联系人信息，包括其基本档案、会员信息、标签关联等。 +*详细的表结构、字段定义、约束及索引设计，请参考最新的《PMS数据模型设计文档》。* + +#### 6.3.2 核心字段设计 +核心业务字段的描述保留在功能需求中，例如： +- **联系人类型 (`contact_type`)**: 用于区分不同类型的联系人，如散客、团队负责人、企业联系人等。具体枚举值参见数据模型文档。 +- **联系人状态 (`contact_status`)**: 标识联系人的当前状态，如活跃、不活跃、黑名单。具体枚举值参见数据模型文档。 +- **会员等级 (`member_level`)**: 记录联系人的会员级别。 +- **证件号码 (`id_number_encrypted`)**: 存储加密后的客户证件号码，确保数据安全。 +- 其他关键业务字段将在后续功能点中结合描述。 + +#### 6.3.3 业务规则 +1. **唯一性约束**: 同一租户内，有效的手机号码 (`phone_number`) 应唯一。若系统配置要求，有效的、未作废的证件号码 (`id_number_encrypted`) 在同一租户内也应唯一。 +2. **数据共享**: 客户联系人核心信息在租户内所有门店间共享。 +3. **隐私保护**: 客户的证件号码、银行卡信息（如果涉及）等敏感数据必须加密存储，并遵循最小权限原则进行访问和展示（如脱敏显示）。 +4. **状态管理**: 支持联系人的多种状态，并可能影响其相关业务操作（例如，黑名单客户可能无法创建新订单）。 +5. **会员体系**: 支持多级会员等级，会员等级可与特定权益或价格策略关联。 + +### 6.4 联系人标签管理 + +#### 6.4.1 功能概述 +- **关联数据表**: `pms_contact_tags` (标签定义表), `pms_contact_tag_relations` (客户与标签关联表) +- **数据权限**: 标签可以定义为租户级（`dept_id` 为 NULL）或门店级（`dept_id` 有效）。查询客户关联的标签时，会合并其可访问的租户级标签和所属门店的门店级标签。 +- **灵活性**: 支持多种标签分类（如客户等级、偏好、来源等），并允许自定义标签颜色以增强可视化区分。 +*详细的表结构、字段定义、约束及索引设计，请参考最新的《PMS数据模型设计文档》。* + +#### 6.4.2 核心字段设计 +- **标签名称 (`name`)**: 标签的显示名称，应简洁明了。 +- **标签分类 (`category`)**: 用于对标签进行分组管理，便于筛选和应用。具体枚举值参见数据模型文档。 +- **部门ID (`dept_id`)**: 用于区分租户级标签和门店级标签。 + +#### 6.4.3 标签关联管理 +- 主要通过 `pms_contact_tag_relations` 表实现客户与标签的多对多关联。 +- 创建关联时需校验标签的有效性和客户的可访问性（租户一致，门店标签需匹配或为租户级）。 + +## 7. 房态管理 + +### 7.1 核心功能与操作 + +#### 7.1.1 房态管理核心 [P0] +- **功能描述:** + - **网格日历视图**: 直观展示房间在选定日期范围内的占用情况（已预订、已入住、清洁中、维护锁定）。 + - **今日状态列表**: 按预抵、在住、预离分类展示当日订单/房间。 + - **清洁状态管理**: 手动标记房间清洁状态（待清洁/清洁中/已干净）。 + - **快捷操作**: 在房态图上可快速创建预订、登记入住/退房、标记房间清洁状态、设置房间临时锁定/解锁。 +- **核心操作:** + - **查询房态**: 用户可按日期范围查看房态日历，不同状态房间用不同颜色标记。 + - **修改房间清洁状态**: 更新房间清洁状态，影响房态图显示。 + - **设置房间维护/锁定**: 设置房间维护或锁定状态，记录原因和时间范围。 + +### 7.2 房型管理 +**数据表**: `pms_room_types` +**数据隔离**: 门店级隔离 + +**房型管理功能**: +- 房型定义、价格设置、设施配置 +- 容量管理、图片上传、详细描述 +- 床型信息、房间面积、设施标签 + +### 7.3 房间管理 +**数据表**: `pms_room_rooms` +**数据隔离**: 门店级隔离 + +**房间管理功能**: +- 房间编号、楼层、当前状态 +- 房间状态：可用/占用中/维护中/暂停服务 +- 清洁状态：已清洁/待清洁/清洁中/已查房 + +### 7.4 实时房态监控 +**数据表**: `pms_room_rooms`, `pms_room_locks` +**数据隔离**: 门店级隔离 + +**实时房态监控功能**: +- 房间状态实时显示：可用、占用中、维护中、暂停服务 +- 清洁状态跟踪：已清洁、待清洁、清洁中、已查房 +- 房态变更历史记录和审计 + +### 7.5 房间锁定管理 +**数据表**: `pms_room_locks` (ER图中的定义) +**数据隔离**: 门店级隔离 + +**锁定类型**: +- 锁定类型：手动锁定、维护锁定、自动锁定、员工自用、清洁锁定 +- 锁定时间段：开始时间、结束时间、锁定原因 +- 批量锁定操作：支持多房间同时锁定 + +### 7.6 清洁流程管理 +**清洁管理功能**: +- 清洁任务分配和跟踪 +- 清洁标准检查清单 +- 查房流程和质量控制 +- 清洁人员工作量统计 + +### 7.7 维护计划管理 +**维护管理功能**: +- 定期维护计划制定 +- 维护任务分配和跟踪 +- 维护成本记录和分析 +- 设备保养提醒 + +## 8. 价格管理 + +### 8.1 动态定价规则 +**数据表**: `pms_room_pricing_rules` +**数据隔离**: 门店级隔离 + +**基础价格设置**: +- 基础价格设置：房型默认价格 +- 季节性价格调整：淡旺季价格策略 +- 周末/节假日价格：特殊日期价格规则 +- 连住优惠：最小/最大入住天数限制 +- **价格调整类型**: 具体的调整类型（如固定价格覆盖、百分比折扣等） + +### 8.2 价格规则管理 +**价格规则功能**: +- 规则优先级设置：数字越大优先级越高 +- 适用日期范围：开始日期、结束日期 +- 适用星期设置：支持特定星期几 +- 房型适用范围：全部房型或特定房型 + +### 8.3 价格计算引擎 +**价格计算功能**: +- 多规则叠加计算 +- 实时价格查询API +- 价格变更历史记录 +- 收益分析和报表 + +### 8.4 价格计算历史追踪 [P0] +**数据表**: `pms_pricing_calculations` +**数据隔离**: 门店级隔离 + +**价格计算历史功能**: +- **计算过程记录**: 完整记录每次价格计算的过程和结果。 +- **规则应用详情**: 记录哪些价格规则被应用，以及具体的调整金额。 +- **价格审计**: 提供价格计算的完整审计轨迹，便于问题排查。 +- **历史价格查询**: 支持查询历史某个时间点的价格计算结果。 +- **价格趋势分析**: 基于历史计算数据分析价格变化趋势。 + +### 8.5 特殊日期价格管理 [P1] +**数据表**: `pms_special_date_pricing` +**数据隔离**: 门店级隔离 + +**特殊日期价格功能**: +- **节假日价格**: 支持国家法定节假日、传统节日的特殊定价。 +- **活动日价格**: 支持本地活动、会展、赛事等特殊事件的定价。 +- **日期类型管理**: 区分不同类型的特殊日期，如节假日、活动日、促销日等。 +- **批量设置**: 支持批量设置连续日期的特殊价格。 +- **优先级控制**: 特殊日期价格具有更高的优先级，覆盖常规价格规则。 + +### 8.6 高级价格规则 [P2] +**价格规则增强功能**: +- **渠道差异化定价**: 不同预订渠道可设置不同的价格策略。 +- **客人数量定价**: 根据入住客人数量调整价格。 +- **提前预订优惠**: 根据提前预订天数给予不同程度的优惠。 +- **规则组合策略**: 支持多个价格规则的智能组合和冲突处理。 +- **动态库存定价**: 根据剩余库存情况动态调整价格。 +- **会员专享价格**: 为不同等级会员提供专属价格。 + +### 8.7 价格策略分析 [P2] +**价格分析功能**: +- **收益优化建议**: 基于历史数据和市场情况提供价格优化建议。 +- **竞争对手价格监控**: 监控竞争对手的价格变化趋势。 +- **价格弹性分析**: 分析价格变化对预订量的影响。 +- **最优价格推荐**: 基于算法模型推荐最优价格策略。 + +## 9. 订单管理 + +### 9.1 订单核心功能 + +#### 9.1.1 核心订单生命周期管理 [P0] +- **功能描述:** 高效、准确地管理所有来源的预订订单，覆盖从订单创建到完成的整个生命周期。订单状态的详细定义 (如 `pending_confirmation`, `confirmed` 等) +- **手动创建订单**: 支持前台为散客或电话预订创建订单。 +- **接收商城订单**: 通过API自动接收来自C端商城H5的预订订单。 +- **订单详情查看与编辑**: 查看订单的全部信息，允许在特定规则下修改部分信息。 +- **核心状态管理**: 管理订单的基本状态流转：待确认、已确认、已入住、已退房、已取消、未入住。 +- **关联联系人与房间**: 将订单与联系人档案和具体房号关联。 +- **生成账单基础**: 为每个订单生成初始账单框架。 +- **房态联动**: 订单的创建、确认、取消、入住、退房应实时更新PMS核心房态图。 + +#### 9.1.2 订单状态流转图 +```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 --> [*] +``` + +#### 9.1.3 订单状态历史追踪 [P0] +- **状态变更记录**: 完整记录订单状态的每次变更，包括变更时间、操作人、变更原因。 +- **操作审计**: 追踪所有订单相关的关键操作，确保业务流程的可追溯性。 +- **状态回滚支持**: 在特殊情况下支持订单状态的回滚操作。 +- **变更通知**: 订单状态变更时自动通知相关人员。 + +#### 9.1.4 订单时间管理 [P0] +- **关键时间点记录**: 记录订单确认时间、实际入住时间、实际退房时间、取消时间等。 +- **预计到达时间**: 支持客人预约到达时间，便于前台安排接待。 +- **时间差异分析**: 分析计划时间与实际时间的差异，优化运营流程。 +- **超时提醒**: 对超时未入住、超时未退房等情况进行自动提醒。 + +#### 9.1.5 入住客人信息管理 [P1] +- **主客人信息**: 记录订单主要联系人的详细信息。 +- **同行客人管理**: 支持记录同行入住客人的基本信息和证件信息。 +- **客人类型区分**: 区分成人、儿童、婴儿等不同类型客人。 +- **证件信息加密**: 客人证件信息采用加密存储，确保数据安全。 +- **入住登记**: 支持快速办理多人入住登记手续。 +- **客人档案关联**: 支持将入住客人与租户级客户档案关联，实现客户信息积累和复用。 +- **智能档案匹配**: 基于姓名、电话、证件号等信息智能匹配现有客户档案。 +- **新档案创建**: 对于新客人，支持在入住登记时同步创建客户档案。 + +#### 9.1.6 客人与联系人关联管理 [P0] +- **主客人关联**: 订单主客人必须关联到客户联系人档案，用于客户关系维护。 +- **同行客人选择性关联**: 同行客人可选择关联现有档案或创建新档案。 +- **临时客人支持**: 支持不关联档案的临时入住客人，仅记录基本入住信息。 +- **档案信息同步**: 客人信息变更时可选择同步更新客户档案。 +- **统计数据更新**: 入住完成后自动更新客户档案的入住次数、消费金额等统计信息。 + +#### 9.1.7 订单管理增强功能 [P1] +- **订单修改**: 允许修改已确认订单的关键信息，系统需重新校验库存和价格。 +- **款项管理**: 处理预付款、押金、部分付款的记录和跟踪。 +- **取消与退款**: 支持更细致的取消政策配置，并根据政策处理退款流程。 +- **基础支付集成**: 对接主流支付网关，支持在线支付扫码收款或记录线下收款。 +- **自动化通知**: 通过短信或微信模板消息，发送订单状态相关的自动化通知。 +- **订单备注与标签**: 支持为订单添加内部备注和自定义标签。 +- **特殊要求处理**: 记录和处理客人的特殊要求，如房间偏好、服务需求等。 + +#### 9.1.8 实用订单工具与基础渠道对接 [P2] +- **简版团体预订管理**: 支持为团体设置统一联系人并关联多个订单。 +- **等候名单**: 当房型在特定日期满房时，允许客人加入等候名单。 +- **Channel Manager单向订单接收**: 通过与第三方Channel Manager对接，实现单向自动接收来自OTA的订单。 +- **订单报表**: 提供多维度订单分析报表。 +- **发票管理**: 支持为订单生成和管理发票信息。 + +### 9.2 订单处理 (详细定义) +**数据表**: `pms_core_orders`, `pms_core_order_items`, `pms_core_channels`, `pms_order_status_history`, `pms_order_guests` +**数据隔离**: 门店级隔离 + +**订单处理功能**: +- 订单创建、修改、取消、确认 +- 入住/退房流程管理 +- 客户信息关联（关联到租户级共享的客户档案） +- 房间分配与变更 +- 订单状态历史追踪 +- 入住客人信息管理 + +### 9.3 订单来源渠道管理 +**数据表**: `pms_core_channels` (ER图中的定义) +**数据隔离**: 门店级隔离 (通常渠道定义可能是租户级或全局，但这里按订单关联的门店) + +**渠道类型与配置**: +- **渠道类型**: 具体的渠道类型 (如 OTA, 直接预订等) 参见 [5.3.4 订单相关枚举](#534-订单相关枚举) 中 `pms_core_channels.channel_type` 的定义。 +- **渠道配置**: 携程、飞猪、官网直订、电话预订、现场步入 +- **渠道管理**: 渠道佣金设置和统计、渠道性能分析 + +### 9.4 订单项目管理 +**数据表**: `pms_core_order_items` (ER图中的定义) +**数据隔离**: 门店级隔离 + +**订单项目功能**: +- 房晚费用、附加服务费用 +- 项目描述、数量、单价、服务日期 +- 费用调整和优惠处理 + +### 9.5 库存管理与房态联动 [P1] +**数据表**: `pms_room_inventory_snapshot` +**数据隔离**: 门店级隔离 + +**库存管理功能**: +- **实时库存查询**: 快速查询指定日期范围内的房型可用性。 +- **库存快照**: 定期生成房型库存快照，提升查询性能。 +- **超售保护**: 防止房间超售，确保库存准确性。 +- **房态实时同步**: 订单状态变更时实时更新房间状态和库存。 +- **可用性预测**: 基于历史数据预测未来库存紧张情况。 + +## 10. 财务管理 + +### 10.1 财务核心功能 + +#### 10.1.1 基础财务管理 [P0] +- **功能描述:** 为民宿提供完整的财务管理能力，确保收入准确记录和账务清晰。 +- **账单(Folio)管理**: 为每个联系人/订单创建和维护详细的费用清单。 +- **交易记录**: 记录所有收入和支出交易，包括房费、押金、额外消费等。 +- **基础支付方式**: 支持现金、银行卡、微信支付、支付宝等常见支付方式。 +- **简单对账**: 提供基础的收入汇总和对账功能。 + +#### 10.1.2 增强财务功能 [P1] +- **多币种支持**: 支持多种货币的收费和汇率转换。 +- **发票管理**: 生成和管理各类发票。 +- **财务报表**: 提供收入、支出、利润等基础财务报表。 +- **预付款和押金管理**: 详细管理预付款、押金的收取和退还。 + +#### 10.1.3 高级财务工具 [P2] +- **成本核算**: 支持房间成本、运营成本的核算。 +- **收益管理**: 提供ADR、RevPAR等关键指标分析。 +- **税务管理**: 支持税务计算和申报辅助功能。 + +### 10.2 账单管理 (详细定义) +**数据表**: `pms_finance_folios` +**数据隔离**: 门店级隔离 + +**账单管理功能**: +- 自动生成订单账单、费用明细 +- 支持额外费用添加、调整 +- 账单状态：Refer to section [5.3.5 财务相关枚举](#535-财务相关枚举) for `pms_finance_folios.folio_status` values. + +### 10.3 支付管理 (详细定义) +**数据表**: `pms_finance_payment_methods` +**数据隔离**: 门店级隔离 (支付方式定义通常是租户级或全局，但这里指门店可用的支付方式关联) + +**支付管理功能**: +- 多种支付方式：Refer to section [5.3.5 财务相关枚举](#535-财务相关枚举) for `pms_finance_payment_methods.method_type` values. +- 支付记录、退款处理 +- 押金管理、预付款处理 + +### 10.4 附加费用管理 (详细定义) +**数据表**: `pms_finance_extra_charge_items` +**数据隔离**: 门店级隔离 + +**附加费用功能**: +- 费用项目定义：项目名称、默认单价、费用类别 (Refer to section [5.3.5 财务相关枚举](#535-财务相关枚举) for `pms_finance_extra_charge_items.category` values) +- 税费设置：是否应税、税率配置 +- 费用统计和分析 + +### 10.5 交易流水管理 (详细定义) +**数据表**: `pms_finance_transactions` +**数据隔离**: 门店级隔离 + +**交易流水功能**: +- 交易类型：Refer to section [5.3.5 财务相关枚举](#535-财务相关枚举) for `pms_finance_transactions.transaction_type` values. +- 支付网关集成：支付宝、微信支付接口 +- 交易作废和冲销处理 +- 财务对账和报表 + +## 11. 系统配置管理 + +### 11.1 系统管理核心功能 + +#### 11.1.1 基础系统管理 [P0] +- **功能描述:** 为租户提供系统配置和管理能力。 +- **用户账号管理**: 管理租户内部员工账号和权限。 +- **基础设置**: 配置民宿基本信息、营业时间等。 +- **角色权限**: 基础的角色权限管理。 + +#### 11.1.2 增强管理功能 [P1] +- **高级权限控制**: 更细粒度的权限控制。 +- **系统日志**: 查看系统操作日志。 +- **数据备份**: 提供数据备份和恢复功能。 + +### 11.2 租户级配置管理 (详细定义) +**数据表**: `pms_tenant_settings` +**数据隔离**: 租户级和门店级配置 + +**租户级配置功能**: +- 配置分组：预订规则、财务参数、界面外观、业务流程 +- 配置项管理：键值对存储、数据类型支持 (`value_type`) +- 敏感配置保护：加密存储 (`is_sensitive` field), 访问控制 +- 配置继承：租户级配置、门店级覆盖 (通过 `dept_id` 可空实现) + +### 11.3 小程序配置 (详细定义) +**数据表**: `pms_mp_settings` +**数据隔离**: 租户级和门店级配置 (通过 `dept_id` 可空实现) + +**小程序配置功能**: +- 主题颜色、品牌标识、功能开关 +- 支付配置、通知配置、地图配置 +- 客户端版本管理、功能权限控制 + +### 11.4 设备管理 (详细定义) +**数据表**: `pms_tenant_user_devices` +**数据隔离**: 租户级 + +**设备管理功能**: +- 用户设备注册：iOS, Android, 微信小程序, Web (来自 `device_type`) +- 推送令牌管理 (`device_token`), 设备状态跟踪 +- 设备登录历史 (`last_login_time`), 安全审计 +- 多设备登录控制 + +### 11.5 配置项示例 +```yaml +预订规则配置: + - max_advance_booking_days: 365 # 最大提前预订天数 + - min_advance_booking_hours: 2 # 最小提前预订小时 + - allow_same_day_booking: true # 允许当日预订 + - auto_confirm_booking: false # 自动确认预订 + +财务参数配置: + - default_currency: CNY # 默认货币 + - tax_rate: 0.06 # 税率 + - deposit_percentage: 0.3 # 押金比例 + - cancellation_fee_rate: 0.1 # 取消费率 + +界面外观配置: + - theme_color: "#409EFF" # 主题色 + - logo_url: "/images/logo.png" # 品牌标识 + - welcome_message: "欢迎入住" # 欢迎语 +``` + +### 11.6 配置模板管理 (新增功能) +**数据表**: 扩展 `pms_tenant_settings` 和 `pms_mp_settings` +**数据隔离**: 租户级 + +**配置模板功能**: +- 预定义配置模板：快速部署标准配置方案 +- 模板分类管理：按业务场景分类（经济型、标准型、豪华型） +- 模板应用机制：一键应用模板到租户或门店 +- 模板导入导出：支持配置方案的备份和迁移 +- 模板版本管理：支持模板的版本控制和回滚 + +### 11.7 系统监控与审计 (新增功能) +**数据表**: 利用系统日志表和配置变更记录 +**数据隔离**: 租户级 + +**监控功能**: +- 配置变更监控：实时监控配置项的变更情况 +- 用户行为监控：跟踪用户的配置操作行为 +- 性能监控：监控配置加载和应用的性能指标 +- 安全审计：记录敏感配置的访问和修改日志 +- 报警管理：配置异常变更的自动报警机制 + +### 11.8 配置继承与覆盖机制 (详细定义) +**实现方式**: 通过 `dept_id` 字段的空值处理 + +**继承规则**: +- 租户级配置：`dept_id` 为 NULL，作为默认配置 +- 门店级配置：`dept_id` 非空，覆盖租户级配置 +- 查询优先级：门店级配置 > 租户级配置 > 系统默认配置 +- 配置合并：支持部分覆盖，未设置的项目继承上级配置 + +**覆盖策略**: +```yaml +配置查询逻辑: + 1. 查询门店级配置 (dept_id = 当前门店ID) + 2. 如果不存在，查询租户级配置 (dept_id IS NULL) + 3. 如果仍不存在，使用系统默认值 + 4. 返回最终配置值 + +配置设置逻辑: + 1. 门店级设置：直接设置 dept_id = 门店ID + 2. 租户级设置：设置 dept_id = NULL + 3. 删除门店级配置：恢复继承租户级配置 +``` + +### 11.9 敏感配置安全管理 (详细定义) +**安全机制**: 通过 `is_sensitive` 字段标识 + +**安全功能**: +- 加密存储：敏感配置值使用AES加密存储 +- 访问控制：敏感配置需要特殊权限才能查看和修改 +- 操作审计：所有敏感配置的操作都记录详细日志 +- 脱敏显示：前端显示时对敏感信息进行脱敏处理 +- 权限分级：不同角色对敏感配置有不同的访问权限 + +**敏感配置示例**: +```yaml +支付配置: + - wechat_app_secret: "加密存储的微信小程序密钥" + - alipay_private_key: "加密存储的支付宝私钥" + - payment_callback_token: "加密存储的支付回调令牌" + +第三方接口配置: + - sms_api_key: "加密存储的短信服务API密钥" + - email_smtp_password: "加密存储的邮件服务密码" + - map_api_secret: "加密存储的地图服务密钥" +``` + +### 11.10 用户设备管理详细功能 (详细定义) +**数据表**: `pms_tenant_user_devices` +**数据隔离**: 租户级 + +**设备注册与管理**: +- 自动设备注册：用户登录时自动注册设备信息 +- 设备信息收集：设备类型、设备名称、操作系统版本、应用版本 +- 设备状态管理：活跃、不活跃、过期、阻止等状态控制 +- 多设备支持：同一用户可在多个设备上登录 + +**推送令牌管理**: +- 令牌自动更新：设备令牌变更时自动更新 +- 推送开关控制：用户可控制是否接收推送通知 +- 推送历史记录：记录推送消息的发送和接收状态 +- 批量推送支持：支持按设备类型、用户群体批量推送 + +**安全审计功能**: +- 登录历史记录：记录每次登录的时间、IP地址、位置信息 +- 异常登录检测：检测异常登录行为并发出警告 +- 设备锁定机制：可远程锁定或解锁特定设备 +- 登录统计分析：提供用户登录行为的统计分析 + +### 11.11 小程序配置管理详细功能 (详细定义) +**数据表**: `pms_mp_settings` +**数据隔离**: 租户级和门店级 + +**主题配置管理**: +- 颜色主题：主色调、辅助色、背景色、文字色 +- 品牌元素：Logo、品牌名称、Slogan、品牌介绍 +- 界面布局：首页布局、菜单样式、按钮样式 +- 多主题支持：支持预设主题和自定义主题 + +**功能开关管理**: +- 业务功能：在线预订、在线支付、客房服务、意见反馈 +- 营销功能：优惠券、积分系统、会员等级、推荐奖励 +- 社交功能：分享功能、评价系统、客服聊天 +- 高级功能：人脸识别、语音助手、AR看房 + +**支付配置管理**: +- 支付方式：微信支付、支付宝、银联支付、现金支付 +- 支付参数：商户号、密钥配置、回调地址 +- 支付流程：支付超时时间、重试机制、退款策略 +- 支付安全：支付验证、风控规则、异常监控 + +**通知配置管理**: +- 通知类型：预订确认、入住提醒、退房提醒、活动通知 +- 通知渠道：小程序消息、短信通知、邮件通知 +- 通知时机：提前通知时间、重复提醒设置 +- 通知模板：消息模板管理、个性化内容设置 + +## 12. 业务流程设计 + +### 12.1 客户管理流程 ```mermaid flowchart TD - subgraph PMSCore["PMS核心业务子系统"] - PMS["PMS租户
核心业务子系统"]:::coreSystem - end + A[客户初次接触] --> B{是否已有档案} + B -->|否| C[创建客户档案] + B -->|是| D[更新客户信息] + C --> E[分配客户标签] + D --> E + E --> F[关联订单信息] + F --> G[更新客户统计] + G --> H[推送营销活动] - 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 + I[门店员工] --> J[查看租户级客户] + J --> K[任意门店可见同一客户] + K --> L[提升服务连贯性] ``` -## 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租户核心业务子系统组件图 +### 12.2 房态管理流程 ```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 + A[客人退房] --> B[房间状态变更为脏房] + B --> C[分配清洁任务] + C --> D[清洁人员开始清洁] + D --> E[清洁状态更新为清洁中] + E --> F[清洁完成] + F --> G[查房人员检查] + G --> H{查房是否通过} + H -->|通过| I[房间状态变更为可用] + H -->|不通过| J[重新清洁] + J --> E + I --> K[房间可供预订] - 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 + L[维护需求] --> M[房间锁定] + M --> N[维护任务执行] + N --> O[维护完成解锁] + O --> I ``` -## 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核心) +### 12.3 动态定价流程 ```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) +flowchart TD + A[客户查询房价] --> B[获取房型基础价格] + B --> C[查询适用的价格规则] + C --> D[按优先级排序规则] + D --> E[应用价格调整] + E --> F[计算最终价格] + F --> G[返回价格信息] - 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) + H[价格规则管理] --> I[创建价格规则] + I --> J[设置适用条件] + J --> K[设置调整类型和值] + K --> L[设置优先级] + L --> M[激活规则] ``` - -### 附录B 实体关系图 (PMS核心及关联) +### 12.4 订单处理流程 ```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 +flowchart TD + A[接收订单] --> B[验证房型可用性] + B --> C[计算动态价格] + C --> D[关联客户档案] + D --> E[生成订单记录] + E --> F[分配房间] + F --> G[生成账单] + G --> H[处理支付] + H --> I[确认订单] + I --> J[入住流程] + J --> K[房态更新] + K --> L[退房结算] ``` + +### 12.5 财务结算流程 + +```mermaid +flowchart TD + A[订单确认] --> B[生成账单Folio] + B --> C[添加房费项目] + C --> D[添加附加费用] + D --> E[计算总金额] + E --> F[客户付款] + F --> G[记录交易流水] + G --> H[更新账单状态] + H --> I{是否结清} + I -->|是| J[关闭账单] + I -->|否| K[等待后续付款] + K --> F + J --> L[生成财务报表] +``` + +### 12.6 入住登记优化流程 + +```mermaid +flowchart TD + A[订单确认] --> B[查询主联系人档案] + B --> C[预填入住信息] + C --> D[录入同行客人] + D --> E{客人是否已有档案} + E -->|是| F[关联现有档案] + E -->|否| G[选择创建新档案] + F --> H[完成入住登记] + G --> I[创建客户档案] + I --> H + H --> J[更新客户统计] + J --> K[房态更新] +``` + +### 12.7 客户档案维护流程 + +```mermaid +flowchart TD + A[客人入住] --> B[记录入住信息] + B --> C[更新客户统计] + C --> D[分析客户偏好] + D --> E[更新会员等级] + E --> F[推送个性化服务] + F --> G[记录服务反馈] + G --> H[优化偏好模型] +``` + +## 13. 接口设计规范 + +### 13.0 通用约定 + +#### 13.0.1 标准成功响应结构 +所有查询类（GET）和操作成功类（POST, PUT, DELETE 无特定返回内容时）的API在成功时，应返回如下结构体： +```json +{ + "code": 0, // 0 表示成功，其他业务错误码见下文 + "message": "操作成功", // 或 "查询成功" + "data": { + // 对于列表查询，通常包含 list 和 total/page/size + // 对于单个对象查询或创建/更新操作，直接是对象本身或其ID + } +} +``` + +#### 13.0.2 标准错误响应结构 +当发生业务逻辑错误、参数校验失败、权限不足或服务器内部错误时，API应返回统一的错误结构体： +```json +{ + "code": 10001, // 具体业务错误码，非0 + "message": "具体的错误描述信息", // 例如 "参数校验失败：名称不能为空" + "details": [ // 可选，用于提供更详细的错误点，例如多字段校验失败 + {"field": "fieldName", "message": "错误详情"} + ] +} +``` +**通用HTTP状态码约定:** +- `200 OK`: GET请求成功，PUT/PATCH部分更新成功。 +- `201 Created`: POST请求成功创建资源。 +- `204 No Content`: DELETE请求成功，响应体中无内容。 +- `400 Bad Request`: 请求参数校验失败、请求体格式错误。 +- `401 Unauthorized`: 未认证或认证无效。 +- `403 Forbidden`: 已认证但无权限访问该资源。 +- `404 Not Found`: 请求的资源不存在。 +- `422 Unprocessable Entity`: 请求格式正确，但由于含有语义错误，无法响应。（例如，尝试创建一个已存在的唯一资源） +- `500 Internal Server Error`: 服务器内部发生未预期错误。 + +#### 13.0.3 分页参数约定 +- `page` (integer, optional, default: 1): 请求的页码，从1开始。 +- `size` (integer, optional, default: 10): 每页返回的记录数量，建议服务端限制最大值 (如100)。 + +#### 13.0.4 日期时间格式 +- 所有API请求和响应中的日期时间格式统一使用 ISO 8601 格式，例如: `YYYY-MM-DDTHH:mm:ssZ` (UTC时间) 或 `YYYY-MM-DD HH:mm:ss` (带时区信息，具体由后端统一确定并在此明确)。推荐使用UTC时间。 + +### 13.1 客户管理API + +#### 13.1.1 查询客户联系人列表 +```http +GET /api/pms/customer-contacts +``` +**描述**: 查询当前租户下的客户联系人列表，支持分页和多种条件筛选。多租户拦截器自动添加 `tenant_id` 过滤。 +**权限**: `pms:customerContacts:list` (示例权限点) + +**查询参数**: +- `page` (integer, optional, default: 1): 页码。 +- `size` (integer, optional, default: 10): 每页数量。 +- `contactType` (string, optional): 联系人类型 (枚举值参考《PMS数据模型设计文档》中 `pms_customer_contacts.contact_type` 定义)。 +- `contactStatus` (string, optional): 联系人状态 (枚举值参考《PMS数据模型设计文档》中 `pms_customer_contacts.contact_status` 定义)。 +- `memberLevel` (string, optional): 会员等级 (枚举值参考《PMS数据模型设计文档》中 `pms_customer_contacts.member_level` 定义)。 +- `fullName` (string, optional, maxLength: 255): 联系人姓名 (模糊查询)。 +- `phoneNumber` (string, optional, maxLength: 50): 联系电话 (精确或模糊查询)。 +- `idNumber` (string, optional): 证件号码 (精确查询, 后端需处理加密匹配)。 （**注意隐私和安全风险，仅在必要且有权限时提供此查询方式**） +- `tagId` (long, optional): 包含指定标签ID的联系人。 +- `sortBy` (string, optional, enum: `createTime`, `lastStayDate`, `totalAmount`): 排序字段。 +- `sortOrder` (string, optional, enum: `asc`, `desc`, default: `desc`): 排序顺序。 + +**成功响应 (200 OK)**: +```json +{ + "code": 0, + "message": "查询成功", + "data": { + "list": [ +{ + "contactId": 1001, + "tenantId": "T001", + "contactType": "individual_guest", + "fullName": "张三", + "phoneNumber": "13800138000", + "email": "zhangsan@example.com", + "gender": "male", // 枚举值参考 PMS数据模型.md 5.1节 + "dateOfBirth": "1990-01-01", + "idType": "ID_CARD", // 枚举值 + "idNumberMasked": "340***********1234", // 脱敏显示 + "nationalityCountryCode": "CHN", + "addressProvince": "安徽省", + "addressCity": "合肥市", + "addressDistrict": "蜀山区", + "addressDetail": "望江西路xxx号", + "postalCode": "230000", + "contactStatus": "active", + "memberLevel": "gold", + "totalStays": 5, + "totalAmount": 2500.00, + "lastStayDate": "2023-10-01", + "remarks": "重要客户", + "createTime": "2023-01-15T10:30:00Z", + "updateTime": "2023-10-02T08:00:00Z", + "tags": [ + {"tagId": 1, "name": "常客", "color": "#FF0000", "category": "contact_level"}, + {"tagId": 5, "name": "喜欢安静房间", "color": "#00FF00", "category": "contact_preference"} + ] + } + ], + "total": 120, + "page": 1, + "size": 10 + } +} +``` + +#### 13.1.2 创建客户联系人 +```http +POST /api/pms/customer-contacts +``` +**描述**: 创建一个新的客户联系人档案。 +**权限**: `pms:customerContacts:add` + +**请求体 (application/json)**: (字段参考 `pms_customer_contacts` 表定义，非所有字段都可创建，例如 `totalStays` 等统计字段后端自动处理) +```json +{ + "contactType": "individual_guest", // (string, required, 枚举值参考《PMS数据模型设计文档》中 pms_customer_contacts.contact_type 定义) + "fullName": "李四", // (string, required, minLength: 1, maxLength: 255) + "phoneNumber": "13900139000", // (string, optional, unique in tenant, valid mobile format) + "email": "lisi@example.com", // (string, optional, valid email format, maxLength: 255) + "gender": "female", // (string, optional, 枚举值参考《PMS数据模型设计文档》中 pms_customer_contacts.gender 定义) + "dateOfBirth": "1995-05-15", // (string, optional, format: YYYY-MM-DD) + "idType": "ID_CARD", // (string, optional, enum, e.g., ID_CARD, PASSPORT) + "idNumber": "34012319950515123X", // (string, optional, valid for idType, backend encrypts) + "nationalityCountryCode": "CHN", // (string, optional, ISO 3166-1 alpha-3 code) + "addressProvince": "北京市", // (string, optional, maxLength: 100) + "addressCity": "北京市", // (string, optional, maxLength: 100) + "addressDistrict": "朝阳区", // (string, optional, maxLength: 100) + "addressDetail": "建国路xx号", // (string, optional, maxLength: 500) + "postalCode": "100000", // (string, optional, valid postal code format) + "memberLevel": "silver", // (string, optional, 枚举值参考《PMS数据模型设计文档》中 pms_customer_contacts.member_level 定义) + "remarks": "希望高楼层", // (string, optional, maxLength: 1000) + "tagIds": [1, 5] // (array of long, optional): 创建时直接关联的标签ID +} +``` +*注：`idNumber` 由前端传递明文，后端负责加密存储。电话号码在租户内应唯一（如果非空）。* + +**成功响应 (201 Created)**: +```json +{ + "code": 0, + "message": "客户联系人创建成功", + "data": { + "contactId": 1002 // 新创建的联系人ID + // 可以考虑返回完整创建的资源，或至少关键信息 + // "contactId": 1002, + // "fullName": "李四", + // "contactType": "individual_guest", + // ... + } +} +``` + +#### 13.1.3 查询单个客户联系人详情 +```http +GET /api/pms/customer-contacts/{contactId} +``` +**描述**: 根据联系人ID查询其详细信息。 +**权限**: `pms:customerContacts:view` 或 用户为该联系人本人 (需特定逻辑) + +**路径参数**: +- `contactId` (long, required): 客户联系人ID。 + +**成功响应 (200 OK)**: +```json +{ + "code": 0, + "message": "查询成功", + "data": { // 结构同 13.1.1 查询列表中的单项，但可能包含更多详情字段 + "contactId": 1001, + "tenantId": "T001", + "contactType": "individual_guest", + "fullName": "张三", + "phoneNumber": "13800138000", + "email": "zhangsan@example.com", + "wechatOpenid": "wxopenid...", // 示例，若有 + "wechatUnionid": "wxunionid...", // 示例，若有 + "gender": "male", + "dateOfBirth": "1990-01-01", + "idType": "ID_CARD", + "idNumberEncrypted": "xxxxxxx", // 后端存储的加密串，不直接返回给不具备权限的前端 + "idNumberMasked": "340***********1234", // 脱敏显示给前端 + "nationalityCountryCode": "CHN", + "addressProvince": "安徽省", + "addressCity": "合肥市", + "addressDistrict": "蜀山区", + "addressDetail": "望江西路xxx号", + "postalCode": "230000", + "contactStatus": "active", + "memberLevel": "gold", + "totalStays": 5, + "totalAmount": 2500.00, + "lastStayDate": "2023-10-01", + "remarks": "重要客户", + "createDept": 103, // 创建部门ID + "createBy": 1, // 创建人用户ID + "createTime": "2023-01-15T10:30:00Z", + "updateBy": 2, + "updateTime": "2023-10-02T08:00:00Z", + "tags": [ + {"tagId": 1, "name": "常客", "color": "#FF0000", "category": "contact_level", "isSystem": false, "sortOrder": 1}, + {"tagId": 5, "name": "喜欢安静房间", "color": "#00FF00", "category": "contact_preference", "isSystem": false, "sortOrder": 2} + ], + "historicalOrders": [ // 简要历史订单信息，可分页 + {"orderId": 9001, "orderStatus": "checked_out", "checkInDate": "2023-10-01", "totalAmount": 500.00, "deptId": 103, "deptName": "黄山路店"} + ] + } +} +``` + +#### 13.1.4 更新客户联系人信息 +```http +PUT /api/pms/customer-contacts/{contactId} +``` +**描述**: 更新指定ID的客户联系人信息。 +**权限**: `pms:customerContacts:edit` + +**路径参数**: +- `contactId` (long, required): 要更新的客户联系人ID。 + +**请求体 (application/json)**: (字段同创建，但所有字段可选，仅提供需要修改的字段) +```json +{ + "fullName": "李四新", + "phoneNumber": "13900139001", + "email": "lisi.new@example.com", + "memberLevel": "platinum", + "remarks": "更新备注信息" + // 不允许直接修改 tenantId, contactId, createTime 等系统控制字段 +} +``` +**成功响应 (200 OK)**: +```json +{ + "code": 0, + "message": "客户联系人更新成功", + "data": { + "contactId": 1002 // 更新后的联系人ID，或返回完整更新后的对象 + } +} +``` + +#### 13.1.5 删除客户联系人 +```http +DELETE /api/pms/customer-contacts/{contactId} +``` +**描述**: 删除（逻辑删除）指定ID的客户联系人。 +**权限**: `pms:customerContacts:delete` + +**路径参数**: +- `contactId` (long, required): 要删除的客户联系人ID。 + +**成功响应 (204 No Content)**: (无响应体) + +**业务规则**: +- 删除前检查该联系人是否有未完成的订单或未结清的账务。若有，根据策略可能禁止删除或提示用户。 +- 逻辑删除，`del_flag` 置为 '1'。 + +#### 13.1.6 为客户批量添加标签 +```http +POST /api/pms/customer-contacts/{contactId}/tags +``` +**描述**: 为指定的客户联系人批量添加一个或多个标签。 +**权限**: `pms:customerContacts:manageTags` + +**路径参数**: +- `contactId` (long, required): 客户联系人ID。 + +**请求体 (application/json)**: +```json +{ + "tagIds": [3, 7] // (array of long, required, non-empty): 要添加的标签ID列表 +} +``` +**成功响应 (200 OK)**: +```json +{ + "code": 0, + "message": "标签添加成功" + // "data": {"addedCount": 2, "existingCount": 0} // 可选返回操作详情 +} +``` +**业务规则**: +- 标签ID必须是当前租户下有效的（租户级或客户所属门店的门店级标签）。 +- 如果客户已有关联的标签，则忽略。 + +#### 13.1.7 从客户批量移除标签 +```http +DELETE /api/pms/customer-contacts/{contactId}/tags +``` +**描述**: 从指定的客户联系人批量移除一个或多个标签。 +**权限**: `pms:customerContacts:manageTags` + +**路径参数**: +- `contactId` (long, required): 客户联系人ID。 + +**请求体 (application/json)**: +```json +{ + "tagIds": [1, 5] // (array of long, required, non-empty): 要移除的标签ID列表 +} +``` +**成功响应 (200 OK)**: +```json +{ + "code": 0, + "message": "标签移除成功" + // "data": {"removedCount": 2} // 可选返回操作详情 +} +``` + +--- +### 13.2 联系人标签API (示例待细化) +```http +# 客户标签查询 (支持门店级和租户级) +GET /api/pms/contact-tags?deptId=103&category=contact_level +# 查询指定门店的标签，包含门店级和租户级标签 + +# 创建客户标签 +POST /api/pms/contact-tags +# ...请求体包含 name, color, category, deptId (可选，门店级) + +# 更新客户标签 +PUT /api/pms/contact-tags/{tagId} + +# 删除客户标签 +DELETE /api/pms/contact-tags/{tagId} +``` + +### 13.3 房态管理API (示例待细化) + +```http +# 房态实时查询 (日历视图/列表视图) +GET /api/pms/room-status?deptId=103&date=2024-01-01&viewType=calendar&startDate=...&endDate=... +# 返回指定门店指定日期范围的房态信息 + +# 房间锁定 +POST /api/pms/room-locks +{ + "roomId": 201, // (long, required) + "deptId": 103, // (long, required) + "lockType": "maintenance", // (string, required, enum) + "startDatetime": "2024-01-01T14:00:00Z", // (datetime, required) + "endDatetime": "2024-01-01T18:00:00Z", // (datetime, required, must be after startDatetime) + "reason": "空调维修" // (string, optional, maxLength: 500) +} + +# 解锁房间 (删除房间锁定记录或更新其状态) +DELETE /api/pms/room-locks/{lockId} + +# 清洁状态更新 +PUT /api/pms/rooms/{roomId}/cleaning-status +{ + "cleaningStatus": "cleaning_in_progress", // (string, required, enum) + "cleanerId": 1001 // (long, optional, 关联 sys_user.user_id) +} +``` +### 13.4 价格管理API (示例待细化) + +```http +# 价格查询 (计算特定房型在某时段的价格) +GET /api/pms/pricing/calculate?deptId=103&roomTypeId=101&checkInDate=2024-01-01&checkOutDate=2024-01-03&guests=2&channelCode=DIRECT +# 返回动态计算后的价格信息，包括明细 + +# 价格规则管理 +GET /api/pms/pricing-rules?deptId=103&roomTypeId=101&status=active +POST /api/pms/pricing-rules +{ + "deptId": 103, // (long, required if not tenant-level rule) + "name": "周末特价", // (string, required, maxLength: 100) + "roomTypeId": 101, // (long, optional, null for all room types in dept/tenant) + "dateRangeStart": "2024-01-01", // (date, required) + "dateRangeEnd": "2024-12-31", // (date, required, must be after start) + "daysOfWeekJson": "[6,7]", // (json array of int [1-7], optional) + "priceAdjustmentType": "percentage_discount_from_base", // (string, required, enum) + "adjustmentValue": 15.00, // (decimal, required, e.g., 15.00 for 15%) + "minLOS": 1, // (int, optional, min length of stay) + "maxLOS": null, // (int, optional, max length of stay) + "priority": 10, // (int, required, higher value means higher priority) + "status": "active" // (string, required, enum: active, inactive) +} +PUT /api/pms/pricing-rules/{ruleId} +DELETE /api/pms/pricing-rules/{ruleId} + +``` +### 13.5 订单管理API (示例待细化) + +```http +# 订单查询 (门店级隔离) +GET /api/pms/orders?deptId=103&orderStatus=confirmed&checkInDate=2024-01-01 +# 多租户拦截器 + 门店级权限控制 + +# 创建订单 (关联租户级客户) +POST /api/pms/orders +{ + "deptId": 103, // (long, required) + "contactId": 1001, // (long, required, 关联租户级共享的客户) + "roomTypeId": 201, // (long, required) + "checkInDate": "2024-01-01", // (date, required) + "checkOutDate": "2024-01-03", // (date, required, must be after checkInDate) + "numAdults": 2, // (int, required, min: 1) + "numChildren": 0, // (int, optional, default: 0) + "channelId": 4, // (long, required, 渠道信息) + "orderSource": "direct_phone", // (string, optional, enum from 5.3.4) + "totalAmountCalculated": 1200.00, // (decimal, optional, 前端可预计算，后端需再校验和计算) + "notes": "客人要求安静房间" // (string, optional) +} + +# 获取订单详情 +GET /api/pms/orders/{orderId}?deptId=103 + +# 修改订单状态 (例如：确认订单、取消订单、办理入住、办理退房) +PUT /api/pms/orders/{orderId}/status +{ + "deptId": 103, // (long, required) + "orderStatus": "checked_in", // (string, required, enum) + "assignedRoomId": 301, // (long, optional, required if checking in) + "notes": "客人已入住301房间" // (string, optional) +} + +# 修改订单信息 (例如：修改联系人、延住) +PUT /api/pms/orders/{orderId} +# ...请求体包含可修改的订单字段 +``` + +### 13.6 财务管理API (示例待细化) + +```http +# 账单查询 +GET /api/pms/finance/folios?deptId=103&orderId=123&folioStatus=open +# 查询指定门店的开放账单 + +# 获取账单详情 +GET /api/pms/finance/folios/{folioId}?deptId=103 + +# 添加账单项目 (手动添加费用) +POST /api/pms/finance/folios/{folioId}/items +{ + "deptId": 103, + "description": "额外早餐", // (string, required) + "quantity": 1, // (int, required) + "unitPrice": 50.00, // (decimal, required) + "productType": "extra_service", // (string, required) + "serviceDate": "2024-01-02" // (date, required) +} + + +# 记录交易 (收款、退款等) +POST /api/pms/finance/transactions +{ + "deptId": 103, // (long, required) + "folioId": 1001, // (long, required) + "transactionType": "payment", // (string, required, enum from 5.3.5) + "amount": 500.00, // (decimal, required, positive for payment/charge, negative for refund) + "paymentMethodId": 1, // (long, required if type is payment/refund) + "description": "房费支付 - 支付宝", // (string, required) + "paymentGatewayTxnId": "ALIPAY_TXN_12345" // (string, optional) +} + +# 获取支付方式列表 +GET /api/pms/finance/payment-methods?deptId=103&status=active + +# 获取附加费用项目列表 +GET /api/pms/finance/extra-charge-items?deptId=103&category=food_beverage +``` + +## 14. 用户界面设计 + +### 14.1 客户管理页面 + +**客户列表页面**: +- 支持按客户类型、状态、标签筛选 +- 显示客户基本信息、最近入住时间、消费金额 +- 支持批量操作：添加标签、状态变更 + +**客户详情页面**: +- 客户基础信息编辑 +- 标签管理：添加/移除标签，支持颜色显示 +- 住宿历史：显示在租户内所有门店的住宿记录 +- 消费统计：总消费、入住次数、平均消费 + +### 14.2 房态管理页面 + +**房态总览页面**: +- 房间状态可视化：网格布局显示所有房间状态 +- 颜色编码：可用(绿色)、占用(红色)、维护(黄色)、锁定(灰色) +- 实时更新：房态变更自动刷新 +- 快速操作：点击房间快速变更状态 + +### 14.3 价格管理页面 + +**价格规则管理**: +- 规则列表：显示所有价格规则及状态 +- 规则创建向导：分步骤创建复杂规则 +- 规则优先级拖拽排序 +- 规则效果预览：显示规则应用后的价格变化 + +### 14.4 订单管理页面 + +**订单列表**: +- 按门店筛选，显示当前门店订单 +- 客户信息显示：关联租户级客户档案 +- 支持快速操作：房间分配、状态变更 + +## 15. 非功能性需求 + +### 15.1 性能要求 +- **响应时间**: 页面加载时间 < 3秒，API响应时间 < 500ms +- **并发用户**: 支持1000个并发用户同时在线 +- **数据处理**: 支持单租户10万条订单记录的快速查询 +- **房态更新**: 房间状态变更实时推送延迟 < 1秒 + +### 15.2 可用性要求 +- **系统可用性**: 99.5%以上的系统可用性 +- **故障恢复**: 系统故障后5分钟内恢复服务 +- **数据备份**: 每日自动备份，支持7天内数据恢复 +- **容灾机制**: 支持异地容灾，RTO < 4小时，RPO < 1小时 + +### 15.3 安全性要求 +- **数据加密**: 敏感数据AES-256加密存储 +- **传输安全**: HTTPS/TLS 1.3加密传输 +- **访问控制**: 基于RBAC的细粒度权限控制 +- **审计日志**: 完整的操作审计日志，保存180天 + +### 15.4 兼容性要求 +- **浏览器兼容**: 支持Chrome 80+、Firefox 75+、Safari 13+、Edge 80+ +- **移动设备**: 支持iOS 12+、Android 8.0+ +- **数据库**: MySQL 8.0+、Redis 6.0+ +- **API兼容**: RESTful API，支持JSON格式 + +## 16. 技术实现要求 + +### 16.1 数据库设计 +- 所有PMS业务表含 `tenant_id` 字段，支持多租户拦截器 +- 客户相关表使用 `customer_contacts` 术语，体现业务准确性 +- 索引设计优先考虑 `(tenant_id, dept_id, 业务字段)` 复合索引 + +### 16.2 缓存策略 +- 客户标签缓存：租户级标签缓存，减少数据库查询 +- 房间状态缓存：实时更新房间可用性 +- 价格规则缓存：缓存活跃的价格规则，提升计算性能 +- 权限数据缓存：用户权限和门店信息缓存 +- 配置缓存：系统配置信息缓存，支持热更新 + +### 16.3 性能优化 +- 客户查询优化：使用复合索引支持多条件查询 +- 标签关联优化：批量查询客户标签关系 +- 房态查询优化：房间状态查询使用索引优化 +- 价格计算优化：规则引擎缓存和并行计算 +- 分页查询：所有列表页面支持分页和排序 + +### 16.4 多租户拦截器配置 +```yaml +# application.yml +tenant: + enable: true + excludes: + # 若依系统表 + - sys_menu + - sys_tenant + - sys_tenant_package + - sys_role_dept + - sys_role_menu + - sys_user_post + - sys_user_role + - sys_client + - sys_oss_config + # PMS供应商合作伙伴表 (支持全局共享，需从标准拦截器中排除，业务层处理 tenant_id IS NULL 或特定 tenant_id) + - pms_suppliers + - pms_partners +``` + +### 16.5 权限控制最佳实践 +1. **联系人信息**: 直接查询，让多租户拦截器自动处理（`tenant_id` 过滤）。 +2. **联系人标签**: 业务层添加 `(dept_id = #{currentDeptId} OR dept_id IS NULL)` 条件，结合多租户拦截器实现门店级和租户级标签的查询。 +3. **订单等门店级数据**: 多租户拦截器自动处理 `tenant_id`，业务代码中需额外添加 `dept_id` 过滤。 +4. **供应商与合作伙伴**: 由于支持平台级共享（`tenant_id` IS NULL）和租户级数据，这些表已从标准多租户拦截器中排除。业务层查询时需手动处理 `tenant_id` 条件，例如 `WHERE (tenant_id IS NULL OR tenant_id = #{currentTenantId})`。 + +## 17. 部署与运维 + +### 17.1 移动端支持 + +#### 17.1.1 小程序 (核心管理功能) + - 移动端房态总览与状态变更 (清洁, 维护, 占用等) + - 客户信息快速查询与核心信息编辑 + - 订单创建、查看、修改与核心处理 (如分配房间, 办理入住/退房) + - 日常清洁与维护任务分配与状态更新 + - 基础价格查看 (价格调整可能仍需后台) + - 接收重要系统通知与告警 + +### 17.2 安全与合规 + +#### 17.2.1 数据安全 +- 租户间数据完全隔离 +- 客户隐私信息加密存储（身份证号等） +- 操作日志记录和审计 +- 敏感配置加密存储 + +#### 17.2.2 权限控制 +- 基于角色的访问控制 +- 门店级数据权限隔离 +- API接口权限验证 +- 配置修改权限控制 + +### 17.3 监控与运维 +- **系统监控**: CPU、内存、磁盘、网络监控 +- **应用监控**: 接口响应时间、错误率、吞吐量 +- **业务监控**: 订单量、房态变更、支付成功率 +- **日志管理**: 集中化日志收集、分析、告警 + +### 17.4 部署架构 +- **容器化部署**: Docker + Kubernetes +- **负载均衡**: Nginx + Keepalived +- **数据库集群**: MySQL主从复制 + Redis集群 +- **文件存储**: 阿里云OSS / MinIO + +--- + +**版本历史:** +- v1.0 - 初始版本，基本功能需求 +- v2.0 - 增加多租户和权限控制需求 +- v3.0 - 联系人管理重构，采用标准化表结构和权限模型 +- v4.0 - 完整版需求文档，整合所有功能模块和技术要求 +- v4.1 - 订单管理和价格管理功能增强，补充状态追踪、时间管理、客人信息、价格历史、特殊日期价格等高级功能 +- v4.2 - 客人信息管理优化，增强客人与联系人档案的关联管理，完善入住登记和客户档案维护流程 +- v4.3 - 系统配置管理模块完善，新增配置模板管理、系统监控、敏感配置安全管理、用户设备管理等功能 + +**重要变更说明 (v4.3):** +- **系统配置管理功能完善**: 新增配置模板管理、系统监控与审计、配置继承与覆盖机制、敏感配置安全管理等高级功能 +- **用户设备管理**: 新增用户设备注册、推送令牌管理、安全审计、多设备支持等功能 +- **小程序配置管理**: 新增主题配置、功能开关、支付配置、通知配置等小程序专项管理功能 +- **配置安全增强**: 支持敏感配置加密存储、访问控制、操作审计、脱敏显示等安全机制 +- **配置继承机制**: 完善租户级和门店级配置的继承与覆盖逻辑，支持灵活的配置管理策略 +- **系统监控功能**: 新增配置变更监控、用户行为监控、性能监控、安全审计、报警管理等监控功能 + +**重要变更说明 (v4.2):** +- **客人信息管理优化**: 完善 `pms_order_guests` 表设计，支持与客户档案的智能关联 +- **入住登记流程优化**: 支持主联系人自动关联、同行客人档案匹配、新档案创建等功能 +- **客户档案维护**: 增强客户信息同步、统计更新、偏好分析等功能 +- **数据一致性保障**: 通过关联查询避免数据冗余，确保客户信息的一致性和准确性 + +**重要变更说明 (v4.1):** +- **订单管理功能增强**: 新增订单状态历史追踪、订单时间管理、入住客人信息管理、库存管理与房态联动等功能模块 +- **价格管理功能完善**: 新增价格计算历史追踪、特殊日期价格管理、高级价格规则、价格策略分析等功能模块 +- **数据表补充**: 新增 `pms_order_status_history`、`pms_order_guests`、`pms_pricing_calculations`、`pms_special_date_pricing`、`pms_room_inventory_snapshot` 等数据表支持 +- **功能优先级调整**: 重新评估和调整各功能模块的优先级，确保核心功能优先实现 +- **业务流程优化**: 完善订单生命周期管理和价格计算流程，提升系统的业务支撑能力 diff --git a/docs/二开todolist.md b/docs/二开todolist.md index 7b68df63a..ec2934857 100644 --- a/docs/二开todolist.md +++ b/docs/二开todolist.md @@ -3,8 +3,8 @@ ## 阶段 0: 项目初始化与理解 - [x] **阅读核心文档:** - - [x] 仔细阅读《PMS数据模型.md》，完全理解PMS核心表的结构、字段定义、关系以及主键/外键/索引规范。 - - [x] 仔细阅读《PMS需求.md》，明确PMS核心模块 [P0] 阶段必须实现的功能需求（房态、订单核心生命周期、基础财务支付、租户级系统管理基础）。 + - [x] 仔细阅读《PMS数据模型.md》(v5.7)，完全理解PMS核心表的结构、字段定义、关系以及主键/外键/索引规范，特别是第5节核心业务枚举值定义。 + - [x] 仔细阅读《PMS需求.md》(v4.3)，明确PMS核心模块 [P0] 阶段必须实现的功能需求（联系人基础、房态核心、价格基础、订单核心生命周期、基础财务、系统配置基础）。 - [x] 通读《RuoYi-Vue-Plus二次开发最佳实践.md》，重点关注以下章节： - Chapter 1: 引言 (文档目的, 模块化特性, **二次开发核心原则**, **Cursor使用优势**) - Chapter 2: 环境准备与项目结构 (前后端环境, **前后端项目结构**, **代码生成器与Cursor协同**) @@ -14,275 +14,673 @@ - 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 中为项目设置特定上下文，如关键模块路径、技术栈等，以便更好地辅助开发。 + - [x] 在 Cursor 中为项目设置特定上下文，包括关键模块路径、技术栈、编码规范等，以便更好地辅助开发。 + +- [x] **版本控制与代码管理准备:** + - [x] 配置Git多仓库管理策略（主仓库 + 子模块） + - [x] 设置upstream远程源以同步官方更新 + - [x] 创建开发分支策略 + - [x] 确保`.gitignore`配置正确，排除target、node_modules等目录 ## 阶段 1: 后端开发 - 模块搭建与核心表结构 -- [ ] **创建后端Maven子模块 `ruoyi-pms`** (参考《最佳实践》Chapter 2.2, 4.2, 8.3): - - [ ] 在 `ruoyi-vue-plus/ruoyi-modules` 目录下创建新的 Maven 子模块 `ruoyi-pms`。 - - [ ] 配置 `ruoyi-pms/pom.xml`： - - [ ] 设置 `` 指向 `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` 的 `` 部分注册 `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`。 +- [x] **创建后端Maven子模块 `ruoyi-pms`** (参考《最佳实践》Chapter 2.2, 4.2, 8.3): + - [x] 在 `ruoyi-vue-plus/ruoyi-modules` 目录下创建新的 Maven 子模块 `ruoyi-pms`。 + - [x] 配置 `ruoyi-pms/pom.xml`： + - [x] 设置 `` 指向 `ruoyi-modules`。 + - [x] 添加必要的公共模块依赖 (如: `ruoyi-common-core`, `ruoyi-common-mybatis`, `ruoyi-common-web`, `ruoyi-common-satoken`, `ruoyi-common-excel`, `ruoyi-common-translate`, `ruoyi-common-tenant`)。 + - [x] 在项目根目录 `pom.xml` 和 `ruoyi-modules/pom.xml` 的 `` 部分注册 `ruoyi-pms`。 + +- [x] **创建后端基础包结构** (参考《最佳实践》Chapter 4.2): + - [x] 在 `ruoyi-pms/src/main/java/` 下创建基础包 `org.dromara.pms` (应用名: pms)。 + - [x] 在 `org.dromara.pms` 下创建标准分层包：`controller`, `service`, `service.impl`, `mapper`, `domain` (包含 `entity`, `bo`, `vo`)。 + +- [x] **后端国际化资源文件**: + - [x] 在 `ruoyi-pms/src/main/resources/` 下创建 `i18n` 目录。 + - [x] 在 `i18n` 目录下创建基础的国际化属性文件，如 `messages_zh_CN.properties` 和 `messages_en_US.properties`。 + +- [x] **API文档配置**: + - [x] 在 `ruoyi-admin` 的 `application.yml` 中配置springdoc扫描PMS模块 (`packages-to-scan: org.dromara.pms`) + - [x] 验证Swagger UI可以显示PMS模块的API文档 + +- [x] **集成新模块到主项目**: + - [x] 在 `ruoyi-admin` 模块的 `pom.xml` 中添加 `ruoyi-pms` 依赖 + - [x] 验证项目可以正常启动并加载PMS模块 + +- [x] **数据库表创建与初始化** (参考《PMS数据模型.md》v5.7): + - [x] **执行SQL脚本**: 确保已在开发数据库中执行了包含所有PMS相关表（如 `pms_customer_contacts`, `pms_contact_tags`, `pms_contact_tag_relations` 等）的创建和初始化脚本。 + - [x] **验证表结构**: 对照《PMS数据模型.md》(v5.7)仔细检查已创建的表结构、字段类型、约束（包括 `del_flag NOT NULL`）、审计字段、索引是否正确。 + - [x] **验证枚举值和基础数据**: 确认联系人相关的字典数据及所有枚举值相关的表字段设计已按《PMS数据模型.md》第5节正确实现。 + - [x] **Cursor辅助**: 已完成PMS联系人模块相关表结构的创建和验证。 + +- [x] **MyBatis Plus配置优化**: + - [x] 在 `ruoyi-pms` 模块中创建配置类，添加 `@MapperScan("org.dromara.pms.mapper")` 注解 + - [x] 配置MyBatis Plus的全局配置（ID生成策略、逻辑删除，确保与《PMS数据模型.md》中的 `del_flag` 定义一致） + - [x] **多租户配置**: 确保 `tenant.excludes` 配置与《PMS数据模型.md》6.2.1节一致，特别是 `pms_suppliers`, `pms_partners` 的排除。 + - [x] 验证数据库连接和基础CRUD操作 + +- [x] **基础测试验证**: + - [x] 创建简单的测试Controller验证模块正常工作 + - [x] 验证包扫描、依赖注入、数据库连接等基础功能 + - [x] 确保项目启动无错误，日志输出正常 + +- [ ] **缓存策略实现** (参考《PMS需求.md》16.2节): + - [ ] **客户标签缓存**: 实现租户级标签缓存，减少数据库查询 + - [ ] **房间状态缓存**: 实现房间可用性实时缓存更新 + - [ ] **价格规则缓存**: 缓存活跃的价格规则，提升计算性能 + - [ ] **权限数据缓存**: 实现用户权限和门店信息缓存 + - [ ] **配置缓存**: 实现系统配置信息缓存，支持热更新 + +- [ ] **性能优化实现** (参考《PMS需求.md》16.3节): + - [ ] **客户查询优化**: 使用复合索引支持多条件查询 + - [ ] **标签关联优化**: 实现批量查询客户标签关系 + - [ ] **房态查询优化**: 房间状态查询使用索引优化 + - [ ] **价格计算优化**: 实现规则引擎缓存和并行计算 + - [ ] **分页查询优化**: 所有列表页面支持分页和排序 + +- [ ] **数据安全与加密实现** (参考《PMS需求.md》15.3节): + - [ ] **敏感数据加密**: 实现客户身份证号等敏感数据AES-256加密存储 + - [ ] **传输安全**: 确保所有API接口使用HTTPS/TLS 1.3加密传输 + - [ ] **访问控制**: 实现基于RBAC的细粒度权限控制 + - [ ] **操作审计日志**: 实现完整的操作审计日志，保存180天 + - [ ] **数据脱敏**: 实现敏感数据在前端的脱敏显示 ## 阶段 2: 后端开发 - 核心业务功能 [P0] -**通用后端开发规范 (参考《最佳实践》Chapter 4 & 7.1):** +**通用后端开发规范 (参考《最佳实践》Chapter 4 & 7.1 及《PMS需求.md》技术要求):** - [ ] 遵循分层架构约定 (Controller -> Service -> Mapper)。 - - [ ] 严格区分 Entity, BO, VO 的职责和使用场景。 + - [ ] 严格区分 Entity, BO, VO 的职责和使用场景。Entity对应《PMS数据模型.md》的表结构。 - [ ] 使用 MapStruct Plus (`@AutoMapper`) 进行对象转换。 - [ ] Service 层实现类的方法应添加 `@Transactional` 注解。 - - [ ] Controller 层方法应添加 `@Log` 操作日志注解和 `@SaCheckPermission` 权限注解。 - - [ ] BO 对象字段使用 JSR 303/380 注解进行参数校验。 + - [ ] Controller 层方法应添加 `@Log` 操作日志注解和 `@SaCheckPermission` 权限注解。权限点参考《PMS需求.md》第13节API设计。 + - [ ] BO 对象字段使用 JSR 303/380 注解进行参数校验，校验规则参考《PMS需求.md》API设计中的请求体定义。 - [ ] VO 对象字段按需使用 `@Translation` 和 `@Sensitive` 注解。 + - [ ] **枚举处理**: 后端使用Java枚举类对应《PMS数据模型.md》第5节定义的枚举值，并确保与数据库存储的 `VARCHAR(50)` 字符串值正确转换。 + - [ ] **状态流转**: 在Service层实现《PMS数据模型.md》第4节定义的订单、房间等状态流转逻辑。 + - [ ] **数据权限**: 严格按照《PMS数据模型.md》6.2.2节和《PMS需求.md》16.5节实现多租户和门店级数据权限。 - [ ] 编写清晰的 Javadoc 注释和行内注释。 - [ ] 使用 Cursor 辅助生成代码、分析逻辑、优化代码。 -**具体功能模块开发:** +**Cursor AI协作技巧提升:** + - [ ] **代码生成提示优化**: "请Cursor根据《PMS数据模型.md》中的 `pms_customer_contacts` 表结构和《PMS需求.md》中13.1节的API规范，为客户联系人模块生成符合《最佳实践》的后端Controller, Service, Mapper, Entity, BO, VO 代码框架。确保包含[P0]功能：基础联系人管理。" + - [ ] **代码审查**: "请Cursor审查我为 `PmsCoreOrderServiceImpl` 编写的订单创建逻辑，检查是否符合事务管理要求、数据校验是否全面、以及状态流转是否正确。" + - [ ] **错误诊断**: "我的 `PmsRoomRoomController` 在查询房态时返回空列表，请Cursor分析代码和相关MyBatis XML，找出可能的原因。日志信息如下..." + - [ ] **重构建议**: "请Cursor分析 `PmsFinanceFolioServiceImpl` 中的账单计算逻辑，是否有可优化的部分，并提供重构建议。" -- [ ] **代码生成器应用 (可选但推荐)** (参考《最佳实践》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》和《最佳实践》进行调整。" +**具体功能模块开发 ([P0] 优先级，参考《PMS需求.md》和《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)。 +- [ ] **代码生成器应用与优化** (参考《最佳实践》Chapter 2.4): + - [ ] **准备代码生成器配置**: + - [ ] 在RuoYi管理后台配置代码生成器，导入《PMS数据模型.md》定义的所有PMS核心业务表（如`pms_customer_contacts`, `pms_room_types`, `pms_room_rooms`, `pms_core_orders`等）。 + - [ ] 配置生成参数（包名 `org.dromara.pms`、模块名 `pms`、作者、表前缀 `pms_` 处理等）。 + - [ ] 设置字段属性（是否必填、查询条件、显示类型等），特别是枚举字段的处理方式。 + - [ ] **批量生成基础代码**: 针对《PMS数据模型.md》中定义的核心表生成初始CRUD代码。 + - [ ] **Cursor辅助优化生成代码**: + - [ ] "请Cursor分析代码生成器为 `pms_customer_contacts` 表生成的后端代码，并对比《PMS需求.md》13.1节的API定义和《PMS数据模型.md》的表结构，指出哪些部分需要手动调整或补充业务逻辑（如加密、唯一性校验、枚举转换）。" + - [ ] "请Cursor帮我优化 `PmsRoomType.java` Entity类，确保所有字段与《PMS数据模型.md》一致，并为相关字段（如`status`）添加正确的Java枚举类型和MyBatis TypeHandler（如果需要）。" + - [ ] "请Cursor检查 `IPmsCoreOrderService.java` 接口是否缺少《PMS需求.md》9.1.1节[P0]核心订单生命周期管理所需的业务方法，并补充完整。" -- [ ] **2. 房间管理 (`pms_room_rooms`)**: - - [ ] **Domain**: `PmsRoomRoom`, `PmsRoomRoomBo`, `PmsRoomRoomVo`. - - [ ] **Mapper**: `PmsRoomRoomMapper.java` & XML. - - [ ] **Service**: `IPmsRoomRoomService.java` & Impl (CRUD, 更新房间状态/清洁状态逻辑). - - [ ] **Controller**: `PmsRoomRoomController.java`. +- [x] **1. 联系人管理 (`pms_customer_contacts`, `pms_contact_tags`, `pms_contact_tag_relations`)** [P0] + - [x] **Domain对象优化**: + - [x] `PmsCustomerContacts`, `PmsCustomerContactsBo`, `PmsCustomerContactsVo` (参考《PMS需求.md》13.1.1 响应体)。 + - [x] `PmsContactTag`, `PmsContactTagBo`, `PmsContactTagVo`. + - [x] `PmsContactTagRelation` (通常只有Entity和BO). + - [x] 实现《PMS数据模型.md》5.1节定义的客户相关枚举 (contact_type, contact_status, gender, member_level, tag_category)。 + - [x] 字段校验：`fullName`必填, `phoneNumber`唯一性 (租户内), `idNumber`加密存储。 + - [x] **数据库操作层**: + - [x] `PmsCustomerContactsMapper`: 实现按姓名、电话、状态、类型、标签等查询。支持租户级数据共享。 + - [x] `PmsContactTagMapper`: 支持租户级和门店级标签查询 (dept_id IS NULL 或特定值)。 + - [x] **业务逻辑层**: `IPmsCustomerContactsService`, `IPmsContactTagService` + - [x] 实现客户档案创建、查询、更新、逻辑删除。 + - [x] 实现客户标签的增删改查，以及客户与标签的关联/解关联。 + - [x] 业务校验逻辑：如电话号码唯一性，标签权限等。 + - [x] **控制器层**: `PmsCustomerContactsController`, `PmsContactTagController` + - [x] 实现《PMS需求.md》13.1节定义的客户管理API和13.2节的标签API。 + - [x] 权限控制: `pms:customerContacts:list`, `add`, `edit`, `delete`, `manageTags`等。 -- [ ] **3. 房间锁定 (`pms_room_locks`)**: - - [ ] **Domain**: `PmsRoomLock`, `PmsRoomLockBo`, `PmsRoomLockVo`. - - [ ] **Mapper**: `PmsRoomLockMapper.java` & XML. - - [ ] **Service**: `IPmsRoomLockService.java` & Impl (CRUD). - - [ ] **Controller**: `PmsRoomLockController.java`. +- [x] **2. 房型管理 (`pms_room_types`)** [P0] + - [x] **Domain对象**: `PmsRoomType`, `PmsRoomTypeBo`, `PmsRoomTypeVo`. + - [x] 实现 `status` 枚举。 + - [x] **数据库操作**: `PmsRoomTypeMapper`. 门店级隔离。 + - [x] **业务逻辑**: `IPmsRoomTypeService`. 实现房型增删改查，状态管理。 + - [x] **控制器**: `PmsRoomTypeController`. -- [ ] **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`. +- [x] **3. 房间管理 (`pms_room_rooms`)** [P0] + - [x] **Domain对象**: `PmsRoomRoom`, `PmsRoomRoomBo`, `PmsRoomRoomVo` (可包含房型名称等关联信息)。 + - [x] 实现 `room_status`, `cleaning_status` 枚举 (参考《PMS数据模型.md》5.4节)。 + - [x] **数据库操作**: `PmsRoomRoomMapper`. 门店级隔离。查询需支持房型、楼层、状态组合。 + - [x] **业务逻辑**: `IPmsRoomRoomService`. + - [x] 实现房间增删改查。 + - [x] 房间物理状态和清洁状态的更新与管理逻辑。 + - [x] 实现《PMS数据模型.md》4.2节房间状态流转。 + - [x] **控制器**: `PmsRoomRoomController`. -- [ ] **5. 订单来源渠道 (`pms_core_channels`)**: - - [ ] **Domain**: `PmsCoreChannel`, `PmsCoreChannelBo`, `PmsCoreChannelVo`. - - [ ] **Mapper**: `PmsCoreChannelMapper` & XML. - - [ ] **Service**: `IPmsCoreChannelService` & Impl (CRUD). - - [ ] **Controller**: `PmsCoreChannelController`. +- [x] **4. 房间锁定管理 (`pms_room_locks`)** [P0] + - [x] **Domain对象**: `PmsRoomLock`, `PmsRoomLockBo`, `PmsRoomLockVo`. + - [x] 实现 `lock_type` 枚举。 + - [x] **业务逻辑**: `IPmsRoomLockService`. 实现房间锁定、解锁、查询，锁定期间冲突检测。 + - [x] **控制器**: `PmsRoomLockController`. -- [ ] **6. 财务-账单管理 (`pms_finance_folios`)** (参考《PMS需求.md》4.2.3 [P0]): - - [ ] **Domain**: `PmsFinanceFolio`, `PmsFinanceFolioBo`, `PmsFinanceFolioVo` (应包含交易流水列表). - - [ ] **Mapper**: `PmsFinanceFolioMapper` & XML. - - [ ] **Service**: `IPmsFinanceFolioService` & Impl (CRUD, 更新账单状态, 计算余额逻辑 - 应用层计算). - - [ ] **Controller**: `PmsFinanceFolioController`. +- [ ] **房态实时推送功能** [P1] + - [ ] **WebSocket集成**: 集成RuoYi框架的WebSocket功能，支持房态实时推送 + - [ ] **房态变更监听**: 实现房间状态变更的事件监听机制 + - [ ] **实时推送服务**: 创建房态实时推送服务，支持按门店推送 + - [ ] **前端WebSocket客户端**: 实现前端WebSocket连接和房态更新处理 + - [ ] **推送性能优化**: 确保房态变更推送延迟 < 1秒 + - [ ] **连接管理**: 实现WebSocket连接的管理和异常处理 -- [ ] **7. 财务-交易流水 (`pms_finance_transactions`)**: - - [ ] **Domain**: `PmsFinanceTransaction`, `PmsFinanceTransactionBo`, `PmsFinanceTransactionVo`. - - [ ] **Mapper**: `PmsFinanceTransactionMapper` & XML. - - [ ] **Service**: `IPmsFinanceTransactionService` & Impl (CRUD, 关联 `pms_finance_payment_methods`). - - [ ] **Controller**: `PmsFinanceTransactionController`. +- [ ] **5. 核心订单管理 (`pms_core_orders`, `pms_core_order_items`)** [P0] + - [ ] **Domain对象设计**: + - [ ] `PmsCoreOrder`, `PmsCoreOrderBo`, `PmsCoreOrderVo` (应包含订单项列表、主要联系人简要信息、预订房型及分配房间信息，参考《PMS需求.md》13.5)。 + - [ ] `PmsCoreOrderItem`, `PmsCoreOrderItemBo`, `PmsCoreOrderItemVo`. + - [ ] 实现 `order_status`, `order_source` 枚举 (参考《PMS数据模型.md》5.6节)。 + - [ ] **复杂查询实现**: `PmsCoreOrderMapper` + - [ ] 多表关联查询（订单+订单项+房型+联系人）。 + - [ ] 按日期范围、状态、门店、联系人等复合条件查询。 + - [ ] **核心业务逻辑**: `IPmsCoreOrderService` + - [ ] **订单创建**: 业务校验（房间可用性、价格计算基于`pms_room_pricing_rules`、库存检查、联系人关联）。 + - [ ] **订单状态流转**: 实现《PMS数据模型.md》4.1节定义的订单状态流转逻辑 (pending_confirmation -> confirmed -> checked_in -> checked_out / cancelled / no_show)。 + - [ ] 订单修改和取消逻辑（特定条件下）。 + - [ ] **自动创建财务账单** (`pms_finance_folios`) 基础框架。 + - [ ] **房态联动**: 订单操作（创建、确认、取消、入住、退房）应触发房态更新。 + - [ ] **事务管理**: 确保订单及关联操作的数据一致性。 + - [ ] **控制器**: `PmsCoreOrderController`. 实现《PMS需求.md》13.5节定义的订单管理核心API。 -- [ ] **8. 财务-支付方式 (`pms_finance_payment_methods`)**: - - [ ] **Domain**: `PmsFinancePaymentMethod`, `PmsFinancePaymentMethodBo`, `PmsFinancePaymentMethodVo`. - - [ ] **Mapper**: `PmsFinancePaymentMethodMapper` & XML. - - [ ] **Service**: `IPmsFinancePaymentMethodService` & Impl (CRUD). - - [ ] **Controller**: `PmsFinancePaymentMethodController`. +- [ ] **6. 订单状态历史追踪 (`pms_order_status_history`)** [P0] + - [ ] **Domain对象**: `PmsOrderStatusHistory`, `PmsOrderStatusHistoryBo`, `PmsOrderStatusHistoryVo`. + - [ ] 实现 `change_reason` 枚举。 + - [ ] **业务逻辑**: `IPmsOrderStatusHistoryService`. + - [ ] 订单状态变更时自动记录历史。 + - [ ] 查询订单状态变更历史。 + - [ ] 支持状态回滚操作（特殊情况）。 + - [ ] **控制器**: `PmsOrderStatusHistoryController`. -- [ ] **9. 财务-附加费用项目 (`pms_finance_extra_charge_items`)**: - - [ ] **Domain**: `PmsFinanceExtraChargeItem`, `PmsFinanceExtraChargeItemBo`, `PmsFinanceExtraChargeItemVo`. - - [ ] **Mapper**: `PmsFinanceExtraChargeItemMapper` & XML. - - [ ] **Service**: `IPmsFinanceExtraChargeItemService` & Impl (CRUD). - - [ ] **Controller**: `PmsFinanceExtraChargeItemController`. +- [ ] **7. 入住客人信息管理 (`pms_order_guests`)** [P1] + - [ ] **Domain对象**: `PmsOrderGuest`, `PmsOrderGuestBo`, `PmsOrderGuestVo`. + - [ ] 实现 `guest_type`, `id_type`, `age_group` 枚举。 + - [ ] 支持与客户档案关联 (`contact_id` 字段)。 + - [ ] **业务逻辑**: `IPmsOrderGuestService`. + - [ ] 入住客人信息管理。 + - [ ] 主客人与联系人档案关联。 + - [ ] 同行客人选择性关联。 + - [ ] 智能档案匹配和新档案创建。 + - [ ] **控制器**: `PmsOrderGuestController`. -- [ ] **10. 价格规则 (`pms_room_pricing_rules`)**: - - [ ] **Domain**: `PmsRoomPricingRule`, `PmsRoomPricingRuleBo`, `PmsRoomPricingRuleVo`. - - [ ] **Mapper**: `PmsRoomPricingRuleMapper` & XML. - - [ ] **Service**: `IPmsRoomPricingRuleService` & Impl (CRUD). - - [ ] **Controller**: `PmsRoomPricingRuleController`. +- [ ] **8. 订单来源渠道管理 (`pms_core_channels`)** [P0] + - [ ] **Domain对象**: `PmsCoreChannel`, `PmsCoreChannelBo`, `PmsCoreChannelVo`. + - [ ] 实现 `channel_type` 枚举。 + - [ ] **业务逻辑**: `IPmsCoreChannelService`. 基础增删改查。门店级隔离（或按需租户级）。 + - [ ] **控制器**: `PmsCoreChannelController`. -- [ ] **11. 联系人基础 (`cmn_contacts`)** (P0阶段主要为订单关联所需字段): - - [ ] **Domain**: `CmnContact`, `CmnContactBo`, `CmnContactVo` (仅包含P0阶段所需字段，如姓名、电话). - - [ ] **Mapper**: `CmnContactMapper` & XML. - - [ ] **Service**: `ICmnContactService` & Impl (提供基础的联系人查询、创建接口供订单模块调用). - - [ ] **Controller**: (P0阶段可能不需要完整独立的Controller，主要通过订单业务间接操作). +- [ ] **9. 财务-账单管理 (`pms_finance_folios`)** [P0] + - [ ] **Domain对象**: `PmsFinanceFolio`, `PmsFinanceFolioBo`, `PmsFinanceFolioVo` (可含交易流水列表，余额通过计算列或业务逻辑实现)。 + - [ ] 实现 `folio_status` 枚举 (参考《PMS数据模型.md》5.7节)。 + - [ ] **业务逻辑**: `IPmsFinanceFolioService`. + - [ ] 订单确认时自动创建账单（基础框架）。 + - [ ] 查询账单、更新账单状态。 + - [ ] **控制器**: `PmsFinanceFolioController`. 实现《PMS需求.md》13.6节定义的账单查询API。 -- [ ] **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`. +- [ ] **10. 财务-交易流水管理 (`pms_finance_transactions`)** [P0] + - [ ] **Domain对象**: `PmsFinanceTransaction`, `PmsFinanceTransactionBo`, `PmsFinanceTransactionVo`. + - [ ] 实现 `transaction_type` 枚举。 + - [ ] **业务逻辑**: `IPmsFinanceTransactionService`. 记录收款、退款等基础交易。 + - [ ] **控制器**: `PmsFinanceTransactionController`. 实现《PMS需求.md》13.6节定义的记录交易API。 -- [ ] **13. 租户用户设备 (`pms_tenant_user_devices`)**: (用于民宿管理小程序推送等) - - [ ] **Domain**: `PmsTenantUserDevice`, `PmsTenantUserDeviceBo`, `PmsTenantUserDeviceVo`. - - [ ] **Mapper**: `PmsTenantUserDeviceMapper` & XML. - - [ ] **Service**: `IPmsTenantUserDeviceService` & Impl (CRUD, 设备注册/更新逻辑). - - [ ] **Controller**: `PmsTenantUserDeviceController`. +- [ ] **11. 财务-支付方式管理 (`pms_finance_payment_methods`)** [P0] + - [ ] **Domain对象**: `PmsFinancePaymentMethod`, `PmsFinancePaymentMethodBo`, `PmsFinancePaymentMethodVo`. + - [ ] 实现 `method_type` 枚举。 + - [ ] **业务逻辑**: `IPmsFinancePaymentMethodService`. 基础增删改查。门店级（或租户级）。 + - [ ] **控制器**: `PmsFinancePaymentMethodController`. -- [ ] **API文档**: - - [ ] 为所有Controller和DTO添加清晰的Swagger/Knife4j注解 (参考《最佳实践》Chapter 8.3)。 +- [x] **12. 价格管理-价格规则基础 (`pms_room_pricing_rules`)** [P0] + - [x] **Domain对象**: `PmsRoomPricingRule`, `PmsRoomPricingRuleBo`, `PmsRoomPricingRuleVo`. + - [x] 实现 `price_adjustment_type` 枚举。 + - [x] 实现 `pricing_rule_status` 枚举。 + - [x] 创建枚举转换器 `PriceAdjustmentTypeConverter`, `PricingRuleStatusConverter`。 + - [x] **业务逻辑**: `IPmsRoomPricingRuleService`. + - [x] 基础增删改查。 + - [x] 价格规则优先级管理。 + - [x] 规则有效性校验。 + - [x] **价格计算引擎**: `IPmsPricingCalculationService`. + - [x] 实现动态价格计算逻辑。 + - [x] 多规则叠加计算。 + - [x] 价格计算历史记录。 + - [x] 集成缓存机制优化性能。 + - [x] 支持并行计算（长期住宿）。 + - [x] 特殊日期价格处理。 + - [x] **缓存策略实现**: `PricingCacheService` + - [x] 活跃价格规则缓存（Redis + 本地缓存）。 + - [x] 特殊日期价格缓存。 + - [x] 房型基础价格缓存。 + - [x] 价格计算结果缓存。 + - [x] 缓存失效和预热机制。 + - [x] **控制器**: `PmsRoomPricingRuleController`, `PmsPricingCalculationController`. -## 阶段 3: 前端开发 - 核心管理界面 [P0] (Soybean Admin Pro) +- [x] **13. 价格计算历史追踪 (`pms_pricing_calculations`)** [P0] + - [x] **Domain对象**: `PmsPricingCalculation`, `PmsPricingCalculationBo`, `PmsPricingCalculationVo`. + - [x] **业务逻辑**: `IPmsPricingCalculationService`. + - [x] 记录每次价格计算的详细过程。 + - [x] 规则应用详情记录。 + - [x] 历史价格查询和趋势分析。 + - [x] **控制器**: `PmsPricingCalculationController`. + +- [x] **14. 特殊日期价格管理 (`pms_special_date_pricing`)** [P1] + - [x] **Domain对象**: `PmsSpecialDatePricing`, `PmsSpecialDatePricingBo`, `PmsSpecialDatePricingVo`. + - [x] 实现 `date_type` 枚举 (`SpecialDateType`)。 + - [x] 实现 `special_date_status` 枚举 (`SpecialDateStatus`)。 + - [x] 创建枚举转换器 `SpecialDateTypeConverter`, `SpecialDateStatusConverter`。 + - [x] **业务逻辑**: `IPmsSpecialDatePricingService`. + - [x] 特殊日期价格设置。 + - [x] 批量设置连续日期价格。 + - [x] 优先级控制和规则覆盖。 + - [x] 冲突检测和解决。 + - [x] **控制器**: `PmsSpecialDatePricingController`. + +- [ ] **15. 库存管理与房态联动 (`pms_room_inventory_snapshot`)** [P1] + - [ ] **Domain对象**: `PmsRoomInventorySnapshot`, `PmsRoomInventorySnapshotBo`, `PmsRoomInventorySnapshotVo`. + - [ ] **业务逻辑**: `IPmsRoomInventorySnapshotService`. + - [ ] 实时库存查询。 + - [ ] 库存快照生成。 + - [ ] 超售保护机制。 + - [ ] 房态实时同步。 + - [ ] **控制器**: `PmsRoomInventorySnapshotController`. + +- [x] **系统配置管理模块建表语句**: + - [x] 创建 `script/sql/pms_system_tables.sql` 文件 + - [x] 包含租户配置表：`pms_tenant_settings` + - [x] 包含小程序配置表：`pms_mp_settings` + - [x] 包含用户设备表：`pms_tenant_user_devices` + - [x] 确保所有表结构与《PMS数据模型.md》v5.7完全一致 + +- [x] **系统配置管理功能菜单创建**: + - [x] 创建 `script/sql/pms_system_menu.sql` 文件 + - [x] 包含系统配置主菜单和子菜单 + - [x] 包含相关权限点定义 + - [x] 按照RuoYi框架的菜单结构标准创建 + +## 阶段 3: 数据库表结构创建与菜单配置 + +- [x] **订单管理模块建表语句**: + - [x] 创建 `script/sql/pms_order_tables.sql` 文件 + - [x] 包含订单核心表：`pms_core_orders`, `pms_core_order_items`, `pms_core_channels` + - [x] 包含订单增强表：`pms_order_status_history`, `pms_order_guests` + - [x] 包含库存管理表：`pms_room_inventory_snapshot` + - [x] 确保所有表结构与《PMS数据模型.md》v5.7完全一致 + +- [x] **价格管理模块建表语句**: + - [x] 创建 `script/sql/pms_pricing_tables.sql` 文件 + - [x] 包含价格规则表：`pms_room_pricing_rules` + - [x] 包含价格计算表：`pms_pricing_calculations` + - [x] 包含特殊日期价格表：`pms_special_date_pricing` + - [x] 确保所有表结构与《PMS数据模型.md》v5.7完全一致 + +- [x] **订单管理功能菜单创建**: + - [x] 创建 `script/sql/pms_order_menu.sql` 文件 + - [x] 包含订单管理主菜单和子菜单 + - [x] 包含相关权限点定义 + - [x] 按照RuoYi框架的菜单结构标准创建 + +- [x] **价格管理功能菜单创建**: + - [x] 创建 `script/sql/pms_pricing_menu.sql` 文件 + - [x] 包含价格管理主菜单和子菜单 + - [x] 包含相关权限点定义 + - [x] 按照RuoYi框架的菜单结构标准创建 + +## 阶段 4: 价格管理功能完整开发 + +- [x] **价格管理实体类创建**: + - [x] 创建 `PmsRoomPricingRule.java` 实体类 + - [x] 创建 `PmsPricingCalculation.java` 实体类 + - [x] 创建 `IPricingService.java` 核心服务接口 + - [x] 包含完整的字段定义和校验注解 + +- [x] **价格规则管理功能**: + - [x] 实现价格规则的CRUD操作 + - [x] 实现规则优先级管理 + - [x] 实现规则有效性校验 + - [x] 实现规则启用/禁用功能 + +- [x] **动态价格计算引擎**: + - [x] 实现基础价格获取 + - [x] 实现多规则叠加计算逻辑 + - [x] 实现价格计算缓存机制 + - [x] 实现价格计算历史记录 + +- [x] **特殊日期价格管理**: + - [x] 实现特殊日期价格设置 + - [x] 实现批量日期价格操作 + - [x] 实现价格优先级控制 + - [x] 实现节假日价格自动应用 + +- [x] **价格管理API接口**: + - [x] 实现价格查询API + - [x] 实现价格计算API + - [x] 实现价格规则管理API + - [x] 实现特殊日期价格API + +- [x] **价格管理MyBatis XML映射文件**: + - [x] 创建 `PmsRoomPricingRuleMapper.xml` 映射文件 + - [x] 创建 `PmsPricingCalculationMapper.xml` 映射文件 + - [x] 创建 `PmsSpecialDatePricingMapper.xml` 映射文件 + - [x] 实现复杂查询SQL语句 + +## 阶段 4.5: 系统配置管理功能完整开发 + +- [x] **系统配置管理实体类创建**: + - [x] 创建 `PmsTenantSetting.java` 实体类 + - [x] 创建 `PmsTenantSettingBo.java` 和 `PmsTenantSettingVo.java` + - [x] 创建 `PmsTenantSettingMapper.java` 接口 + - [x] 创建 `IPmsTenantSettingService.java` 服务接口 + - [x] 创建 `PmsMpSetting.java` 实体类 + - [x] 创建 `PmsMpSettingBo.java` 和 `PmsMpSettingVo.java` + - [x] 创建 `PmsTenantUserDevice.java` 实体类 + - [x] 实现相关枚举值定义 (`SettingType` 等) + +- [ ] **租户配置管理功能**: + - [ ] 实现配置项的CRUD操作 + - [ ] 实现配置分组管理 + - [ ] 实现租户级和门店级配置继承 + - [ ] 实现敏感配置的加密存储 + - [ ] 实现配置项类型验证和转换 + +- [ ] **配置继承与覆盖机制**: + - [ ] 实现租户级配置作为默认配置 + - [ ] 实现门店级配置覆盖租户级配置 + - [ ] 实现配置查询优先级逻辑 + - [ ] 实现配置合并策略 + - [ ] 实现配置删除后的继承恢复 + +- [ ] **敏感配置安全管理**: + - [ ] 实现敏感配置AES加密存储 + - [ ] 实现敏感配置访问权限控制 + - [ ] 实现敏感配置操作审计日志 + - [ ] 实现前端敏感信息脱敏显示 + - [ ] 实现敏感配置权限分级管理 + +- [ ] **配置模板管理功能**: + - [ ] 实现预定义配置模板创建 + - [ ] 实现配置模板分类管理 + - [ ] 实现配置模板一键应用功能 + - [ ] 实现配置模板导入导出 + - [ ] 实现配置模板版本管理和回滚 + +- [ ] **系统监控与审计功能**: + - [ ] 实现配置变更监控和记录 + - [ ] 实现用户行为监控和分析 + - [ ] 实现系统性能监控指标 + - [ ] 实现安全审计日志管理 + - [ ] 实现异常配置变更报警机制 + +- [ ] **小程序配置管理功能**: + - [ ] 实现小程序主题配置 + - [ ] 实现功能开关管理 + - [ ] 实现支付配置管理 + - [ ] 实现通知配置管理 + - [ ] 实现租户级和门店级配置 + +- [ ] **用户设备管理功能**: + - [ ] 实现设备注册和管理 + - [ ] 实现推送令牌管理 + - [ ] 实现设备状态跟踪 + - [ ] 实现多设备登录控制 + - [ ] 实现设备安全审计 + +- [ ] **系统配置API接口**: + - [ ] 实现配置查询API + - [ ] 实现配置更新API + - [ ] 实现配置批量操作API + - [ ] 实现配置导入导出API + - [ ] 实现设备管理API + - [ ] 实现配置模板管理API + - [ ] 实现系统监控API + +- [ ] **系统配置前端页面**: + - [ ] 租户配置管理页面 + - [ ] 门店配置管理页面 + - [ ] 小程序配置页面 + - [ ] 用户设备管理页面 + - [ ] 配置导入导出页面 + - [ ] 配置模板管理页面 + - [ ] 系统监控仪表板页面 + +- [ ] **预定义配置项实现**: + - [ ] 预订规则配置项 + - [ ] 财务参数配置项 + - [ ] 界面外观配置项 + - [ ] 业务流程配置项 + - [ ] 小程序功能配置项 + +## 阶段 5: 前端开发 - 核心功能界面 [P0] **通用前端开发规范 (参考《最佳实践》Chapter 5 & 7.2):** - - [ ] 遵循 Soybean Admin Pro 的项目结构和编码规范。 - - [ ] 使用 Vue 3 Composition API + `