starRiverProperty/docs/testing/广发基金访客被访楼层接口生产验证.md

广发基金访客被访楼层接口生产验证操作文档

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

请求头模板：

Content-Type: application/json
businessid: 2524639890ba4f2cba9ba1a4eeaa4015
authorization: Bearer <TOKEN>
loginid: <LOGIN_ID>
platformuserid: <PLATFORM_USER_ID>
applicationid: <APPLICATION_ID>

请求体模板：

{
  "id": "<MENG_HAI_WEN_PERSON_ID>",
  "businessId": "2524639890ba4f2cba9ba1a4eeaa4015"
}

curl 示例：

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）

示例查询（电梯库）：

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 置空或不传）：

{
  "visitorId": "<TEST_VISITOR_PERSON_ID>",
  "personId": "<MENG_HAI_WEN_PERSON_ID>",
  "begVisitorTime": <BEGIN_TS_MS>,
  "endVisitorTime": <END_TS_MS>,
  "floorIds": []
}

时间戳示例（毫秒）：

• begVisitorTime: 当前时间
• endVisitorTime: 当前时间 + 1 天

curl 示例：

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

请求体模板：

{
  "personId": "<TEST_VISITOR_PERSON_ID>",
  "businessId": "2524639890ba4f2cba9ba1a4eeaa4015",
  "imageStoreIds": [],
  "includeOrganizations": [],
  "includeLabels": []
}

curl 示例：

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 安装依赖

cd maven-cw-elevator-application/tools/visitor_floor_verification
python3 -m pip install -r requirements.txt

10.2 设置请求头环境变量

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 执行脚本

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 字段。