mirror of
https://github.com/hpd840321/starRiverProperty.git
synced 2026-06-09 08:20:31 +08:00
hpd840321
7b2bd307f1
- 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.
308 lines
8.9 KiB
Markdown
308 lines
8.9 KiB
Markdown
# 广发基金访客被访楼层接口生产验证操作文档
|
||
|
||
## 1. 目标与范围
|
||
|
||
本文用于生产环境验证以下事项：
|
||
|
||
- 广发基金租户下，访客开通接口在不传 `floorIds` 时，是否按被访人楼层与租户策略进行处理。
|
||
- 验证对象固定为广发基金员工 **蒙海文** 的关联信息（`personId`、`businessId`、`floorList`）。
|
||
- 输出可审计的执行记录，包含输入参数、返回结果、结论与留痕。
|
||
|
||
说明：本操作仅做接口调用和数据核验，不修改生产配置、不执行策略变更 SQL。
|
||
|
||
## 2. 前置条件
|
||
|
||
### 2.1 必备信息
|
||
|
||
- 电梯服务地址：`ELEVATOR_BASE_URL`（示例：`http://<host>:16112`）。
|
||
- 组织服务地址：`ORG_BASE_URL`（示例：`http://<host>:17016` 或网关地址）。
|
||
- 广发基金租户 `businessId`：`2524639890ba4f2cba9ba1a4eeaa4015`。
|
||
- 测试访客 `visitorId`（专用测试账号，避免使用真实业务访客）。
|
||
- 鉴权头（按现场网关要求）：`authorization`、`loginid`、`platformuserid`、`applicationid`。
|
||
|
||
### 2.2 风险提示
|
||
|
||
- 生产环境调用会产生真实接口访问日志，请在低峰时段执行。
|
||
- `add/visitor` 会写入访客通行规则，建议只使用测试访客并设置短期有效期。
|
||
- 若现场策略已变更，需先复核 `tenant_visitor_floor_policy` 再执行。
|
||
|
||
## 3. 蒙海文关联信息确认（必做）
|
||
|
||
先确认“蒙海文”在组织服务中的关键关联信息，作为后续请求入参依据。
|
||
|
||
### 3.1 确认项清单
|
||
|
||
- 员工姓名：蒙海文
|
||
- 员工 `personId`：`<MENG_HAI_WEN_PERSON_ID>`
|
||
- 员工 `businessId`：`2524639890ba4f2cba9ba1a4eeaa4015`
|
||
- 员工 `floorList`：`["..."]`（至少 1 个楼层 ID）
|
||
|
||
### 3.2 被访人详情接口请求模板（输入参数）
|
||
|
||
接口：`POST /component/person/detail`
|
||
|
||
请求头模板：
|
||
|
||
```text
|
||
Content-Type: application/json
|
||
businessid: 2524639890ba4f2cba9ba1a4eeaa4015
|
||
authorization: Bearer <TOKEN>
|
||
loginid: <LOGIN_ID>
|
||
platformuserid: <PLATFORM_USER_ID>
|
||
applicationid: <APPLICATION_ID>
|
||
```
|
||
|
||
请求体模板：
|
||
|
||
```json
|
||
{
|
||
"id": "<MENG_HAI_WEN_PERSON_ID>",
|
||
"businessId": "2524639890ba4f2cba9ba1a4eeaa4015"
|
||
}
|
||
```
|
||
|
||
`curl` 示例：
|
||
|
||
```bash
|
||
curl -sS -X POST "${ORG_BASE_URL}/component/person/detail" \
|
||
-H "Content-Type: application/json" \
|
||
-H "businessid: 2524639890ba4f2cba9ba1a4eeaa4015" \
|
||
-H "authorization: Bearer <TOKEN>" \
|
||
-H "loginid: <LOGIN_ID>" \
|
||
-H "platformuserid: <PLATFORM_USER_ID>" \
|
||
-H "applicationid: <APPLICATION_ID>" \
|
||
-d '{
|
||
"id":"<MENG_HAI_WEN_PERSON_ID>",
|
||
"businessId":"2524639890ba4f2cba9ba1a4eeaa4015"
|
||
}'
|
||
```
|
||
|
||
验收要点：
|
||
|
||
- `data.name` 为“蒙海文”。
|
||
- `data.businessId` 为 `2524639890ba4f2cba9ba1a4eeaa4015`。
|
||
- `data.floorList` 非空并记录原始值。
|
||
|
||
## 4. 租户策略基线确认（建议）
|
||
|
||
用于确认广发基金策略是否启用，避免误判。
|
||
|
||
参考策略脚本：`docs/sql/tenant_visitor_floor_policy_init_guangfa_fund.sql`
|
||
|
||
关键期望：
|
||
|
||
- `business_id='2524639890ba4f2cba9ba1a4eeaa4015'`
|
||
- `policy_type='INTERSECT_ALLOWLIST'`
|
||
- `enabled=1`
|
||
- `allow_zone_ids` 含 `605560545117995008`（28F）
|
||
|
||
示例查询（电梯库）：
|
||
|
||
```sql
|
||
SELECT business_id, policy_type, allow_zone_ids, enabled, policy_version, updated_at
|
||
FROM tenant_visitor_floor_policy
|
||
WHERE business_id = '2524639890ba4f2cba9ba1a4eeaa4015';
|
||
```
|
||
|
||
## 5. 访客开通接口验证（核心）
|
||
|
||
### 5.1 请求信息（输入参数）
|
||
|
||
接口：`POST /elevator/person/add/visitor`
|
||
|
||
请求头：与第 3 节一致，`businessid` 固定为 `2524639890ba4f2cba9ba1a4eeaa4015`。
|
||
|
||
请求体模板（验证“自动按被访人楼层处理”时，`floorIds` 置空或不传）：
|
||
|
||
```json
|
||
{
|
||
"visitorId": "<TEST_VISITOR_PERSON_ID>",
|
||
"personId": "<MENG_HAI_WEN_PERSON_ID>",
|
||
"begVisitorTime": <BEGIN_TS_MS>,
|
||
"endVisitorTime": <END_TS_MS>,
|
||
"floorIds": []
|
||
}
|
||
```
|
||
|
||
时间戳示例（毫秒）：
|
||
|
||
- `begVisitorTime`: 当前时间
|
||
- `endVisitorTime`: 当前时间 + 1 天
|
||
|
||
`curl` 示例：
|
||
|
||
```bash
|
||
curl -sS -X POST "${ELEVATOR_BASE_URL}/elevator/person/add/visitor" \
|
||
-H "Content-Type: application/json" \
|
||
-H "businessid: 2524639890ba4f2cba9ba1a4eeaa4015" \
|
||
-H "authorization: Bearer <TOKEN>" \
|
||
-H "loginid: <LOGIN_ID>" \
|
||
-H "platformuserid: <PLATFORM_USER_ID>" \
|
||
-H "applicationid: <APPLICATION_ID>" \
|
||
-d '{
|
||
"visitorId":"<TEST_VISITOR_PERSON_ID>",
|
||
"personId":"<MENG_HAI_WEN_PERSON_ID>",
|
||
"begVisitorTime":<BEGIN_TS_MS>,
|
||
"endVisitorTime":<END_TS_MS>,
|
||
"floorIds":[]
|
||
}'
|
||
```
|
||
|
||
期望：
|
||
|
||
- 返回成功码（常见 `code=0` 或 `success=true`，以现场协议为准）。
|
||
- 若返回 `76260532`，表示求交后无可开通楼层，需按“预期失败”流程记录。
|
||
|
||
## 6. 回读访客楼层权限验证
|
||
|
||
### 6.1 回读接口请求模板（输入参数）
|
||
|
||
接口：`POST /elevator/passRule/image`
|
||
|
||
请求体模板：
|
||
|
||
```json
|
||
{
|
||
"personId": "<TEST_VISITOR_PERSON_ID>",
|
||
"businessId": "2524639890ba4f2cba9ba1a4eeaa4015",
|
||
"imageStoreIds": [],
|
||
"includeOrganizations": [],
|
||
"includeLabels": []
|
||
}
|
||
```
|
||
|
||
`curl` 示例：
|
||
|
||
```bash
|
||
curl -sS -X POST "${ELEVATOR_BASE_URL}/elevator/passRule/image" \
|
||
-H "Content-Type: application/json" \
|
||
-H "businessid: 2524639890ba4f2cba9ba1a4eeaa4015" \
|
||
-H "authorization: Bearer <TOKEN>" \
|
||
-H "loginid: <LOGIN_ID>" \
|
||
-H "platformuserid: <PLATFORM_USER_ID>" \
|
||
-H "applicationid: <APPLICATION_ID>" \
|
||
-d '{
|
||
"personId":"<TEST_VISITOR_PERSON_ID>",
|
||
"businessId":"2524639890ba4f2cba9ba1a4eeaa4015",
|
||
"imageStoreIds":[],
|
||
"includeOrganizations":[],
|
||
"includeLabels":[]
|
||
}'
|
||
```
|
||
|
||
### 6.2 判定规则
|
||
|
||
- 成功判定：
|
||
- `add/visitor` 成功。
|
||
- `passRule/image` 返回 `data[]` 非空。
|
||
- 返回楼层（`zoneId` / `zoneName`）符合当前租户策略和被访人 `floorList` 的交集预期。
|
||
- 预期失败判定：
|
||
- `add/visitor` 返回 `76260532`（交集为空），记录为预期失败，不记为系统缺陷。
|
||
- 异常失败判定：
|
||
- 鉴权失败（401/403）。
|
||
- 参数格式错误（400）。
|
||
- 下游服务不可达、超时、5xx。
|
||
|
||
## 7. 标准执行顺序
|
||
|
||
1. 记录执行人、时间窗、目标环境与业务单号。
|
||
2. 调 `/component/person/detail`，确认并记录蒙海文信息。
|
||
3. （建议）执行策略查询，确认 allowlist 状态。
|
||
4. 调 `/elevator/person/add/visitor` 开通测试访客。
|
||
5. 调 `/elevator/passRule/image` 回读访客楼层。
|
||
6. 依据第 6.2 节判定并形成结论。
|
||
|
||
## 8. 现场结论记录模板（复制填写）
|
||
|
||
### 8.1 基本信息
|
||
|
||
- 执行时间：
|
||
- 执行环境：
|
||
- 执行人：
|
||
- 工单/需求编号：
|
||
|
||
### 8.2 蒙海文关联信息核对结果
|
||
|
||
- 姓名：蒙海文
|
||
- `personId`：
|
||
- `businessId`：
|
||
- `floorList`：
|
||
- 核对结论（通过/不通过）：
|
||
|
||
### 8.3 接口调用记录
|
||
|
||
1) `/component/person/detail`
|
||
- 请求参数摘要：
|
||
- 响应摘要：
|
||
- 结果判定：
|
||
|
||
2) `/elevator/person/add/visitor`
|
||
- 请求参数摘要（含 `visitorId`、`personId`、时间窗）：
|
||
- 响应摘要（含业务码）：
|
||
- 结果判定：
|
||
|
||
3) `/elevator/passRule/image`
|
||
- 请求参数摘要：
|
||
- 响应摘要（含 `zoneId/zoneName`）：
|
||
- 结果判定：
|
||
|
||
### 8.4 最终结论
|
||
|
||
- 结论：通过 / 预期失败 / 失败
|
||
- 失败原因分类：
|
||
- 后续处理建议：
|
||
|
||
## 9. 附件留痕要求
|
||
|
||
至少保留以下附件（脱敏后归档）：
|
||
|
||
- 三次接口请求与响应（建议 JSON 文件各 1 份）。
|
||
- 关键日志截图（包含时间戳与业务码）。
|
||
- 本文档第 8 节填写后的结果页。
|
||
|
||
建议命名：`gf-visitor-floor-verify-<yyyyMMdd-HHmm>-<executor>.zip`
|
||
|
||
## 10. 方案B：Python 脚本一键模拟（完整实现）
|
||
|
||
仓库已提供可执行脚本：
|
||
|
||
- `maven-cw-elevator-application/tools/visitor_floor_verification/scripts/simulate_gf_visitor_flow.py`
|
||
|
||
### 10.1 安装依赖
|
||
|
||
```bash
|
||
cd maven-cw-elevator-application/tools/visitor_floor_verification
|
||
python3 -m pip install -r requirements.txt
|
||
```
|
||
|
||
### 10.2 设置请求头环境变量
|
||
|
||
```bash
|
||
export ELEVATOR_HEADER_AUTHORIZATION='Bearer <TOKEN>'
|
||
export ELEVATOR_HEADER_LOGINID='<LOGIN_ID>'
|
||
export ELEVATOR_HEADER_PLATFORMUSERID='<PLATFORM_USER_ID>'
|
||
export ELEVATOR_HEADER_APPLICATIONID='<APPLICATION_ID>'
|
||
```
|
||
|
||
说明：`businessid` 由脚本参数 `--business-id` 自动注入，同时也会写入 `ELEVATOR_HEADER_BUSINESSID`。
|
||
|
||
### 10.3 执行脚本
|
||
|
||
```bash
|
||
python3 scripts/simulate_gf_visitor_flow.py \
|
||
--org-base-url "http://<ORG_HOST>:<ORG_PORT>" \
|
||
--elevator-base-url "http://<ELEVATOR_HOST>:<ELEVATOR_PORT>" \
|
||
--meng-person-id "<MENG_HAI_WEN_PERSON_ID>" \
|
||
--visitor-person-id "<TEST_VISITOR_PERSON_ID>" \
|
||
--business-id "2524639890ba4f2cba9ba1a4eeaa4015" \
|
||
--window-hours 24 \
|
||
--strict-name-check
|
||
```
|
||
|
||
### 10.4 输出与判定
|
||
|
||
- 控制台会打印三步调用的关键摘要（详情 code、回读 data 条数、是否全通过）。
|
||
- 报告文件自动生成到：
|
||
- `maven-cw-elevator-application/tools/visitor_floor_verification/report/gf-visitor-sim-<timestamp>.json`
|
||
- 若脚本退出码为 `0` 表示检查通过；退出码为 `1` 表示存在未通过项，需查看报告里的 `checks`、`steps` 字段。
|