@catax/catax-crs

@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: 导入失败怎么办？

A:

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

Q: 生成的链接打不开？

A:

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

许可证

MIT © CaTax