huangping/starRiverProperty
1
0
Fork 0
mirror of https://github.com/hpd840321/starRiverProperty.git synced 2026-06-09 08:20:31 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
721e88dd8931e5e00fb2052586f247248d01b5c7
starRiverProperty/docs/business/租户访客默认楼层-数据库阶段变更记录.md
T
hpd840321 7b2bd307f1 Initial commit: reorganized source tree 
- backend/: 13 Maven modules (cw-elevator-application, cloudwalk-cloud, intelligent-cwoscomponent, ninca-crk, etc.)
- frontend/: 4 Vue projects (elevator-front, cwos-portal, alarm-front, front_acs) + decompiled + scripts
- scripts/: build, test-env, tools (Docker Compose, service templates, API parity)
- docs/: AGENTS.md, superpowers specs, architecture docs
- .gitignore: standard Java/Maven exclusions

Moved from legacy maven-*/ root layout to backend/ organized structure.
2026-05-09 09:56:45 +08:00

134 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 租户访客默认楼层（数据库配置阶段）— 变更记录
> **用途**：记录本仓库内已落地的代码与脚本变更，便于评审、发版说明与运维回溯。
> **设计依据**：[租户访客默认楼层-数据库配置阶段技术设计](租户访客默认楼层-数据库配置阶段技术设计.md)
> **产品依据**：[租户访客默认楼层技术产品方案](租户访客默认楼层技术产品方案.md)
> **流程依据**：[访客注册与派梯楼层业务流程走查](访客注册与派梯楼层业务流程走查.md)
---
## 1. 版本信息
| 项目 | 内容 |
|------|------|
| **Git 分支** | `feature/tenant-visitor-floor-policy-db` |
| **主提交** | `25cff4d` — `feat(elevator): 租户访客默认楼层策略表与 UC-01 求交` |
| **涉及工程** | `maven-cw-elevator-application`（`cw-elevator-application-data`、`cw-elevator-application-service`） |
| **对外接口** | 无新增 HTTP；行为变更集中在 **`POST /elevator/person/add/visitor`**（`PersonRuleServiceImpl.addVisitor`） |
---
## 2. 变更摘要
1. **新增数据库表** `tenant_visitor_floor_policy`：按租户（`business_id`）配置访客允许 `zoneId` 列表（JSON），本阶段仅支持 **`INTERSECT_ALLOWLIST`** 与 **租户级**（`building_id` 为空）策略行。
2. **电梯服务 `addVisitor`**：当请求 **未携带非空 `floorIds`**（走查 **UC-01**）时，在取得组织侧被访人 **`floorList`** 后，若存在启用策略且 `allow_zone_ids` 解析为非空数组，则 **`effective = floorList ∩ allow`**（**保持 `floorList` 原有顺序**）；无交集则失败；无表/停用/允许列表为空或 JSON 无效则 **与现网一致** 使用全量 `floorList`。
3. **当请求已携带非空 `floorIds`**（**UC-02**）：**不读策略表**、不对入参求交，行为与变更前一致。
4. **健壮性**：组织 `detail` 失败透传错误码；`PersonResult` / `floorList` 为空返回 **`76260531`**；策略求交为空返回 **`76260532`**；最终 `floorIds` 仍为空时返回 **`76260531`**；`addVisitor` 中 **`ServiceException` 不再被泛化 `catch` 吞掉**，避免一律映射为 `76260530`。
---
## 3. 文件清单
### 3.1 新增
| 路径 | 说明 |
|------|------|
| `docs/sql/tenant_visitor_floor_policy.sql` | 建表 DDL（`CREATE TABLE IF NOT EXISTS`）及注释示例 |
| `maven-cw-elevator-application/cw-elevator-application-data/.../person/dto/TenantVisitorFloorPolicyDto.java` | 策略行 DTO |
| `maven-cw-elevator-application/cw-elevator-application-data/.../person/mapper/TenantVisitorFloorPolicyMapper.java` | MyBatis Mapper 接口 |
| `maven-cw-elevator-application/cw-elevator-application-data/.../person/mapper/TenantVisitorFloorPolicyMapper.xml` | `selectEnabledTenantDefault` SQL |
| `maven-cw-elevator-application/cw-elevator-application-data/.../person/dao/TenantVisitorFloorPolicyDao.java` | DAO 接口 |
| `maven-cw-elevator-application/cw-elevator-application-data/.../person/impl/TenantVisitorFloorPolicyDaoImpl.java` | DAO 实现 |
| `docs/business/租户访客默认楼层-数据库配置阶段技术设计.md` | 技术设计（含实现分支与 DDL 路径说明） |
### 3.2 修改
| 路径 | 说明 |
|------|------|
| `maven-cw-elevator-application/cw-elevator-application-service/.../person/impl/PersonRuleServiceImpl.java` | `addVisitor` 主流程；注入 `TenantVisitorFloorPolicyDao`；新增 `parseAllowZoneIds`、`intersectPreserveHostOrder` |
---
## 4. 行为对照表（验收速查）
| 场景 | `floorIds` 请求体 | 库中策略 | 期望 |
|------|-------------------|----------|------|
| UC-01 基线 | 空 / 未传 | 无行或 `enabled=0` 或 `allow_zone_ids` 空/无效 JSON | 与变更前一致：使用组织 **`floorList` 全集** |
| UC-01 + 策略 | 空 / 未传 | 有启用行且 allow 非空 | **`floorList ∩ allow`**（保序） |
| 策略无交集 | 空 / 未传 | allow 与 `floorList` 无共同元素 | **`CloudwalkResult.fail("76260532", ...)`** |
| 被访人无楼层 | 空 / 未传 | 任意 | **`76260531`**（`floorList` 空或 null） |
| 组织 detail 失败 | 空 / 未传 | 任意 | **透传** `detail` 的 code/message |
| UC-02 | **非空** `floorIds` | 任意 | **不读表**，按请求列表后续处理（与变更前一致） |
---
## 5. 数据库与配置
### 5.1 执行顺序
1. 在电梯应用（或与电梯同数据源）库执行 **`docs/sql/tenant_visitor_floor_policy.sql`**。
2. 对目标租户 **`INSERT`** 策略行（`business_id`、`allow_zone_ids` JSON、`enabled=1`、`policy_type='INTERSECT_ALLOWLIST'`、`building_id` 为 **NULL**）。
3. 发布包含本分支的 **`cw-elevator-application`** 制品。
### 5.2 `allow_zone_ids` 格式
- JSON 数组字符串，例如：`["zoneId1","zoneId2"]`。
- 解析失败或解析结果为空：**按无有效策略处理**（不打断 UC-01，避免误配导致全租户不可用）；并打 **WARN** 日志。
### 5.3 查询规则（与 Mapper 一致）
- `business_id = ?`
- `enabled = 1`
- `policy_type = 'INTERSECT_ALLOWLIST'`
- `building_id IS NULL OR building_id = ''`
- `ORDER BY updated_at DESC, policy_version DESC LIMIT 1`
**运维约定**：同一租户、租户级策略（`building_id` 为空）**仅维护一行**，避免多行时仅命中最新一条。
---
## 6. 错误码与文案（待资源文件补全）
| 错误码 | 触发条件 | 建议中文文案（需在统一 messages 中配置） |
|--------|----------|------------------------------------------|
| `76260531` | 被访人无 `floorList`；或经处理后仍无可用楼层 | 无法为访客开通派梯：被访人无授权楼层或无可生效楼层 |
| `76260532` | 租户允许列表与被访人 `floorList` 交集为空 | 无法为访客开通派梯：租户访客楼层策略与被访人授权楼层不一致，请联系管理员 |
若未配置文案，`getMessage` 可能回退为码或占位，**发版前请在现网 i18n 资源中登记**。
---
## 7. 日志
- 当发生 **策略求交且结果非空** 时，打 **INFO**：`businessId`、`personId`、`visitorId`、`policyId`、`policyVersion`、**生效楼层数量** `effectiveSize`（不落全量 zoneId，减少日志敏感面；若排障需要可临时调高或改为 DEBUG）。
---
## 8. 集成与运行依赖
| 项 | 说明 |
|----|------|
| **MyBatis** | 启动类需能扫描到 **`cn.cloudwalk.elevator.person.mapper`**（或与现有 `cn.cloudwalk.elevator` 下 Mapper 扫描策略一致）；`Mapper.xml` 位于 `cw-elevator-application-data` 的 `src/main/java/.../mapper/*.xml`（与现有模块一致）。 |
| **表不存在** | 未执行 DDL 时访问表会抛 SQL 异常，通常落入 `76260530` 包装；**须先 DDL 再发应用**。 |
| **本地编译** | 聚合工程要求 **JDK 8** 跑 Maven（enforcer）；若 `cw-elevator-application-common` 等模块因私服依赖未解析失败，与本次新增类无直接关系，需在完整依赖环境编译。 |
---
## 9. 明确未包含（后续迭代）
- 物业管理端页面、策略 CRUD REST、审计与 `policy_version` 写入登记快照。
- 登记页 / BFF **预览接口**与电梯开通结果的 **展示同源**（见技术设计 §8）。
- 按 **`building_id`** 的多套策略（表字段已预留，查询与产品未定前不启用）。
---
## 10. 修订历史
| 日期 | 修订内容 |
|------|----------|
| 2026-04-24 | 初稿：对应分支 `feature/tenant-visitor-floor-policy-db`、提交 `25cff4d` |
---
*本文档随该功能后续提交持续更新；合并主干后建议在提交说明中引用本路径。*
Reference in New Issue View Git Blame Copy Permalink