{"_id":"@catax/catax-crs","_rev":"5-aeab70f9ee316d5737658124d0062dde","name":"@catax/catax-crs","dist-tags":{"latest":"1.1.2"},"versions":{"1.0.3":{"name":"@catax/catax-crs","version":"1.0.3","keywords":["catax","crs","customer","cli"],"author":{"name":"CaTax"},"license":"MIT","_id":"@catax/catax-crs@1.0.3","maintainers":[{"name":"coobeea","email":"coobeea@outlook.com"}],"bin":{"catax-crs":"bin/catax-crs.js"},"dist":{"shasum":"f421d551309c8563199d4312340e037e29d28365","tarball":"https://registry.npmjs.org/@catax/catax-crs/-/catax-crs-1.0.3.tgz","fileCount":13,"integrity":"sha512-w/mjF6LLCEUAEtd4miOX6z+072d7HrebSxeG7Wuj2IkcbnjzgRNL90UI/kySYUimJgnYbC1vaf6t/NfJ1fERsA==","signatures":[{"sig":"MEYCIQDmSakRCVQa4raLGh9eXkI68+RhE/BJqV90qEd7OZKtpAIhAJ8HomPjey4b8kUBdOkAtAk66ZZ2HMPV9F7k68kHgpL3","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":34062},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"4f5dfebb5b3bbc7a40732e74f7dfba9682a3bf0d","_npmUser":{"name":"coobeea","email":"coobeea@outlook.com"},"_npmVersion":"10.9.4","description":"CaTax CRS 命令行工具 - 客户数据导入与免密跳转","directories":{},"_nodeVersion":"22.21.1","dependencies":{"chalk":"^5.4.1","commander":"^13.1.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/catax-crs_1.0.3_1775986535858_0.08274172850205685","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@catax/catax-crs","version":"1.0.4","keywords":["catax","crs","customer","cli"],"author":{"name":"CaTax"},"license":"MIT","_id":"@catax/catax-crs@1.0.4","maintainers":[{"name":"coobeea","email":"coobeea@outlook.com"}],"bin":{"catax-crs":"bin/catax-crs.js"},"dist":{"shasum":"f9eb0b0dfc214227caee3c52cbd2ddf285a97221","tarball":"https://registry.npmjs.org/@catax/catax-crs/-/catax-crs-1.0.4.tgz","fileCount":13,"integrity":"sha512-tU+yw4c9d8gpMD74Qqy/TcStue9vV6DFQejILHTaeHuwwf/xU6hggB/y7EstwibZ7jGxKvBxo1vOtOifB9ZGgg==","signatures":[{"sig":"MEUCIDekzWMiSaHcyHjncn2oiaNxmUTT6IRO0I2GGITu+G+eAiEAxYsg969Tj/vOu/Or9jHMD6hc5XHBaQkf/P26VoN9jyM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":34062},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"4f5dfebb5b3bbc7a40732e74f7dfba9682a3bf0d","_npmUser":{"name":"coobeea","email":"coobeea@outlook.com"},"_npmVersion":"10.9.4","description":"CaTax CRS 命令行工具 - 客户数据导入与免密跳转","directories":{},"_nodeVersion":"22.21.1","dependencies":{"chalk":"^5.4.1","commander":"^13.1.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/catax-crs_1.0.4_1775986596024_0.8798929119394043","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@catax/catax-crs","version":"1.1.0","keywords":["catax","crs","customer","cli"],"author":{"name":"CaTax"},"license":"MIT","_id":"@catax/catax-crs@1.1.0","maintainers":[{"name":"coobeea","email":"coobeea@outlook.com"}],"bin":{"catax-crs":"bin/catax-crs.js"},"dist":{"shasum":"4fd5fd2dc6a327b6c22b33e673e8cc4641bfffae","tarball":"https://registry.npmjs.org/@catax/catax-crs/-/catax-crs-1.1.0.tgz","fileCount":14,"integrity":"sha512-aDHiD4C+CqrX5Pm9acApB8QIaTBPstgjxNlGMjiEJFOB+2sE9324RCF+apO0vS9FjCle1rRChE8gUeMmanyPnQ==","signatures":[{"sig":"MEYCIQDIC79jJAAwUeNTdjbgV3AUzWP8b3c6z5Asu2dStqSgggIhAP5ueJxhLMQHAbpBfMzxQoolmHNsbypN0Ug6F9r647g4","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":36315},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"0521d1116b807aeffb0968ca6bc805ec81390f1b","_npmUser":{"name":"coobeea","email":"coobeea@outlook.com"},"_npmVersion":"10.9.4","description":"CaTax CRS 命令行工具 - 客户数据导入与免密跳转","directories":{},"_nodeVersion":"22.21.1","dependencies":{"chalk":"^5.4.1","commander":"^13.1.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/catax-crs_1.1.0_1777533843584_0.6776247192521505","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@catax/catax-crs","version":"1.1.1","keywords":["catax","crs","customer","cli"],"author":{"name":"CaTax"},"license":"MIT","_id":"@catax/catax-crs@1.1.1","maintainers":[{"name":"coobeea","email":"coobeea@outlook.com"}],"bin":{"catax-crs":"bin/catax-crs.js"},"dist":{"shasum":"03e4f8ba04e2c4e124b00b1dccd5f2d8ab60f6fa","tarball":"https://registry.npmjs.org/@catax/catax-crs/-/catax-crs-1.1.1.tgz","fileCount":14,"integrity":"sha512-d00Ast85djByTpiy7dJjpeyqPWElITrsxwyaOmlMyYT2FtKKJvGbh2iAGROenCorZWjQrCLXDt6dsnU2ZLMMfQ==","signatures":[{"sig":"MEUCIGCerKnzaazewyj0fzpYouWzlbhEvle/xI9TOANViQrLAiEA/s+auTz1iPkbJJok5RCzfWAVp7Avb3GgTRrSG/SQJTo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":36125},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"f9b9a36be02bc7988fffca4e5c27e5f71bf73891","_npmUser":{"name":"coobeea","email":"coobeea@outlook.com"},"_npmVersion":"10.9.4","description":"CaTax CRS 命令行工具 - 客户数据导入与免密跳转","directories":{},"_nodeVersion":"22.21.1","dependencies":{"chalk":"^5.4.1","commander":"^13.1.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/catax-crs_1.1.1_1777536505289_0.6467952545232163","host":"s3://npm-registry-packages-npm-production"}},"1.1.2":{"name":"@catax/catax-crs","version":"1.1.2","description":"CaTax CRS 命令行工具 - 客户数据导入与免密跳转","type":"module","bin":{"catax-crs":"bin/catax-crs.js"},"engines":{"node":">=18.0.0"},"keywords":["catax","crs","customer","cli"],"author":{"name":"CaTax"},"license":"MIT","dependencies":{"chalk":"^5.4.1","commander":"^13.1.0"},"_id":"@catax/catax-crs@1.1.2","gitHead":"aa3b5034862e3f701cc6ec0c579c4b5ff1c98f35","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-XxhX4zV3TwLsUj+O7exHE9ri+8Mf1/YLuWXW8Ho0TqGRtnVIuHngLYNrFF54xdn9FXwmKFaLsLrp9mCidB2BiQ==","shasum":"cb56f9a5ad16f571ab9f442942f213828e0c8554","tarball":"https://registry.npmjs.org/@catax/catax-crs/-/catax-crs-1.1.2.tgz","fileCount":14,"unpackedSize":36145,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCXAK/f5iTUO6zkeRnSSTjZkHHX8XMl/qQk4OAUb96toAIhAM5C0ESMUsgJvyBaGcw3FwGPFLMg6y1bJFBeBJv/sERs"}]},"_npmUser":{"name":"coobeea","email":"coobeea@outlook.com"},"directories":{},"maintainers":[{"name":"coobeea","email":"coobeea@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/catax-crs_1.1.2_1777537364996_0.06176656643898282"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-12T09:35:35.800Z","modified":"2026-04-30T08:22:45.273Z","1.0.3":"2026-04-12T09:35:36.033Z","1.0.4":"2026-04-12T09:36:36.185Z","1.1.0":"2026-04-30T07:24:03.715Z","1.1.1":"2026-04-30T08:08:25.422Z","1.1.2":"2026-04-30T08:22:45.136Z"},"author":{"name":"CaTax"},"license":"MIT","keywords":["catax","crs","customer","cli"],"description":"CaTax CRS 命令行工具 - 客户数据导入与免密跳转","maintainers":[{"name":"coobeea","email":"coobeea@outlook.com"}],"readme":"# @catax/catax-crs 命令功能说明书\n\n本工具是基于 Node.js 开发的命令行接口（CLI）客户端，旨在将 CaTax CRS 系统的后端 API 接口封装为易于外部系统调用的命令行工具。\n核心能力包括：执行客户数据的批量导入、查询客户及其年度数据信息，以及生成前端免密跳转链接。\n\n**快速开始**：\n```bash\n# 1. 初始化配置（自动使用生产环境地址）\ncatax-crs init\n\n# 2. 开始使用\ncatax-crs client-list \"测试客户\"\ncatax-crs quick-link \"测试客户\" \"2024\"\n```\n\n**默认配置**：\n- 后端 API：`https://api.taxai.catax.cn`\n- 前端 Web：`http://boss.taxai.catax.cn`\n\n**快速入门**：查看 [使用示例文档](EXAMPLES.md) 了解更多配置和使用场景。\n\n## 1. 认证与鉴权\n\n所有业务命令在执行前，必须向服务端提供有效的 API Key 进行身份认证。\n\n**鉴权参数获取优先级：**\n1. 命令行参数：`--key <apiKey>`（每次执行时动态传入，优先级最高）\n2. 环境变量：`CATAX_CRS_API_KEY=<apiKey>`（适合在服务器/容器环境配置）\n3. 全局配置文件：`~/.catax/crs-config.json`（通过 `catax-crs init` 命令生成）\n\n**服务地址配置：**\n\n本工具**默认使用生产环境地址**，无需配置即可使用：\n\n- **后端 API 地址**（`apiBaseUrl`）：用于调用后端接口（导入、查询等）\n  - 默认值：`https://api.taxai.catax.cn`（生产环境）\n  - 命令行参数：`--api-url <apiBaseUrl>`（可选，用于本地开发）\n  - 配置文件字段：`apiBaseUrl`\n\n- **前端 Web 地址**（`webBaseUrl`）：用于生成浏览器跳转链接\n  - 默认值：`http://boss.taxai.catax.cn`（生产环境）\n  - 命令行参数：`--web-url <webBaseUrl>`（可选，用于本地开发）\n  - 配置文件字段：`webBaseUrl`\n\n**配置示例：**\n\n```bash\n# 1. 生产环境（默认地址，无需指定）\ncatax-crs init\n# 直接输入 API Key 即可，自动使用生产环境地址\n\n# 2. 本地开发环境（需要覆盖默认地址）\ncatax-crs init \\\n  --api-url http://127.0.0.1:8081 \\\n  --web-url http://127.0.0.1:8081\n\n# 3. 临时使用不同地址（不保存到配置文件）\ncatax-crs client-list \"测试\" \\\n  --api-url http://localhost:3000 \\\n  --web-url http://localhost:3000\n```\n\n**使用说明：**\n- 首次使用只需运行 `catax-crs init` 并输入 API Key\n- 默认连接生产环境，无需配置地址\n- 本地开发时才需要使用 `--api-url` 和 `--web-url` 参数\n\n---\n\n## 2. 核心命令集 (API 映射)\n\n本章节以功能说明的维度，详细列出工具提供的所有命令、参数定义及其底层映射的 API 行为。\n\n### 2.1 客户查询 (`client-list`)\n\n**功能描述**：查询当前用户权限下可访问的客户列表，主要用于获取客户的全局唯一标识（`clientId`）。\n\n**命令格式**：\n```bash\ncatax-crs client-list <clientName> [options]\n```\n\n**参数说明**：\n| 参数类型 | 名称 | 必填 | 说明 |\n|----------|------|------|------|\n| Positional | `<clientName>` | 是 | 用于模糊或精确匹配的客户名称 |\n| Option | `-p, --page <num>` | 否 | 分页查询的页码，默认为 `1` |\n| Option | `-s, --size <num>` | 否 | 分页查询的每页记录数，默认为 `10` |\n\n**适用场景**：\n在生成跳转链接之前，当外部系统只知道客户名称而不知道数据库中的 `clientId` 时，需通过此命令进行查询。\n*底层接口映射*：`POST /user-api/cap/client/list`\n\n### 2.2 客户年度查询 (`client-years`)\n\n**功能描述**：根据指定的客户 ID，查询该客户所有已创建的年度数据列表，主要用于获取年度标识（`yearId`）。\n\n**命令格式**：\n```bash\ncatax-crs client-years <clientId>\n```\n\n**参数说明**：\n| 参数类型 | 名称 | 必填 | 说明 |\n|----------|------|------|------|\n| Positional | `<clientId>` | 是 | 客户的全局唯一标识，通常由 `client-list` 命令获取 |\n\n**适用场景**：\n在明确客户后，需进一步确定目标数据所在的业务年度。获取的 `yearId` 将作为后续生成免密跳转链接的必要参数。\n*底层接口映射*：`GET /user-api/cap/client/years?clientId={clientId}`\n\n### 2.3 生成免密跳转链接 — 报告页 (`generate-link`)\n\n**功能描述**：向服务端申请单次有效（60秒内）的鉴权票据（`onceToken`），并将其与必要的业务参数拼接，生成一个可直接在浏览器中打开的系统直达链接，**落地页为申报报告页**。\n\n**命令格式**：\n```bash\ncatax-crs generate-link [options]\n```\n\n**参数说明**：\n| 参数类型 | 名称 | 必填 | 说明 |\n|----------|------|------|------|\n| Option | `-c, --client-id <id>` | 是 | 客户 ID。决定前端加载哪个客户的数据。 |\n| Option | `-y, --year-id <id>` | 是 | 年度 ID。决定前端加载哪个申报年度。 |\n| Option | `-n, --client-name <name>` | 是 | 客户名称。仅用于前端界面的顶部展示。 |\n| Option | `-Y, --year-name <name>` | 是 | 年度名称（如 \"2024\"）。仅用于前端界面的年份下拉框展示。 |\n\n**适用场景**：\n当外部系统或用户希望跳过常规的登录流程，直接从第三方平台跳转至 CaTax CRS 系统的特定客户申报报告页时使用。\n*底层接口映射*：\n1. `POST /user-api/system/login/apikey/login` (获取 `onceToken`)\n2. 构造前端 URL，并自动附加 `redirect=/service/overseasTaxMulti/report` 参数。\n\n### 2.4 生成免密跳转链接 — 数据管理页 (`generate-data-link`)\n\n**功能描述**：获取单次有效鉴权票据，生成免密直达链接，**落地页为境外收入数据管理总览页**（可查看所有已导入的客户数据列表）。\n\n**命令格式**：\n```bash\ncatax-crs generate-data-link\n```\n\n**参数说明**：\n无需任何参数。数据管理页为全局总览，不绑定特定客户或年度。\n\n**适用场景**：\n当管理员或运维人员需要快速打开数据管理后台，查看所有客户的导入状态和申报进度时使用。\n*底层接口映射*：\n1. `POST /user-api/system/login/apikey/login` (获取 `onceToken`)\n2. 构造前端 URL，并自动附加 `redirect=/service/overseasTaxMulti` 参数。\n\n### 2.5 数据导入 (`import`)\n\n**功能描述**：将符合 CaTax CRS 系统规范的客户数据 ZIP 包批量上传至服务端。\n\n**命令格式**：\n```bash\ncatax-crs import <zipFile>\n```\n\n**参数说明**：\n| 参数类型 | 名称 | 必填 | 说明 |\n|----------|------|------|------|\n| Positional | `<zipFile>` | 是 | 包含客户数据的 ZIP 压缩包的本地绝对或相对路径 |\n\n**适用场景**：\n定期从外部数据源（如 ERP 系统）导出数据后，通过该命令自动将数据同步至税务系统。\n*底层接口映射*：`POST /user-api/cap/overseas2-multi/batch-import` (multipart/form-data)\n\n---\n\n## 3. 调试工具 (`debug`)\n\n**功能描述**：用于开发人员排查接口调用异常，输出底层的原始 JSON 响应报文，不进行任何业务逻辑封装。\n\n**命令格式**：\n```bash\ncatax-crs debug --test <apiName> [options]\n```\n\n**支持的测试接口**：\n- `jwt`：测试 JWT Token 交换是否成功\n- `client-list`：测试客户查询接口（需附加 `--client-name`）\n- `client-years`：测试年度查询接口（需附加 `--client-id`）\n| `/user-api/cap/client/years` | GET | - | Header: `X-Token` | 查询客户年度 |\n| `/user-api/system/login/apikey/login` | POST | `application/x-www-form-urlencoded` | Form: `apiKey` | 获取前端跳转 onceToken |\n\n**认证说明**：\n- 步骤 1、5 使用 API Key 通过表单参数传递\n- 步骤 2、3、4 使用 JWT Token 通过 `X-Token` Header 传递\n\n**Content-Type 说明**：\n- Form 接口（步骤 1、3、5）：`application/x-www-form-urlencoded`\n- 文件上传接口（步骤 2）：`multipart/form-data`\n- GET 接口（步骤 4）：无需 Content-Type\n\n### 跳转链接格式\n\n**报告页链接**（`generate-link` 生成）：\n```\n<webBaseUrl>/#/apikey-login?onceToken=<token>&redirect=/service/overseasTaxMulti/report&clientId=<id>&yearId=<id>&clientName=<name>&yearName=<year>\n```\n\n**数据管理页链接**（`generate-data-link` 生成）：\n```\n<webBaseUrl>/#/apikey-login?onceToken=<token>&redirect=/service/overseasTaxMulti\n```\n\n**注意**：\n- `onceToken` 有效期为 **60 秒**\n- 每个 token **仅可使用一次**\n- 用户浏览器打开链接后，前端会自动完成登录并跳转\n- `onceToken` 从后端 API 地址获取，但跳转链接使用前端 Web 地址\n\n## 常见问题\n\n### Q: 提示 \"API Key 无效或缺失\"？\n\n**A**: 检查以下几点：\n1. 确认已执行 `catax-crs init` 或设置了环境变量\n2. API Key 格式正确（以 `cak_` 开头）\n3. API Key 未过期且有相应权限\n\n### Q: 导入失败怎么办？\n\n**A**: \n1. 确认 ZIP 文件包含 `client.json` 和数据文件\n2. 检查文件格式是否符合要求\n3. 查看详细错误信息，可能是数据格式问题\n\n### Q: 生成的链接打不开？\n\n**A**:\n1. 确认链接在 60 秒内打开\n2. 每个链接只能使用一次，需重新生成\n3. 确认服务地址配置正确：\n   - 后端 API 地址（`--api-url`）用于获取 token\n   - 前端 Web 地址（`--web-url`）用于生成跳转链接\n   - 如果前后端分离部署，需分别配置两个地址\n\n## 许可证\n\nMIT © CaTax\n","readmeFilename":"README.md"}