Przeglądaj źródła

✨ (tipitaka): 新增 /v3/tipitaka-chapters,按名字找章节或列出一本书的全部标题

取代 v2 search-title-index(只回标题文字、LIKE 硬匹配):
- 按名字找:不分大小写与变音符号、去序号与丛书缩写,拼错一两个字母也能找到(三字母粗筛 +
  编辑距离),公开译本的中文章节名也能搜;分档打分,同档里根本典在前
- 不给 q 给 book(可加 para、max_level):按经文顺序列出全部标题
- 每条带坐标、layer(mula/atthakatha/tika/anna)、段数与字符数、上下章、路径、公开译名
- q 的 PHP 匹配只用来验证按名定位的效果,正式实现走 OpenSearch(search-recall.md 4.6)

同时:Pest 11 条、api-test 用例、OpenAPI 规格与 dashboard-v6 类型、v2 端点标 deprecated、
CLAUDE.md 对照表加一行。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
visuddhinanda 5 dni temu
rodzic
commit
f3ec024488

+ 1 - 0
CLAUDE.md

@@ -354,6 +354,7 @@ Resource / FormRequest / 测试同理;URL 只换版本前缀
 | `access-token`(agent 用途)/ `AccessTokenController@store` | `agent-grants` / `V3\AgentGrantController` | 人类为自己名下的 AI 模型签 channel 写入授权。载荷由服务端决定(v2 原样签客户端 payload)、绑定模型(act)与签发人(grantor)、带模型 token_version、独立密钥;写入时放 `X-Agent-Grant` 头而不是请求体 |
 | `sent-discussion-tree`(部分)/ `DiscussionController@discussion_tree` | `tipitaka-discussions/{channel}` / `V3\TipitakaDiscussionController` | 新能力为主:按经文范围(channel 必填;`book` + `chapter` 或 `para`/`to`,不给 book 即整个 channel)列挂在句子上的话题,每条带 `sentence` 坐标,按经文顺序排;`type` 可逗号多选,默认只列话题,可见性同 `/v3/discussions`。v2 那条要调用方逐句列出坐标、只回标题与回复数,未迁也不迁(只有 v4 在用)。与 `/v3/discussions`(单个对象)必填参数不同,按规范第 1 条分成两个端点 |
 | `sign-in` + `auth/current` / `AuthController@signIn` + `@getUserInfoByToken` | `sessions` + `me` / `V3\SessionController` + `V3\MeController` | 登录一次返回 `{token, user}`,不再二次查询;`login` 字段收用户名或邮箱(邮箱不区分大小写),失败统一 422 `errors.login`;按账号 + IP 限流。`me` 的字段沿用 v2 的驼峰用户摘要(`UserService::profile()`),`roles` 恒为数组,另加 `email`,不再回显 token。token 与 v2 完全相同、两边互认 |
+| `search-title-index` / `SearchTitleController@index` | `tipitaka-chapters` / `V3\TipitakaChapterController` | 章节标题检索。v2 只回标题文字、`LIKE` 硬匹配、依赖去变音不干净的 `title_en`;v3 回坐标(book/para)、层级、`layer`(mula/atthakatha/tika/anna,取自书的 tag)、段数与字符数、上下章、路径、公开 channel 的章节译名;匹配不分大小写与变音符号、去序号与丛书缩写、拼错按编辑距离容错(档位:相等 1 / 开头 0.95 / 包含 0.9 / 拼错 ≤0.85)。不给 `q` 给 `book`(可加 `para`、`max_level`)= 按经文顺序列出整本书的标题,给 agent「先选书再选章」用。标题目录缓存一天(`TipitakaChapterService`)。**`q` 的 PHP 匹配只用来验证按名定位的效果,正式实现走 OpenSearch**(插件 `locate` 将改调 `/v3/search`,见 `api-v13/documents/search-recall.md` 4.6),这里不再扩展 |
 | `progress?view=chapter_channels` / `ProgressChapterController@index`(一个 view 分支) | `tipitaka-chapter-channels/{book}/{para}` / `V3\TipitakaChapterChannelController` | 某章有哪些 channel 及完成度(阅读页版本切换)。`par`→路径 `{para}`;**只列看得见的 channel**(公开 + 自己的 + 共享给自己或所在群组的;v2 连私有 channel 也对所有人列);字段重组:行 `uid`→`id`,`channel_id`/`name`/`type` 收进 `channel{id,name,type,lang}`;去掉 `likes`(前端没用);views/studio 整页批量查,消除 N+1;按 progress 降序 + channel_id 稳定排序,分页(per_page 最大 200)。v6、mobile、wikipali-plugins(`versions --chapter`)已切 |
 
 **注意**:`tipitaka-reading` **不是** v2 `paragraph-content` / `chapter-content` 的替代品。

+ 44 - 0
api-test/cases/11_tipitaka_chapters.php

@@ -0,0 +1,44 @@
+<?php
+
+use \WikipaliApi\Api\TipitakaChaptersApi;
+
+/*
+ * 章节标题:GET /v3/tipitaka-chapters
+ *
+ * 只读、无写操作。用长部《大般涅槃经》(book 94 para 287)——CST 三藏的坐标在各服务器上相同。
+ * 容错打分的各档、译名可见性、layer 过滤由 api-v13 的 TipitakaChapterV3Test 覆盖。
+ */
+
+test('GET /v3/tipitaka-chapters?q=(不带变音符号、拼错)→ 200,找到大般涅槃经', function () {
+    $res = request(fn () => api(TipitakaChaptersApi::class)
+        ->getApiV3TipitakaChaptersWithHttpInfo(1, 5, 'mahaparinibanasuta', null, null, 'mula'));
+    assert_status(200, $res, 'tipitaka-chapters q');
+    $top = $res['body']['data'][0] ?? null;
+    if (! $top) {
+        fail('tipitaka-chapters:拼错的经名应能找到');
+    }
+    assert_eq(94, $top['book'] ?? null, 'book');
+    assert_eq(287, $top['para'] ?? null, 'para');
+    assert_eq('mula', $top['layer'] ?? null, 'layer');
+    foreach (['title', 'translations', 'paragraphs', 'chars', 'path', 'score'] as $key) {
+        assert_has_key($key, $top, 'tipitaka-chapters 行');
+    }
+});
+
+test('GET /v3/tipitaka-chapters?book=&para= → 200,按经文顺序列出这一章下面的标题', function () {
+    $res = raw('GET', '/v3/tipitaka-chapters', ['book' => 94, 'para' => 287, 'per_page' => 1000]);
+    assert_status(200, $res, 'tipitaka-chapters book');
+    $paras = array_column($res['body']['data'] ?? [], 'para');
+    assert_eq(287, $paras[0] ?? null, '第一条是这一章自己');
+    $sorted = $paras;
+    sort($sorted);
+    assert_eq($sorted, $paras, '按段号升序');
+    if (! in_array(585, $paras, true)) {
+        fail('tipitaka-chapters:应包含小节 94:585(Tathāgatapacchimavācā)');
+    }
+});
+
+test('GET /v3/tipitaka-chapters(q 与 book 都不给)→ 422', function () {
+    $res = raw('GET', '/v3/tipitaka-chapters');
+    assert_status(422, $res, '无条件');
+});

+ 572 - 0
api-test/client/lib/Api/TipitakaChaptersApi.php

@@ -0,0 +1,572 @@
+<?php
+/**
+ * TipitakaChaptersApi
+ * PHP version 8.1
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ */
+
+/**
+ * MINT API
+ *
+ * International Academy Of Pali Tipitaka(国际巴利三藏学院)  由 `php openapi/scripts/generate.php` 依据 api-v13 的路由与控制器源码生成。 响应统一封装为 `{ok, message, data}`;`ok=false` 时 `message` 为错误信息。
+ *
+ * The version of the OpenAPI document: 2026.11.11
+ * Generated by: https://openapi-generator.tech
+ * Generator version: 7.25.0
+ */
+
+/**
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+namespace WikipaliApi\Api;
+
+use GuzzleHttp\Client;
+use GuzzleHttp\ClientInterface;
+use GuzzleHttp\Exception\ConnectException;
+use GuzzleHttp\Exception\RequestException;
+use GuzzleHttp\Psr7\MultipartStream;
+use GuzzleHttp\Psr7\Request;
+use GuzzleHttp\RequestOptions;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+use WikipaliApi\ApiException;
+use WikipaliApi\Configuration;
+use WikipaliApi\FormDataProcessor;
+use WikipaliApi\HeaderSelector;
+use WikipaliApi\ObjectSerializer;
+
+/**
+ * TipitakaChaptersApi Class Doc Comment
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ */
+class TipitakaChaptersApi
+{
+    /**
+     * @var ClientInterface
+     */
+    protected $client;
+
+    /**
+     * @var Configuration
+     */
+    protected $config;
+
+    /**
+     * @var HeaderSelector
+     */
+    protected $headerSelector;
+
+    /**
+     * @var int Host index
+     */
+    protected $hostIndex;
+
+    /** @var string[] $contentTypes **/
+    public const contentTypes = [
+        'getApiV3TipitakaChapters' => [
+            'application/json',
+        ],
+    ];
+
+    /**
+     * @param ClientInterface $client
+     * @param Configuration   $config
+     * @param HeaderSelector  $selector
+     * @param int             $hostIndex (Optional) host index to select the list of hosts if defined in the OpenAPI spec
+     */
+    public function __construct(
+        ?ClientInterface $client = null,
+        ?Configuration $config = null,
+        ?HeaderSelector $selector = null,
+        int $hostIndex = 0
+    ) {
+        $this->client = $client ?: new Client();
+        $this->config = $config ?: Configuration::getDefaultConfiguration();
+        $this->headerSelector = $selector ?: new HeaderSelector();
+        $this->hostIndex = $hostIndex;
+    }
+
+    /**
+     * Set the host index
+     *
+     * @param int $hostIndex Host index (required)
+     */
+    public function setHostIndex($hostIndex): void
+    {
+        $this->hostIndex = $hostIndex;
+    }
+
+    /**
+     * Get the host index
+     *
+     * @return int Host index
+     */
+    public function getHostIndex()
+    {
+        return $this->hostIndex;
+    }
+
+    /**
+     * @return Configuration
+     */
+    public function getConfig()
+    {
+        return $this->config;
+    }
+
+    /**
+     * Operation getApiV3TipitakaChapters
+     *
+     * 找章节
+     *
+     * @param  int|null $page 页码 (optional, default to 1)
+     * @param  int|null $per_page 每页数量,最大 1000 (optional, default to 50)
+     * @param  string|null $q 章节名:巴利名或译名,不给 book 时必填 (optional)
+     * @param  int|null $book 书号,不给 q 时必填 (optional)
+     * @param  int|null $para 只列 book 里这一章下面的标题(含它自己),要和 book 一起给 (optional)
+     * @param  string|null $layer 只要某几层,逗号分隔 (optional)
+     * @param  int|null $max_level 只要层级不深于它的标题(1 是书名) (optional)
+     * @param  string $contentType The value for the Content-Type header. Check self::contentTypes['getApiV3TipitakaChapters'] to see the possible values for this operation
+     *
+     * @throws \WikipaliApi\ApiException on non-2xx response or if the response body is not in the expected format
+     * @throws \InvalidArgumentException
+     * @return \WikipaliApi\Model\GetApiV3TipitakaChapters200Response|\WikipaliApi\Model\ProblemDetails
+     */
+    public function getApiV3TipitakaChapters($page = 1, $per_page = 50, $q = null, $book = null, $para = null, $layer = null, $max_level = null, string $contentType = self::contentTypes['getApiV3TipitakaChapters'][0])
+    {
+        list($response) = $this->getApiV3TipitakaChaptersWithHttpInfo($page, $per_page, $q, $book, $para, $layer, $max_level, $contentType);
+        return $response;
+    }
+
+    /**
+     * Operation getApiV3TipitakaChaptersWithHttpInfo
+     *
+     * 找章节
+     *
+     * @param  int|null $page 页码 (optional, default to 1)
+     * @param  int|null $per_page 每页数量,最大 1000 (optional, default to 50)
+     * @param  string|null $q 章节名:巴利名或译名,不给 book 时必填 (optional)
+     * @param  int|null $book 书号,不给 q 时必填 (optional)
+     * @param  int|null $para 只列 book 里这一章下面的标题(含它自己),要和 book 一起给 (optional)
+     * @param  string|null $layer 只要某几层,逗号分隔 (optional)
+     * @param  int|null $max_level 只要层级不深于它的标题(1 是书名) (optional)
+     * @param  string $contentType The value for the Content-Type header. Check self::contentTypes['getApiV3TipitakaChapters'] to see the possible values for this operation
+     *
+     * @throws \WikipaliApi\ApiException on non-2xx response or if the response body is not in the expected format
+     * @throws \InvalidArgumentException
+     * @return array of \WikipaliApi\Model\GetApiV3TipitakaChapters200Response|\WikipaliApi\Model\ProblemDetails, HTTP status code, HTTP response headers (array of strings)
+     */
+    public function getApiV3TipitakaChaptersWithHttpInfo($page = 1, $per_page = 50, $q = null, $book = null, $para = null, $layer = null, $max_level = null, string $contentType = self::contentTypes['getApiV3TipitakaChapters'][0])
+    {
+        $request = $this->getApiV3TipitakaChaptersRequest($page, $per_page, $q, $book, $para, $layer, $max_level, $contentType);
+
+        try {
+            $options = $this->createHttpClientOption();
+            try {
+                $response = $this->client->send($request, $options);
+            } catch (RequestException $e) {
+                throw new ApiException(
+                    "[{$e->getCode()}] {$e->getMessage()}",
+                    (int) $e->getCode(),
+                    $e->getResponse() ? $e->getResponse()->getHeaders() : null,
+                    $e->getResponse() ? (string) $e->getResponse()->getBody() : null
+                );
+            } catch (ConnectException $e) {
+                throw new ApiException(
+                    "[{$e->getCode()}] {$e->getMessage()}",
+                    (int) $e->getCode(),
+                    null,
+                    null
+                );
+            }
+
+            $statusCode = $response->getStatusCode();
+
+
+            switch($statusCode) {
+                case 200:
+                    return $this->handleResponseWithDataType(
+                        '\WikipaliApi\Model\GetApiV3TipitakaChapters200Response',
+                        $request,
+                        $response,
+                    );
+                case 422:
+                    return $this->handleResponseWithDataType(
+                        '\WikipaliApi\Model\ProblemDetails',
+                        $request,
+                        $response,
+                    );
+            }
+
+            
+
+            if ($statusCode < 200 || $statusCode > 299) {
+                throw new ApiException(
+                    sprintf(
+                        '[%d] Error connecting to the API (%s)',
+                        $statusCode,
+                        (string) $request->getUri()
+                    ),
+                    $statusCode,
+                    $response->getHeaders(),
+                    (string) $response->getBody()
+                );
+            }
+
+            return $this->handleResponseWithDataType(
+                '\WikipaliApi\Model\GetApiV3TipitakaChapters200Response',
+                $request,
+                $response,
+            );
+        } catch (ApiException $e) {
+            switch ($e->getCode()) {
+                case 200:
+                    $data = ObjectSerializer::deserialize(
+                        $e->getResponseBody(),
+                        '\WikipaliApi\Model\GetApiV3TipitakaChapters200Response',
+                        $e->getResponseHeaders()
+                    );
+                    $e->setResponseObject($data);
+                    throw $e;
+                case 422:
+                    $data = ObjectSerializer::deserialize(
+                        $e->getResponseBody(),
+                        '\WikipaliApi\Model\ProblemDetails',
+                        $e->getResponseHeaders()
+                    );
+                    $e->setResponseObject($data);
+                    throw $e;
+            }
+        
+
+            throw $e;
+        }
+    }
+
+    /**
+     * Operation getApiV3TipitakaChaptersAsync
+     *
+     * 找章节
+     *
+     * @param  int|null $page 页码 (optional, default to 1)
+     * @param  int|null $per_page 每页数量,最大 1000 (optional, default to 50)
+     * @param  string|null $q 章节名:巴利名或译名,不给 book 时必填 (optional)
+     * @param  int|null $book 书号,不给 q 时必填 (optional)
+     * @param  int|null $para 只列 book 里这一章下面的标题(含它自己),要和 book 一起给 (optional)
+     * @param  string|null $layer 只要某几层,逗号分隔 (optional)
+     * @param  int|null $max_level 只要层级不深于它的标题(1 是书名) (optional)
+     * @param  string $contentType The value for the Content-Type header. Check self::contentTypes['getApiV3TipitakaChapters'] to see the possible values for this operation
+     *
+     * @throws \InvalidArgumentException
+     * @return \GuzzleHttp\Promise\PromiseInterface
+     */
+    public function getApiV3TipitakaChaptersAsync($page = 1, $per_page = 50, $q = null, $book = null, $para = null, $layer = null, $max_level = null, string $contentType = self::contentTypes['getApiV3TipitakaChapters'][0])
+    {
+        return $this->getApiV3TipitakaChaptersAsyncWithHttpInfo($page, $per_page, $q, $book, $para, $layer, $max_level, $contentType)
+            ->then(
+                function ($response) {
+                    return $response[0];
+                }
+            );
+    }
+
+    /**
+     * Operation getApiV3TipitakaChaptersAsyncWithHttpInfo
+     *
+     * 找章节
+     *
+     * @param  int|null $page 页码 (optional, default to 1)
+     * @param  int|null $per_page 每页数量,最大 1000 (optional, default to 50)
+     * @param  string|null $q 章节名:巴利名或译名,不给 book 时必填 (optional)
+     * @param  int|null $book 书号,不给 q 时必填 (optional)
+     * @param  int|null $para 只列 book 里这一章下面的标题(含它自己),要和 book 一起给 (optional)
+     * @param  string|null $layer 只要某几层,逗号分隔 (optional)
+     * @param  int|null $max_level 只要层级不深于它的标题(1 是书名) (optional)
+     * @param  string $contentType The value for the Content-Type header. Check self::contentTypes['getApiV3TipitakaChapters'] to see the possible values for this operation
+     *
+     * @throws \InvalidArgumentException
+     * @return \GuzzleHttp\Promise\PromiseInterface
+     */
+    public function getApiV3TipitakaChaptersAsyncWithHttpInfo($page = 1, $per_page = 50, $q = null, $book = null, $para = null, $layer = null, $max_level = null, string $contentType = self::contentTypes['getApiV3TipitakaChapters'][0])
+    {
+        $returnType = '\WikipaliApi\Model\GetApiV3TipitakaChapters200Response';
+        $request = $this->getApiV3TipitakaChaptersRequest($page, $per_page, $q, $book, $para, $layer, $max_level, $contentType);
+
+        return $this->client
+            ->sendAsync($request, $this->createHttpClientOption())
+            ->then(
+                function ($response) use ($returnType) {
+                    if ($returnType === '\SplFileObject') {
+                        $content = $response->getBody(); //stream goes to serializer
+                    } else {
+                        $content = (string) $response->getBody();
+                        if ($returnType !== 'string') {
+                            $content = json_decode($content);
+                        }
+                    }
+
+                    return [
+                        ObjectSerializer::deserialize($content, $returnType, []),
+                        $response->getStatusCode(),
+                        $response->getHeaders()
+                    ];
+                },
+                function ($exception) {
+                    $response = $exception->getResponse();
+                    $statusCode = $response->getStatusCode();
+                    throw new ApiException(
+                        sprintf(
+                            '[%d] Error connecting to the API (%s)',
+                            $statusCode,
+                            $exception->getRequest()->getUri()
+                        ),
+                        $statusCode,
+                        $response->getHeaders(),
+                        (string) $response->getBody()
+                    );
+                }
+            );
+    }
+
+    /**
+     * Create request for operation 'getApiV3TipitakaChapters'
+     *
+     * @param  int|null $page 页码 (optional, default to 1)
+     * @param  int|null $per_page 每页数量,最大 1000 (optional, default to 50)
+     * @param  string|null $q 章节名:巴利名或译名,不给 book 时必填 (optional)
+     * @param  int|null $book 书号,不给 q 时必填 (optional)
+     * @param  int|null $para 只列 book 里这一章下面的标题(含它自己),要和 book 一起给 (optional)
+     * @param  string|null $layer 只要某几层,逗号分隔 (optional)
+     * @param  int|null $max_level 只要层级不深于它的标题(1 是书名) (optional)
+     * @param  string $contentType The value for the Content-Type header. Check self::contentTypes['getApiV3TipitakaChapters'] to see the possible values for this operation
+     *
+     * @throws \InvalidArgumentException
+     * @return \GuzzleHttp\Psr7\Request
+     */
+    public function getApiV3TipitakaChaptersRequest($page = 1, $per_page = 50, $q = null, $book = null, $para = null, $layer = null, $max_level = null, string $contentType = self::contentTypes['getApiV3TipitakaChapters'][0])
+    {
+
+
+
+
+
+
+
+
+
+        $resourcePath = '/v3/tipitaka-chapters';
+        $formParams = [];
+        $queryParams = [];
+        $headerParams = [];
+        $httpBody = '';
+        $multipart = false;
+
+        // query params
+        $queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
+            $page,
+            'page', // param base name
+            'integer', // openApiType
+            'form', // style
+            true, // explode
+            false // required
+        ) ?? []);
+        // query params
+        $queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
+            $per_page,
+            'per_page', // param base name
+            'integer', // openApiType
+            'form', // style
+            true, // explode
+            false // required
+        ) ?? []);
+        // query params
+        $queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
+            $q,
+            'q', // param base name
+            'string', // openApiType
+            'form', // style
+            true, // explode
+            false // required
+        ) ?? []);
+        // query params
+        $queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
+            $book,
+            'book', // param base name
+            'integer', // openApiType
+            'form', // style
+            true, // explode
+            false // required
+        ) ?? []);
+        // query params
+        $queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
+            $para,
+            'para', // param base name
+            'integer', // openApiType
+            'form', // style
+            true, // explode
+            false // required
+        ) ?? []);
+        // query params
+        $queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
+            $layer,
+            'layer', // param base name
+            'string', // openApiType
+            'form', // style
+            true, // explode
+            false // required
+        ) ?? []);
+        // query params
+        $queryParams = array_merge($queryParams, ObjectSerializer::toQueryValue(
+            $max_level,
+            'max_level', // param base name
+            'integer', // openApiType
+            'form', // style
+            true, // explode
+            false // required
+        ) ?? []);
+
+
+
+
+        $headers = $this->headerSelector->selectHeaders(
+            ['application/json', 'application/problem+json', ],
+            $contentType,
+            $multipart
+        );
+
+        // for model (json/xml)
+        if (count($formParams) > 0) {
+            if ($multipart) {
+                $multipartContents = [];
+                foreach ($formParams as $formParamName => $formParamValue) {
+                    $formParamValueItems = is_array($formParamValue) ? $formParamValue : [$formParamValue];
+                    foreach ($formParamValueItems as $formParamValueItem) {
+                        $multipartContents[] = [
+                            'name' => $formParamName,
+                            'contents' => $formParamValueItem
+                        ];
+                    }
+                }
+                // for HTTP post (form)
+                $httpBody = new MultipartStream($multipartContents);
+
+            } elseif (stripos($headers['Content-Type'], 'application/json') !== false) {
+                # if Content-Type contains "application/json", json_encode the form parameters
+                try {
+                    $httpBody = json_encode($formParams, JSON_THROW_ON_ERROR);
+                } catch (\JsonException $e) {
+                    throw new \InvalidArgumentException('json_encode error: ' . $e->getMessage(), 0, $e);
+                }
+            } else {
+                // for HTTP post (form)
+                $httpBody = ObjectSerializer::buildQuery($formParams);
+            }
+        }
+
+        // this endpoint requires Bearer authentication (access token)
+        if (!empty($this->config->getAccessToken())) {
+            $headers['Authorization'] = 'Bearer ' . $this->config->getAccessToken();
+        }
+
+        $defaultHeaders = [];
+        if ($this->config->getUserAgent()) {
+            $defaultHeaders['User-Agent'] = $this->config->getUserAgent();
+        }
+
+        $headers = array_merge(
+            $defaultHeaders,
+            $headerParams,
+            $headers
+        );
+
+        $operationHost = $this->config->getHost();
+        $query = ObjectSerializer::buildQuery($queryParams);
+        return new Request(
+            'GET',
+            $operationHost . $resourcePath . ($query ? "?{$query}" : ''),
+            $headers,
+            $httpBody
+        );
+    }
+
+    /**
+     * Create http client option
+     *
+     * @throws \RuntimeException on file opening failure
+     * @return array of http client options
+     */
+    protected function createHttpClientOption()
+    {
+        $options = [];
+        if ($this->config->getDebug()) {
+            $options[RequestOptions::DEBUG] = fopen($this->config->getDebugFile(), 'a');
+            if (!$options[RequestOptions::DEBUG]) {
+                throw new \RuntimeException('Failed to open the debug file: ' . $this->config->getDebugFile());
+            }
+        }
+
+        if ($this->config->getCertFile()) {
+            $options[RequestOptions::CERT] = $this->config->getCertFile();
+        }
+
+        if ($this->config->getKeyFile()) {
+            $options[RequestOptions::SSL_KEY] = $this->config->getKeyFile();
+        }
+
+        return $options;
+    }
+
+    private function handleResponseWithDataType(
+        string $dataType,
+        RequestInterface $request,
+        ResponseInterface $response
+    ): array {
+        if ($dataType === '\SplFileObject') {
+            $content = $response->getBody(); //stream goes to serializer
+        } else {
+            $content = (string) $response->getBody();
+            if ($dataType !== 'string') {
+                try {
+                    $content = json_decode($content, false, 512, JSON_THROW_ON_ERROR);
+                } catch (\JsonException $exception) {
+                    throw new ApiException(
+                        sprintf(
+                            'Error JSON decoding server response (%s)',
+                            $request->getUri()
+                        ),
+                        $response->getStatusCode(),
+                        $response->getHeaders(),
+                        $content
+                    );
+                }
+            }
+        }
+
+        return [
+            ObjectSerializer::deserialize($content, $dataType, []),
+            $response->getStatusCode(),
+            $response->getHeaders()
+        ];
+    }
+
+    private function responseWithinRangeCode(
+        string $rangeCode,
+        int $statusCode
+    ): bool {
+        $left = (int) ($rangeCode[0].'00');
+        $right = (int) ($rangeCode[0].'99');
+
+        return $statusCode >= $left && $statusCode <= $right;
+    }
+}

+ 443 - 0
api-test/client/lib/Model/GetApiV3TipitakaChapters200Response.php

@@ -0,0 +1,443 @@
+<?php
+/**
+ * GetApiV3TipitakaChapters200Response
+ *
+ * PHP version 8.1
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ */
+
+/**
+ * MINT API
+ *
+ * International Academy Of Pali Tipitaka(国际巴利三藏学院)  由 `php openapi/scripts/generate.php` 依据 api-v13 的路由与控制器源码生成。 响应统一封装为 `{ok, message, data}`;`ok=false` 时 `message` 为错误信息。
+ *
+ * The version of the OpenAPI document: 2026.11.11
+ * Generated by: https://openapi-generator.tech
+ * Generator version: 7.25.0
+ */
+
+/**
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+namespace WikipaliApi\Model;
+
+use \ArrayAccess;
+use \WikipaliApi\ObjectSerializer;
+
+/**
+ * GetApiV3TipitakaChapters200Response Class Doc Comment
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ * @implements \ArrayAccess<string, mixed>
+ */
+class GetApiV3TipitakaChapters200Response implements ModelInterface, ArrayAccess, \JsonSerializable
+{
+    public const DISCRIMINATOR = null;
+
+    /**
+     * The original name of the model.
+     *
+     * @var string
+     */
+    protected static $openAPIModelName = 'get_api_v3_tipitaka_chapters_200_response';
+
+    /**
+     * Array of property to type mappings. Used for (de)serialization
+     *
+     * @var string[]
+     */
+    protected static $openAPITypes = [
+        'data' => '\WikipaliApi\Model\GetApiV3TipitakaChapters200ResponseDataInner[]',
+        'meta' => '\WikipaliApi\Model\PaginationMeta'
+    ];
+
+    /**
+     * Array of property to format mappings. Used for (de)serialization
+     *
+     * @var string[]
+     * @phpstan-var array<string, string|null>
+     * @psalm-var array<string, string|null>
+     */
+    protected static $openAPIFormats = [
+        'data' => null,
+        'meta' => null
+    ];
+
+    /**
+     * Array of nullable properties. Used for (de)serialization
+     *
+     * @var boolean[]
+     */
+    protected static array $openAPINullables = [
+        'data' => false,
+        'meta' => false
+    ];
+
+    /**
+     * If a nullable field gets set to null, insert it here
+     *
+     * @var boolean[]
+     */
+    protected array $openAPINullablesSetToNull = [];
+
+    /**
+     * Array of property to type mappings. Used for (de)serialization
+     *
+     * @return array
+     */
+    public static function openAPITypes()
+    {
+        return self::$openAPITypes;
+    }
+
+    /**
+     * Array of property to format mappings. Used for (de)serialization
+     *
+     * @return array
+     */
+    public static function openAPIFormats()
+    {
+        return self::$openAPIFormats;
+    }
+
+    /**
+     * Array of nullable properties
+     *
+     * @return array
+     */
+    protected static function openAPINullables(): array
+    {
+        return self::$openAPINullables;
+    }
+
+    /**
+     * Array of nullable field names deliberately set to null
+     *
+     * @return boolean[]
+     */
+    private function getOpenAPINullablesSetToNull(): array
+    {
+        return $this->openAPINullablesSetToNull;
+    }
+
+    /**
+     * Setter - Array of nullable field names deliberately set to null
+     *
+     * @param boolean[] $openAPINullablesSetToNull
+     */
+    private function setOpenAPINullablesSetToNull(array $openAPINullablesSetToNull): void
+    {
+        $this->openAPINullablesSetToNull = $openAPINullablesSetToNull;
+    }
+
+    /**
+     * Checks if a property is nullable
+     *
+     * @param string $property
+     * @return bool
+     */
+    public static function isNullable(string $property): bool
+    {
+        return self::openAPINullables()[$property] ?? false;
+    }
+
+    /**
+     * Checks if a nullable property is set to null.
+     *
+     * @param string $property
+     * @return bool
+     */
+    public function isNullableSetToNull(string $property): bool
+    {
+        return in_array($property, $this->getOpenAPINullablesSetToNull(), true);
+    }
+
+    /**
+     * Array of attributes where the key is the local name,
+     * and the value is the original name
+     *
+     * @var string[]
+     */
+    protected static $attributeMap = [
+        'data' => 'data',
+        'meta' => 'meta'
+    ];
+
+    /**
+     * Array of attributes to setter functions (for deserialization of responses)
+     *
+     * @var string[]
+     */
+    protected static $setters = [
+        'data' => 'setData',
+        'meta' => 'setMeta'
+    ];
+
+    /**
+     * Array of attributes to getter functions (for serialization of requests)
+     *
+     * @var string[]
+     */
+    protected static $getters = [
+        'data' => 'getData',
+        'meta' => 'getMeta'
+    ];
+
+    /**
+     * Array of attributes where the key is the local name,
+     * and the value is the original name
+     *
+     * @return array
+     */
+    public static function attributeMap()
+    {
+        return self::$attributeMap;
+    }
+
+    /**
+     * Array of attributes to setter functions (for deserialization of responses)
+     *
+     * @return array
+     */
+    public static function setters()
+    {
+        return self::$setters;
+    }
+
+    /**
+     * Array of attributes to getter functions (for serialization of requests)
+     *
+     * @return array
+     */
+    public static function getters()
+    {
+        return self::$getters;
+    }
+
+    /**
+     * The original name of the model.
+     *
+     * @return string
+     */
+    public function getModelName()
+    {
+        return self::$openAPIModelName;
+    }
+
+
+    /**
+     * Associative array for storing property values
+     *
+     * @var mixed[]
+     */
+    protected $container = [];
+
+    /**
+     * Constructor
+     *
+     * @param mixed[]|null $data Associated array of property values
+     *                      initializing the model
+     */
+    public function __construct(?array $data = null)
+    {
+        $this->setIfExists('data', $data ?? [], null);
+        $this->setIfExists('meta', $data ?? [], null);
+    }
+
+    /**
+     * Sets $this->container[$variableName] to the given data or to the given default Value; if $variableName
+     * is nullable and its value is set to null in the $fields array, then mark it as "set to null" in the
+     * $this->openAPINullablesSetToNull array
+     *
+     * @param string $variableName
+     * @param array  $fields
+     * @param mixed  $defaultValue
+     */
+    private function setIfExists(string $variableName, array $fields, $defaultValue): void
+    {
+        if (self::isNullable($variableName) && array_key_exists($variableName, $fields) && is_null($fields[$variableName])) {
+            $this->openAPINullablesSetToNull[] = $variableName;
+        }
+
+        $this->container[$variableName] = $fields[$variableName] ?? $defaultValue;
+    }
+
+    /**
+     * Show all the invalid properties with reasons.
+     *
+     * @return array invalid properties with reasons
+     */
+    public function listInvalidProperties()
+    {
+        $invalidProperties = [];
+
+        return $invalidProperties;
+    }
+
+    /**
+     * Validate all the properties in the model
+     * return true if all passed
+     *
+     * @return bool True if all properties are valid
+     */
+    public function valid()
+    {
+        return count($this->listInvalidProperties()) === 0;
+    }
+
+
+    /**
+     * Gets data
+     *
+     * @return \WikipaliApi\Model\GetApiV3TipitakaChapters200ResponseDataInner[]|null
+     */
+    public function getData()
+    {
+        return $this->container['data'];
+    }
+
+    /**
+     * Sets data
+     *
+     * @param \WikipaliApi\Model\GetApiV3TipitakaChapters200ResponseDataInner[]|null $data data
+     *
+     * @return self
+     */
+    public function setData($data)
+    {
+        if (is_null($data)) {
+            throw new \InvalidArgumentException('non-nullable data cannot be null');
+        }
+        $this->container['data'] = $data;
+
+        return $this;
+    }
+
+    /**
+     * Gets meta
+     *
+     * @return \WikipaliApi\Model\PaginationMeta|null
+     */
+    public function getMeta()
+    {
+        return $this->container['meta'];
+    }
+
+    /**
+     * Sets meta
+     *
+     * @param \WikipaliApi\Model\PaginationMeta|null $meta meta
+     *
+     * @return self
+     */
+    public function setMeta($meta)
+    {
+        if (is_null($meta)) {
+            throw new \InvalidArgumentException('non-nullable meta cannot be null');
+        }
+        $this->container['meta'] = $meta;
+
+        return $this;
+    }
+    /**
+     * Returns true if offset exists. False otherwise.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return boolean
+     */
+    public function offsetExists(mixed $offset): bool
+    {
+        return isset($this->container[$offset]);
+    }
+
+    /**
+     * Gets offset.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return mixed|null
+     */
+    #[\ReturnTypeWillChange]
+    public function offsetGet(mixed $offset)
+    {
+        return $this->container[$offset] ?? null;
+    }
+
+    /**
+     * Sets value based on offset.
+     *
+     * @param int|null $offset Offset
+     * @param mixed    $value  Value to be set
+     *
+     * @return void
+     */
+    public function offsetSet($offset, $value): void
+    {
+        if (is_null($offset)) {
+            $this->container[] = $value;
+        } else {
+            $this->container[$offset] = $value;
+        }
+    }
+
+    /**
+     * Unsets offset.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return void
+     */
+    public function offsetUnset(mixed $offset): void
+    {
+        unset($this->container[$offset]);
+    }
+
+    /**
+     * Serializes the object to a value that can be serialized natively by json_encode().
+     * @link https://www.php.net/manual/en/jsonserializable.jsonserialize.php
+     *
+     * @return mixed Returns data which can be serialized by json_encode(), which is a value
+     * of any type other than a resource.
+     */
+    #[\ReturnTypeWillChange]
+    public function jsonSerialize()
+    {
+       return ObjectSerializer::sanitizeForSerialization($this);
+    }
+
+    /**
+     * Gets the string presentation of the object
+     *
+     * @return string
+     */
+    public function __toString()
+    {
+        return json_encode(
+            ObjectSerializer::sanitizeForSerialization($this),
+            JSON_PRETTY_PRINT
+        );
+    }
+
+    /**
+     * Gets a header-safe presentation of the object
+     *
+     * @return string
+     */
+    public function toHeaderValue()
+    {
+        return json_encode(ObjectSerializer::sanitizeForSerialization($this));
+    }
+}
+
+

+ 838 - 0
api-test/client/lib/Model/GetApiV3TipitakaChapters200ResponseDataInner.php

@@ -0,0 +1,838 @@
+<?php
+/**
+ * GetApiV3TipitakaChapters200ResponseDataInner
+ *
+ * PHP version 8.1
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ */
+
+/**
+ * MINT API
+ *
+ * International Academy Of Pali Tipitaka(国际巴利三藏学院)  由 `php openapi/scripts/generate.php` 依据 api-v13 的路由与控制器源码生成。 响应统一封装为 `{ok, message, data}`;`ok=false` 时 `message` 为错误信息。
+ *
+ * The version of the OpenAPI document: 2026.11.11
+ * Generated by: https://openapi-generator.tech
+ * Generator version: 7.25.0
+ */
+
+/**
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+namespace WikipaliApi\Model;
+
+use \ArrayAccess;
+use \WikipaliApi\ObjectSerializer;
+
+/**
+ * GetApiV3TipitakaChapters200ResponseDataInner Class Doc Comment
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ * @implements \ArrayAccess<string, mixed>
+ */
+class GetApiV3TipitakaChapters200ResponseDataInner implements ModelInterface, ArrayAccess, \JsonSerializable
+{
+    public const DISCRIMINATOR = null;
+
+    /**
+     * The original name of the model.
+     *
+     * @var string
+     */
+    protected static $openAPIModelName = 'get_api_v3_tipitaka_chapters_200_response_data_inner';
+
+    /**
+     * Array of property to type mappings. Used for (de)serialization
+     *
+     * @var string[]
+     */
+    protected static $openAPITypes = [
+        'book' => 'int',
+        'para' => 'int',
+        'level' => 'int',
+        'title' => 'string',
+        'translations' => '\WikipaliApi\Model\GetApiV3TipitakaChapters200ResponseDataInnerTranslationsInner[]',
+        'layer' => 'string',
+        'paragraphs' => 'int',
+        'chars' => 'int',
+        'parent' => 'int',
+        'prev' => 'int',
+        'next' => 'int',
+        'path' => '\WikipaliApi\Model\GetApiV3TipitakaChapters200ResponseDataInnerPathInner[]',
+        'score' => 'float'
+    ];
+
+    /**
+     * Array of property to format mappings. Used for (de)serialization
+     *
+     * @var string[]
+     * @phpstan-var array<string, string|null>
+     * @psalm-var array<string, string|null>
+     */
+    protected static $openAPIFormats = [
+        'book' => null,
+        'para' => null,
+        'level' => null,
+        'title' => null,
+        'translations' => null,
+        'layer' => null,
+        'paragraphs' => null,
+        'chars' => null,
+        'parent' => null,
+        'prev' => null,
+        'next' => null,
+        'path' => null,
+        'score' => null
+    ];
+
+    /**
+     * Array of nullable properties. Used for (de)serialization
+     *
+     * @var boolean[]
+     */
+    protected static array $openAPINullables = [
+        'book' => false,
+        'para' => false,
+        'level' => false,
+        'title' => false,
+        'translations' => false,
+        'layer' => false,
+        'paragraphs' => false,
+        'chars' => false,
+        'parent' => true,
+        'prev' => true,
+        'next' => true,
+        'path' => false,
+        'score' => false
+    ];
+
+    /**
+     * If a nullable field gets set to null, insert it here
+     *
+     * @var boolean[]
+     */
+    protected array $openAPINullablesSetToNull = [];
+
+    /**
+     * Array of property to type mappings. Used for (de)serialization
+     *
+     * @return array
+     */
+    public static function openAPITypes()
+    {
+        return self::$openAPITypes;
+    }
+
+    /**
+     * Array of property to format mappings. Used for (de)serialization
+     *
+     * @return array
+     */
+    public static function openAPIFormats()
+    {
+        return self::$openAPIFormats;
+    }
+
+    /**
+     * Array of nullable properties
+     *
+     * @return array
+     */
+    protected static function openAPINullables(): array
+    {
+        return self::$openAPINullables;
+    }
+
+    /**
+     * Array of nullable field names deliberately set to null
+     *
+     * @return boolean[]
+     */
+    private function getOpenAPINullablesSetToNull(): array
+    {
+        return $this->openAPINullablesSetToNull;
+    }
+
+    /**
+     * Setter - Array of nullable field names deliberately set to null
+     *
+     * @param boolean[] $openAPINullablesSetToNull
+     */
+    private function setOpenAPINullablesSetToNull(array $openAPINullablesSetToNull): void
+    {
+        $this->openAPINullablesSetToNull = $openAPINullablesSetToNull;
+    }
+
+    /**
+     * Checks if a property is nullable
+     *
+     * @param string $property
+     * @return bool
+     */
+    public static function isNullable(string $property): bool
+    {
+        return self::openAPINullables()[$property] ?? false;
+    }
+
+    /**
+     * Checks if a nullable property is set to null.
+     *
+     * @param string $property
+     * @return bool
+     */
+    public function isNullableSetToNull(string $property): bool
+    {
+        return in_array($property, $this->getOpenAPINullablesSetToNull(), true);
+    }
+
+    /**
+     * Array of attributes where the key is the local name,
+     * and the value is the original name
+     *
+     * @var string[]
+     */
+    protected static $attributeMap = [
+        'book' => 'book',
+        'para' => 'para',
+        'level' => 'level',
+        'title' => 'title',
+        'translations' => 'translations',
+        'layer' => 'layer',
+        'paragraphs' => 'paragraphs',
+        'chars' => 'chars',
+        'parent' => 'parent',
+        'prev' => 'prev',
+        'next' => 'next',
+        'path' => 'path',
+        'score' => 'score'
+    ];
+
+    /**
+     * Array of attributes to setter functions (for deserialization of responses)
+     *
+     * @var string[]
+     */
+    protected static $setters = [
+        'book' => 'setBook',
+        'para' => 'setPara',
+        'level' => 'setLevel',
+        'title' => 'setTitle',
+        'translations' => 'setTranslations',
+        'layer' => 'setLayer',
+        'paragraphs' => 'setParagraphs',
+        'chars' => 'setChars',
+        'parent' => 'setParent',
+        'prev' => 'setPrev',
+        'next' => 'setNext',
+        'path' => 'setPath',
+        'score' => 'setScore'
+    ];
+
+    /**
+     * Array of attributes to getter functions (for serialization of requests)
+     *
+     * @var string[]
+     */
+    protected static $getters = [
+        'book' => 'getBook',
+        'para' => 'getPara',
+        'level' => 'getLevel',
+        'title' => 'getTitle',
+        'translations' => 'getTranslations',
+        'layer' => 'getLayer',
+        'paragraphs' => 'getParagraphs',
+        'chars' => 'getChars',
+        'parent' => 'getParent',
+        'prev' => 'getPrev',
+        'next' => 'getNext',
+        'path' => 'getPath',
+        'score' => 'getScore'
+    ];
+
+    /**
+     * Array of attributes where the key is the local name,
+     * and the value is the original name
+     *
+     * @return array
+     */
+    public static function attributeMap()
+    {
+        return self::$attributeMap;
+    }
+
+    /**
+     * Array of attributes to setter functions (for deserialization of responses)
+     *
+     * @return array
+     */
+    public static function setters()
+    {
+        return self::$setters;
+    }
+
+    /**
+     * Array of attributes to getter functions (for serialization of requests)
+     *
+     * @return array
+     */
+    public static function getters()
+    {
+        return self::$getters;
+    }
+
+    /**
+     * The original name of the model.
+     *
+     * @return string
+     */
+    public function getModelName()
+    {
+        return self::$openAPIModelName;
+    }
+
+
+    /**
+     * Associative array for storing property values
+     *
+     * @var mixed[]
+     */
+    protected $container = [];
+
+    /**
+     * Constructor
+     *
+     * @param mixed[]|null $data Associated array of property values
+     *                      initializing the model
+     */
+    public function __construct(?array $data = null)
+    {
+        $this->setIfExists('book', $data ?? [], null);
+        $this->setIfExists('para', $data ?? [], null);
+        $this->setIfExists('level', $data ?? [], null);
+        $this->setIfExists('title', $data ?? [], null);
+        $this->setIfExists('translations', $data ?? [], null);
+        $this->setIfExists('layer', $data ?? [], null);
+        $this->setIfExists('paragraphs', $data ?? [], null);
+        $this->setIfExists('chars', $data ?? [], null);
+        $this->setIfExists('parent', $data ?? [], null);
+        $this->setIfExists('prev', $data ?? [], null);
+        $this->setIfExists('next', $data ?? [], null);
+        $this->setIfExists('path', $data ?? [], null);
+        $this->setIfExists('score', $data ?? [], null);
+    }
+
+    /**
+     * Sets $this->container[$variableName] to the given data or to the given default Value; if $variableName
+     * is nullable and its value is set to null in the $fields array, then mark it as "set to null" in the
+     * $this->openAPINullablesSetToNull array
+     *
+     * @param string $variableName
+     * @param array  $fields
+     * @param mixed  $defaultValue
+     */
+    private function setIfExists(string $variableName, array $fields, $defaultValue): void
+    {
+        if (self::isNullable($variableName) && array_key_exists($variableName, $fields) && is_null($fields[$variableName])) {
+            $this->openAPINullablesSetToNull[] = $variableName;
+        }
+
+        $this->container[$variableName] = $fields[$variableName] ?? $defaultValue;
+    }
+
+    /**
+     * Show all the invalid properties with reasons.
+     *
+     * @return array invalid properties with reasons
+     */
+    public function listInvalidProperties()
+    {
+        $invalidProperties = [];
+
+        return $invalidProperties;
+    }
+
+    /**
+     * Validate all the properties in the model
+     * return true if all passed
+     *
+     * @return bool True if all properties are valid
+     */
+    public function valid()
+    {
+        return count($this->listInvalidProperties()) === 0;
+    }
+
+
+    /**
+     * Gets book
+     *
+     * @return int|null
+     */
+    public function getBook()
+    {
+        return $this->container['book'];
+    }
+
+    /**
+     * Sets book
+     *
+     * @param int|null $book book
+     *
+     * @return self
+     */
+    public function setBook($book)
+    {
+        if (is_null($book)) {
+            throw new \InvalidArgumentException('non-nullable book cannot be null');
+        }
+        $this->container['book'] = $book;
+
+        return $this;
+    }
+
+    /**
+     * Gets para
+     *
+     * @return int|null
+     */
+    public function getPara()
+    {
+        return $this->container['para'];
+    }
+
+    /**
+     * Sets para
+     *
+     * @param int|null $para para
+     *
+     * @return self
+     */
+    public function setPara($para)
+    {
+        if (is_null($para)) {
+            throw new \InvalidArgumentException('non-nullable para cannot be null');
+        }
+        $this->container['para'] = $para;
+
+        return $this;
+    }
+
+    /**
+     * Gets level
+     *
+     * @return int|null
+     */
+    public function getLevel()
+    {
+        return $this->container['level'];
+    }
+
+    /**
+     * Sets level
+     *
+     * @param int|null $level level
+     *
+     * @return self
+     */
+    public function setLevel($level)
+    {
+        if (is_null($level)) {
+            throw new \InvalidArgumentException('non-nullable level cannot be null');
+        }
+        $this->container['level'] = $level;
+
+        return $this;
+    }
+
+    /**
+     * Gets title
+     *
+     * @return string|null
+     */
+    public function getTitle()
+    {
+        return $this->container['title'];
+    }
+
+    /**
+     * Sets title
+     *
+     * @param string|null $title title
+     *
+     * @return self
+     */
+    public function setTitle($title)
+    {
+        if (is_null($title)) {
+            throw new \InvalidArgumentException('non-nullable title cannot be null');
+        }
+        $this->container['title'] = $title;
+
+        return $this;
+    }
+
+    /**
+     * Gets translations
+     *
+     * @return \WikipaliApi\Model\GetApiV3TipitakaChapters200ResponseDataInnerTranslationsInner[]|null
+     */
+    public function getTranslations()
+    {
+        return $this->container['translations'];
+    }
+
+    /**
+     * Sets translations
+     *
+     * @param \WikipaliApi\Model\GetApiV3TipitakaChapters200ResponseDataInnerTranslationsInner[]|null $translations translations
+     *
+     * @return self
+     */
+    public function setTranslations($translations)
+    {
+        if (is_null($translations)) {
+            throw new \InvalidArgumentException('non-nullable translations cannot be null');
+        }
+        $this->container['translations'] = $translations;
+
+        return $this;
+    }
+
+    /**
+     * Gets layer
+     *
+     * @return string|null
+     */
+    public function getLayer()
+    {
+        return $this->container['layer'];
+    }
+
+    /**
+     * Sets layer
+     *
+     * @param string|null $layer layer
+     *
+     * @return self
+     */
+    public function setLayer($layer)
+    {
+        if (is_null($layer)) {
+            throw new \InvalidArgumentException('non-nullable layer cannot be null');
+        }
+        $this->container['layer'] = $layer;
+
+        return $this;
+    }
+
+    /**
+     * Gets paragraphs
+     *
+     * @return int|null
+     */
+    public function getParagraphs()
+    {
+        return $this->container['paragraphs'];
+    }
+
+    /**
+     * Sets paragraphs
+     *
+     * @param int|null $paragraphs paragraphs
+     *
+     * @return self
+     */
+    public function setParagraphs($paragraphs)
+    {
+        if (is_null($paragraphs)) {
+            throw new \InvalidArgumentException('non-nullable paragraphs cannot be null');
+        }
+        $this->container['paragraphs'] = $paragraphs;
+
+        return $this;
+    }
+
+    /**
+     * Gets chars
+     *
+     * @return int|null
+     */
+    public function getChars()
+    {
+        return $this->container['chars'];
+    }
+
+    /**
+     * Sets chars
+     *
+     * @param int|null $chars chars
+     *
+     * @return self
+     */
+    public function setChars($chars)
+    {
+        if (is_null($chars)) {
+            throw new \InvalidArgumentException('non-nullable chars cannot be null');
+        }
+        $this->container['chars'] = $chars;
+
+        return $this;
+    }
+
+    /**
+     * Gets parent
+     *
+     * @return int|null
+     */
+    public function getParent()
+    {
+        return $this->container['parent'];
+    }
+
+    /**
+     * Sets parent
+     *
+     * @param int|null $parent parent
+     *
+     * @return self
+     */
+    public function setParent($parent)
+    {
+        if (is_null($parent)) {
+            array_push($this->openAPINullablesSetToNull, 'parent');
+        } else {
+            $nullablesSetToNull = $this->getOpenAPINullablesSetToNull();
+            $index = array_search('parent', $nullablesSetToNull);
+            if ($index !== FALSE) {
+                unset($nullablesSetToNull[$index]);
+                $this->setOpenAPINullablesSetToNull($nullablesSetToNull);
+            }
+        }
+        $this->container['parent'] = $parent;
+
+        return $this;
+    }
+
+    /**
+     * Gets prev
+     *
+     * @return int|null
+     */
+    public function getPrev()
+    {
+        return $this->container['prev'];
+    }
+
+    /**
+     * Sets prev
+     *
+     * @param int|null $prev prev
+     *
+     * @return self
+     */
+    public function setPrev($prev)
+    {
+        if (is_null($prev)) {
+            array_push($this->openAPINullablesSetToNull, 'prev');
+        } else {
+            $nullablesSetToNull = $this->getOpenAPINullablesSetToNull();
+            $index = array_search('prev', $nullablesSetToNull);
+            if ($index !== FALSE) {
+                unset($nullablesSetToNull[$index]);
+                $this->setOpenAPINullablesSetToNull($nullablesSetToNull);
+            }
+        }
+        $this->container['prev'] = $prev;
+
+        return $this;
+    }
+
+    /**
+     * Gets next
+     *
+     * @return int|null
+     */
+    public function getNext()
+    {
+        return $this->container['next'];
+    }
+
+    /**
+     * Sets next
+     *
+     * @param int|null $next next
+     *
+     * @return self
+     */
+    public function setNext($next)
+    {
+        if (is_null($next)) {
+            array_push($this->openAPINullablesSetToNull, 'next');
+        } else {
+            $nullablesSetToNull = $this->getOpenAPINullablesSetToNull();
+            $index = array_search('next', $nullablesSetToNull);
+            if ($index !== FALSE) {
+                unset($nullablesSetToNull[$index]);
+                $this->setOpenAPINullablesSetToNull($nullablesSetToNull);
+            }
+        }
+        $this->container['next'] = $next;
+
+        return $this;
+    }
+
+    /**
+     * Gets path
+     *
+     * @return \WikipaliApi\Model\GetApiV3TipitakaChapters200ResponseDataInnerPathInner[]|null
+     */
+    public function getPath()
+    {
+        return $this->container['path'];
+    }
+
+    /**
+     * Sets path
+     *
+     * @param \WikipaliApi\Model\GetApiV3TipitakaChapters200ResponseDataInnerPathInner[]|null $path path
+     *
+     * @return self
+     */
+    public function setPath($path)
+    {
+        if (is_null($path)) {
+            throw new \InvalidArgumentException('non-nullable path cannot be null');
+        }
+        $this->container['path'] = $path;
+
+        return $this;
+    }
+
+    /**
+     * Gets score
+     *
+     * @return float|null
+     */
+    public function getScore()
+    {
+        return $this->container['score'];
+    }
+
+    /**
+     * Sets score
+     *
+     * @param float|null $score 仅在部分查询口径下返回。
+     *
+     * @return self
+     */
+    public function setScore($score)
+    {
+        if (is_null($score)) {
+            throw new \InvalidArgumentException('non-nullable score cannot be null');
+        }
+        $this->container['score'] = $score;
+
+        return $this;
+    }
+    /**
+     * Returns true if offset exists. False otherwise.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return boolean
+     */
+    public function offsetExists(mixed $offset): bool
+    {
+        return isset($this->container[$offset]);
+    }
+
+    /**
+     * Gets offset.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return mixed|null
+     */
+    #[\ReturnTypeWillChange]
+    public function offsetGet(mixed $offset)
+    {
+        return $this->container[$offset] ?? null;
+    }
+
+    /**
+     * Sets value based on offset.
+     *
+     * @param int|null $offset Offset
+     * @param mixed    $value  Value to be set
+     *
+     * @return void
+     */
+    public function offsetSet($offset, $value): void
+    {
+        if (is_null($offset)) {
+            $this->container[] = $value;
+        } else {
+            $this->container[$offset] = $value;
+        }
+    }
+
+    /**
+     * Unsets offset.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return void
+     */
+    public function offsetUnset(mixed $offset): void
+    {
+        unset($this->container[$offset]);
+    }
+
+    /**
+     * Serializes the object to a value that can be serialized natively by json_encode().
+     * @link https://www.php.net/manual/en/jsonserializable.jsonserialize.php
+     *
+     * @return mixed Returns data which can be serialized by json_encode(), which is a value
+     * of any type other than a resource.
+     */
+    #[\ReturnTypeWillChange]
+    public function jsonSerialize()
+    {
+       return ObjectSerializer::sanitizeForSerialization($this);
+    }
+
+    /**
+     * Gets the string presentation of the object
+     *
+     * @return string
+     */
+    public function __toString()
+    {
+        return json_encode(
+            ObjectSerializer::sanitizeForSerialization($this),
+            JSON_PRETTY_PRINT
+        );
+    }
+
+    /**
+     * Gets a header-safe presentation of the object
+     *
+     * @return string
+     */
+    public function toHeaderValue()
+    {
+        return json_encode(ObjectSerializer::sanitizeForSerialization($this));
+    }
+}
+
+

+ 511 - 0
api-test/client/lib/Model/GetApiV3TipitakaChapters200ResponseDataInnerPathInner.php

@@ -0,0 +1,511 @@
+<?php
+/**
+ * GetApiV3TipitakaChapters200ResponseDataInnerPathInner
+ *
+ * PHP version 8.1
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ */
+
+/**
+ * MINT API
+ *
+ * International Academy Of Pali Tipitaka(国际巴利三藏学院)  由 `php openapi/scripts/generate.php` 依据 api-v13 的路由与控制器源码生成。 响应统一封装为 `{ok, message, data}`;`ok=false` 时 `message` 为错误信息。
+ *
+ * The version of the OpenAPI document: 2026.11.11
+ * Generated by: https://openapi-generator.tech
+ * Generator version: 7.25.0
+ */
+
+/**
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+namespace WikipaliApi\Model;
+
+use \ArrayAccess;
+use \WikipaliApi\ObjectSerializer;
+
+/**
+ * GetApiV3TipitakaChapters200ResponseDataInnerPathInner Class Doc Comment
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ * @implements \ArrayAccess<string, mixed>
+ */
+class GetApiV3TipitakaChapters200ResponseDataInnerPathInner implements ModelInterface, ArrayAccess, \JsonSerializable
+{
+    public const DISCRIMINATOR = null;
+
+    /**
+     * The original name of the model.
+     *
+     * @var string
+     */
+    protected static $openAPIModelName = 'get_api_v3_tipitaka_chapters_200_response_data_inner_path_inner';
+
+    /**
+     * Array of property to type mappings. Used for (de)serialization
+     *
+     * @var string[]
+     */
+    protected static $openAPITypes = [
+        'book' => 'int',
+        'para' => 'int',
+        'title' => 'string',
+        'level' => 'int'
+    ];
+
+    /**
+     * Array of property to format mappings. Used for (de)serialization
+     *
+     * @var string[]
+     * @phpstan-var array<string, string|null>
+     * @psalm-var array<string, string|null>
+     */
+    protected static $openAPIFormats = [
+        'book' => null,
+        'para' => null,
+        'title' => null,
+        'level' => null
+    ];
+
+    /**
+     * Array of nullable properties. Used for (de)serialization
+     *
+     * @var boolean[]
+     */
+    protected static array $openAPINullables = [
+        'book' => false,
+        'para' => false,
+        'title' => false,
+        'level' => false
+    ];
+
+    /**
+     * If a nullable field gets set to null, insert it here
+     *
+     * @var boolean[]
+     */
+    protected array $openAPINullablesSetToNull = [];
+
+    /**
+     * Array of property to type mappings. Used for (de)serialization
+     *
+     * @return array
+     */
+    public static function openAPITypes()
+    {
+        return self::$openAPITypes;
+    }
+
+    /**
+     * Array of property to format mappings. Used for (de)serialization
+     *
+     * @return array
+     */
+    public static function openAPIFormats()
+    {
+        return self::$openAPIFormats;
+    }
+
+    /**
+     * Array of nullable properties
+     *
+     * @return array
+     */
+    protected static function openAPINullables(): array
+    {
+        return self::$openAPINullables;
+    }
+
+    /**
+     * Array of nullable field names deliberately set to null
+     *
+     * @return boolean[]
+     */
+    private function getOpenAPINullablesSetToNull(): array
+    {
+        return $this->openAPINullablesSetToNull;
+    }
+
+    /**
+     * Setter - Array of nullable field names deliberately set to null
+     *
+     * @param boolean[] $openAPINullablesSetToNull
+     */
+    private function setOpenAPINullablesSetToNull(array $openAPINullablesSetToNull): void
+    {
+        $this->openAPINullablesSetToNull = $openAPINullablesSetToNull;
+    }
+
+    /**
+     * Checks if a property is nullable
+     *
+     * @param string $property
+     * @return bool
+     */
+    public static function isNullable(string $property): bool
+    {
+        return self::openAPINullables()[$property] ?? false;
+    }
+
+    /**
+     * Checks if a nullable property is set to null.
+     *
+     * @param string $property
+     * @return bool
+     */
+    public function isNullableSetToNull(string $property): bool
+    {
+        return in_array($property, $this->getOpenAPINullablesSetToNull(), true);
+    }
+
+    /**
+     * Array of attributes where the key is the local name,
+     * and the value is the original name
+     *
+     * @var string[]
+     */
+    protected static $attributeMap = [
+        'book' => 'book',
+        'para' => 'para',
+        'title' => 'title',
+        'level' => 'level'
+    ];
+
+    /**
+     * Array of attributes to setter functions (for deserialization of responses)
+     *
+     * @var string[]
+     */
+    protected static $setters = [
+        'book' => 'setBook',
+        'para' => 'setPara',
+        'title' => 'setTitle',
+        'level' => 'setLevel'
+    ];
+
+    /**
+     * Array of attributes to getter functions (for serialization of requests)
+     *
+     * @var string[]
+     */
+    protected static $getters = [
+        'book' => 'getBook',
+        'para' => 'getPara',
+        'title' => 'getTitle',
+        'level' => 'getLevel'
+    ];
+
+    /**
+     * Array of attributes where the key is the local name,
+     * and the value is the original name
+     *
+     * @return array
+     */
+    public static function attributeMap()
+    {
+        return self::$attributeMap;
+    }
+
+    /**
+     * Array of attributes to setter functions (for deserialization of responses)
+     *
+     * @return array
+     */
+    public static function setters()
+    {
+        return self::$setters;
+    }
+
+    /**
+     * Array of attributes to getter functions (for serialization of requests)
+     *
+     * @return array
+     */
+    public static function getters()
+    {
+        return self::$getters;
+    }
+
+    /**
+     * The original name of the model.
+     *
+     * @return string
+     */
+    public function getModelName()
+    {
+        return self::$openAPIModelName;
+    }
+
+
+    /**
+     * Associative array for storing property values
+     *
+     * @var mixed[]
+     */
+    protected $container = [];
+
+    /**
+     * Constructor
+     *
+     * @param mixed[]|null $data Associated array of property values
+     *                      initializing the model
+     */
+    public function __construct(?array $data = null)
+    {
+        $this->setIfExists('book', $data ?? [], null);
+        $this->setIfExists('para', $data ?? [], null);
+        $this->setIfExists('title', $data ?? [], null);
+        $this->setIfExists('level', $data ?? [], null);
+    }
+
+    /**
+     * Sets $this->container[$variableName] to the given data or to the given default Value; if $variableName
+     * is nullable and its value is set to null in the $fields array, then mark it as "set to null" in the
+     * $this->openAPINullablesSetToNull array
+     *
+     * @param string $variableName
+     * @param array  $fields
+     * @param mixed  $defaultValue
+     */
+    private function setIfExists(string $variableName, array $fields, $defaultValue): void
+    {
+        if (self::isNullable($variableName) && array_key_exists($variableName, $fields) && is_null($fields[$variableName])) {
+            $this->openAPINullablesSetToNull[] = $variableName;
+        }
+
+        $this->container[$variableName] = $fields[$variableName] ?? $defaultValue;
+    }
+
+    /**
+     * Show all the invalid properties with reasons.
+     *
+     * @return array invalid properties with reasons
+     */
+    public function listInvalidProperties()
+    {
+        $invalidProperties = [];
+
+        return $invalidProperties;
+    }
+
+    /**
+     * Validate all the properties in the model
+     * return true if all passed
+     *
+     * @return bool True if all properties are valid
+     */
+    public function valid()
+    {
+        return count($this->listInvalidProperties()) === 0;
+    }
+
+
+    /**
+     * Gets book
+     *
+     * @return int|null
+     */
+    public function getBook()
+    {
+        return $this->container['book'];
+    }
+
+    /**
+     * Sets book
+     *
+     * @param int|null $book book
+     *
+     * @return self
+     */
+    public function setBook($book)
+    {
+        if (is_null($book)) {
+            throw new \InvalidArgumentException('non-nullable book cannot be null');
+        }
+        $this->container['book'] = $book;
+
+        return $this;
+    }
+
+    /**
+     * Gets para
+     *
+     * @return int|null
+     */
+    public function getPara()
+    {
+        return $this->container['para'];
+    }
+
+    /**
+     * Sets para
+     *
+     * @param int|null $para para
+     *
+     * @return self
+     */
+    public function setPara($para)
+    {
+        if (is_null($para)) {
+            throw new \InvalidArgumentException('non-nullable para cannot be null');
+        }
+        $this->container['para'] = $para;
+
+        return $this;
+    }
+
+    /**
+     * Gets title
+     *
+     * @return string|null
+     */
+    public function getTitle()
+    {
+        return $this->container['title'];
+    }
+
+    /**
+     * Sets title
+     *
+     * @param string|null $title title
+     *
+     * @return self
+     */
+    public function setTitle($title)
+    {
+        if (is_null($title)) {
+            throw new \InvalidArgumentException('non-nullable title cannot be null');
+        }
+        $this->container['title'] = $title;
+
+        return $this;
+    }
+
+    /**
+     * Gets level
+     *
+     * @return int|null
+     */
+    public function getLevel()
+    {
+        return $this->container['level'];
+    }
+
+    /**
+     * Sets level
+     *
+     * @param int|null $level level
+     *
+     * @return self
+     */
+    public function setLevel($level)
+    {
+        if (is_null($level)) {
+            throw new \InvalidArgumentException('non-nullable level cannot be null');
+        }
+        $this->container['level'] = $level;
+
+        return $this;
+    }
+    /**
+     * Returns true if offset exists. False otherwise.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return boolean
+     */
+    public function offsetExists(mixed $offset): bool
+    {
+        return isset($this->container[$offset]);
+    }
+
+    /**
+     * Gets offset.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return mixed|null
+     */
+    #[\ReturnTypeWillChange]
+    public function offsetGet(mixed $offset)
+    {
+        return $this->container[$offset] ?? null;
+    }
+
+    /**
+     * Sets value based on offset.
+     *
+     * @param int|null $offset Offset
+     * @param mixed    $value  Value to be set
+     *
+     * @return void
+     */
+    public function offsetSet($offset, $value): void
+    {
+        if (is_null($offset)) {
+            $this->container[] = $value;
+        } else {
+            $this->container[$offset] = $value;
+        }
+    }
+
+    /**
+     * Unsets offset.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return void
+     */
+    public function offsetUnset(mixed $offset): void
+    {
+        unset($this->container[$offset]);
+    }
+
+    /**
+     * Serializes the object to a value that can be serialized natively by json_encode().
+     * @link https://www.php.net/manual/en/jsonserializable.jsonserialize.php
+     *
+     * @return mixed Returns data which can be serialized by json_encode(), which is a value
+     * of any type other than a resource.
+     */
+    #[\ReturnTypeWillChange]
+    public function jsonSerialize()
+    {
+       return ObjectSerializer::sanitizeForSerialization($this);
+    }
+
+    /**
+     * Gets the string presentation of the object
+     *
+     * @return string
+     */
+    public function __toString()
+    {
+        return json_encode(
+            ObjectSerializer::sanitizeForSerialization($this),
+            JSON_PRETTY_PRINT
+        );
+    }
+
+    /**
+     * Gets a header-safe presentation of the object
+     *
+     * @return string
+     */
+    public function toHeaderValue()
+    {
+        return json_encode(ObjectSerializer::sanitizeForSerialization($this));
+    }
+}
+
+

+ 443 - 0
api-test/client/lib/Model/GetApiV3TipitakaChapters200ResponseDataInnerTranslationsInner.php

@@ -0,0 +1,443 @@
+<?php
+/**
+ * GetApiV3TipitakaChapters200ResponseDataInnerTranslationsInner
+ *
+ * PHP version 8.1
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ */
+
+/**
+ * MINT API
+ *
+ * International Academy Of Pali Tipitaka(国际巴利三藏学院)  由 `php openapi/scripts/generate.php` 依据 api-v13 的路由与控制器源码生成。 响应统一封装为 `{ok, message, data}`;`ok=false` 时 `message` 为错误信息。
+ *
+ * The version of the OpenAPI document: 2026.11.11
+ * Generated by: https://openapi-generator.tech
+ * Generator version: 7.25.0
+ */
+
+/**
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+namespace WikipaliApi\Model;
+
+use \ArrayAccess;
+use \WikipaliApi\ObjectSerializer;
+
+/**
+ * GetApiV3TipitakaChapters200ResponseDataInnerTranslationsInner Class Doc Comment
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ * @implements \ArrayAccess<string, mixed>
+ */
+class GetApiV3TipitakaChapters200ResponseDataInnerTranslationsInner implements ModelInterface, ArrayAccess, \JsonSerializable
+{
+    public const DISCRIMINATOR = null;
+
+    /**
+     * The original name of the model.
+     *
+     * @var string
+     */
+    protected static $openAPIModelName = 'get_api_v3_tipitaka_chapters_200_response_data_inner_translations_inner';
+
+    /**
+     * Array of property to type mappings. Used for (de)serialization
+     *
+     * @var string[]
+     */
+    protected static $openAPITypes = [
+        'lang' => 'string',
+        'title' => 'string'
+    ];
+
+    /**
+     * Array of property to format mappings. Used for (de)serialization
+     *
+     * @var string[]
+     * @phpstan-var array<string, string|null>
+     * @psalm-var array<string, string|null>
+     */
+    protected static $openAPIFormats = [
+        'lang' => null,
+        'title' => null
+    ];
+
+    /**
+     * Array of nullable properties. Used for (de)serialization
+     *
+     * @var boolean[]
+     */
+    protected static array $openAPINullables = [
+        'lang' => false,
+        'title' => false
+    ];
+
+    /**
+     * If a nullable field gets set to null, insert it here
+     *
+     * @var boolean[]
+     */
+    protected array $openAPINullablesSetToNull = [];
+
+    /**
+     * Array of property to type mappings. Used for (de)serialization
+     *
+     * @return array
+     */
+    public static function openAPITypes()
+    {
+        return self::$openAPITypes;
+    }
+
+    /**
+     * Array of property to format mappings. Used for (de)serialization
+     *
+     * @return array
+     */
+    public static function openAPIFormats()
+    {
+        return self::$openAPIFormats;
+    }
+
+    /**
+     * Array of nullable properties
+     *
+     * @return array
+     */
+    protected static function openAPINullables(): array
+    {
+        return self::$openAPINullables;
+    }
+
+    /**
+     * Array of nullable field names deliberately set to null
+     *
+     * @return boolean[]
+     */
+    private function getOpenAPINullablesSetToNull(): array
+    {
+        return $this->openAPINullablesSetToNull;
+    }
+
+    /**
+     * Setter - Array of nullable field names deliberately set to null
+     *
+     * @param boolean[] $openAPINullablesSetToNull
+     */
+    private function setOpenAPINullablesSetToNull(array $openAPINullablesSetToNull): void
+    {
+        $this->openAPINullablesSetToNull = $openAPINullablesSetToNull;
+    }
+
+    /**
+     * Checks if a property is nullable
+     *
+     * @param string $property
+     * @return bool
+     */
+    public static function isNullable(string $property): bool
+    {
+        return self::openAPINullables()[$property] ?? false;
+    }
+
+    /**
+     * Checks if a nullable property is set to null.
+     *
+     * @param string $property
+     * @return bool
+     */
+    public function isNullableSetToNull(string $property): bool
+    {
+        return in_array($property, $this->getOpenAPINullablesSetToNull(), true);
+    }
+
+    /**
+     * Array of attributes where the key is the local name,
+     * and the value is the original name
+     *
+     * @var string[]
+     */
+    protected static $attributeMap = [
+        'lang' => 'lang',
+        'title' => 'title'
+    ];
+
+    /**
+     * Array of attributes to setter functions (for deserialization of responses)
+     *
+     * @var string[]
+     */
+    protected static $setters = [
+        'lang' => 'setLang',
+        'title' => 'setTitle'
+    ];
+
+    /**
+     * Array of attributes to getter functions (for serialization of requests)
+     *
+     * @var string[]
+     */
+    protected static $getters = [
+        'lang' => 'getLang',
+        'title' => 'getTitle'
+    ];
+
+    /**
+     * Array of attributes where the key is the local name,
+     * and the value is the original name
+     *
+     * @return array
+     */
+    public static function attributeMap()
+    {
+        return self::$attributeMap;
+    }
+
+    /**
+     * Array of attributes to setter functions (for deserialization of responses)
+     *
+     * @return array
+     */
+    public static function setters()
+    {
+        return self::$setters;
+    }
+
+    /**
+     * Array of attributes to getter functions (for serialization of requests)
+     *
+     * @return array
+     */
+    public static function getters()
+    {
+        return self::$getters;
+    }
+
+    /**
+     * The original name of the model.
+     *
+     * @return string
+     */
+    public function getModelName()
+    {
+        return self::$openAPIModelName;
+    }
+
+
+    /**
+     * Associative array for storing property values
+     *
+     * @var mixed[]
+     */
+    protected $container = [];
+
+    /**
+     * Constructor
+     *
+     * @param mixed[]|null $data Associated array of property values
+     *                      initializing the model
+     */
+    public function __construct(?array $data = null)
+    {
+        $this->setIfExists('lang', $data ?? [], null);
+        $this->setIfExists('title', $data ?? [], null);
+    }
+
+    /**
+     * Sets $this->container[$variableName] to the given data or to the given default Value; if $variableName
+     * is nullable and its value is set to null in the $fields array, then mark it as "set to null" in the
+     * $this->openAPINullablesSetToNull array
+     *
+     * @param string $variableName
+     * @param array  $fields
+     * @param mixed  $defaultValue
+     */
+    private function setIfExists(string $variableName, array $fields, $defaultValue): void
+    {
+        if (self::isNullable($variableName) && array_key_exists($variableName, $fields) && is_null($fields[$variableName])) {
+            $this->openAPINullablesSetToNull[] = $variableName;
+        }
+
+        $this->container[$variableName] = $fields[$variableName] ?? $defaultValue;
+    }
+
+    /**
+     * Show all the invalid properties with reasons.
+     *
+     * @return array invalid properties with reasons
+     */
+    public function listInvalidProperties()
+    {
+        $invalidProperties = [];
+
+        return $invalidProperties;
+    }
+
+    /**
+     * Validate all the properties in the model
+     * return true if all passed
+     *
+     * @return bool True if all properties are valid
+     */
+    public function valid()
+    {
+        return count($this->listInvalidProperties()) === 0;
+    }
+
+
+    /**
+     * Gets lang
+     *
+     * @return string|null
+     */
+    public function getLang()
+    {
+        return $this->container['lang'];
+    }
+
+    /**
+     * Sets lang
+     *
+     * @param string|null $lang lang
+     *
+     * @return self
+     */
+    public function setLang($lang)
+    {
+        if (is_null($lang)) {
+            throw new \InvalidArgumentException('non-nullable lang cannot be null');
+        }
+        $this->container['lang'] = $lang;
+
+        return $this;
+    }
+
+    /**
+     * Gets title
+     *
+     * @return string|null
+     */
+    public function getTitle()
+    {
+        return $this->container['title'];
+    }
+
+    /**
+     * Sets title
+     *
+     * @param string|null $title title
+     *
+     * @return self
+     */
+    public function setTitle($title)
+    {
+        if (is_null($title)) {
+            throw new \InvalidArgumentException('non-nullable title cannot be null');
+        }
+        $this->container['title'] = $title;
+
+        return $this;
+    }
+    /**
+     * Returns true if offset exists. False otherwise.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return boolean
+     */
+    public function offsetExists(mixed $offset): bool
+    {
+        return isset($this->container[$offset]);
+    }
+
+    /**
+     * Gets offset.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return mixed|null
+     */
+    #[\ReturnTypeWillChange]
+    public function offsetGet(mixed $offset)
+    {
+        return $this->container[$offset] ?? null;
+    }
+
+    /**
+     * Sets value based on offset.
+     *
+     * @param int|null $offset Offset
+     * @param mixed    $value  Value to be set
+     *
+     * @return void
+     */
+    public function offsetSet($offset, $value): void
+    {
+        if (is_null($offset)) {
+            $this->container[] = $value;
+        } else {
+            $this->container[$offset] = $value;
+        }
+    }
+
+    /**
+     * Unsets offset.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return void
+     */
+    public function offsetUnset(mixed $offset): void
+    {
+        unset($this->container[$offset]);
+    }
+
+    /**
+     * Serializes the object to a value that can be serialized natively by json_encode().
+     * @link https://www.php.net/manual/en/jsonserializable.jsonserialize.php
+     *
+     * @return mixed Returns data which can be serialized by json_encode(), which is a value
+     * of any type other than a resource.
+     */
+    #[\ReturnTypeWillChange]
+    public function jsonSerialize()
+    {
+       return ObjectSerializer::sanitizeForSerialization($this);
+    }
+
+    /**
+     * Gets the string presentation of the object
+     *
+     * @return string
+     */
+    public function __toString()
+    {
+        return json_encode(
+            ObjectSerializer::sanitizeForSerialization($this),
+            JSON_PRETTY_PRINT
+        );
+    }
+
+    /**
+     * Gets a header-safe presentation of the object
+     *
+     * @return string
+     */
+    public function toHeaderValue()
+    {
+        return json_encode(ObjectSerializer::sanitizeForSerialization($this));
+    }
+}
+
+

+ 53 - 0
api-v13/app/Http/Controllers/V3/TipitakaChapterController.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace App\Http\Controllers\V3;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\V3\IndexTipitakaChapterRequest;
+use App\Http\Resources\V3\TipitakaChapterResource;
+use App\Services\V3\TipitakaChapterService;
+
+/**
+ * 三藏章节标题:按名字找章节,或列出一本书的全部标题。
+ *
+ * 取代 `GET /v2/search-title-index`(`SearchTitleController@index`)。v2 那份只回标题文字、
+ * 不带坐标,在 dashboard-v4 下线前原样保留,不要改动。
+ */
+class TipitakaChapterController extends Controller
+{
+    public function __construct(private readonly TipitakaChapterService $chapters) {}
+
+    /**
+     * 找章节
+     *
+     * 两种用法,可以叠加:
+     *
+     * - **按名字找**(给 `q`):巴利名不分大小写、变音符号可有可无(`mahaparinibbana`),可以只写
+     *   名字的一部分,拼错一两个字母也能找到;也能用公开译本里的章节译名(如「大般涅槃经」)。
+     *   按匹配度排序,带 `score`(相等 1、开头相同 0.95、包含 0.9,拼错的按相似度最高 0.85);同一档里根本典在前,再按与整个标题的接近度、大章在前。
+     * - **列出一本书的标题**(给 `book`,不给 `q`):按经文顺序。再给 `para` 只列那一章下面的;
+     *   `max_level` 限制层级深浅。
+     *
+     * `layer` 是这本书属于根本典(mula)、义注(atthakatha)、复注(tika)还是其他(anna);
+     * `paragraphs` / `chars` 是这一章的段数与字符数;`parent` / `prev` / `next` 是同一本书里的段号,
+     * 没有为 null;`path` 是从丛书到上一级的路径(不含本章)。
+     *
+     * @unauthenticated
+     *
+     * @queryParam q string 章节名:巴利名或译名,不给 book 时必填。Example: mahaparinibbana
+     * @queryParam book integer 书号,不给 q 时必填。Example: 94
+     * @queryParam para integer 只列 book 里这一章下面的标题(含它自己),要和 book 一起给。Example: 287
+     * @queryParam layer string 只要某几层,逗号分隔。Enum: mula, atthakatha, tika, anna
+     * @queryParam max_level integer 只要层级不深于它的标题(1 是书名)。Example: 3
+     * @queryParam page integer 页码。Default: 1
+     * @queryParam per_page integer 每页数量,最大 1000。Default: 50
+     */
+    public function __invoke(IndexTipitakaChapterRequest $request)
+    {
+        return TipitakaChapterResource::collection($this->chapters->search(
+            $request->safe()->only(['q', 'book', 'para', 'layer', 'max_level']),
+            $request->integer('page', 1),
+            $request->integer('per_page', 50),
+        ));
+    }
+}

+ 41 - 0
api-v13/app/Http/Requests/V3/IndexTipitakaChapterRequest.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace App\Http\Requests\V3;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+/**
+ * `GET /v3/tipitaka-chapters` 的入参。
+ *
+ * 全是过滤条件,但至少要给 `q` 或 `book` 之一:不加条件就是 3.7 万条标题全表,没人会翻。
+ * 两者可以同时给(在一本书里按名字找)。`para` 是 book 里的一章,只列它下面的标题,所以要和 book 一起给。
+ */
+class IndexTipitakaChapterRequest extends FormRequest
+{
+    /** layer 的取值:根本典、义注、复注、其他 */
+    public const LAYERS = ['mula', 'atthakatha', 'tika', 'anna'];
+
+    /**
+     * 公开的只读接口。
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, array<int, mixed>>
+     */
+    public function rules(): array
+    {
+        return [
+            'q' => ['required_without:book', 'string', 'min:1', 'max:200'],
+            'book' => ['required_without:q', 'required_with:para', 'integer', 'min:1'],
+            'para' => ['sometimes', 'integer', 'min:1'],
+            'layer' => ['sometimes', 'string', 'regex:/^('.implode('|', self::LAYERS).')(,('.implode('|', self::LAYERS).'))*$/'],
+            'max_level' => ['sometimes', 'integer', 'min:1', 'max:7'],
+            'page' => ['sometimes', 'integer', 'min:1'],
+            'per_page' => ['sometimes', 'integer', 'min:1', 'max:1000'],
+        ];
+    }
+}

+ 41 - 0
api-v13/app/Http/Resources/V3/TipitakaChapterResource.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace App\Http\Resources\V3;
+
+use App\Services\V3\TipitakaChapterService;
+use Illuminate\Http\Request;
+
+/**
+ * 三藏里的一个章节标题。
+ *
+ * 载荷是 {@see TipitakaChapterService::search()} 组好的数组,不查库。底层是 pali_texts 中
+ * level < 8 的一行;译名来自公开 channel 的 progress_chapters.title。
+ *
+ * 类型核对自 information_schema:pali_texts.book / paragraph / level / chapter_len /
+ * chapter_strlen / parent / prev_chapter / next_chapter 都是 integer,toc 是 text,path 是 json。
+ */
+class TipitakaChapterResource extends BaseResource
+{
+    /**
+     * @param  Request  $request
+     * @return array{
+     *     book: int,
+     *     para: int,
+     *     level: int,
+     *     title: string,
+     *     translations: array<int, array{lang: string, title: string}>,
+     *     layer: string,
+     *     paragraphs: int,
+     *     chars: int,
+     *     parent: int|null,
+     *     prev: int|null,
+     *     next: int|null,
+     *     path: array<int, array{book: int, para: int, title: string, level: int}>,
+     *     score?: float
+     * }
+     */
+    public function toArray($request): array
+    {
+        return $this->resource;
+    }
+}

+ 417 - 0
api-v13/app/Services/V3/TipitakaChapterService.php

@@ -0,0 +1,417 @@
+<?php
+
+namespace App\Services\V3;
+
+use App\Facades\RedisCache;
+use App\Models\PaliText;
+use App\Models\ProgressChapter;
+use Illuminate\Contracts\Database\Eloquent\Builder;
+use Illuminate\Pagination\LengthAwarePaginator;
+
+/**
+ * 三藏章节标题:按名字找章节(容错),或列出一本书的全部标题。
+ *
+ * 取代 v2 `SearchTitleController@index`(`GET /v2/search-title-index`)。v2 那份原样保留、不共用
+ * (CLAUDE.md 铁律 2)。与 v2 的差别:
+ *
+ * - **返回坐标**(book、para)与体量、路径、上下章;v2 只回标题文字,拿到也定位不了。
+ * - **容错匹配**:不分大小写与变音符号(`mahaparinibbana` 能找到 Mahāparinibbānasuttaṃ),
+ *   去掉序号与括号里的丛书缩写,拼错一两个字母也能命中(按编辑距离打分)。v2 是
+ *   `LIKE %key%`,还依赖 `title_en` 列——那一列去变音符号做得不干净(`3. Ānandattheragatha`)。
+ * - **译名也能搜**:公开 channel 在 `progress_chapters.title` 里写的章节译名(如「大般涅槃经」)。
+ * - 可按 book(及其中一章)列出全部标题,给 agent「先选书、再从整本书的标题里选章」用。
+ *
+ * 实现:3.7 万条标题与规范化后的匹配键缓存一天,匹配在 PHP 里做(库里没有 pg_trgm /
+ * fuzzystrmatch,又不能装扩展)。先用三字母片段粗筛,再对候选算编辑距离。
+ *
+ * **定位(2026-11-11 定)**:本端点是 v2 `search-title-index` 的替代品。`q` 的容错匹配放在 PHP 里,
+ * 只是为了先验证「按章节名定位」对 agent 的检索效果(评测见 agent-poc
+ * `agent-tuning/docs/retrieval-recall-2026-11.md` 第七节)。**按名字找章节的正式实现要走 OpenSearch**:
+ * 插件 `locate` 改调 `/v3/search`(granularity=chapter),计划见 `documents/search-recall.md` 4.6。
+ * 届时这里的 PHP 匹配只保留给 v2 替代与小规模调用,不再扩展。
+ */
+class TipitakaChapterService
+{
+    /** 只有 level < 8 的段落是标题(与 v2、IndexTipitaka 同口径) */
+    private const MAX_TITLE_LEVEL = 8;
+
+    /** 缓存键带版本号:catalog 的结构变了就改版本号,不用等过期 */
+    private const CATALOG_KEY = '/v3/tipitaka-chapters/catalog/v1';
+
+    private const CATALOG_TTL = 86400;
+
+    /** channels.status:全网公开。只有公开 channel 的章节译名才能被搜到、被返回 */
+    private const STATUS_PUBLIC = 30;
+
+    /** 书的 tag → layer。一本书有多个时按这个顺序取第一个 */
+    private const LAYER_TAGS = ['mūla' => 'mula', 'aṭṭhakathā' => 'atthakatha', 'ṭīkā' => 'tika', 'añña' => 'anna'];
+
+    /** 没有任何 layer tag 的书 */
+    private const DEFAULT_LAYER = 'anna';
+
+    private const SCORE_EXACT = 1.0;
+
+    private const SCORE_PREFIX = 0.95;
+
+    private const SCORE_CONTAINS = 0.9;
+
+    /** 编辑距离匹配的最高分(低于「包含」:拼错的永远排在拼对的后面),乘以片段相似度 */
+    private const SCORE_FUZZY_MAX = 0.85;
+
+    /**
+     * 片段相似度(1 - 距离/查询长度)低于这个就不算命中:20 个字母最多错 4 个。
+     *
+     * 0.75 太松:`etadaggapali` 会因为共有词尾 `-vaggapali` 命中 `(DN) Mahāvaggapāḷi`。
+     */
+    private const FUZZY_MIN_SIMILARITY = 0.8;
+
+    /** 粗筛:查询的三字母片段至少有这么大比例出现在标题里,才算编辑距离 */
+    private const TRIGRAM_MIN_RATIO = 0.5;
+
+    /** 变音符号 → 拉丁字母(巴利罗马转写用到的全部) */
+    private const FOLD = [
+        'ā' => 'a', 'ī' => 'i', 'ū' => 'u', 'ṅ' => 'n', 'ñ' => 'n', 'ṇ' => 'n', 'ṭ' => 't',
+        'ḍ' => 'd', 'ḷ' => 'l', 'ṃ' => 'm', 'ṁ' => 'm', 'ŋ' => 'm', 'ḥ' => 'h', 'ṛ' => 'r', 'ś' => 's', 'ṣ' => 's',
+    ];
+
+    /**
+     * 找章节。给 q 按匹配度排序(同一档里根本典在前,再按与整个标题的接近度、大章在前、经文顺序);
+     * 不给 q 按经文顺序。
+     *
+     * @param  array{q?: string, book?: int, para?: int, layer?: string, max_level?: int}  $filters
+     * @return LengthAwarePaginator<int, array<string, mixed>>
+     */
+    public function search(array $filters, int $page, int $perPage): LengthAwarePaginator
+    {
+        $rows = $this->filter($this->catalog(), $filters);
+
+        $query = isset($filters['q']) ? self::normalize($filters['q']) : null;
+        if ($query !== null) {
+            $rows = $this->rank($rows, $query);
+        }
+
+        $total = count($rows);
+        $items = $this->hydrate(array_slice($rows, ($page - 1) * $perPage, $perPage), $query !== null);
+
+        return new LengthAwarePaginator($items, $total, $perPage, $page);
+    }
+
+    /**
+     * 名字规范化成匹配键:小写、去变音符号、去括号里的丛书缩写(`(DN)`)、去序号与一切非字母。
+     *
+     * 汉字也是字母,保留;简繁不转换(同一章常有简繁两种译名)。
+     */
+    public static function normalize(string $text): string
+    {
+        $text = preg_replace('/\([^)]*\)|\[[^\]]*\]/u', '', mb_strtolower($text)) ?? '';
+
+        return preg_replace('/[^\p{L}]+/u', '', strtr($text, self::FOLD)) ?? '';
+    }
+
+    /**
+     * 一个匹配键对一个标题键打分,返回 [匹配度, 接近度];匹配度 0 = 不算命中。
+     *
+     * 匹配度只分几档,便于解释也便于排序:相等 1、开头相同 0.95、包含 0.9、拼错的按片段相似度
+     * 最高 0.85(取两位小数)。接近度是查询与整个标题有多像(0–1),只在同一档、同一层里决定先后——
+     * 比如拼错的 `anandatheragatha` 对 Ānandattheragāthā 与 Girimānandattheragāthā 片段距离相同,
+     * 靠它把前者排前。
+     *
+     * 非 ASCII 的键(汉字)只做包含匹配:`levenshtein()` 按字节算,对多字节字符没有意义。
+     *
+     * @return array{0: float, 1: float}
+     */
+    public static function score(string $query, string $title): array
+    {
+        if ($query === '' || $title === '') {
+            return [0.0, 0.0];
+        }
+        $position = strpos($title, $query);
+        if ($position !== false) {
+            $closeness = strlen($query) / strlen($title);
+            $grade = match (true) {
+                $title === $query => self::SCORE_EXACT,
+                $position === 0 => self::SCORE_PREFIX,
+                default => self::SCORE_CONTAINS,
+            };
+
+            return [$grade, $closeness];
+        }
+        if (! mb_check_encoding($query, 'ASCII') || ! mb_check_encoding($title, 'ASCII')) {
+            return [0.0, 0.0];
+        }
+
+        return self::fuzzyScore($query, $title);
+    }
+
+    /**
+     * @return array{0: float, 1: float}
+     */
+    private static function fuzzyScore(string $query, string $title): array
+    {
+        $miss = [0.0, 0.0];
+        $queryLength = strlen($query);
+        $titleLength = strlen($title);
+        if ($queryLength < 4 || $titleLength < $queryLength * 0.6) {
+            return $miss;
+        }
+
+        $trigrams = [];
+        for ($i = 0; $i <= $queryLength - 3; $i++) {
+            $trigrams[substr($query, $i, 3)] = true;
+        }
+        $shared = 0;
+        foreach (array_keys($trigrams) as $trigram) {
+            if (str_contains($title, $trigram)) {
+                $shared++;
+            }
+        }
+        if ($shared < count($trigrams) * self::TRIGRAM_MIN_RATIO) {
+            return $miss;
+        }
+
+        $best = $queryLength;
+        $lastStart = max(0, $titleLength - $queryLength + 1);
+        for ($start = 0; $start <= $lastStart; $start++) {
+            foreach ([$queryLength - 1, $queryLength, $queryLength + 1] as $width) {
+                $best = min($best, levenshtein($query, substr($title, $start, $width)));
+            }
+        }
+        $similarity = 1 - $best / $queryLength;
+        if ($similarity < self::FUZZY_MIN_SIMILARITY) {
+            return $miss;
+        }
+        $closeness = max(0.0, 1 - levenshtein($query, $title) / max($queryLength, $titleLength));
+
+        return [round(self::SCORE_FUZZY_MAX * $similarity, 2), $closeness];
+    }
+
+    /**
+     * @param  list<array<string, mixed>>  $rows
+     * @param  array{q?: string, book?: int, para?: int, layer?: string, max_level?: int}  $filters
+     * @return list<array<string, mixed>>
+     */
+    private function filter(array $rows, array $filters): array
+    {
+        $book = $filters['book'] ?? null;
+        $layers = isset($filters['layer']) ? explode(',', $filters['layer']) : null;
+        $maxLevel = $filters['max_level'] ?? null;
+
+        $range = null;
+        if ($book !== null && isset($filters['para'])) {
+            $range = $this->subtreeRange($rows, (int) $book, (int) $filters['para']);
+        }
+
+        return array_values(array_filter($rows, fn (array $row) => ($book === null || $row['book'] === (int) $book)
+            && ($range === null || ($row['para'] >= $range[0] && $row['para'] < $range[1]))
+            && ($layers === null || in_array($row['layer'], $layers, true))
+            && ($maxLevel === null || $row['level'] <= $maxLevel)));
+    }
+
+    /**
+     * 一章在书里覆盖的段落范围 [起, 止)。章不存在时返回空范围。
+     *
+     * @param  list<array<string, mixed>>  $rows
+     * @return array{0: int, 1: int}
+     */
+    private function subtreeRange(array $rows, int $book, int $para): array
+    {
+        foreach ($rows as $row) {
+            if ($row['book'] === $book && $row['para'] === $para) {
+                return [$para, $para + max(1, $row['paragraphs'])];
+            }
+        }
+
+        return [0, 0];
+    }
+
+    /**
+     * 按匹配度排序,去掉不命中的。巴利名与各个译名取最高分。
+     *
+     * @param  list<array<string, mixed>>  $rows
+     * @return list<array<string, mixed>>
+     */
+    private function rank(array $rows, string $query): array
+    {
+        $layerOrder = array_flip(array_values(self::LAYER_TAGS));
+        $hits = [];
+        foreach ($rows as $row) {
+            $best = self::score($query, $row['key']);
+            foreach ($row['translations'] as $translation) {
+                $best = max($best, self::score($query, $translation['key']));
+            }
+            if ($best[0] > 0) {
+                [$row['score'], $row['closeness']] = $best;
+                $hits[] = $row;
+            }
+        }
+        usort($hits, fn (array $a, array $b) => [$b['score'], $layerOrder[$a['layer']], $b['closeness'], $a['level'], $a['book'], $a['para']]
+            <=> [$a['score'], $layerOrder[$b['layer']], $a['closeness'], $b['level'], $b['book'], $b['para']]);
+
+        return $hits;
+    }
+
+    /**
+     * 给一页补上路径(只有这一页查库,整页一次)。
+     *
+     * @param  list<array<string, mixed>>  $rows
+     * @return list<array<string, mixed>>
+     */
+    private function hydrate(array $rows, bool $withScore): array
+    {
+        $paths = PaliText::query()
+            ->whereKey(array_column($rows, 'id'))
+            ->pluck('path', 'id');
+
+        return array_map(function (array $row) use ($paths, $withScore) {
+            $item = [
+                'book' => $row['book'],
+                'para' => $row['para'],
+                'level' => $row['level'],
+                'title' => $row['title'],
+                'translations' => array_map(fn (array $t) => ['lang' => $t['lang'], 'title' => $t['title']], $row['translations']),
+                'layer' => $row['layer'],
+                'paragraphs' => $row['paragraphs'],
+                'chars' => $row['chars'],
+                'parent' => $row['parent'],
+                'prev' => $row['prev'],
+                'next' => $row['next'],
+                'path' => self::decodePath($paths[$row['id']] ?? null),
+            ];
+            if ($withScore) {
+                $item['score'] = $row['score'];
+            }
+
+            return $item;
+        }, $rows);
+    }
+
+    /**
+     * @return list<array{book: int, para: int, title: string, level: int}>
+     */
+    private static function decodePath(?string $json): array
+    {
+        $nodes = json_decode($json ?? '[]', true);
+        if (! is_array($nodes)) {
+            return [];
+        }
+
+        return array_values(array_map(fn (array $node) => [
+            'book' => (int) ($node['book'] ?? 0),
+            'para' => (int) ($node['paragraph'] ?? 0),
+            'title' => (string) ($node['title'] ?? ''),
+            'level' => (int) ($node['level'] ?? 0),
+        ], array_filter($nodes, 'is_array')));
+    }
+
+    /**
+     * 全部标题(经文顺序),带匹配键、layer、公开译名。缓存一天。
+     *
+     * @return list<array<string, mixed>>
+     */
+    private function catalog(): array
+    {
+        return RedisCache::remember(self::CATALOG_KEY, self::CATALOG_TTL, function () {
+            $layers = $this->bookLayers();
+            $translations = $this->translations();
+
+            return PaliText::query()
+                ->where('level', '<', self::MAX_TITLE_LEVEL)
+                ->orderBy('book')
+                ->orderBy('paragraph')
+                ->get(['id', 'book', 'paragraph', 'level', 'toc', 'chapter_len', 'chapter_strlen', 'parent', 'prev_chapter', 'next_chapter'])
+                ->map(function (PaliText $row) use ($layers, $translations) {
+                    $title = trim((string) $row->toc);
+                    $key = self::normalize($title);
+                    $own = array_values(array_filter(
+                        $translations["{$row->book}-{$row->paragraph}"] ?? [],
+                        fn (array $t) => $t['key'] !== $key,
+                    ));
+
+                    return [
+                        'id' => (int) $row->id,
+                        'book' => (int) $row->book,
+                        'para' => (int) $row->paragraph,
+                        'level' => (int) $row->level,
+                        'title' => $title,
+                        'key' => $key,
+                        'translations' => $own,
+                        'layer' => $layers[(int) $row->book] ?? self::DEFAULT_LAYER,
+                        'paragraphs' => (int) $row->chapter_len,
+                        'chars' => (int) $row->chapter_strlen,
+                        'parent' => self::chapterOrNull($row->parent),
+                        'prev' => self::chapterOrNull($row->prev_chapter),
+                        'next' => self::chapterOrNull($row->next_chapter),
+                    ];
+                })
+                ->all();
+        });
+    }
+
+    /** 上下章、父章的段号;库里用 0 / -1 表示没有 */
+    private static function chapterOrNull(mixed $para): ?int
+    {
+        return $para !== null && (int) $para > 0 ? (int) $para : null;
+    }
+
+    /**
+     * 每本书属于哪一层:取书(level 1 那一段)的 tag。
+     *
+     * @return array<int, string>
+     */
+    private function bookLayers(): array
+    {
+        $layerTags = fn (Builder $q) => $q->whereIn('name', array_keys(self::LAYER_TAGS));
+        $books = PaliText::query()
+            ->where('level', 1)
+            ->whereHas('tagMaps.tags', $layerTags)
+            ->with(['tagMaps.tags' => $layerTags])
+            ->get(['uid', 'book']);
+
+        $order = array_flip(array_keys(self::LAYER_TAGS));
+        $layers = [];
+        foreach ($books as $book) {
+            foreach ($book->tagMaps as $map) {
+                $name = $map->tags?->name;
+                $current = $layers[(int) $book->book] ?? null;
+                if ($name !== null && ($current === null || $order[$name] < $order[$current])) {
+                    $layers[(int) $book->book] = $name;
+                }
+            }
+        }
+
+        return array_map(fn (string $tag) => self::LAYER_TAGS[$tag], $layers);
+    }
+
+    /**
+     * 公开 channel 写的章节译名,按「book-para」分组,同一章同一个匹配键只留一条。
+     *
+     * 排除巴利原文 channel 的标题(`lang = pali`)、逐词 channel 存进来的 JSON(以 `[` 开头)。
+     *
+     * @return array<string, list<array{lang: string, title: string, key: string}>>
+     */
+    private function translations(): array
+    {
+        $rows = ProgressChapter::query()
+            ->whereHas('channel', fn (Builder $q) => $q->where('status', self::STATUS_PUBLIC))
+            ->where('lang', '<>', 'pali')
+            ->whereRaw("trim(title) <> ''")
+            ->where('title', 'not like', '[%')
+            ->orderBy('book')
+            ->orderBy('para')
+            ->orderBy('lang')
+            ->get(['book', 'para', 'lang', 'title']);
+
+        $grouped = [];
+        foreach ($rows as $row) {
+            $title = trim((string) $row->title);
+            $key = self::normalize($title);
+            $chapter = "{$row->book}-{$row->para}";
+            if ($key === '' || isset($grouped[$chapter][$key])) {
+                continue;
+            }
+            $grouped[$chapter][$key] = ['lang' => (string) $row->lang, 'title' => $title, 'key' => $key];
+        }
+
+        return array_map('array_values', $grouped);
+    }
+}

+ 33 - 0
api-v13/documents/search-recall.md

@@ -123,6 +123,39 @@
   连音(`koṭisanthāra`、`vassaṃvutthānaṃ`)会漏。`wbw_templates` 里已有拆好的词与词根,
   可给每段写一个词根字段进索引,比维护同义词表可靠。需要重建索引。
 
+### 4.6 章节标题检索走 OpenSearch(取代 `/v3/tipitaka-chapters` 里的 PHP 匹配)
+
+2026-11-11 新建了 `GET /v3/tipitaka-chapters`(取代 v2 `search-title-index`),`q` 的容错匹配写在 PHP 里
+(`App\Services\V3\TipitakaChapterService`:去变音符号、去序号与丛书缩写、三字母粗筛 + 编辑距离,
+外加公开译本的中文章节名),**只用来先验证「按章节名定位」的效果**。验证结果见 agent-poc
+`agent-tuning/docs/retrieval-recall-2026-11.md` 第七节:插件 `locate` 一条路就让 148 道真实问题里
+能作答的从 40 题(`find` 前 3 段)到 54 题,与 `find` 互补后 74 题。
+
+正式实现要放到 OpenSearch,插件 `locate` 改调 `/v3/search`。
+
+**已有的基础**:`opensearch:index-tipitaka --granularity=chapter`(`IndexTipitaka::indexChapter`)为每个
+「章节 × channel」建一份文档(`tipitaka_chapter_{book}-{para}_{channel}`,跳过逐词 channel):标题是该 channel
+在章节起始段的第一句——巴利原文 channel 就是三藏标题,译文 channel 就是译文标题——正文是这一章到下一个标题之前
+的文本,`related_id = "{book}-{para}"`,`granularity` 是 `chapter`(level 1 为 `book`)。所以**三藏标题与各译本的
+章节标题都已在索引设计里**,不需要另建字段。差距(本地索引 `wikipali_20260813` 只建了 paragraph 与 session,
+章节文档要先补建):
+
+| 需要 | 现状 | 要做 |
+| --- | --- | --- |
+| 一章只出一条 | 每个 channel 一份文档,同一章会出几十条 | 查询用 `collapse: {field: related_id}`(keyword,可折叠),`inner_hits` 带回命中的是哪个标题 |
+| 不出现私有译本 | 索引不分 channel 公开与否,私有译本的标题、正文都会被搜到;文档里也没写 `metadata.channel`(`search()` 的 channel 过滤对章节文档无效) | 建索引时写 `metadata.channel` 与公开状态,查询按公开过滤(或只索引公开 channel) |
+| 不分变音符号 | `title.text.pali` 是 standard + lowercase,`ā` ≠ `a` | 加子字段:asciifolding + 去序号与括号缩写的 char_filter |
+| 名字的一部分(`parinibbāna` 找 Mahāparinibbānasuttaṃ) | 复合词标题是一个 token | 加 3-gram 子字段,或对折叠后的 keyword 用 wildcard |
+| 拼错一两个字母 | — | 折叠子字段用 `fuzziness: AUTO`;长复合词错得多时靠 ngram 的 `minimum_should_match` |
+| 译文标题进对的语言字段 | 只有 `zh*` 写进 `title.text.zh`,其余语言(en、my…)都写进 `title.text.pali`(代码里有 TODO) | 按 channel 语言分字段;非巴利、非中文的另设字段或不进标题检索 |
+| 坐标与体量 | 只有 `related_id` 字符串;章节文档没有 `path`、段数、字符数、layer | 写入 book / para / level / chapter_len / chapter_strlen / path / layer,`locate` 才能直接给出体量与路径 |
+| 每本书最后一章 | `indexChapter` 求最后一章的结束段时调用了 `$model->value('paragraph')`,它会新开一个不带条件的查询,返回的是全表第一行的段号(实测 book 162 得到 858,真实最后一段是 4669),于是最后一章的范围为空、**没有被索引** | 改成 `PaliText::where('book', $book)->max('paragraph')` |
+
+做法:新 `search_mode=title`(或 `granularity=chapter` 时的默认),`OpenSearchService` 里建查询;插件 `locate`
+改调 `/v3/search`,输出保持不变。**验收**:用 `agent-tuning/eval/recall/eval_navigate.py` + `eval_judge.py`
+重跑,locate 一路不低于 PHP 版(留出集 54/148、调参集 10/11)。`/v3/tipitaka-chapters` 继续作为 v2 替代与
+`toc`(按书列标题)的数据源,PHP 匹配不再扩展。
+
 ## 复现
 
 评测脚本目前放在开发机,没有进仓库:

+ 5 - 0
api-v13/routes/v3/tipitaka.php

@@ -19,6 +19,7 @@
 */
 
 use App\Http\Controllers\V3\TipitakaChapterChannelController;
+use App\Http\Controllers\V3\TipitakaChapterController;
 use App\Http\Controllers\V3\TipitakaDiscussionController;
 use App\Http\Controllers\V3\TipitakaReadingController;
 use App\Http\Controllers\V3\TipitakaRelatedParagraphAggregateController;
@@ -39,6 +40,10 @@ Route::get('tipitaka-discussions/{channel}', TipitakaDiscussionController::class
 Route::get('tipitaka-chapter-channels/{book}/{para}', TipitakaChapterChannelController::class)
     ->whereNumber(['book', 'para']);
 
+// 章节标题:按名字找章节(容错),或列出一本书的全部标题(原 v2 search-title-index)。q / book 至少给一个,都是过滤条件。
+Route::get('tipitaka-chapters', TipitakaChapterController::class)
+    ->name('tipitaka-chapters.index');
+
 // 段落关联关系:查询(原 v2 related-paragraph)+ 聚合(book_name 列表 / 某 book_name 的 cs_para)。
 Route::get('tipitaka-related-paragraphs/aggregate', [TipitakaRelatedParagraphAggregateController::class, 'index'])
     ->name('tipitaka-related-paragraphs.aggregate');

+ 180 - 0
api-v13/tests/Feature/TipitakaChapterV3Test.php

@@ -0,0 +1,180 @@
+<?php
+
+use App\Models\Channel;
+use App\Models\PaliText;
+use App\Models\ProgressChapter;
+use App\Models\Tag;
+use App\Models\TagMap;
+use App\Services\V3\TipitakaChapterService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Str;
+
+uses(RefreshDatabase::class);
+
+/*
+ * GET /v3/tipitaka-chapters:按名字找章节(容错)、列出一本书的标题。
+ *
+ * 这里断言的是形状而非契约(spectator 未安装,见 v3-resource skill 第 3 步)。
+ */
+
+function tcV3Title(int $book, int $para, int $level, string $toc, int $chapterLen = 10, ?array $path = null): PaliText
+{
+    $row = new PaliText;
+    $row->forceFill([
+        'book' => $book,
+        'paragraph' => $para,
+        'level' => $level,
+        'class' => '',
+        'toc' => $toc,
+        'text' => $toc,
+        'html' => '',
+        'pcd_book_id' => 0,
+        'chapter_len' => $chapterLen,
+        'chapter_strlen' => $chapterLen * 100,
+        'parent' => $level > 1 ? 3 : -1,
+        'prev_chapter' => 0,
+        'next_chapter' => -1,
+        'path' => json_encode($path ?? [['book' => $book, 'paragraph' => 3, 'title' => 'book', 'level' => '1']]),
+        'uid' => (string) Str::uuid(),
+    ])->save();
+
+    return $row;
+}
+
+function tcV3Tag(PaliText $book, string $name): void
+{
+    $tag = Tag::where('name', $name)->first();
+    if (! $tag) {
+        $tag = new Tag;
+        $tag->forceFill(['id' => (string) Str::uuid(), 'name' => $name, 'color' => 0, 'owner_id' => (string) Str::uuid()])->save();
+    }
+    (new TagMap)->forceFill([
+        'id' => (string) Str::uuid(), 'table_name' => 'pali_texts', 'anchor_id' => $book->uid, 'tag_id' => $tag->id,
+    ])->save();
+}
+
+function tcV3Translation(int $book, int $para, string $title, int $status = 30, string $lang = 'zh'): void
+{
+    $channel = makeChannel((string) Str::uuid());
+    Channel::where('uid', $channel)->update(['status' => $status]);
+    (new ProgressChapter)->forceFill([
+        'id' => random_int(1, PHP_INT_MAX),
+        'uid' => (string) Str::uuid(),
+        'book' => $book,
+        'para' => $para,
+        'lang' => $lang,
+        'channel_id' => $channel,
+        'progress' => 0.5,
+        'title' => $title."\n",
+        'all_trans' => 0,
+        'public' => 0,
+    ])->save();
+}
+
+/**
+ * 根本典 book 94(长部大品)与它的义注 book 104,各一部经;另有一部 anna 书里同名的短章。
+ */
+function tcV3Fixture(): void
+{
+    tcV3Tag(tcV3Title(94, 3, 1, '(DN) Mahāvaggapāḷi', 1000), 'mūla');
+    tcV3Title(94, 287, 2, '3. Mahāparinibbānasuttaṃ', 376);
+    tcV3Title(94, 585, 4, 'Tathāgatapacchimavācā', 4);
+    tcV3Title(94, 663, 2, '4. Mahāsudassanasuttaṃ', 74);
+    tcV3Tag(tcV3Title(104, 3, 1, '(DN) Mahāvaggaṭṭhakathā', 1000), 'aṭṭhakathā');
+    tcV3Title(104, 420, 2, '3. Mahāparinibbānasuttavaṇṇanā', 300);
+    tcV3Title(162, 3809, 4, '3. Ānandattheragāthā', 112);
+    tcV3Title(162, 1539, 4, '3. Girimānandattheragāthā', 12);
+    tcV3Translation(94, 287, '大般涅槃经');
+    tcV3Translation(94, 663, '私密译名', 10);
+}
+
+it('lists a book in canonical order with coordinates and size', function () {
+    tcV3Fixture();
+
+    $response = $this->getJson('/api/v3/tipitaka-chapters?book=94')->assertOk();
+
+    expect(array_column($response->json('data'), 'para'))->toBe([3, 287, 585, 663]);
+    $sutta = $response->json('data.1');
+    expect($sutta)->toMatchArray([
+        'book' => 94, 'para' => 287, 'level' => 2, 'title' => '3. Mahāparinibbānasuttaṃ',
+        'layer' => 'mula', 'paragraphs' => 376, 'chars' => 37600, 'parent' => 3, 'prev' => null, 'next' => null,
+    ])->and($sutta['translations'])->toBe([['lang' => 'zh', 'title' => '大般涅槃经']])
+        ->and($sutta['path'][0])->toBe(['book' => 94, 'para' => 3, 'title' => 'book', 'level' => 1])
+        ->and($sutta)->not->toHaveKey('score');
+    expect($response->json('meta.total'))->toBe(4);
+});
+
+it('narrows a book listing to one chapter and by level', function () {
+    tcV3Fixture();
+
+    $this->getJson('/api/v3/tipitaka-chapters?book=94&para=287')
+        ->assertOk()
+        ->assertJsonPath('data.*.para', [287, 585]);
+
+    $this->getJson('/api/v3/tipitaka-chapters?book=94&max_level=2')
+        ->assertOk()
+        ->assertJsonPath('data.*.para', [3, 287, 663]);
+});
+
+it('finds a title regardless of case and diacritics, canonical text first', function () {
+    tcV3Fixture();
+
+    $data = $this->getJson('/api/v3/tipitaka-chapters?q=MAHAPARINIBBANA')->assertOk()->json('data');
+
+    expect(array_map(fn ($r) => [$r['book'], $r['para'], $r['score']], $data))
+        ->toBe([[94, 287, 0.95], [104, 420, 0.95]]);
+});
+
+it('tolerates misspellings and ranks the closer title first', function () {
+    tcV3Fixture();
+
+    $typo = $this->getJson('/api/v3/tipitaka-chapters?q=mahaparinibanasuta')->assertOk()->json('data');
+    expect($typo[0]['para'])->toBe(287)
+        ->and($typo[0]['score'])->toBeLessThan(0.86)->toBeGreaterThan(0.6);
+
+    $ananda = $this->getJson('/api/v3/tipitaka-chapters?q=anandatheragatha')->assertOk()->json('data');
+    expect($ananda[0]['para'])->toBe(3809);
+});
+
+it('finds a chapter by its public translated title only', function () {
+    tcV3Fixture();
+
+    $this->getJson('/api/v3/tipitaka-chapters?q='.urlencode('大般涅槃'))
+        ->assertOk()
+        ->assertJsonPath('data.*.para', [287]);
+
+    $this->getJson('/api/v3/tipitaka-chapters?q='.urlencode('私密译名'))
+        ->assertOk()
+        ->assertJsonCount(0, 'data');
+    $this->getJson('/api/v3/tipitaka-chapters?book=94&para=663')
+        ->assertOk()
+        ->assertJsonPath('data.0.translations', []);
+});
+
+it('filters by layer', function () {
+    tcV3Fixture();
+
+    $this->getJson('/api/v3/tipitaka-chapters?q=mahaparinibbana&layer=atthakatha')
+        ->assertOk()
+        ->assertJsonPath('data.*.book', [104]);
+});
+
+it('rejects a query without q or book, para without book, and unknown layers', function (string $query, string $field) {
+    $this->getJson('/api/v3/tipitaka-chapters'.$query)
+        ->assertUnprocessable()
+        ->assertJsonValidationErrors($field);
+})->with([
+    'no condition' => ['', 'q'],
+    'para without book' => ['?q=x&para=287', 'book'],
+    'unknown layer' => ['?book=94&layer=sutta', 'layer'],
+    'per_page too large' => ['?book=94&per_page=5000', 'per_page'],
+]);
+
+it('scores tiers so that misspellings never outrank correct spellings', function () {
+    expect(TipitakaChapterService::score('mahaparinibbana', 'mahaparinibbana')[0])->toBe(1.0)
+        ->and(TipitakaChapterService::score('mahaparinibbana', 'mahaparinibbanasuttam')[0])->toBe(0.95)
+        ->and(TipitakaChapterService::score('parinibbana', 'mahaparinibbanasuttam')[0])->toBe(0.9)
+        ->and(TipitakaChapterService::score('mahaparinibanasuta', 'mahaparinibbanasuttam')[0])->toBeLessThanOrEqual(0.85)
+        ->and(TipitakaChapterService::score('vessantara', 'mahaparinibbanasuttam')[0])->toBe(0.0)
+        ->and(TipitakaChapterService::normalize('(DN) 3. Mahāparinibbānasuttaṃ'))->toBe('mahaparinibbanasuttam');
+});

+ 107 - 1
dashboard-v6/src/api/schema.d.ts

@@ -5120,7 +5120,9 @@ export interface paths {
         };
         /**
          * 列出 search-title-index
-         * @description 实现:`SearchTitleController@index`
+         * @deprecated
+         * @description 已被 `GET /v3/tipitaka-chapters` 取代(带坐标、容错匹配、可按书列出全部标题),
+         *     保留仅为 dashboard-v4 兼容,待 v4 下线后删除。
          */
         get: operations["get_api_v2_search_title_index"];
         put?: never;
@@ -8309,6 +8311,36 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v3/tipitaka-chapters": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * 找章节
+         * @description 两种用法,可以叠加:
+         *     - **按名字找**(给 `q`):巴利名不分大小写、变音符号可有可无(`mahaparinibbana`),可以只写
+         *     名字的一部分,拼错一两个字母也能找到;也能用公开译本里的章节译名(如「大般涅槃经」)。
+         *     按匹配度排序,带 `score`(相等 1、开头相同 0.95、包含 0.9,拼错的按相似度最高 0.85);同一档里根本典在前,再按与整个标题的接近度、大章在前。
+         *     - **列出一本书的标题**(给 `book`,不给 `q`):按经文顺序。再给 `para` 只列那一章下面的;
+         *     `max_level` 限制层级深浅。
+         *     `layer` 是这本书属于根本典(mula)、义注(atthakatha)、复注(tika)还是其他(anna);
+         *     `paragraphs` / `chars` 是这一章的段数与字符数;`parent` / `prev` / `next` 是同一本书里的段号,
+         *     没有为 null;`path` 是从丛书到上一级的路径(不含本章)。
+         *
+         *     实现:`V3\TipitakaChapterController@__invoke`
+         */
+        get: operations["get_api_v3_tipitaka_chapters"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v3/tipitaka-discussions/{channel}": {
         parameters: {
             query?: never;
@@ -36516,6 +36548,80 @@ export interface operations {
             422: components["responses"]["ProblemValidation"];
         };
     };
+    get_api_v3_tipitaka_chapters: {
+        parameters: {
+            query?: {
+                /** @description 页码 */
+                page?: number;
+                /** @description 每页数量,最大 1000 */
+                per_page?: number;
+                /**
+                 * @description 章节名:巴利名或译名,不给 book 时必填
+                 * @example mahaparinibbana
+                 */
+                q?: string;
+                /**
+                 * @description 书号,不给 q 时必填
+                 * @example 94
+                 */
+                book?: number;
+                /**
+                 * @description 只列 book 里这一章下面的标题(含它自己),要和 book 一起给
+                 * @example 287
+                 */
+                para?: number;
+                /** @description 只要某几层,逗号分隔 */
+                layer?: "mula" | "atthakatha" | "tika" | "anna";
+                /**
+                 * @description 只要层级不深于它的标题(1 是书名)
+                 * @example 3
+                 */
+                max_level?: number;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description 成功 */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            book?: number;
+                            para?: number;
+                            level?: number;
+                            title?: string;
+                            translations?: {
+                                lang?: string;
+                                title?: string;
+                            }[];
+                            layer?: string;
+                            paragraphs?: number;
+                            chars?: number;
+                            parent?: number | null;
+                            prev?: number | null;
+                            next?: number | null;
+                            path?: {
+                                book?: number;
+                                para?: number;
+                                title?: string;
+                                level?: number;
+                            }[];
+                            /** @description 仅在部分查询口径下返回。 */
+                            score?: number;
+                        }[];
+                        meta?: components["schemas"]["PaginationMeta"];
+                    };
+                };
+            };
+            422: components["responses"]["ProblemValidation"];
+        };
+    };
     get_api_v3_tipitaka_discussions_channel_: {
         parameters: {
             query?: {

+ 2 - 0
openapi/public/assets/protocol/main.yaml

@@ -727,6 +727,8 @@ paths:
     $ref: ./resources/auto/v3-sessions.yaml
   '/v3/tipitaka-chapter-channels/{book}/{para}':
     $ref: ./resources/auto/v3-tipitaka-chapter-channels-book-para.yaml
+  /v3/tipitaka-chapters:
+    $ref: ./resources/auto/v3-tipitaka-chapters.yaml
   '/v3/tipitaka-discussions/{channel}':
     $ref: ./resources/auto/v3-tipitaka-discussions-channel.yaml
   '/v3/tipitaka-reading/{channel}':

+ 5 - 0
openapi/public/assets/protocol/overrides/v2-search-title-index.yaml

@@ -0,0 +1,5 @@
+get:
+  deprecated: true
+  description: |
+    已被 `GET /v3/tipitaka-chapters` 取代(带坐标、容错匹配、可按书列出全部标题),
+    保留仅为 dashboard-v4 兼容,待 v4 下线后删除。

+ 4 - 1
openapi/public/assets/protocol/resources/auto/v2-search-title-index.yaml

@@ -4,7 +4,9 @@ get:
   tags:
     - search-title-index
   operationId: get_api_v2_search_title_index
-  description: 实现:`SearchTitleController@index`
+  description: |
+    已被 `GET /v3/tipitaka-chapters` 取代(带坐标、容错匹配、可按书列出全部标题),
+    保留仅为 dashboard-v4 兼容,待 v4 下线后删除。
   parameters:
     -
       name: key
@@ -68,6 +70,7 @@ get:
       $ref: '../../main.yaml#/components/responses/Unauthorized'
     422:
       $ref: '../../main.yaml#/components/responses/ValidationError'
+  deprecated: true
 post:
   summary: '新建 search-title-index'
   tags:

+ 125 - 0
openapi/public/assets/protocol/resources/auto/v3-tipitaka-chapters.yaml

@@ -0,0 +1,125 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-tipitaka-chapters.yaml
+get:
+  summary: 找章节
+  tags:
+    - tipitaka-chapters
+  operationId: get_api_v3_tipitaka_chapters
+  description: |-
+    两种用法,可以叠加:
+    - **按名字找**(给 `q`):巴利名不分大小写、变音符号可有可无(`mahaparinibbana`),可以只写
+    名字的一部分,拼错一两个字母也能找到;也能用公开译本里的章节译名(如「大般涅槃经」)。
+    按匹配度排序,带 `score`(相等 1、开头相同 0.95、包含 0.9,拼错的按相似度最高 0.85);同一档里根本典在前,再按与整个标题的接近度、大章在前。
+    - **列出一本书的标题**(给 `book`,不给 `q`):按经文顺序。再给 `para` 只列那一章下面的;
+    `max_level` 限制层级深浅。
+    `layer` 是这本书属于根本典(mula)、义注(atthakatha)、复注(tika)还是其他(anna);
+    `paragraphs` / `chars` 是这一章的段数与字符数;`parent` / `prev` / `next` 是同一本书里的段号,
+    没有为 null;`path` 是从丛书到上一级的路径(不含本章)。
+
+    实现:`V3\TipitakaChapterController@__invoke`
+  security:
+    - {  }
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: page
+      in: query
+      schema:
+        type: integer
+        default: 1
+      description: 页码
+    -
+      name: per_page
+      in: query
+      schema:
+        type: integer
+        default: 50
+      description: '每页数量,最大 1000'
+    -
+      name: q
+      in: query
+      schema:
+        type: string
+      description: '章节名:巴利名或译名,不给 book 时必填'
+      example: mahaparinibbana
+    -
+      name: book
+      in: query
+      schema:
+        type: integer
+      description: '书号,不给 q 时必填'
+      example: 94
+    -
+      name: para
+      in: query
+      schema:
+        type: integer
+      description: '只列 book 里这一章下面的标题(含它自己),要和 book 一起给'
+      example: 287
+    -
+      name: layer
+      in: query
+      schema:
+        type: string
+        enum:
+          - mula
+          - atthakatha
+          - tika
+          - anna
+      description: 只要某几层,逗号分隔
+    -
+      name: max_level
+      in: query
+      schema:
+        type: integer
+      description: '只要层级不深于它的标题(1 是书名)'
+      example: 3
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    book:
+                      type: integer
+                    para:
+                      type: integer
+                    level:
+                      type: integer
+                    title:
+                      type: string
+                    translations:
+                      type: array
+                      items: { type: object, properties: { lang: { type: string }, title: { type: string } } }
+                    layer:
+                      type: string
+                    paragraphs:
+                      type: integer
+                    chars:
+                      type: integer
+                    parent:
+                      type: integer
+                      nullable: true
+                    prev:
+                      type: integer
+                      nullable: true
+                    next:
+                      type: integer
+                      nullable: true
+                    path:
+                      type: array
+                      items: { type: object, properties: { book: { type: integer }, para: { type: integer }, title: { type: string }, level: { type: integer } } }
+                    score:
+                      type: number
+                      description: 仅在部分查询口径下返回。
+              meta:
+                $ref: '../../main.yaml#/components/schemas/PaginationMeta'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'