Acasă Explorează Ajutor
Autentificare
18307996893
/
Saas-voc
1
0
Bifurcare 0
Fisiere Probleme 0 Trageți solicitările 0 Wiki
Ramură: main
Ramuri Etichete
Saas-voc
/
tools
/
generate-jd-api-permissions-doc.mjs

generate-jd-api-permissions-doc.mjs 16 KB
Permalink Istoric Crud

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253 
  1. #!/usr/bin/env node
    2. 

  2. 

  3. import fs from 'node:fs/promises';
    4. 

  4. 

  5. const TABLES_FILE = new URL('../logs/jd-official-upgrade-tables-2026-08-24.json', import.meta.url);
    6. 

  6. const SP_PROBE_FILE = new URL('../logs/jd-sp-api-probe-2026-08-24.json', import.meta.url);
    7. 

  7. const JOS_PROBE_FILE = new URL('../logs/jd-jos-api-probe-2026-08-24.json', import.meta.url);
    8. 

  8. const DOC_FILE = new URL('../docs/JD-API-PERMISSIONS.md', import.meta.url);
    9. 

  9. 

  10. const escapeCell = (value) => String(value ?? '').replace(/\r?\n/g, ' ').replace(/\|/g, '\\|').trim();
    11. 

  11. const compact = (value, limit = 100) => {
    12. 

  12.   const text = escapeCell(value).replace(/\s+/g, ' ');
    13. 

  13.   return text.length > limit ? `${text.slice(0, limit)}…` : text;
    14. 

  14. };
    15. 

  15. 

  16. function parseOfficial(tables) {
    17. 

  17.   const endpoints = new Map();
    18. 

  18.   const mappingRows = [];
    19. 

  19.   for (const table of tables.filter((entry) => entry.ti >= 4 && entry.ti <= 11)) {
    20. 

  20.     let current = null;
    21. 

  21.     for (const cells of table.rows.slice(1)) {
    22. 

  22.       if (/^(GET|POST|PUT|PATCH|DELETE)\s/.test(cells[2] || '')) {
    23. 

  23.         const [method, ...rest] = cells[2].split(/\s+/);
    24. 

  24.         const path = `/${rest.join(' ')}`;
    25. 

  25.         current = {
    26. 

  26.           domain: cells[0] || '', subdomain: cells[1] || '', method, path,
    27. 

  27.           name: cells[3] || '', jos: [],
    28. 

  28.         };
    29. 

  29.         if (!endpoints.has(`${method} ${path}`)) endpoints.set(`${method} ${path}`, current);
    30. 

  30.         else current = endpoints.get(`${method} ${path}`);
    31. 

  31.       }
    32. 

  32.       if (!current) continue;
    33. 

  33.       const josApi = cells[4] || '';
    34. 

  34.       if (josApi) {
    35. 

  35.         const mapping = {
    36. 

  36.           domain: current.domain, spMethod: current.method, spPath: current.path, spName: current.name,
    37. 

  37.           josApi, josName: cells[5] || '', josCategory: cells[6] || '',
    38. 

  38.         };
    39. 

  39.         current.jos.push(mapping);
    40. 

  40.         mappingRows.push(mapping);
    41. 

  41.       }
    42. 

  42.     }
    43. 

  43.   }
    44. 

  44.   return { endpoints: [...endpoints.values()], mappingRows };
    45. 

  45. }
    46. 

  46. 

  47. function groupCount(rows, field) {
    48. 

  48.   const result = new Map();
    49. 

  49.   for (const row of rows) result.set(row[field], (result.get(row[field]) || 0) + 1);
    50. 

  50.   return [...result.entries()].sort((a, b) => b[1] - a[1]);
    51. 

  51. }
    52. 

  52. 

  53. function spResultTextSafe(result) {
    54. 

  54.   if (!result) return '未执行（非 GET）';
    55. 

  55.   if (result.status === '成功') return '成功（HTTP 200，`success: true`）';
    56. 

  56.   const code = result.code ? `，\`${escapeCell(result.code)}\`` : '';
    57. 

  57.   const message = result.message ? `，${compact(result.message, 64)}` : '';
    58. 

  58.   return `HTTP ${result.httpStatus}${code}${message}`;
    59. 

  59. }
    60. 

  60. 

  61. function josResultText(result) {
    62. 

  62.   const code = result.code ? `，\`${escapeCell(result.code)}\`` : '';
    63. 

  63.   const message = result.message ? `，${compact(result.message, 64)}` : '';
    64. 

  64.   return `${escapeCell(result.status)}（HTTP ${result.httpStatus}${code}${message}）`;
    65. 

  65. }
    66. 

  66. 

  67. const tables = JSON.parse(await fs.readFile(TABLES_FILE, 'utf8'));
    68. 

  68. const spProbe = JSON.parse(await fs.readFile(SP_PROBE_FILE, 'utf8'));
    69. 

  69. const josProbe = JSON.parse(await fs.readFile(JOS_PROBE_FILE, 'utf8'));
    70. 

  70. const official = parseOfficial(tables);
    71. 

  71. const spByKey = new Map(spProbe.results.map((row) => [`${row.method} ${row.path}`, row]));
    72. 

  72. const josByMethod = new Map(josProbe.results.map((row) => [row.josApi, row]));
    73. 

  73. const officialJosMethods = new Set(official.mappingRows.map((row) => row.josApi).filter((value) => /^jingdong\./.test(value)));
    74. 

  74. const testedOfficialJos = josProbe.results.filter((row) => officialJosMethods.has(row.josApi));
    75. 

  75. const extraJos = josProbe.results.filter((row) => !officialJosMethods.has(row.josApi));
    76. 

  76. const nonGet = official.endpoints.filter((row) => row.method !== 'GET');
    77. 

  77. 

  78. const spPassed = spProbe.results.filter((row) => row.status === '成功');
    79. 

  79. const spBlocked = spProbe.results.filter((row) => ['99904030008', '99904030005'].includes(row.code));
    80. 

  80. const spOther = spProbe.results.filter((row) => row.status !== '成功' && !['99904030008', '99904030005'].includes(row.code));
    81. 

  81. const josPassed = josProbe.results.filter((row) => row.status === '方法响应');
    82. 

  82. const josBlocked = josProbe.results.filter((row) => ['无接口调用权限', '要求云鼎调用'].includes(row.status));
    83. 

  83. const josOther = josProbe.results.filter((row) => !['方法响应', '无接口调用权限', '要求云鼎调用'].includes(row.status));
    84. 

  84. const endpointByKey = new Map(official.endpoints.map((row) => [`${row.method} ${row.path}`, row]));
    85. 

  85. 

  86. const lines = [];
    87. 

  87. lines.push('# 京东官方 API 接口权限实测清单');
    88. 

  88. lines.push('');
    89. 

  89. lines.push('> 测试日期：2026-08-24  ');
    90. 

  90. lines.push('> 配置来源：`docs/JD-CONNECTION-CONFIG.local.md`，店铺 Token 来源为 Parse `EcomAuth`。  ');
    91. 

  91. lines.push('> 官方清单来源：[京东 SP-API 升级说明](https://open.jd.com/v2/#/doc/api?apiCateId=200436&articleId=1100596&gwType=1)。');
    92. 

  92. lines.push('');
    93. 

  93. lines.push('## 1. 测试范围和结果');
    94. 

  94. lines.push('');
    95. 

  95. lines.push('| 接口体系 | 官方接口数 | 已实际请求 | 通过/返回方法响应 | 明确拒绝 | 其他错误 |');
    96. 

  96. lines.push('| --- | ---: | ---: | ---: | ---: | ---: |');
    97. 

  97. lines.push(`| SP-API | ${official.endpoints.length} | ${spProbe.results.length} | ${spPassed.length} | ${spBlocked.length} | ${spOther.length} |`);
    98. 

  98. lines.push(`| JOS 1.0 | ${officialJosMethods.size} 个官方映射方法 + ${extraJos.length} 个评价方法 | ${josProbe.results.length} | ${josPassed.length} | ${josBlocked.length} | ${josOther.length} |`);
    99. 

  99. lines.push('');
    100. 

  100. lines.push(`SP-API 的 ${official.endpoints.length} 个接口均已发起请求，包括 ${spProbe.results.filter((row) => row.method === 'GET').length} 个 GET 和 ${spProbe.results.filter((row) => row.method !== 'GET').length} 个非 GET。非 GET 使用占位路径参数和空 JSON 请求体执行，没有提交有效业务数据。`);
    101. 

  101. lines.push('');
    102. 

  102. lines.push('判定口径：');
    103. 

  103. lines.push('');
    104. 

  104. lines.push('- SP-API 返回 `success: true`：通过。');
    105. 

  105. lines.push('- JOS 返回对应方法响应对象，且未返回网关权限错误：方法已响应。');
    106. 

  106. lines.push('- `99904030008`、JOS `24/88`：明确无接口调用权限。');
    107. 

  107. lines.push('- `99904030005`、JOS `73`：明确要求云鼎调用。');
    108. 

  108. lines.push('- 参数错误或后端服务错误：本次未通过，不等同于已拥有完整业务调用能力。');
    109. 

  109. lines.push('');
    110. 

  110. lines.push('## 2. 未通过接口的申请条件和申请方式');
    111. 

  111. lines.push('');
    112. 

  112. lines.push('### 2.1 当前失败结果分别怎么处理');
    113. 

  113. lines.push('');
    114. 

  114. lines.push('| 实测结果 | 当前涉及范围 | 申请条件 | 申请入口与操作 |');
    115. 

  115. lines.push('| --- | --- | --- | --- |');
    116. 

  116. lines.push('| SP `99904030008`；JOS `24/88` | 商品、订单物流、售后、财务、会员、客服、商家、通用服务 | 当前应用类型和应用场景下，该接口权限包必须出现在应用概览页的“可申请”列表 | 开发者后台 → 应用中心 → 应用列表 → 当前应用 → 应用概览 → 权限包清单 → 申请；填写申请原因并提交 |');
    117. 

  117. lines.push('| SP `99904030005`；JOS `73` | 订单、部分售后、财务以及其他敏感接口 | 应用审核完成；使用与开放平台店铺主账号一致的京东账号激活京东云并完成企业实名认证；完成云鼎入驻和应用部署 | 先完成接口权限包申请，再进入云鼎入驻页选择“零售”提交申请；云鼎审核通过后在云鼎环境部署并调用 |');
    118. 

  118. lines.push('| SP `99904000013`、`99904000001` 及各业务参数错误码；JOS `61/400` | 本轮使用空请求体、占位 ID 或缺省参数的接口 | 这类响应是请求参数校验结果，本轮响应不能判定为缺少权限包 | 按具体接口文档补齐必填参数、有效业务 ID、场景字段和请求体后再次调用；不走权限包申请 |');
    119. 

  119. lines.push('| HTTP 503、JOS `65/67` | 商品、商家、通用等接口 | 本轮返回业务后端或服务异常，没有形成权限拒绝结论 | 使用完整参数复测；仍返回服务异常时，通过开放平台工单提交接口、时间和 requestId |');
    120. 

  120. lines.push('');
    121. 

  121. lines.push('### 2.2 普通接口权限包');
    122. 

  122. lines.push('');
    123. 

  123. lines.push('京东官方把权限包分为“默认开通”和“可申请”：');
    124. 

  124. lines.push('');
    125. 

  125. lines.push('- 默认开通：应用创建后直接拥有。');
    126. 

  126. lines.push('- 可申请：需要单独申请，运营审核通过后获得。');
    127. 

  127. lines.push('');
    128. 

  128. lines.push('申请步骤：');
    129. 

  129. lines.push('');
    130. 

  130. lines.push('1. 登录[京东开放平台开发者后台](https://open-console.jd.com/v2#/app/index)。');
    131. 

  131. lines.push('2. 进入“应用中心 → 应用列表”，点击当前应用。');
    132. 

  132. lines.push('3. 在应用概览页下方查看权限包清单。');
    133. 

  133. lines.push('4. 在“可申请”权限包上点击“申请”。');
    134. 

  134. lines.push('5. 填写申请原因并提交。');
    135. 

  135. lines.push('6. 官方记录的审核周期为 1—3 个工作日。');
    136. 

  136. lines.push('');
    137. 

  137. lines.push('如果所需接口在“已获得”和“可申请”中都不存在，官方给出的处理方式是提交工单，或加入咚咚群 `10220332728` 咨询。');
    138. 

  138. lines.push('');
    139. 

  139. lines.push('当前 `99904030008` 的 SP-API 分布：');
    140. 

  140. lines.push('');
    141. 

  141. lines.push('| 数据域 | 接口数 |');
    142. 

  142. lines.push('| --- | ---: |');
    143. 

  143. for (const [domain, count] of [...new Map(spProbe.results.filter((row) => row.code === '99904030008').reduce((items, row) => items.set(row.domain, (items.get(row.domain) || 0) + 1), new Map())).entries()].sort((a, b) => b[1] - a[1])) {
    144. 

  144.   lines.push(`| ${escapeCell(domain)} | ${count} |`);
    145. 

  145. }
    146. 

  146. lines.push('');
    147. 

  147. lines.push('### 2.3 云鼎敏感接口');
    148. 

  148. lines.push('');
    149. 

  149. lines.push('官方云鼎入驻条件和流程：');
    150. 

  150. lines.push('');
    151. 

  151. lines.push('1. 先在京东开放平台创建并完成应用审核；官方云鼎文档注明，自研应用审核完成后再执行云鼎入驻。');
    152. 

  152. lines.push('2. 与开放平台商家店铺主账号一致的京东账号，需要在京东云激活并完成企业实名认证。');
    153. 

  153. lines.push('3. 使用该账号进入[云鼎入驻页](https://yd.jdcloud.com/#/enter)，业务选择“零售”；官方记录的审核周期为 1—2 个工作日。');
    154. 

  154. lines.push('4. 审核通过后，在云鼎应用管理平台完成应用部署。');
    155. 

  155. lines.push('5. 按云鼎文档配置云资源；文档将对外提供 HTTP/HTTPS 的 Web 服务器、访问 JDO 敏感接口的应用服务器，以及存储敏感字段的云 RDS 列为基础部署资源。');
    156. 

  156. lines.push('6. 从云鼎环境重新调用订单、售后、财务等返回 `99904030005` / JOS `73` 的接口。');
    157. 

  157. lines.push('');
    158. 

  158. lines.push('当前 `99904030005` 的 SP-API 分布：');
    159. 

  159. lines.push('');
    160. 

  160. lines.push('| 数据域 | 接口数 |');
    161. 

  161. lines.push('| --- | ---: |');
    162. 

  162. for (const [domain, count] of [...new Map(spProbe.results.filter((row) => row.code === '99904030005').reduce((items, row) => items.set(row.domain, (items.get(row.domain) || 0) + 1), new Map())).entries()].sort((a, b) => b[1] - a[1])) {
    163. 

  163.   lines.push(`| ${escapeCell(domain)} | ${count} |`);
    164. 

  164. }
    165. 

  165. lines.push('');
    166. 

  166. lines.push('### 2.4 自营供应链接口的特殊流程');
    167. 

  167. lines.push('');
    168. 

  168. lines.push('京东官方注明：自营供应链接口权限除在应用的 API 权限管理中申请权限包外，还需要使用核心产品线账号向主采销发起邮件；采销邮件审核通过后，平台才审核开通。该流程只适用于自营供应链接口。');
    169. 

  169. lines.push('');
    170. 

  170. lines.push('### 2.5 服务对象和店铺授权前置条件');
    171. 

  171. lines.push('');
    172. 

  172. lines.push('- 自研 POP 应用需要添加 POP 店铺账号作为服务对象；自营应用需要添加供应商账号。');
    173. 

  173. lines.push('- 同一公司账号可自动审核；同一主体、同法人、同集团等关系需要提交关系证明，官方记录的人工审核时限为 1 个工作日。');
    174. 

  174. lines.push('- 服务对象绑定成功后才能执行店铺授权并获得 Token。当前项目已经取得有效 Token，此项不是本次商品接口成功/失败差异的阻断点。');
    175. 

  175. lines.push('');
    176. 

  176. lines.push('### 2.6 官方依据');
    177. 

  177. lines.push('');
    178. 

  178. lines.push('- [接口权限包申请](https://open.jd.com/v2/#/doc/guide?listId=1911)');
    179. 

  179. lines.push('- [开放平台新手指南](https://open.jd.com/v2/#/doc/begin-guide?listId=1900)');
    180. 

  180. lines.push('- [自研与 ISV 授权 Token 获取](https://open.jd.com/v2/#/doc/dev-guide?listId=1100981)');
    181. 

  181. lines.push('- [云鼎入驻流程](https://yd-doc.jdcloud.com/)');
    182. 

  182. lines.push('');
    183. 

  183. lines.push('## 3. 通过的接口');
    184. 

  184. lines.push('');
    185. 

  185. lines.push('### 3.1 SP-API：业务响应成功');
    186. 

  186. lines.push('');
    187. 

  187. lines.push('| 数据域 | 方法与路径 | 官方名称 | 结果 |');
    188. 

  188. lines.push('| --- | --- | --- | --- |');
    189. 

  189. for (const row of spPassed) lines.push(`| ${escapeCell(row.domain)} | \`${row.method} ${row.path}\` | ${escapeCell(row.name)} | HTTP ${row.httpStatus}，\`success: true\` |`);
    190. 

  190. lines.push('');
    191. 

  191. lines.push('### 3.2 JOS：方法已响应');
    192. 

  192. lines.push('');
    193. 

  193. lines.push('| 数据域 | JOS 方法 | 对应 SP-API | 结果 |');
    194. 

  194. lines.push('| --- | --- | --- | --- |');
    195. 

  195. for (const row of josPassed) {
    196. 

  196.   const sp = row.spPath ? `\`${row.spMethod} ${row.spPath}\`` : '商品评价旧接口';
    197. 

  197.   lines.push(`| ${escapeCell(row.domain)} | \`${escapeCell(row.josApi)}\` | ${sp} | HTTP ${row.httpStatus}，返回方法响应对象 |`);
    198. 

  198. }
    199. 

  199. lines.push('');
    200. 

  200. lines.push('## 4. 未通过的 SP-API');
    201. 

  201. lines.push('');
    202. 

  202. lines.push('### 4.1 明确被京东网关拒绝');
    203. 

  203. lines.push('');
    204. 

  204. lines.push('| 数据域 | 方法与路径 | 官方名称 | 实测结果 |');
    205. 

  205. lines.push('| --- | --- | --- | --- |');
    206. 

  206. for (const row of spBlocked) lines.push(`| ${escapeCell(row.domain)} | \`${row.method} ${row.path}\` | ${escapeCell(row.name)} | ${spResultTextSafe(row)} |`);
    207. 

  207. lines.push('');
    208. 

  208. lines.push('### 4.2 参数或服务错误，本次未成功');
    209. 

  209. lines.push('');
    210. 

  210. lines.push('| 数据域 | 方法与路径 | 官方名称 | 实测结果 |');
    211. 

  211. lines.push('| --- | --- | --- | --- |');
    212. 

  212. for (const row of spOther) lines.push(`| ${escapeCell(row.domain)} | \`${row.method} ${row.path}\` | ${escapeCell(row.name)} | ${spResultTextSafe(row)} |`);
    213. 

  213. lines.push('');
    214. 

  214. lines.push('## 5. 未通过的 JOS 接口');
    215. 

  215. lines.push('');
    216. 

  216. lines.push('### 5.1 明确无权限或要求云鼎');
    217. 

  217. lines.push('');
    218. 

  218. lines.push('| 数据域 | JOS 方法 | 对应 SP-API | 实测结果 |');
    219. 

  219. lines.push('| --- | --- | --- | --- |');
    220. 

  220. for (const row of josBlocked) {
    221. 

  221.   const sp = row.spPath ? `\`${row.spMethod} ${row.spPath}\`` : '无对应 SP 路径';
    222. 

  222.   lines.push(`| ${escapeCell(row.domain)} | \`${escapeCell(row.josApi)}\` | ${sp} | ${josResultText(row)} |`);
    223. 

  223. }
    224. 

  224. lines.push('');
    225. 

  225. lines.push('### 5.2 参数或服务错误，本次未成功');
    226. 

  226. lines.push('');
    227. 

  227. lines.push('| 数据域 | JOS 方法 | 对应 SP-API | 实测结果 |');
    228. 

  228. lines.push('| --- | --- | --- | --- |');
    229. 

  229. for (const row of josOther) {
    230. 

  230.   const sp = row.spPath ? `\`${row.spMethod} ${row.spPath}\`` : '无对应 SP 路径';
    231. 

  231.   lines.push(`| ${escapeCell(row.domain)} | \`${escapeCell(row.josApi)}\` | ${sp} | ${josResultText(row)} |`);
    232. 

  232. }
    233. 

  233. lines.push('');
    234. 

  234. lines.push('## 6. 项目内已经实现的京东调用');
    235. 

  235. lines.push('');
    236. 

  236. lines.push('| 项目位置 | 京东接口 | 用途 |');
    237. 

  237. lines.push('| --- | --- | --- |');
    238. 

  238. lines.push('| `tools/jd-import-products.mjs` | `GET /sp-product/v0/products` | 商品分页读取 |');
    239. 

  239. lines.push('| `tools/jd-import-products.mjs` | `GET /sp-product/v0/skus` | SKU 读取 |');
    240. 

  240. lines.push('| `tools/jd-import-products.mjs` | `GET /sp-product/v0/sku-stocks` | SKU 库存读取 |');
    241. 

  241. lines.push('| `tools/jd-import-products.mjs` | `GET /sp-product/v0/products/{productId}` | 商品详情读取 |');
    242. 

  242. lines.push('| `Saas-voc-server/scripts/sync-jd-listings.ts` | 商品列表、商品详情 | Listing 全量同步 |');
    243. 

  243. lines.push('');
    244. 

  244. lines.push('## 7. 测试文件');
    245. 

  245. lines.push('');
    246. 

  246. lines.push('- `logs/jd-official-upgrade-tables-2026-08-24.json`');
    247. 

  247. lines.push('- `logs/jd-sp-api-probe-2026-08-24.json`');
    248. 

  248. lines.push('- `logs/jd-jos-api-probe-2026-08-24.json`');
    249. 

  249. lines.push('- `tools/jd-api-permission-probe.mjs`');
    250. 

  250. lines.push('- `tools/jd-jos-api-permission-probe.mjs`');
    251. 

  251. 

  252. await fs.writeFile(DOC_FILE, `${lines.join('\n')}\n`, 'utf8');
    253. 

  253. console.log(`Generated ${DOC_FILE.pathname}: ${official.endpoints.length} SP endpoints, ${official.mappingRows.length} mapping rows.`);
    254.