# VOC E-Commerce API 接口纪要

更新时间：2026-06-04

## 服务说明

`voc-e-commerce` 是电商数据代理服务，用来代理 JustOne API 的电商接口。调用方只访问平台自有接口，不直接暴露 JustOne 供应商地址和 token。

线上地址：

```text
https://server.fmode.cn/api/voc-e-commerce
```

本地地址：

```text
http://localhost:7337/api/voc-e-commerce
```

本地启动命令：

```bash
cd E:\workspace\server\future-server
node server.js --local --config ./config/config.nova.json
```

本地 `server.js` 实际加载的包：

```text
E:\workspace\server\future-server\.modules\voc-e-commerce.min.cjs
```

源码与构建产物位置：

```text
E:\workspace\server\future-server\fmode-server\modules\voc-e-commerce
E:\workspace\server\future-server\fmode-server\modules\voc-e-commerce\dist\0.1.0\voc-e-commerce.min.cjs
```

## 健康检查

```bash
curl "https://server.fmode.cn/api/voc-e-commerce/health"
```

返回示例：

```json
{
  "service": "voc-e-commerce",
  "timestamp": "2026-06-04T06:40:30.000Z"
}
```

测试路由：

```bash
curl "https://server.fmode.cn/api/voc-e-commerce/test"
```

## 业务接口调用方式

代理规则：

```text
/api/voc-e-commerce/{platform}/{upstreamPath}
```

例如 JustOne 上游路径：

```text
/api/taobao/search-item-list/v1
```

平台代理路径：

```text
/api/voc-e-commerce/taobao/search-item-list/v1
```

请求示例：

```bash
curl \
  -H "Authorization: Bearer <Parse sessionToken>" \
  "https://server.fmode.cn/api/voc-e-commerce/taobao/search-item-list/v1?keyword=葛根粉&page=1&company=<Company objectId>"
```

本地请求示例：

```bash
curl \
  -H "Authorization: Bearer <Parse sessionToken>" \
  "http://localhost:7337/api/voc-e-commerce/taobao/search-item-list/v1?keyword=local-test&page=1&company=<Company objectId>"
```

常用参数：

```text
keyword   搜索关键词，透传给上游
page      页码，透传给上游
company   Company objectId，用于匹配 APIGAuth 计费记录
isRefresh 可选，true 时跳过缓存并重新请求上游
```

响应结构：

```json
{
  "code": 200,
  "data": {
    "code": 0,
    "data": {
      "code": "SUCCESS",
      "model": {
        "itemList": [],
        "page": {}
      }
    }
  }
}
```

## 鉴权方式

业务接口需要传平台用户 sessionToken：

```text
Authorization: Bearer <Parse sessionToken>
```

当前鉴权服务读取以下位置：

```text
Authorization: Bearer xxx
body.token
x-api-key
```

注意：`X-Parse-Session-Token` 不会被 `AuthService.guardAuthToken` 当作业务接口鉴权 token 使用。

sessionToken 鉴权成功后会得到用户信息。若请求参数带 `company`，优先使用请求参数里的 company；否则使用 `authData.company.id` 或 `authData.user.company`。

## APIGAuth 计费逻辑

电商 API 对应的 APIG：

```text
APIG.path = /apig/voc-e-commerce
```

接口会查询 `APIGAuth`：

```text
优先按 api + user 查询用户级授权
用户级授权不存在或余额不足时，再按 api + company 查询公司级授权
```

查询方式已对齐平台现有 Parse SDK 查询习惯：`api`、`company`、`user` 查询值按对象 ID 字符串传入，不在业务代码里手动构造 Pointer。

说明：这次调整后，即使用户属于某个 company，只要该 user 自己有 `APIGAuth` 且余额充足，也会优先扣用户级余额。这样用户级付费记录可以生效；公司级余额作为兜底。

扣费规则：

```text
上游请求成功：count - 1，used + 1
缓存命中：count - 1，used + 1
余额不足或未开通：403
鉴权失败：401
```

403 返回示例：

```json
{
  "code": 403,
  "mess": "没有开通电商数据API权限或余额不足"
}
```

## 缓存逻辑

缓存表：

```text
VocECommerceCache
```

主要字段：

```text
uuid     稳定缓存 key
type     平台类型，例如 taobao
apiPath  代理路径，例如 taobao/search-item-list/v1
params   透传给上游的业务参数，不包含 company/isRefresh
result   上游返回结果
api      APIG Pointer
company  ownerId，目前保存 company objectId 字符串
```

缓存 key 由以下信息生成：

```text
ownerId + path + method + params
```

`ownerId` 使用实际扣费账套：优先为 user objectId，fallback 时为 company objectId。同一 owner、同一路径、同一方法、同一业务参数会命中同一缓存。命中缓存时不会重复请求上游，也不会重复保存缓存，但仍会扣费。

## 本地测试结果

本地启动命令：

```bash
cd E:\workspace\server\future-server
node server.js --local --config ./config/config.nova.json
```

测试结果：

```text
GET /api/voc-e-commerce/health => 200
GET /api/voc-e-commerce/test => 200
GET /api/voc-e-commerce/taobao/search-item-list/v1?keyword=local-fixed-test&page=1&company=<Company objectId> => 200
```

缓存扣费验证：

```text
第一次请求：APIGAuth count 14 -> 13，used 6 -> 7
第二次同参数请求：APIGAuth count 13 -> 12，used 7 -> 8
同 uuid 缓存记录数：1
```

## 线上测试结果

线上业务接口已验证通过：

```text
GET https://server.fmode.cn/api/voc-e-commerce/taobao/search-item-list/v1?keyword=online-fixed-test&page=1&company=<Company objectId>
=> 200
```

缓存扣费验证：

```text
请求前：count=11 used=9
重复同参数请求后：count=10 used=10
同 uuid 缓存记录数：1
```

说明：

```text
线上接口可用
上游 JustOne 正常返回
APIGAuth 查询正常
扣费正常
缓存命中也扣费
缓存没有重复保存
```

## 构建与发布注意事项

模块内构建：

```bash
cd E:\workspace\server\future-server\fmode-server\modules\voc-e-commerce
npm test
npm run build
```

构建产物：

```text
E:\workspace\server\future-server\fmode-server\modules\voc-e-commerce\dist\0.1.0\voc-e-commerce.min.cjs
```

本地 `server.js` 与线上部署使用的包路径是 `.modules` 下的 CJS 包。更新时需要确保替换：

```text
E:\workspace\server\future-server\.modules\voc-e-commerce.min.cjs
```

线上同理应替换服务实际加载的：

```text
.modules/voc-e-commerce.min.cjs
```

若只更新 `dist/0.1.0`，但没有同步 `.modules/voc-e-commerce.min.cjs`，`server.js` 不会加载到最新修复。

## 排查记录

曾遇到的问题：

```text
线上 health/test 正常，但业务接口 403
APIGAuth 数据存在且余额充足
```

原因：

```text
旧包中 APIGAuth 查询手动构造 Pointer：
query.equalTo("company", Pointer)
query.equalTo("api", Pointer)

需要对齐 voc-social-api 的查询方式，直接传对象 ID：
query.equalTo("company", company)
query.equalTo("api", apigId)
```

修复后，本地与线上均验证通过。

2026-06-05 追加排查：

```text
现象：某 user 维度 APIGAuth 有 1000+ 次余额，但请求仍扣 company 账套。
原因：旧逻辑在用户有 company 时把 userId 置空，只查 company APIGAuth。
修复：user APIGAuth 优先；user 不存在或余额不足时 fallback company APIGAuth。
测试：新增单测覆盖 user 授权优先、company fallback 两种路径。
```

## 安全说明

文档中不记录真实 masterKey、sessionToken、JustOne token。调试时从安全配置或临时沟通渠道获取，不建议写入仓库文档。