📝 docs(tsl-api): add missing financial API codegen entries

2026-08-21 16:09:08 +08:00
parent 5484fc7519
commit 476f999139
7 changed files with 636 additions and 0 deletions
@@ -418,3 +418,143 @@ v := reportOfEndT(46, 20150101T, "营业收入");
 return v;
 // 输出：146388004498.44
 ```
+
+## `financialItemIn12Month_HK(r_date, info_id, if_to_func_currency)`
+
+声明：function
+
+返回港股最近 12 个月财务指标，与系统参数中的证券代码相关。指定报告期不存在时返回 0；港股财务数据仅支持半年报和年报
+
+<!-- tags: 金融 财务分析 扩展基本面数据 港股 HK TTM 最近12个月 财务指标 -->
+
+| 参数                  | 类型    | 说明                                              |
+| --------------------- | ------- | ------------------------------------------------- |
+| `r_date`              | integer | 报告期。官网定义中的类型原文拼作 `Ingeter`        |
+| `info_id`             | integer | 基本面数据 ID。官网定义中的类型原文拼作 `Ingeter` |
+| `if_to_func_currency` | bool    | 可选。是否转为本币，默认 0，即保留原币记账        |
+
+if_to_func_currency 取值
+
+- `0` — 不转为本币，使用原币币种记账
+- `1` — 使用天软汇率数据转为本币币种；港股本币为港元
+
+返回：real
+
+若报告类型为年报，TTM 数据等于本报告期数据；若报告类型为半年报，TTM 数据等于本报告期数据加上“往前推两期数据减同比报告期数据”
+
+### 示例
+
+范例01：按原币取得港股 TTM 数据
+
+```tsl
+end_t := 20260611T;
+stock_id := 'HK00659';
+setSysParam(pn_stock(), stock_id);
+setSysParam(pn_date(), end_t);
+r_date := 20250630;
+return financialItemIn12Month_HK(r_date, 46002);
+// 输出：24285300000
+```
+
+范例02：将港股 TTM 数据转为港元
+
+```tsl
+end_t := 20260611T;
+stock_id := 'HK00005';
+setSysParam(pn_stock(), stock_id);
+setSysParam(pn_date(), end_t);
+r_date := 20250630;
+return financialItemIn12Month_HK(r_date, 46002, 1);
+// 输出：587736013816.547
+```
+
+## `reportType_HK(r_date, r_type)`
+
+声明：function
+
+根据报告期返回港股报告类型，或判断报告期与报告类型是否匹配，与系统参数中的证券代码相关。港股仅支持半年报和年报
+
+<!-- tags: 金融 财务分析 扩展基本面数据 港股 HK 报告期 报告类型 半年报 年报 -->
+
+| 参数     | 类型    | 说明                                             |
+| -------- | ------- | ------------------------------------------------ |
+| `r_date` | integer | 报告期。官网定义中的类型原文拼作 `Ingeter`       |
+| `r_type` | integer | 可选。返回结果类型，默认 0。官网定义中的类型原文拼作 `Ingeter` |
+
+r_type 取值
+
+- `0` — 返回报告类型字符串：`年报` 或 `半年报`
+- `1` — 返回 0 或 1，表示报告期与报告类型是否匹配
+- `-1` — 返回包含报告期、报告类型和是否匹配的数组
+
+返回：string|integer|array
+
+匹配规则为：半年报的报告期应为 `****0630`，年报的报告期应为 `****1231`；其他组合均不匹配
+
+### 示例
+
+范例01：返回报告类型
+
+```tsl
+setSysParam(pn_stock(), 'HK00659');
+r_date := 20251231;
+return reportType_HK(r_date, 0);
+// 输出：半年报
+```
+
+范例02：判断报告期与报告类型是否匹配
+
+```tsl
+setSysParam(pn_stock(), 'HK00659');
+r_date := 20251231;
+return reportType_HK(r_date, 1);
+// 输出：0
+```
+
+范例03：返回报告期、报告类型和是否匹配
+
+```tsl
+setSysParam(pn_stock(), 'HK00659');
+r_date := 20251231;
+return reportType_HK(r_date, -1);
+// 输出：array('报告期':20251231,'报告类型':'半年报','是否匹配':0)
+```
+
+## `originalToFunctionalCurrency_HK(end_t, original_value, original_currency)`
+
+声明：function
+
+使用天软汇率数据将港股财务数据从原币币种换算为本币币种，港股本币为港元
+
+<!-- tags: 金融 财务分析 扩展基本面数据 港股 HK 汇率 原币 本币 港元 币种转换 -->
+
+| 参数                | 类型   | 说明                                      |
+| ------------------- | ------ | ----------------------------------------- |
+| `end_t`             | date   | 截止日期                                  |
+| `original_value`    | real   | 按原币记账的数据值                        |
+| `original_currency` | string | 原币币种，使用大写代码，如 HKD、CNY、USD |
+
+返回：real
+
+### 示例
+
+范例01：将美元换算为港元
+
+```tsl
+return originalToFunctionalCurrency_HK(20251231T, 1, 'USD');
+// 输出：7.78
+```
+
+范例02：将人民币换算为港元
+
+```tsl
+return originalToFunctionalCurrency_HK(20251231T, 1, 'CNY');
+// 输出：1.11
+```
+
+范例03：将泰铢换算为港元
+
+```tsl
+return originalToFunctionalCurrency_HK(20251231T, 1, 'THB');
+// 输出：0.25
+```
@@ -0,0 +1,203 @@
+# 金融 / 金融工程 / 因子研究 / 绩效分析 / 收益率评价 / 中间函数 / 常用报表
+
+## `fi_report_excessYields(rt_data, fname_pf, fname_bm, fname_date, plot_type)`
+
+声明：function
+
+分析组合与基准的超额收益，计算超额收益率、累计收益、相对净值和回撤指标；可返回完整数据集或生成多子图
+
+<!-- tags: 金融 金融工程 因子研究 绩效分析 收益率评价 常用报表 超额收益 回撤 相对净值 -->
+
+| 参数         | 类型        | 说明                           |
+| ------------ | ----------- | ------------------------------ |
+| `rt_data`    | array       | 二维数组，净值收益率百分比序列 |
+| `fname_pf`   | string      | 组合字段名称                   |
+| `fname_bm`   | string      | 基准字段名称                   |
+| `fname_date` | string      | 日期字段名称                   |
+| `plot_type`  | user_define | 返回类型                       |
+
+plot_type 取值
+
+- `0` — 返回包含超额、累计、回撤和相对净值的完整数据集
+- `1` — 返回 `tssubplot_lines` 生成的多子图数组
+
+返回：array
+
+### 示例
+
+范例01：生成组合与基准的超额收益图表
+
+```tsl
+rt_data := TSUT_Data_ZSZF();
+return fi_report_excessYields(rt_data, '沪深300', '中证500', '截止日', 1);
+```
+
+## `fi_report_corrAnalysis(rt_data, fname_date)`
+
+声明：function
+
+生成收益率评价的相关性分析报表
+
+<!-- tags: 金融 金融工程 因子研究 绩效分析 收益率评价 常用报表 相关性 分析 -->
+
+| 参数         | 类型    | 说明                           |
+| ------------ | ------- | ------------------------------ |
+| `rt_data`    | db_data | 收益率数据表                   |
+| `fname_date` | string  | 日期字段名称，通常为“截止日”   |
+
+返回：array
+
+### 示例
+
+范例01：生成相关性分析报表
+
+```tsl
+rt_data := tsindexs_get_rQK2('TSI010001', 20250601T, 20260601T, '日线', 1);
+fname_date := '截止日';
+return fi_report_corrAnalysis(rt_data, fname_date);
+```
+
+## `fi_report_historicalPerformance(rt_data, fname_bm, fname_date, cycle, factor_roll_n_year)`
+
+声明：function
+
+生成收益率评价的历史行情走势报表
+
+<!-- tags: 金融 金融工程 因子研究 绩效分析 收益率评价 常用报表 历史行情 走势 -->
+
+| 参数                 | 类型       | 说明                 |
+| -------------------- | ---------- | -------------------- |
+| `rt_data`            | db_data    | 收益率数据表                                   |
+| `fname_bm`           | string     | 基准字段名称                                   |
+| `fname_date`         | string     | 日期字段名称                                   |
+| `cycle`              | cycle_list | 滚动周期；官网范例未传入，定义未说明默认值     |
+| `factor_roll_n_year` | integer    | 滚动年数；官网范例未传入，定义未说明默认值     |
+
+返回：array
+
+### 示例
+
+范例01：生成历史行情走势报表
+
+```tsl
+rt_data := tsindexs_get_rQK('TSI010001', 20250601T, 20260601T, '日线', 'SH000300');
+fname_bm := 'SH000300';
+fname_date := '截止日';
+return fi_report_historicalPerformance(rt_data, fname_bm, fname_date);
+```
+
+## `fi_report_periodReturn(rt_data, fname_date)`
+
+声明：function
+
+生成收益率评价的阶段收益报表
+
+<!-- tags: 金融 金融工程 因子研究 绩效分析 收益率评价 常用报表 阶段收益 业绩查询 -->
+
+| 参数         | 类型    | 说明                         |
+| ------------ | ------- | ---------------------------- |
+| `rt_data`    | db_data | 收益率数据表                 |
+| `fname_date` | string  | 日期字段名称，通常为“截止日” |
+
+返回：array
+
+### 示例
+
+范例01：生成阶段收益报表
+
+```tsl
+rt_data := tsindexs_get_rQK('TSI010001', 20250601T, 20260601T, '日线');
+fname_date := '截止日';
+return fi_report_periodReturn(rt_data, fname_date);
+```
+
+## `fi_report_returnAndRisk(rt_data, fname_date, qk_type, cycle, days_in_1_y)`
+
+声明：function
+
+生成收益率评价的阶段收益风险特征报表
+
+<!-- tags: 金融 金融工程 因子研究 绩效分析 收益率评价 常用报表 收益 风险 阶段 -->
+
+| 参数          | 类型        | 说明                         |
+| ------------- | ----------- | ---------------------------- |
+| `rt_data`     | db_data     | 收益率数据表                                   |
+| `fname_date`  | string      | 日期字段名称，通常为“截止日”                   |
+| `qk_type`     | user_define | 采样类型                                       |
+| `cycle`       | cycle_list  | 采样周期                                       |
+| `days_in_1_y` | integer     | 年化系数；官网范例未传入，定义未说明默认值     |
+
+qk_type 取值
+
+- `0` — 固定周期
+- `1` — 滚动周期
+
+返回：array
+
+### 示例
+
+范例01：按固定季度生成阶段收益风险特征报表
+
+```tsl
+rt_data := tsindexs_get_rQK(
+    array('TSI010001', 'TSI010002'), 20250601T, 20260601T, '日线');
+fname_date := '截止日';
+qk_type := 0;
+cycle := '季线';
+return fi_report_returnAndRisk(rt_data, fname_date, qk_type, cycle);
+```
+
+## `fi_report_riskFeature(rt_data, fname_bm, fname_date, days_in_1_y)`
+
+声明：function
+
+生成收益率评价的收益风险特征报表
+
+<!-- tags: 金融 金融工程 因子研究 绩效分析 收益率评价 常用报表 收益 风险 特征 -->
+
+| 参数          | 类型    | 说明         |
+| ------------- | ------- | ------------ |
+| `rt_data`     | db_data | 收益率数据表                               |
+| `fname_bm`    | string  | 基准字段名称                               |
+| `fname_date`  | string  | 日期字段名称                               |
+| `days_in_1_y` | integer | 年化系数；官网范例未传入，定义未说明默认值 |
+
+返回：array
+
+### 示例
+
+范例01：生成收益风险特征报表
+
+```tsl
+rt_data := tsindexs_get_rQK('TSI010001', 20250601T, 20260601T, '日线', 'SH000300');
+fname_bm := 'SH000300';
+fname_date := '截止日';
+return fi_report_riskFeature(rt_data, fname_bm, fname_date);
+```
+
+## `fi_report_rollReturn(rt_data, fname_date, cycle)`
+
+声明：function
+
+生成收益率评价的滚动收益报表
+
+<!-- tags: 金融 金融工程 因子研究 绩效分析 收益率评价 常用报表 滚动收益 业绩查询 -->
+
+| 参数         | 类型       | 说明                         |
+| ------------ | ---------- | ---------------------------- |
+| `rt_data`    | db_data    | 收益率数据表                 |
+| `fname_date` | string     | 日期字段名称，通常为“截止日” |
+| `cycle`      | cycle_list | 滚动周期                     |
+
+返回：array
+
+### 示例
+
+范例01：生成季度滚动收益报表
+
+```tsl
+rt_data := tsindexs_get_rQK('TSI010001', 20250601T, 20260601T, '日线');
+fname_date := '截止日';
+cycle := '季线';
+return fi_report_rollReturn(rt_data, fname_date, cycle);
+```
@@ -74,3 +74,26 @@ else
    result := array(); // 获取失败
 return result;
 ```
+
+## `getEtfListByDate(bk_name, end_t)`
+
+声明：function
+
+返回指定日期仍在运作的 ETF 基金交易代码列表
+
+<!-- tags: 金融 基金 ETF 指定日 运作 交易代码 列表 -->
+
+| 参数      | 类型        | 说明                               |
+| --------- | ----------- | ---------------------------------- |
+| `bk_name` | string      | 市场和板块名称，多个名称以分号分隔 |
+| `end_t`   | t_date_time | 截止日期                           |
+
+返回：array
+
+### 示例
+
+范例01：取得指定日仍在运作的沪深 ETF 交易代码
+
+```tsl
+return getEtfListByDate('上证ETF;深证ETF', 20200924T);
+```
@@ -168,6 +168,31 @@ return GetBKGoMarketByDate("SZ399102", 20201201T, 1);
 return GetBKNameToId("A股", 20201201T);
 ```

+## `getIndexAdjustDate(index_id, beg_t, end_t)`
+
+声明：function
+
+返回指定指数在起止日期区间内的全部调整日序列
+
+<!-- tags: 金融 指数 指数情况 调整日 调仓 日期 序列 -->
+
+| 参数       | 类型       | 说明     |
+| ---------- | ---------- | -------- |
+| `index_id` | index_list | 指数代码 |
+| `beg_t`    | date       | 开始日期 |
+| `end_t`    | date       | 截止日期 |
+
+返回：array
+
+### 示例
+
+范例01：取得沪深 300 在 2025 年内的全部调整日
+
+```tsl
+return getIndexAdjustDate('SH000300', 20250101T, 20251231T);
+// 输出：array(20250304,20250616,20250905,20251215)
+```
+
 ## `stock_hsgEligibleInfo(bkid, stockid)`

 声明：function
@@ -1995,6 +1995,89 @@ return StockZtOrDtClose(0);
 // 输出：26.62
 ```

+## `adjustmentFactor(rate_day)`
+
+声明：function
+
+返回从复权基准日到系统时间的比例复权因子，与系统参数中的证券代码和系统时间相关。支持股票、ETF、LOF 和可转债；模型考虑股权分置改革的分红送股，不考虑权证。复权价格等于收盘价乘以复权因子
+
+<!-- tags: 金融 行情 指定日 复权 复权因子 股票 ETF LOF 可转债 -->
+
+| 参数       | 类型        | 说明                         |
+| ---------- | ----------- | ---------------------------- |
+| `rate_day` | t_date_time | 可选。复权基准日，默认上市日 |
+
+返回：real
+
+### 示例
+
+范例01：以上市日为基准日取得复权因子
+
+```tsl
+setSysParam(pn_stock(), 'SH603117');
+setSysParam(pn_date(), 20180702T);
+return adjustmentFactor();
+// 输出：1.01472183639756
+```
+
+范例02：计算以上市日为基准的复权价格
+
+```tsl
+setSysParam(pn_stock(), 'SH603117');
+setSysParam(pn_date(), 20191112T);
+return simpleRoundTo(close() * adjustmentFactor(), -2);
+// 输出：5.31
+```
+
+范例03：指定复权基准日
+
+```tsl
+setSysParam(pn_stock(), 'SH603117');
+setSysParam(pn_date(), 20191112T);
+rate_day := 20200721T;
+return adjustmentFactor(rate_day);
+// 输出：0.98989898989899
+```
+
+## `stockZtOrDtCloseOfMD(flag)`
+
+声明：function
+
+返回交易所提供的涨停价或跌停价，与系统参数中的证券代码和系统时间相关
+
+<!-- tags: 金融 行情 指定日 涨停 跌停 涨跌停价 交易所 -->
+
+| 参数   | 类型    | 说明           |
+| ------ | ------- | -------------- |
+| `flag` | integer | 涨停或跌停标志 |
+
+flag 取值
+
+- `0` — 涨停
+- `1` — 跌停
+
+返回：real
+
+### 示例
+
+范例01：取得科创板股票上市第二天的涨停价
+
+```tsl
+setSysParam(pn_stock(), 'SH688067');
+setSysParam(pn_date(), 20210622T);
+return stockZtOrDtCloseOfMD(0);
+// 输出：0
+```
+
+范例02：取得深市股票的涨停价
+
+```tsl
+setSysParam(pn_stock(), 'SZ000002');
+setSysParam(pn_date(), 20210622T);
+return stockZtOrDtCloseOfMD(0);
+// 输出：26.62
+```
+
 ## `zlToFuturesId(zlid, end_t)`

 声明：function