mirror of https://github.com/hpd840321/starRiverProperty.git synced 2026-06-09 08:20:31 +08:00

Files

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

7.6 KiB

Raw Permalink Blame History

租户访客默认楼层（数据库配置阶段）— 变更记录

用途：记录本仓库内已落地的代码与脚本变更，便于评审、发版说明与运维回溯。
设计依据：租户访客默认楼层-数据库配置阶段技术设计
产品依据：租户访客默认楼层技术产品方案
流程依据：访客注册与派梯楼层业务流程走查

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. 变更摘要

新增数据库表 tenant_visitor_floor_policy：按租户（business_id）配置访客允许 zoneId 列表（JSON），本阶段仅支持 INTERSECT_ALLOWLIST 与 租户级（building_id 为空）策略行。
电梯服务 addVisitor：当请求 未携带非空 floorIds（走查 UC-01）时，在取得组织侧被访人 floorList 后，若存在启用策略且 allow_zone_ids 解析为非空数组，则 effective = floorList ∩ allow（保持 floorList 原有顺序）；无交集则失败；无表/停用/允许列表为空或 JSON 无效则 与现网一致 使用全量 floorList。
当请求已携带非空 floorIds（UC-02）：不读策略表、不对入参求交，行为与变更前一致。
健壮性：组织 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 执行顺序

在电梯应用（或与电梯同数据源）库执行 docs/sql/tenant_visitor_floor_policy.sql。
对目标租户 INSERT 策略行（business_id、allow_zone_ids JSON、enabled=1、policy_type='INTERSECT_ALLOWLIST'、building_id 为 NULL）。
发布包含本分支的 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`

本文档随该功能后续提交持续更新；合并主干后建议在提交说明中引用本路径。

7.6 KiB Raw Permalink Blame History Unescape Escape