♻️ refactor(tsl-api): tighten docs and retire stale tests

2026-08-21 10:11:48 +08:00
parent 2e8c46e152
commit 5484fc7519
24 changed files with 505 additions and 2700 deletions
@@ -0,0 +1,167 @@
+# 分类属性代码（行业与基金分类）
+
+天软把「个券归属会随时间变更」的分类维护成**分类属性**，用一套属性代码
+（如 `SWHY210000`）标识。分类目录本身和个券归属分别放在不同的字典表里，
+取数入口也不同。本页收拢这类分类的代码体系与取数路径。
+
+本页是手写整理页，不由字典生成器产出；`references/data_dictionary/` 下的页面
+是生成产物，不要把这里的内容写回那些页面。
+
+## 目前维护的分类属性
+
+| 资产 | 所属属性代码 | 分类名称           | 级数 | 备注                        |
+| ---- | ------------ | ------------------ | ---- | --------------------------- |
+| 股票 | `SWHY`       | 申万行业           | 三级 |                             |
+| 股票 | `CAPCHY`     | 中上协行业         | 二级 | 2024-02-19 起接替证监会行业 |
+| 股票 | `CSRCHY`     | 证监会行业         | 二级 | **2024-02-19 起不再维护**   |
+| 基金 | `YHFL`       | 银河基金分类       | 二级 | 数据起始 2021-01-04         |
+| 基金 | `TSJJ02`     | 投资风格           | 二级 |                             |
+| 基金 | `TSJJ03`     | 净值增长率计算方法 | 二级 |                             |
+
+属性代码的构成是「所属属性代码 + 层级编号」，例如 `SWHY` → `SWHY210000`（申万采掘，
+一级）→ 其下二级、三级继续细分；`CSRCHY` → `CSRCHYA`（农、林、牧、渔业）→
+`CSRCHYA01`（农业）。
+
+## 两类表：分类目录 vs 个券归属
+
+分类目录（有哪些分类、上下级关系、启用与剔除日期）和个券归属（某只券在某段时间属于
+哪个分类）是两张不同的表，访问代码不同：
+
+| 表 ID | 表名                  | 访问代码                              | 用途               |
+| ----- | --------------------- | ------------------------------------- | ------------------ |
+| 138   | 股票.股票行业分类信息 | **属性代码**，如 `SWHY`、`SWHY110000` | 股票分类目录       |
+| 355   | 基金.基金分类信息     | **属性代码**，如 `YHFL`、`YHFL010000` | 基金分类目录       |
+| 356   | 基金.基金分类         | **基金代码**，如 `OF000316`           | 单只基金的分类归属 |
+
+138 与 355 的字段结构一致：`属性代码`、`属性名称`、`级数`、`上级属性代码`、
+`上级属性名称`、`入选日期`、`剔除日期`、`最新标识`、`所属属性代码`。
+
+传错访问代码是这里最常见的错误：把基金代码传给 355、或把属性代码传给 356，都不会报错，
+只会返回空表。字段清单与取数示例见字典页，用
+`dictionary_lookup.py --query 股票行业分类信息` / `--query 基金分类信息` 取回。
+
+## 取分类目录
+
+按属性代码取某个分类节点及其记录：
+
+```tsl
+// 申万行业分类目录（全部层级）
+return select * from infotable 138 of "SWHY" end;
+```
+
+`getbk(板块名)` 可以一次取回某个分类下的全部属性代码，再喂给 `infotable`：
+
+```tsl
+// 申万行业的全部分类属性代码，按级数分组展示
+codes := getbk("申万行业");
+t := select * from infotable 138 of codes end;
+return select ['级数'], select * from thisgroup end as '分类列表'
+       from t group by ['级数'] order by ['级数'] end;
+```
+
+`getbk("属性代码")` 是跨资产的总入口，同时覆盖股票与基金两侧：
+
+```tsl
+codes := getbk("属性代码");
+t1 := select "股票" as '资产', * from infotable 138 of codes end;
+t2 := select "基金" as '资产', * from infotable 355 of codes end;
+return t1 union t2;
+```
+
+`getbk` 取的是**最新**成分，且入参是板块名称而非代码；签名与板块名约束见
+`lookup.py --name getbk`。
+
+## 沿层级向下走
+
+分类属性代码后缀 `.N` 表示「该属性下的所有下级分类属性代码」：
+
+```tsl
+// 指定日所有申万一级行业代码
+return getbkbydate("SWHY.N", 20210423T);
+
+// 指定一级行业下的二级行业代码
+return getbkbydate("SWHY210000" $ ".N", 20210423T);
+```
+
+三级同理，用二级代码加 `.N`。也有直接返回下级列表的函数，签名用
+`lookup.py --name stockIndustryLowerArr` / `--name fundYHIndustryArr` 取回。
+
+## 取分类成分
+
+不带 `.N` 时，`getBkByDate` 把属性代码当分类节点，返回该分类在指定日的成分券：
+
+```tsl
+return getbkbydate("SWHY740000", 20220101T);   // 申万煤炭成分股
+return getbkbydate("CAPCHYD", 20240219T);      // 中上协：电力、热力、燃气及水
+return getbkbydate("YHFL030000", 20220101T);   // 银河债券型成分基金
+return getbkbydate("TSJJ0201", 20220101T);     // 投资风格：股票型
+```
+
+`getBkByDate` 的字典条目只描述了指数代码入参，分类属性代码入参同样成立；两种入参
+共用一个函数。签名与 `extype` 参数见 `lookup.py --name getBkByDate`。
+
+## 行业分类代码 ≠ 行业指数代码
+
+同一个申万行业有两套代码，用途不同，混用会取到空结果：
+
+| 用途                 | 代码形态                 | 示例                          |
+| -------------------- | ------------------------ | ----------------------------- |
+| 行业**分类**属性代码 | `SWHY` + 层级编号        | `SWHY210000` 申万采掘         |
+| 行业**指数**代码     | `SWHY00000N`（N 为级数） | `SWHY000001` 申万一级行业指数 |
+
+取行业指数代码序列走指数侧：
+
+```tsl
+// 指定日所有申万一级行业指数代码
+return getbkbydate("SWHY000001", 20190201T);
+
+// 最新的行业指数序列也可按板块名取
+return getbk("申万一级行业指数");
+```
+
+二级、三级分别对应 `SWHY000002` / `SWHY000003`，板块名分别是
+`申万二级行业指数` / `申万三级行业指数`。代码转名称用
+`lookup.py --name stockName`。
+
+## 反查：个券在指定日属于哪个分类
+
+申万各级有成对的名称/编码查询函数，与系统参数「证券」「日期」相关：
+
+```tsl
+setSysParam(pn_stock(), "SZ000002");
+setSysParam(pn_date(), 20200101T);
+return array("一级名称": stockSWIndustryName1(),
+             "一级编码": stockSWIndustryID1(),
+             "二级名称": stockSWIndustryName2(),
+             "二级编码": stockSWIndustryID2(),
+             "三级名称": stockSWIndustryName3(),
+             "三级编码": stockSWIndustryID3());
+```
+
+批量反查配合 `spec(...)` 逐券切换系统参数：
+
+```tsl
+endt := 20240103T;
+stocks := getbkbydate("SH000016", endt);
+setSysParam(pn_date(), endt);
+return select thisRow as "sid",
+              spec(stockSWIndustryName1(), thisRow) as "一级行业名称",
+              spec(stockSWIndustryID1(), thisRow) as "一级行业编码"
+       from stocks end;
+```
+
+这六个函数无参数，签名逐个用 `lookup.py --name stockSWIndustryName1` 等确认。
+按板块分类批量反查另有 `stocksbklist`，其 `bktype` 是整数板块类别，取值不在本页
+事实范围内，用前先确认。
+
+## 其它取数代码
+
+少量非个券维度的数据也用代码位取：`HG000001` 宏观数据表格，`HG000001`～`HG000004`
+分别对应港股通（沪）、沪股通、港股通（深）、深股通方向。其余特别数据（如国债收益率
+曲线）按字典页或专题文档确认，不在本页枚举。
+
+## 事实边界
+
+本页只给代码体系与取数路径。函数签名、参数类型、返回形态一律以
+`lookup.py --name` 的条目正文为准，本页示例不作为签名依据。具体分类下有哪些属性代码
+会随上游调整，不在本页硬编码；用上面的 `getbk` + `infotable` 组合在运行时取回当前列表。
@@ -0,0 +1,194 @@
+# 证券代码序列取数
+
+「先拿到一批证券代码，再逐个取指标」是天软里最常见的起手动作。代码序列有三条互不
+等价的取数路径，选错路径会静默拿到错误的样本集：
+
+| 路径              | 函数           | 时点语义           | 入参                       |
+| ----------------- | -------------- | ------------------ | -------------------------- |
+| 板块最新成分      | `getbk`        | **最新**，不带日期 | 板块中文名                 |
+| 板块历史成分      | `getAbkbyDate` | 指定日             | 板块中文名（仅限部分板块） |
+| 指数/分类历史成分 | `getBkByDate`  | 指定日             | 指数代码或分类属性代码     |
+
+`getbk` 没有日期入参，拿到的永远是当前成分；做历史回测时用它会引入前视偏差。
+签名与各自的适用范围用 `lookup.py --name getbk` / `--name getAbkbyDate` /
+`--name getBkByDate` 取回。
+
+本页是手写整理页，不由字典生成器产出。
+
+## 板块名是复合的
+
+多个板块名用英文分号拼接，一次传入：
+
+```tsl
+return getbk("深证A股;上证A股");        // 只要主板
+return getbk("A股;暂停上市;终止上市");  // 含退市与暂停上市
+return getbk("港股;终止上市港股");      // 全部港股
+return getbk("上市指数;退市指数");      // 全部指数
+return getbk("上证基金;深证基金");      // 在市基金交易代码
+```
+
+`A股` 本身就是复合板块，等于 `深证A股;上证A股;创业板;科创板;北证A股`。需要单独一个
+板块时直接写该板块名，不要在 `A股` 结果上二次过滤。
+
+板块划分会随上游调整：港股在 2026-06-25 之前全部在「港股」板块内，之后拆出
+「终止上市港股」。依赖板块名的代码在跨越这类调整时要复核。
+
+具体有哪些板块名不在本页事实范围内；`getbk` 要求名称与板块管理中的名称完全一致，
+先在客户端板块管理里确认。
+
+## 指定日的市场板块成分
+
+`getAbkbyDate(bk_name, endt)` 按板块中文名取指定日成分，并剔除暂停上市：
+
+```tsl
+return getAbkbyDate("A股", 20200210T);
+return getAbkbyDate("深证A股;上证A股;北证A股", 20200210T);
+```
+
+它只支持市场板块（`A股`、`上证A股`、`深证A股`、`北证A股`、`创业板`、`科创板`、
+`中小企业板`），其它板块名不支持。
+
+另一条等价路径是用天软自编的市场板块**指数**代码走 `getBkByDate`：
+
+| 代码        | 板块    | 代码        | 板块    |
+| ----------- | ------- | ----------- | ------- |
+| `TSI000001` | A股     | `TSI000006` | 北证A股 |
+| `TSI000002` | 上证A股 | `TSI000007` | B股     |
+| `TSI000003` | 科创板  | `TSI000008` | 上证B股 |
+| `TSI000004` | 深证A股 | `TSI000009` | 深证B股 |
+| `TSI000005` | 创业板  |             |         |
+
+```tsl
+return getbkbydate("TSI000001", 20230810T);   // A股板块 20230810 成分
+```
+
+## 指数成分必须用指数代码
+
+指数成分来源于指数成份变更表（`infotable 752` 指数.指数成份），与板块来源不同，
+只能用指数代码取：
+
+```tsl
+return getbkbydate("SH000300", 20210908T);   // 沪深300 指定日成分
+```
+
+板块名传给 `getBkByDate` 不会报错，只会返回空表。字段清单用
+`dictionary_lookup.py --query 指数成份` 取回。
+
+## 行业分类与行业指数是两套代码
+
+`getbkbydate("SWHY740000", ...)` 取的是**行业分类**成分（来源：个股所属行业），
+`getbkbydate("SW801150", ...)` 取的是**行业指数**成分（来源：指数成份表）。两者
+样本可能不同。先用 `SWHY00000N` 拿到该级全部行业指数代码，再逐个取成分：
+
+```tsl
+idx := getbkbydate("SWHY000001", 20190201T);   // 所有申万一级行业指数代码
+return getbkbydate(idx[0], 20190201T);          // 其中一个的成分股
+```
+
+分类属性代码体系见 [`classification-codes.md`](classification-codes.md)。
+
+## 沪深港通
+
+沪深港通合资格名单也记在 `infotable 752`，用四个方向虚拟代码取：
+
+| 代码       | 方向         | 代码       | 方向         |
+| ---------- | ------------ | ---------- | ------------ |
+| `HG000001` | 港股通（沪） | `HG000003` | 港股通（深） |
+| `HG000002` | 沪股通       | `HG000004` | 深股通       |
+
+```tsl
+// 指定日北向（A股）合资格名单
+return getbkbydate("HG000002", 20240701T) union2 getbkbydate("HG000004", 20240701T);
+
+// 指定日南向（港股）合资格名单
+return getbkbydate("HG000001", 20240701T) union2 getbkbydate("HG000003", 20240701T);
+
+// 曾经进过港股通的全部港股代码
+return sselect distinct ["证券代码"]
+       from infotable 752 of array("HG000001", "HG000003") end;
+```
+
+## 基金：在市与运作状态是两回事
+
+板块决定「是否上市」，运作状态要另外筛：
+
+```tsl
+return getbk("上市基金");                                    // 当前在市
+return getbk("已退市基金");                                  // 已退市
+return getbkall("普通股票型");                               // 某分类全部，含已停止运作
+return fundOperateFundsbyBkname("上市基金;已退市基金", 20200924T);  // 指定日仍在运作
+return fundsOperateFunds(getbkall("股票型"), 20200101T);      // 对给定列表筛运作中
+```
+
+`getBkAll` 返回板块全部样本含退市，但对一批板块不适用（A股类、指数成份类、概念板块
+等），限制清单见 `lookup.py --name getBkAll` 的条目正文。
+
+按基金分类取指定日成分优先走分类属性代码：
+
+```tsl
+return getbkbydate("TSJJ0201", 20220101T);   // 投资风格：股票型
+```
+
+一级市场代码与二级市场（交易）代码不同：`getbk("上证基金;深证基金")` 取的是交易代码，
+两者可通过基金基本信息表里的交易代码字段互转。
+
+## 债券
+
+```tsl
+return getbk("深交所债券;上交所债券;银行间债券");   // 当前在市全部债券
+return getbk("可转债");                            // 当前在市可转债
+return getbk("可转债;退市可转债");                 // 含退市
+return getbkall("可转债");                         // 同上，走 getBkAll
+return bondConvertibleBonds2();                    // 专用函数：所有可转债
+return cb_getTradeMarkByDate(20210813T);           // 指定日有交易的转债
+```
+
+券种板块名（`国债`、`企业债` 等）走同一套 `getbk` 路径。两个专用函数的签名见
+`lookup.py --name bondConvertibleBonds2` / `--name cb_getTradeMarkByDate`。
+
+## 期货
+
+期货有「合约」和「品种」两层，代码序列要分清取哪一层：
+
+```tsl
+return getbk("上市期货");                    // 当前在市合约
+return getbk("上市期货;退市期货");           // 含退市合约
+return getbk("期货品种代码");                // 品种代码（CU、IF 这类）
+return getbk("期货品种代码;退市期货品种代码");
+return getbk("期货主力");                    // 主力线；期货连续/次主力/指数线同理
+return getFuturesBkbydate("上市期货;退市期货", 20251218T);   // 指定日在市合约
+return getFuturesBkbydate("郑州商品交易所;中国金融期货交易所", 20240508T);
+```
+
+`getFuturesBkbydate` 的板块名可以是交易所名、期货类别（`股指期货`、`商品期货`、
+`农产品期货`）或品种名，签名见 `lookup.py --name getFuturesBkbydate`。
+
+品种代码与主力/次主力/指数线/连续代码的对照关系在 `infotable 708`
+（期货.期货品种代码对照表），任一形态的代码都能查到其余形态；访问代码与字段用
+`dictionary_lookup.py --query 期货品种` 取回。按品种取全部合约要先把品种代码换成
+品种名称再走 `getBkAll`。
+
+## 期权
+
+```tsl
+return getbk("上市期权");                     // 当前在市合约
+return getbk("ETF期权");                      // 按标的类型
+return getbk("华泰柏瑞沪深300ETF期权");        // 按标的名称
+```
+
+## 其它代码位
+
+`HG000001` 也用作宏观数据表格的取数代码位（如国内生产总值 816 表、居民消费价格
+822 表）。其余特别数据（国债收益率曲线等）按字典页确认。
+
+## 事实边界
+
+本页只给取数路径与代码位体系。函数签名、参数类型、返回形态一律以
+`lookup.py --name` 的条目正文为准。板块名清单、分类代码清单会随上游调整，不在本页
+硬编码，用运行时取回。
+
+FAQ 中出现但当前 API 索引查不到的名称（`GetETFListByDate`、`GetFuturesID`）不作为
+可用 API；需要时先用 `lookup.py --kw` 确认存在再使用，查不到就按 SKILL.md 的
+CHECKPOINT 停止。上表中 `getbk` 系列、`getAbkbyDate`、`getBkByDate`、`getBkAll`、
+`getFuturesBkbydate`、`fundOperateFundsbyBkname`、`fundsOperateFunds`、
+`bondConvertibleBonds2`、`cb_getTradeMarkByDate` 均已在索引中核对存在。