# 房屋管理功能需求说明

## 通用操作

* 删除：将数据删除，删除后，数据不可恢复。（软删除）

* 数值符号：如无特殊说明，所有数值类型默认为__无符号数__。

## 名词定义

| 名称  | 定义                                                             |
|:---:| -------------------------------------------------------------- |
| 小区  | 小区，是指在城市一定区域内、具有相对独立居住环境的大片居民住宅，同时是配有成套的生活服务设施，如商业网点、学校（幼儿园）等。 |
| 楼栋  | 小区内居民居住或商铺使用的具有唯一编号的独立建筑物。                                     |
| 单元  | 按照出入口将楼栋划分成一个或多个部分进行管理的建筑物                                     |
| 房屋  | 房屋是住人或存放东西的建筑物。房屋是家庭的基体。                                       |

## 小区管理

小区管理功能用于物业客户在平台上数字化管理其管辖的小区信息，包括小区信息查看，添加，编辑，删除等操作。

### 表单字段说明

| 字段名称   | 字段类型   | 备注                                                                                      | 是否必填 |
| ------ | ------ | --------------------------------------------------------------------------------------- | ---- |
| 小区名称   | String | 在所属城市名称是__唯一__的，一般是根据开发商的楼盘名称设置。                                                        | 是    |
| 所属公司   | String | 关联管辖该小区的物业公司ID，对于集团公司而言，可能是总公司，也可能是分公司。                                                 | 是    |
| 所属管理处  | String | 关联管辖该小区的物业管理处ID，其中物业管理处属于小区所属公司的下级部门。                                                   | 否    |
| 所在省份   | Int    | 小区所在的省份的ID                                                                              | 是    |
| 所在城市   | Int    | 小区所在的城市的ID，该城市属于小区所在省份的下级                                                               | 是    |
| 所在地区   | Int    | 小区所在地区的ID，该地区行政级别对于城市为地级市的为区县级别，对于县级市的为乡镇级别                                             | 是    |
| 详细地址   | String | 小区所在街道，门牌编号等信息，通过百度地图定位后再填写                                                             | 是    |
| 经度     | Float  | 小区地理位置的百度地图经度坐标，精确度保留6位小数，坐标类型为BD09                                                     | 是    |
| 纬度     | Float  | 小区地理位置的百度地图纬度坐标，精确度保留6位小数，坐标类型为BD09                                                     | 是    |
| 物业类型   | Enum   | 枚举类型，可多选。包括住宅，别墅，公寓，写字楼，办公楼，厂房，医院，酒店，学校。                                                | 否    |
| Logo   | Image  | 小区Logo图片，尺寸为320 x 320像素，前端裁剪完再上传。上传格式支持jpg，jpeg，png。上传文件大小限制为1MB。                       | 否    |
| Banner | Image  | 小区Banner展示图，用于微信关注推送时首条消息的图片展示，尺寸为900 x 500像素，前端裁剪完再上传。上传格式支持jpg，jpeg，png。上传文件大小限制为1MB。 |      |
| 备注     | String | 不超过200个字符，对小区的一些额外补充信息。                                                                 | 否    |
| 详细介绍   | Text   | 小区图文介绍，用于C端用户了解小区信息                                                                     | 是    |

### 业务说明

* 可见状态：小区创建后，未保证功能可用性和数据的准确性，可见状态为`false`，即对C端用户是隐藏的。小区最终由平台管理方决定该小区是否对住户开放。

* 数据状态：小区的数据状态包括正常和已删除；已上线的小区，或小区已有房屋数据、车场等数据不允许删除。

* 上线状态：小区创建后默认为下线状态，即C端用户无法查看到小区。小区由平台管理方设置为上线。设置为上线后，需要经由平台操作方可下线。

* 唯一性约束：小区名称在所在城市要求是唯一的，包括正常状态和回收站的小区，但不包括已删除状态的小区。

* 排序：展示的小区列表按小区名称首字母升序排序，数据库需要存储小区名称的首字母和全拼拼音（均为大写字母）。

* 数据筛选：支持按小区名称模糊搜索，支持按公司、省份、城市，地区、物业类型进行筛选。

* 统计字段：小区主表中冗余下属楼栋数量，单元数量和房屋数量。

* 可编辑字段：小区上线后，只允许编辑Logo，Banner，备注，详细介绍等信息；未上线前可编辑全部信息。

## 楼栋管理

楼栋管理功能用于管理小区中的楼栋信息。

### 表单字段说明

| 字段名  | 字段类型   | 备注                        | 是否必填 |
| ---- | ------ | ------------------------- | ---- |
| 楼栋名称 | String | 所在小区唯一                    | 是    |
| 有无单元 | Bool   | 选择无时系统自动创建一个默认单元，单元名为：1单元 | 是    |

### 业务说明

* 表单提交时需要把小区ID（String类型）一并提交。

* 可见状态：新建的楼栋默认是可见的，后台暂不开放可见性设置功能。

* 数据状态：楼栋的数据状态包括正常，已删除。新建的楼栋默认是正常状态，楼栋下有单元或房屋数据时，不允许删除。

* 唯一性约束：楼栋名称要求在所在小区是唯一的（已删除的不算重复）。

* 排序：为保证楼栋排序按物理楼栋号升序，存储楼栋数据时，需要额外提取楼栋号，楼栋号提取规则如下：

  * 将特殊字符全部去掉（替换为''），如1#替换为1。

  * 楼栋名称全部是中文，则提取拼音的前三个字母作为排序号（不足三个字母的保留全部字母），如紫金阁，则排序号为ZIJ；

  * 楼栋名称有ASCII字符或阿拉伯数字的，提取ASCII码或数字作为排序号，保留三个字符，不足三个字符的前面补0，如A栋，则排序号取值为00A；1号楼取值为001。

* 统计字段：下属单元数，下属房屋数

* 数据筛选：支持按楼栋名称模糊搜索。

* 可编辑字段：小区未上线前可编辑楼栋名称，上线后禁止编辑。

## 单元管理

单元管理用于管理楼栋下的单元信息，需要注意的是有些楼栋没有单元概念，但为保证数据一致性，需要添加默认的单元，默认单元统一为1单元（楼栋无单元时，缴费通知单，收据等单据上，缴费记录等不显示单元名称）。

### 表单字段说明

| 字段名称 | 字段类型   | 备注                 | 是否必填 |
| ---- | ------ | ------------------ | ---- |
| 单元名称 | String | 所属楼栋唯一             | 是    |
| 地上层数 | Int    | 该单元楼地面最高层数，必须大于等于1 | 是    |
| 地下层数 | Int    | 该单元楼地下最高层数，允许为0    | 是    |

### 业务说明

* 表单提交时需要把小区ID和楼栋ID一并提交

* 可见状态：新建的单元默认是可见的，后台暂不开放单元可见性设置功能。

* 数据状态：单元的数据状态包括正常和已删除。新建的单元默认是正常状态，单元下已有房屋数据时不允许删除。

* 唯一性约束：单元名称在所在楼栋是唯一的（已删除的不算重复）。

* 排序：为保证单元排序按物理楼栋号升序，存储单元数据时，需要额外提取单元号，单元号提取规则如下：

  - 将特殊字符全部去掉（替换为''），如1#替换为1。

  - 单元名称全部是中文，则提取拼音的前三个字母作为排序号（不足三个字母的保留全部字母），如紫金阁，则排序号为ZIJ；

  - 单元名称有ASCII字符或阿拉伯数字的，提取ASCII码或数字作为排序号，保留三个字符，不足三个字符的前面补0，如A栋，则排序号取值为00A；1号楼取值为001。

* 单元的楼层不作为房屋楼层数据录入的约束，仅用作查看。

* 统计字段：下属房屋数。

* 数据筛选：由于楼栋的单元数一般不超过3个，可不做任何筛选。

* 可编辑字段：小区上线前可以编辑名称，地上层数和地下层数；上线后禁止编辑。

## 房屋管理

房屋管理用于管理小区的房屋信息，房屋是账单的物理载体，是物业服务的主要对象。

### 表单字段说明

| 字段名称     | 字段类型   | 备注                                                            | 是否必填 |
| -------- | ------ | ------------------------------------------------------------- | ---- |
| 房屋号      | String | 整个小区唯一                                                        | 是    |
| 房屋简称     | String | 所属单元唯一                                                        | 是    |
| 所在楼层     | Int    | 房屋所在楼层，允许为负数                                                  | 是    |
| 建筑面积     | Float  | 房屋的建筑面积，最多可保留2位小数                                             | 是    |
| 计费面积     | Float  | 房屋的计费面积，最多可保留2位小数                                             | 是    |
| 分摊倍数     | Int    | 按房屋分摊费用时的系数，允许为0，即不参与分摊                                       | 是    |
| 是否装修     | Bool   | 标记该房屋是否已经完成装修，默认为是，该参数会参与费用计算                                 | 是    |
| 是否交房     | Bool   | 标记该房屋业主是否已经完成交房手续，默认为是，该参数会参与费用计算                             | 是    |
| 是否入住     | Bool   | 标记该房屋是否已经有人居住，默认为是，该参数会参与费用计算                                 | 是    |
| 是否签署服务协议 | Bool   | 标记该房屋业主是否与物业公司签订服务协议，若未签订服务协议，则业主提出服务时，需要额外支付费用。该字段仅在部分小区会使用。 | 是    |
| 公摊面积     | Float  | 房屋公摊面积，最多可保留2位小数。                                             | 否    |
| 套内面积     | Float  | 房屋套内使用面积，最多可保留2位小数                                            | 否    |
| 使用情况     | Enum   | 枚举，从自住，出租和空置三个选项中选择，默认为自住。                                    | 否    |
| 交房日期     | Date   | 业主交房时的日期，该日期不得超过系统当前日期                                        | 否    |
| 备注       | String | 房屋备注信息，不得超过200个字符                                             | 否    |

### 业务说明

- 接口需要把小区ID，楼栋ID和单元ID一并提交。

- 可见状态：新建的房屋默认是可见的，后台暂不开放单元可见性设置功能。

- 数据状态：单元的数据状态包括正常和已删除。__一旦房屋有关联的资产（仪表，车辆，车位）、住户或账单，则不允许将房屋放入回收站__。

- 唯一性约束：房屋号在所在小区是唯一的（已删除的不算重复），房屋简称在所在单元是唯一的。

- 房屋简称：房屋简称采用正则匹配特殊字符分隔方法，取最后得到的字符串作为房屋简称，如1-2-301，用“-”分隔得到301，1#301则用'#'分隔得到301。该处理由前端完成，后端需要校验所在单元的唯一性。

- 排序：列表时，按照楼栋、单元、楼层、房屋号升序排序返回给前端。

- 数据筛选：支持房屋号模糊搜索，支持按小区，楼栋，单元和楼层筛选房屋。

- 可编辑字段：小区上线前若房屋未关联资产或账单可允许编辑全部字段。上线后，仅可编辑备注，签署服务协议，是否装修，是否交房，是否入住，是否签署服务协议，使用情况，交房日期等字段。__上线后，房屋号编辑时需单独开发编辑房屋号功能，且需要记录房屋号的历史版本__（该情况发生于部分企业租赁房屋的情况，如2018年租赁该房屋的是A公司，2019年租赁该房屋的是B公司，部分物业企业会以公司名称作为房屋号）。