# `naisi_tree_get_descendant_ids`

按深度优先顺序返回平级节点列表中指定节点的全部后代 ID。

同级节点保持输入顺序。节点 ID 接受正整数或规范的非负十进制整数字符串，父节点 ID
还可为 0；输出统一为整数。目标不存在、字段缺失、ID 无效或重复、目标子树存在循环、
未授权或内部处理失败时返回 false。与目标无关的孤立节点不影响结果。

## 函数签名

```php
function naisi_tree_get_descendant_ids(
    array $nodes,
    int $node_id,
    bool $include_self = false,
    string $id_key = 'id',
    string $parent_key = 'parent_id'
): array|false
```

## 调用前提

应用入口先调用 [naisi_is_ext_license_valid](/web/developers/naisilib/naisi-is-ext-license-valid) 并确认返回 `true`。只验证同一请求内已有的有效 FULL/BASIC 证明；没有证明或证明失效时立即返回失败值，不现场补做完整校验。

授权类别：`LICENSE`；执行模式：`PROOF`。许可不代替登录、租户或权限上下文；身份与数据要求见本页参数及用途说明。

## 参数

### `$nodes`

- 类型：`array`
- 必填：是
- 默认值：无
- 方向：输入参数。

平级节点列表。每个节点必须是数组，并至少包含由 $id_key 和 $parent_key 指定的两个字段；其他字段被忽略。

### `$node_id`

- 类型：`int`
- 必填：是
- 默认值：无
- 方向：输入参数。

要查询的目标节点 ID，必须大于 0，并且必须出现在 $nodes 中。

### `$include_self`

- 类型：`bool`
- 必填：否
- 默认值：`false`
- 方向：输入参数。

是否在结果首位包含目标节点自身，默认 false。

### `$id_key`

- 类型：`string`
- 必填：否
- 默认值：`'id'`
- 方向：输入参数。

节点 ID 字段名，默认 "id"。

### `$parent_key`

- 类型：`string`
- 必填：否
- 默认值：`'parent_id'`
- 方向：输入参数。

父节点 ID 字段名，默认 "parent_id"。

## 返回值

类型：`array|false`

成功时返回按先序深度优先排列的整数 ID 数组；叶子节点返回空数组，包含自身时返回仅含目标 ID 的数组；失败时返回 false。

## 调用示例

当前请求须满足上方调用前提；请检查实际返回值和引用输出，随机结果及数据包内容以运行环境为准。

```php
$nodes = [
    [
        'id' => 1,
        'parent_id' => 0
    ],
    [
        'id' => 2,
        'parent_id' => 1
    ],
    [
        'id' => 3,
        'parent_id' => 2
    ]
];
$node_id = 1;
$include_self = false;
$id_key = 'id';
$parent_key = 'parent_id';

$result = naisi_tree_get_descendant_ids($nodes, $node_id, $include_self, $id_key, $parent_key);
var_export($result);
```

## 节点格式与失败规则

节点列表按输入顺序处理，同级顺序不变；输出为先序深度优先的整数 ID 数组。节点 ID 接受正整数或规范的非负十进制整数字符串，父 ID 还可为 `0`。目标不存在、必需字段缺失、ID 无效或重复、目标子树有循环时返回 `false`；与目标无关的孤立节点不影响结果。叶子节点成功时可返回空数组。

## 版本信息

- 自版本：`1.0.6`
- 实现模块：`array`
- 授权类别：`LICENSE` / `PROOF`
- 失败回退：`false`
- 文档同步：`2026-10-18`