china-nbs 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+## 0.3.0 (2026-11-04)
+
+首个公开发布版本，补齐 M2-C 工程项。
+
+- 通用分片发现：分类树叶子名称带 `(2021-)`、`(2016-2020)`、`(-2015)` 等年份范围时，自动查找同父节点兄弟叶子并按指标名匹配，合并为 `shards`
+- `compare` 明确为**单指标多地区**；多指标请分多次调用
+- NOT_FOUND 负缓存：5 分钟 TTL，避免重复解析不存在的指标
+- 熔断器：连续 5 次可重试失败后打开，冷却 30 秒；支持 `circuitBreaker: false` 关闭
+- 代理注入：库层支持 `fetchImpl` / `dispatcher`；CLI 新增 `--proxy`（需可选安装 `undici`）
+- 新增 `CIRCUIT_OPEN` 错误码
+- 测试从 53 个增加到 **58 个**
+- 文档更新：分片发现、负缓存、熔断、代理、compare 边界
+- curated **130 个**，评测 **168 条**（159 curated + 9 fallback）
+
+## 0.2.2 (2026-11-03)
+
+覆盖率继续扩展，并修正城市范围。
+
+- 通过官网 `getDasByDaCatalogId` 确认：主要城市年度（code=8）官方只覆盖 **36 个城市**（4 个直辖市 + 32 个地级市）
+- 移除误导性的 334 个地级市列表，改为官方 36 城；其他地级市没有城市年度数据
+- 新增 58 个 curated：
+  - 能源消费总量、发电量、原煤产量、原油产量
+  - 全国年度商品房销售面积/销售额
+  - 分省年度建筑业总产值
+  - 分省年度/季度农村居民人均可支配收入
+  - 全国月度房地产投资
+  - 实物商品网上零售额
+  - 分省规模以上工业企业营业利润
+  - 分省经营单位所在地出口总额
+  - 分省新建商品房销售面积累计增长
+  - 人口出生率、死亡率、自然增长率、总抚养比
+  - 水泥、粗钢、钢材、汽车、手机、集成电路产量
+  - 旅客/货物运输量、旅客/货物周转量、快递量/收入、移动电话用户、宽带接入用户
+  - M2、金融机构各项存款、各项贷款
+  - 普通高等学校数、本专科在校生、高校专任教师
+  - 医疗卫生机构数、卫生技术人员、床位、卫生总费用
+  - 供水总量、生活垃圾清运量/无害化处理率、造林总面积
+  - 煤炭、油气、黑色金属矿、汽车、计算机通信电子制造业 PPI
+  - 月度 M2/M1 期末值、M2 同比
+  - 国有单位平均工资、原煤占能源生产总量比重、25–29 岁失业率、制造业产能利用率
+- curated 从 72 个扩到 **130 个**
+- 评测集从 101 条扩到 **168 条**：159 条 curated + 9 条 fallback
+- curated 离线 **159/159 top-1**；在线整体 **168/168（100.0%）**，fallback **9/9**
+- 文档更新城市范围、新增指标与覆盖率评估
+
+## 0.2.1 (2026-11-03)
+
+M2-B：覆盖率扩展。
+
+- curated 从 10 个扩到 **72 个**，覆盖社零、固投、收入、消费、财政、粮食、进出口、工业、失业率、房地产、建筑业、能源、网上零售等
+- 新增 36 个主要城市年度（`code=8`）和城市 GDP curated；城市季度/月度单城市数据明确不支持
+- 通用解析改进：
+  - 查询先清洗日期/地区/停用词
+  - 完整名称匹配，避免短别名抢走限定词查询
+  - 限定词评分（城镇/农村、税收/支出、利润/营业收入、夏收/秋收等）
+  - 分类树提示词扩展 + 叶子 n-gram 排序
+  - 搜索结果不确定时继续走分类树
+- 新增 `npm run eval`（离线）和 `npm run eval:live`
+- 评测集 **101 条**，离线/在线 top-1 100%、top-3 100%
+- 测试从 46 个增加到 53 个
+- 新增 `docs/evaluation.md`，更新 README/PROJECT/契约/口径/限流文档
+
+## 0.2.0 (2026-11-03)
+
+M2-A：分省月度/季度接入。
+
+- 新增 `scope × period → code` 映射：全国 `1/2/3`，分省 `4/5/6`
+- 分省季度 GDP（累计值）curated：`44ecf9ea21884caea5451c35e9c08fff`
+- 分省月度 CPI（4 个分片）curated，分片 id 与全国不同
+- 解除 `resolver` / `compare` 对分省月度、季度的拦截
+- `catalog` 支持 `code=4/5/7/8/9`（分省月/季、主要城市、港澳台）
+- CLI 新增分省季度/月度示例，`--code` 说明更新为 `1-9`
+- `fetchSeries` 合并分片时按分片 `indicId` 取值，避免多指标时取错列
+- 新增 10 个测试（共 46 个）
+- 文档补充 `code` 矩阵、分省实测样例与请求预算
+
+## 0.1.0 (2026-11-03)
+
+首个 M1 版本。
+
+- 统一 `query()` 入口，支持 `search`、`series`、`compare`、`catalog`
+- 全国年度/季度/月度查询；分省年度查询
+- 关键词搜索 + 频率/地区/口径排序
+- `AMBIGUOUS` 候选 + `indicatorId` 消歧
+- 月度 CPI 分片自动合并（2026- / 2021–2025 / 2016–2020 / –2015）
+- 34 个地区映射（含台湾、香港、澳门）
+- CLI：`search`、`series`、`compare`、`catalog`
+- 文本/表格/JSON 渲染
+- TTL+LRU 缓存、串行限流、超时、一次重试
+- 真实接口契约文档与固定 fixtures
+- 36 个单元/集成测试

package/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+欢迎补充指标别名、fixtures 和文档。这个项目最容易出错的地方不是代码，而是**口径**和**上游契约**。
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run lint
+npm run build
+npm run eval     # 离线评测 curated
+npm run smoke    # 手动跑真实接口
+```
+
+## 添加一个常用指标
+
+1. 用真实接口确认 `cid` 和 `indicatorId`（见 `docs/contracts.md`）。
+2. 在 `src/curated.ts` 增加一个 `CuratedEntry`：
+   - `aliases` 只放**完整等价**的说法；不要把 `GDP指数` 这样的限定词放进去。
+   - `frequency`、`regionScope`、`measure` 要和指标实际口径一致。
+   - 分片指标在 `shards` 中写清每个分片的 `cid`、`indicId`、起止年份。
+3. 在 `test/fixtures/` 放固定响应；测试不要依赖线上接口。
+4. 在 `test/resolver.test.ts` 或 `test/series.test.ts` 增加断言。
+5. 在 `scripts/eval-cases.ts` 增加至少一条查询用例（`expectedKey`）。
+6. 更新 `docs/data-semantics.md`（如果涉及口径）和 `CHANGELOG.md`。
+
+## 添加一个别名
+
+- 别名表在 `src/aliases.ts`。
+- 只加真正等价的缩写，例如 `社零` → `社会消费品零售总额`。
+- 有口径差异的词（同比/累计/当季/不变价/人均/贡献率）不要互相映射。
+
+## 修改解析/排序
+
+- 先加 fixture，再改 `scoreRecord`。
+- 任何新的“默认偏好”都要有测试，尤其是：
+  - GDP 总量 vs 贡献率/指数/人均/不变价
+  - CPI 年度 vs 月度
+  - 人口总数 vs 男性/女性/城镇/乡村
+- 不确定时返回 `AMBIGUOUS`，不要猜。
+
+## 上游礼貌
+
+- 不要提高默认并发；不要移除 2 秒间隔。
+- 不要加“绕过 WAF/换 IP/伪造 Cookie”的逻辑。
+- 403 不重试；429/5xx 最多重试一次。
+- 新增请求前先考虑缓存和请求预算。
+
+## PR 检查
+
+- [ ] `npm run typecheck`
+- [ ] `npm test`
+- [ ] `npm run lint`
+- [ ] `npm run build`
+- [ ] `npm run eval`
+- [ ] 如涉及真实接口，手动跑过 `npm run smoke`
+- [ ] 文档/CHANGELOG 已更新

package/LICENSE

@@ -0,0 +1,31 @@
+MIT License
+
+Copyright (c) 2026 china-nbs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Data notice:
+
+The data accessed by this software is published by China's National Bureau of
+Statistics (国家统计局). The MIT License above covers the software code only,
+not the data. Data remains subject to the National Bureau of Statistics' terms
+of use. This project is not affiliated with or endorsed by the National Bureau
+of Statistics.

package/README.md

@@ -1,3 +1,299 @@
-# Temporary Holding Version
+# china-nbs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/china-nbs)](https://www.npmjs.com/package/china-nbs)
+[![license](https://img.shields.io/npm/l/china-nbs)](https://github.com/salt-fishes/china-nbs/blob/main/LICENSE)
+
+用**一个 `query()` 入口**查询中国国家统计局数据发布库的 Node.js 库 + CLI。
+
+> **非国家统计局官方项目。** 数据来源：国家统计局（[data.stats.gov.cn](https://data.stats.gov.cn/)）。  
+> 代码使用 MIT License，但 MIT 不覆盖国家统计局数据；请依法、准确使用并注明来源。  
+> 新版数据发布库仍处于试运行期，接口可能变化。本项目不绕过 WAF，也不批量镜像或转售数据。
+
+## 特性
+
+- **一个入口**：`query()` 自动完成关键词搜索、分类树导航、指标解析、时间序列查询、分片合并。
+- **四个动作**：`search`（最新数据）、`series`（时间序列）、`compare`（分省对比）、`catalog`（分类树）。
+- **覆盖广**：全国、分省、主要城市；年度、季度、月度；130 个常用指标 curated，其他走分类树兜底。
+- **歧义可控**：候选分数接近时返回 `AMBIGUOUS` + 候选列表，可用 `indicatorId` 精确回查，不猜错误指标。
+- **口径优先**：默认优先总量/亿元；识别“增速、指数、人均、贡献率、累计、当季、不变价”等口径。
+- **分片合并**：自动识别分类树里的跨年份分片（不只 CPI），按时间范围拆分请求、合并、去重、排序。
+- **可评测**：168 条评测用例（159 curated + 9 fallback），`npm run eval` 离线测 curated，`npm run eval:live` 测真实解析。
+- **零运行时依赖**：Node 22+ 原生 `fetch`；TypeScript 编写，ESM + CJS。
+- **对上游友好**：默认串行限流（2 秒间隔）、TTL+LRU 缓存、in-flight 去重、超时、一次重试、NOT_FOUND 负缓存和熔断器。
+- **可接代理**：库支持 `fetchImpl` / `dispatcher` 注入；CLI 支持 `--proxy`（可选安装 `undici`）。
+
+## 环境
+
+- Node.js **>= 22**
+- 无需 API Key，无需 Cookie
+- 数据接口：`https://data.stats.gov.cn/dg/website/publicrelease/web/external`
+
+## 安装
+
+```bash
+npm install china-nbs
+```
+
+CLI 可直接运行：
+
+```bash
+npx china-nbs search GDP
+```
+
+本地开发：
+
+```bash
+npm install
+npm run build
+node dist/cli.js search GDP
+```
+
+## 快速开始
+
+```ts
+import { query, render } from 'china-nbs';
+
+const result = await query({
+  action: 'series',
+  query: 'GDP',
+  region: '全国',
+  period: 'year',
+  start: 2015,
+  end: 2025,
+});
+
+console.log(render(result, 'text'));
+```
+
+输出：
+
+```text
+国家统计局 · 国内生产总值 (亿元)
+2015年 全国：702,511.5 亿元
+...
+2025年 全国：1,401,879.2 亿元
+来源：国家统计局（data.stats.gov.cn）
+```
+
+`query()` **永远返回结构化 `QueryResult`**；`format` 不改变返回类型。展示用 `render(result, 'text' | 'table' | 'json')`。
+
+## CLI
+
+```bash
+# 最新数据
+npx china-nbs search GDP --period year --region 全国
+
+# 时间序列
+npx china-nbs series GDP --start 2015 --end 2025
+
+# 月度 CPI
+npx china-nbs series CPI --start 2025-01 --end 2025-10
+
+# 分省季度 GDP（累计值）
+npx china-nbs series GDP --period quarter --region 广东 --start 2025Q1 --end 2026Q3
+
+# 分省月度 CPI
+npx china-nbs series CPI --period month --region 广东 --start 2025-01 --end 2025-10
+
+# 主要城市年度数据
+npx china-nbs series 广州GDP --start 2020 --end 2024
+npx china-nbs compare GDP --regions 广州,深圳 --year 2024
+
+# 常用宏观指标
+npx china-nbs series 居民人均消费支出 --start 2020 --end 2025
+npx china-nbs series PPI --period month --start 2025-01 --end 2025-10
+npx china-nbs series 31个大城市城镇调查失业率 --period month --start 2025-01 --end 2025-10
+
+# 分省对比
+npx china-nbs compare GDP --regions 广东,江苏,浙江 --year 2025
+npx china-nbs compare GDP --regions 广东,江苏,浙江 --period quarter --start 2025Q1 --end 2025Q4
+
+# 分类树
+npx china-nbs catalog --code 3 --depth 2
+npx china-nbs catalog --code 4 --depth 2
+
+# JSON 输出
+npx china-nbs search CPI --json
+```
+
+退出码：
+
+| 码  | 含义                    |
+| --- | ----------------------- |
+| 0   | 成功                    |
+| 1   | 参数错误 / 不支持的动作 |
+| 2   | 未找到指标              |
+| 3   | 上游错误 / 超时         |
+| 4   | 歧义，需要选择候选      |
+
+### 消歧
+
+```bash
+npx china-nbs search 人口 --period year --json
+# 看 candidates[].id，或直接用序号：
+npx china-nbs search 人口 --period year --select 1
+```
+
+## API
+
+### `query(options): Promise<QueryResult>`
+
+| 参数                     | 类型                                             | 说明                                            |
+| ------------------------ | ------------------------------------------------ | ----------------------------------------------- |
+| `action`                 | `'search' \| 'series' \| 'compare' \| 'catalog'` | 默认 `search`                                   |
+| `query`                  | `string`                                         | 指标关键词，如 `GDP`、`CPI`、`广东 GDP`         |
+| `region`                 | `string`                                         | 单个地区，默认 `全国`；支持分省和 36 个主要城市 |
+| `regions`                | `string[]`                                       | `compare` 用                                    |
+| `period`                 | `'year' \| 'quarter' \| 'month'`                 | 不填则按 start/end/关键词推断                   |
+| `start` / `end`          | `string \| number`                               | 闭区间；`2015`、`2025Q1`、`2025-01`             |
+| `limit`                  | `number`                                         | `search` 最新数据点数量，默认 5                 |
+| `maxPoints`              | `number`                                         | `series` 最大数据点，默认 240                   |
+| `indicatorId`            | `string`                                         | 候选的 `id`，用于消歧                           |
+| `code` / `pid` / `depth` | `string` / `string` / `number`                   | `catalog` 用；`code` 1-9，默认 3                |
+| `timeoutMs`              | `number`                                         | 单请求超时，默认 20000                          |
+| `totalTimeoutMs`         | `number`                                         | 整次查询超时，默认 45000                        |
+| `signal`                 | `AbortSignal`                                    | 调用方取消                                      |
+| `noCache`                | `boolean`                                        | 跳过本次缓存                                    |
+| `fetchImpl`              | `typeof fetch`                                   | 自定义 fetch，用于代理/网关/测试                |
+| `dispatcher`             | `unknown`                                        | undici dispatcher，如 `new ProxyAgent(url)`     |
+| `debug` / `logger`       | `boolean` / function                             | 调试日志                                        |
+
+`compare` 只比较**一个指标**在多个地区的序列；需要比较多个指标时请分多次调用，不要在一次 `compare` 里混指标。
+
+### `QueryResult`
+
+```ts
+interface QueryResult {
+  ok: boolean;
+  action: Action;
+  indicator?: IndicatorMeta;
+  points?: DataPoint[];
+  series?: CompareSeries[];
+  candidates?: IndicatorCandidate[];
+  nodes?: CatalogNode[];
+  source: { name: '国家统计局'; url: string; retrievedAt: string };
+  notes?: string[];
+  partial?: boolean;
+  error?: { code: ErrorCode; message: string; retryable: boolean; hint?: string };
+}
+```
+
+示例：
+
+```ts
+const latest = await query({ action: 'search', query: 'GDP', period: 'year' });
+
+const ambiguous = await query({ action: 'search', query: '人口', period: 'year' });
+if (ambiguous.error?.code === 'AMBIGUOUS') {
+  const choice = ambiguous.candidates?.[0];
+  if (choice) {
+    const precise = await query({
+      action: 'series',
+      query: '人口',
+      period: 'year',
+      indicatorId: choice.id,
+      start: 2020,
+      end: 2025,
+    });
+  }
+}
+```
+
+## 支持范围（v0.2）
+
+| 数据                        | 状态                                                |
+| --------------------------- | --------------------------------------------------- |
+| 全国年度                    | ✅                                                  |
+| 全国季度                    | ✅（GDP 等常用指标；季度 GDP 默认累计值）           |
+| 全国月度                    | ✅（CPI/PPI/社零/固投/失业率/财政/M2/M1 等）        |
+| 分省年度（code=6）          | ✅（GDP、社零、固投、收入、财政、粮食等）           |
+| 分省季度（code=5）          | ✅（GDP、收入、消费、社零增速、建筑业、农林牧渔等） |
+| 分省月度（code=4）          | ✅（CPI、PPI、工业、固投、房地产等）                |
+| 主要城市年度（code=8）      | ✅（内置 36 个主要城市；GDP curated，其他走分类树） |
+| 主要城市月度价格（code=7）  | ⏳ 36/70 城市汇总价格指数，不是单城市数据           |
+| 港澳台 / 部门 / 国际 / 普查 | ⏳ 后续                                             |
+| MCP server                  | ⏳ 计划 v0.4                                        |
+
+常用指标 curated 共 **130 个**，覆盖 GDP、CPI、PPI、人口与人口结构、社零、固投、收入、消费、财政、粮食、进出口、工业与工业产品产量、失业率、房地产、建筑业、能源、交通邮电、金融（含月度 M2/M1）、教育、卫生、环境、分行业 PPI、网上零售等。
+
+## 评测
+
+```bash
+npm run eval        # 离线：只测 curated 快速路径，不请求上游
+npm run eval:live   # 在线：curated + search/tree 的真实解析
+```
+
+当前评测集 **168 条**：159 条 curated 用例 + 9 条 fallback 用例，覆盖全国/分省/主要城市、年/季/月、总量/累计/增速等口径。离线 curated 为 **159/159 top-1**；在线整体 **168/168 top-1（100.0%）**，其中 fallback 为 **9/9**。评测集在 `scripts/eval-cases.ts`，新增指标时请同时补用例。
+
+## 数据口径
+
+一定要区分：
+
+- **同比**：月度 CPI 常见 `上年同月=100`；年度 `上年=100`。
+- **累计 / 当季**：全国季度 GDP 同时存在累计值和当季值；默认 `GDP` 取累计值，`GDP当季` 取当季值。分省季度目前只有累计值和指数，没有当季值。
+- **分省 code**：分省年度/季度/月度分别用 `code=6/5/4`；不要把所有分省查询都当成年度。
+- **社零**：月度默认取**当期值**；`社零累计` 取累计值，`社零同比/社零增速` 取同比增长。分省季度只有累计增速。
+- **固投**：全国年度取亿元总量；全国月度、分省年度/月度只有增速，没有亿元总量。
+- **PPI**：月度/年度都是 `上年（同月）=100` 的指数，不是百分比涨跌幅。
+- **失业率**：默认月度**城镇调查失业率**；年度**城镇登记失业率**数据截至 2021，且口径不同。
+- **城市**：主要城市年度 `code=8`，内置 36 个城市；`code=7` 是 36/70 城市汇总价格指数，不是单城市数据。
+- **现价 / 不变价**：默认取现价总量；问“实际增速/不变价”时会降权现价指标。
+- **贡献率 / 拉动 / 构成**：只有明确问到时才优先。
+- **人均**：只有明确问“人均”时才优先。
+- **修订**：GDP 等数据会初步核算、最终核实和修订；结果带 `retrievedAt`，请注明查询时间。
+
+详见 [docs/data-semantics.md](docs/data-semantics.md)。
+
+## 限流与缓存
+
+| 内容     | TTL     |
+| -------- | ------- |
+| 搜索     | 10 分钟 |
+| 时间序列 | 30 分钟 |
+| 分类树   | 24 小时 |
+| 指标列表 | 24 小时 |
+| 省份列表 | 7 天    |
+
+默认串行请求，请求间隔 ≥ 2 秒（加 0–250ms jitter），5xx/429 重试 1 次。连续 5 次可重试失败后熔断 30 秒（可配置），`NOT_FOUND` 结果会做 5 分钟负缓存。详见 [docs/rate-limit.md](docs/rate-limit.md)。
+
+## 代理
+
+库层可以直接注入 `dispatcher`（需要安装 `undici`）：
+
+```ts
+import { query } from 'china-nbs';
+import { ProxyAgent } from 'undici';
+
+const result = await query({
+  query: 'GDP',
+  dispatcher: new ProxyAgent('http://127.0.0.1:7890'),
+});
+```
+
+CLI：
+
+```bash
+npm install -g undici
+china-nbs search GDP --proxy http://127.0.0.1:7890
+```
+
+也可以传自定义 `fetchImpl`，接入公司网关或测试桩。
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run lint
+npm run build
+npm run smoke   # 手动跑真实接口，不在 CI 中执行
+```
+
+真实接口契约和字段说明见 [docs/contracts.md](docs/contracts.md)。
+
+## License
+
+代码：MIT。  
+数据：国家统计局，版权归国家统计局所有；本项目不主张数据版权。  
+请勿用本项目批量镜像、转售或商业分发国家统计局数据。