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

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