@catax/catax-crs

v1.1.2

Published

a month ago

CaTax CRS 命令行工具 - 客户数据导入与免密跳转

0High
0Medium
0Low

coobeea

catax crs customer cli

@catax/catax-crs 命令功能说明书

本工具是基于 Node.js 开发的命令行接口（CLI）客户端，旨在将 CaTax CRS 系统的后端 API 接口封装为易于外部系统调用的命令行工具。核心能力包括：执行客户数据的批量导入、查询客户及其年度数据信息，以及生成前端免密跳转链接。

快速开始：

# 1. 初始化配置（自动使用生产环境地址）
catax-crs init

# 2. 开始使用
catax-crs client-list "测试客户"
catax-crs quick-link "测试客户" "2024"

默认配置：

后端 API：https://api.taxai.catax.cn
前端 Web：http://boss.taxai.catax.cn

快速入门：查看使用示例文档了解更多配置和使用场景。

1. 认证与鉴权

所有业务命令在执行前，必须向服务端提供有效的 API Key 进行身份认证。

鉴权参数获取优先级：

命令行参数：--key <apiKey>（每次执行时动态传入，优先级最高）
环境变量：CATAX_CRS_API_KEY=<apiKey>（适合在服务器/容器环境配置）
全局配置文件：~/.catax/crs-config.json（通过 catax-crs init 命令生成）

服务地址配置：

本工具默认使用生产环境地址，无需配置即可使用：

后端 API 地址（apiBaseUrl）：用于调用后端接口（导入、查询等）
- 默认值：https://api.taxai.catax.cn（生产环境）
- 命令行参数：--api-url <apiBaseUrl>（可选，用于本地开发）
- 配置文件字段：apiBaseUrl
前端 Web 地址（webBaseUrl）：用于生成浏览器跳转链接
- 默认值：http://boss.taxai.catax.cn（生产环境）
- 命令行参数：--web-url <webBaseUrl>（可选，用于本地开发）
- 配置文件字段：webBaseUrl

配置示例：

# 1. 生产环境（默认地址，无需指定）
catax-crs init
# 直接输入 API Key 即可，自动使用生产环境地址

# 2. 本地开发环境（需要覆盖默认地址）
catax-crs init \
  --api-url http://127.0.0.1:8081 \
  --web-url http://127.0.0.1:8081

# 3. 临时使用不同地址（不保存到配置文件）
catax-crs client-list "测试" \
  --api-url http://localhost:3000 \
  --web-url http://localhost:3000

使用说明：

首次使用只需运行 catax-crs init 并输入 API Key
默认连接生产环境，无需配置地址
本地开发时才需要使用 --api-url 和 --web-url 参数

2. 核心命令集 (API 映射)

本章节以功能说明的维度，详细列出工具提供的所有命令、参数定义及其底层映射的 API 行为。

2.1 客户查询 (`client-list`)

功能描述：查询当前用户权限下可访问的客户列表，主要用于获取客户的全局唯一标识（clientId）。

命令格式：

catax-crs client-list <clientName> [options]

参数说明： | 参数类型 | 名称 | 必填 | 说明 | |----------|------|------|------| | Positional | <clientName> | 是 | 用于模糊或精确匹配的客户名称 | | Option | -p, --page <num> | 否 | 分页查询的页码，默认为 1 | | Option | -s, --size <num> | 否 | 分页查询的每页记录数，默认为 10 |

适用场景：在生成跳转链接之前，当外部系统只知道客户名称而不知道数据库中的 clientId 时，需通过此命令进行查询。 底层接口映射：POST /user-api/cap/client/list

2.2 客户年度查询 (`client-years`)

功能描述：根据指定的客户 ID，查询该客户所有已创建的年度数据列表，主要用于获取年度标识（yearId）。

命令格式：

catax-crs client-years <clientId>

参数说明： | 参数类型 | 名称 | 必填 | 说明 | |----------|------|------|------| | Positional | <clientId> | 是 | 客户的全局唯一标识，通常由 client-list 命令获取 |

适用场景：在明确客户后，需进一步确定目标数据所在的业务年度。获取的 yearId 将作为后续生成免密跳转链接的必要参数。 底层接口映射：GET /user-api/cap/client/years?clientId={clientId}

2.3 生成免密跳转链接 — 报告页 (`generate-link`)

功能描述：向服务端申请单次有效（60秒内）的鉴权票据（onceToken），并将其与必要的业务参数拼接，生成一个可直接在浏览器中打开的系统直达链接，落地页为申报报告页。

命令格式：

catax-crs generate-link [options]

参数说明： | 参数类型 | 名称 | 必填 | 说明 | |----------|------|------|------| | Option | -c, --client-id <id> | 是 | 客户 ID。决定前端加载哪个客户的数据。 | | Option | -y, --year-id <id> | 是 | 年度 ID。决定前端加载哪个申报年度。 | | Option | -n, --client-name <name> | 是 | 客户名称。仅用于前端界面的顶部展示。 | | Option | -Y, --year-name <name> | 是 | 年度名称（如 "2024"）。仅用于前端界面的年份下拉框展示。 |

适用场景：当外部系统或用户希望跳过常规的登录流程，直接从第三方平台跳转至 CaTax CRS 系统的特定客户申报报告页时使用。 底层接口映射：

POST /user-api/system/login/apikey/login (获取 onceToken)
构造前端 URL，并自动附加 redirect=/service/overseasTaxMulti/report 参数。

2.4 生成免密跳转链接 — 数据管理页 (`generate-data-link`)

功能描述：获取单次有效鉴权票据，生成免密直达链接，落地页为境外收入数据管理总览页（可查看所有已导入的客户数据列表）。

命令格式：

catax-crs generate-data-link

参数说明：无需任何参数。数据管理页为全局总览，不绑定特定客户或年度。

适用场景：当管理员或运维人员需要快速打开数据管理后台，查看所有客户的导入状态和申报进度时使用。 底层接口映射：

POST /user-api/system/login/apikey/login (获取 onceToken)
构造前端 URL，并自动附加 redirect=/service/overseasTaxMulti 参数。

2.5 数据导入 (`import`)

功能描述：将符合 CaTax CRS 系统规范的客户数据 ZIP 包批量上传至服务端。

命令格式：

catax-crs import <zipFile>

参数说明： | 参数类型 | 名称 | 必填 | 说明 | |----------|------|------|------| | Positional | <zipFile> | 是 | 包含客户数据的 ZIP 压缩包的本地绝对或相对路径 |

适用场景：定期从外部数据源（如 ERP 系统）导出数据后，通过该命令自动将数据同步至税务系统。 底层接口映射：POST /user-api/cap/overseas2-multi/batch-import (multipart/form-data)

3. 调试工具 (`debug`)

功能描述：用于开发人员排查接口调用异常，输出底层的原始 JSON 响应报文，不进行任何业务逻辑封装。

命令格式：

catax-crs debug --test <apiName> [options]

支持的测试接口：

jwt：测试 JWT Token 交换是否成功
client-list：测试客户查询接口（需附加 --client-name）
client-years：测试年度查询接口（需附加 --client-id） | /user-api/cap/client/years | GET | - | Header: X-Token | 查询客户年度 | | /user-api/system/login/apikey/login | POST | application/x-www-form-urlencoded | Form: apiKey | 获取前端跳转 onceToken |

认证说明：

步骤 1、5 使用 API Key 通过表单参数传递
步骤 2、3、4 使用 JWT Token 通过 X-Token Header 传递

Content-Type 说明：

Form 接口（步骤 1、3、5）：application/x-www-form-urlencoded
文件上传接口（步骤 2）：multipart/form-data
GET 接口（步骤 4）：无需 Content-Type

跳转链接格式

报告页链接（generate-link 生成）：

<webBaseUrl>/#/apikey-login?onceToken=<token>&redirect=/service/overseasTaxMulti/report&clientId=<id>&yearId=<id>&clientName=<name>&yearName=<year>

数据管理页链接（generate-data-link 生成）：

<webBaseUrl>/#/apikey-login?onceToken=<token>&redirect=/service/overseasTaxMulti

注意：

onceToken 有效期为 60 秒
每个 token 仅可使用一次
用户浏览器打开链接后，前端会自动完成登录并跳转
onceToken 从后端 API 地址获取，但跳转链接使用前端 Web 地址

常见问题

Q: 提示 "API Key 无效或缺失"？

A: 检查以下几点：

确认已执行 catax-crs init 或设置了环境变量
API Key 格式正确（以 cak_ 开头）
API Key 未过期且有相应权限

Q: 导入失败怎么办？

确认 ZIP 文件包含 client.json 和数据文件
检查文件格式是否符合要求
查看详细错误信息，可能是数据格式问题

Q: 生成的链接打不开？

确认链接在 60 秒内打开
每个链接只能使用一次，需重新生成
确认服务地址配置正确：
- 后端 API 地址（--api-url）用于获取 token
- 前端 Web 地址（--web-url）用于生成跳转链接
- 如果前后端分离部署，需分别配置两个地址

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@catax/catax-crs 命令功能说明书

1. 认证与鉴权

2. 核心命令集 (API 映射)

2.1 客户查询 (client-list)

2.2 客户年度查询 (client-years)

2.3 生成免密跳转链接 — 报告页 (generate-link)

2.4 生成免密跳转链接 — 数据管理页 (generate-data-link)

2.5 数据导入 (import)

3. 调试工具 (debug)

跳转链接格式

常见问题

Q: 提示 "API Key 无效或缺失"？

Q: 导入失败怎么办？

Q: 生成的链接打不开？

许可证

2.1 客户查询 (`client-list`)

2.2 客户年度查询 (`client-years`)

2.3 生成免密跳转链接 — 报告页 (`generate-link`)

2.4 生成免密跳转链接 — 数据管理页 (`generate-data-link`)

2.5 数据导入 (`import`)

3. 调试工具 (`debug`)