voc-e-commerce-api-notes.md 7.1 KB
VOC E-Commerce API 接口纪要
更新时间：2026-06-04
服务说明
voc-e-commerce 是电商数据代理服务，用来代理 JustOne API 的电商接口。调用方只访问平台自有接口，不直接暴露 JustOne 供应商地址和 token。
线上地址：
https://server.fmode.cn/api/voc-e-commerce
本地地址：
http://localhost:7337/api/voc-e-commerce
本地启动命令：
cd E:\workspace\server\future-server
node server.js --local --config ./config/config.nova.json
本地 server.js 实际加载的包：
E:\workspace\server\future-server\.modules\voc-e-commerce.min.cjs
源码与构建产物位置：
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
健康检查
curl "https://server.fmode.cn/api/voc-e-commerce/health"
返回示例：
{
"service": "voc-e-commerce",
"timestamp": "2026-06-04T06:40:30.000Z"
}
测试路由：
curl "https://server.fmode.cn/api/voc-e-commerce/test"
业务接口调用方式
代理规则：
/api/voc-e-commerce/{platform}/{upstreamPath}
例如 JustOne 上游路径：
/api/taobao/search-item-list/v1
平台代理路径：
/api/voc-e-commerce/taobao/search-item-list/v1
请求示例：
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>"
本地请求示例：
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>"
常用参数：
keyword 搜索关键词，透传给上游
page 页码，透传给上游
company Company objectId，用于匹配 APIGAuth 计费记录
isRefresh 可选，true 时跳过缓存并重新请求上游
响应结构：
{
"code": 200,
"data": {
"code": 0,
"data": {
"code": "SUCCESS",
"model": {
"itemList": [],
"page": {}
}
}
}
}
鉴权方式
业务接口需要传平台用户 sessionToken：
Authorization: Bearer <Parse sessionToken>
当前鉴权服务读取以下位置：
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：
APIG.path = /apig/voc-e-commerce
接口会查询 APIGAuth：
优先按 api + user 查询用户级授权
用户级授权不存在或余额不足时，再按 api + company 查询公司级授权
查询方式已对齐平台现有 Parse SDK 查询习惯：api、company、user 查询值按对象 ID 字符串传入，不在业务代码里手动构造 Pointer。
说明：这次调整后，即使用户属于某个 company，只要该 user 自己有 APIGAuth 且余额充足，也会优先扣用户级余额。这样用户级付费记录可以生效；公司级余额作为兜底。
扣费规则：
上游请求成功：count - 1，used + 1
缓存命中：count - 1，used + 1
余额不足或未开通：403
鉴权失败：401
403 返回示例：
{
"code": 403,
"mess": "没有开通电商数据API权限或余额不足"
}
缓存逻辑
缓存表：
VocECommerceCache
主要字段：
uuid 稳定缓存 key
type 平台类型，例如 taobao
apiPath 代理路径，例如 taobao/search-item-list/v1
params 透传给上游的业务参数，不包含 company/isRefresh
result 上游返回结果
api APIG Pointer
company ownerId，目前保存 company objectId 字符串
缓存 key 由以下信息生成：
ownerId + path + method + params
ownerId 使用实际扣费账套：优先为 user objectId，fallback 时为 company objectId。同一 owner、同一路径、同一方法、同一业务参数会命中同一缓存。命中缓存时不会重复请求上游，也不会重复保存缓存，但仍会扣费。
本地测试结果
本地启动命令：
cd E:\workspace\server\future-server
node server.js --local --config ./config/config.nova.json
测试结果：
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
缓存扣费验证：
第一次请求：APIGAuth count 14 -> 13，used 6 -> 7
第二次同参数请求：APIGAuth count 13 -> 12，used 7 -> 8
同 uuid 缓存记录数：1
线上测试结果
线上业务接口已验证通过：
GET https://server.fmode.cn/api/voc-e-commerce/taobao/search-item-list/v1?keyword=online-fixed-test&page=1&company=<Company objectId>
=> 200
缓存扣费验证：
请求前：count=11 used=9
重复同参数请求后：count=10 used=10
同 uuid 缓存记录数：1
说明：
线上接口可用
上游 JustOne 正常返回
APIGAuth 查询正常
扣费正常
缓存命中也扣费
缓存没有重复保存
构建与发布注意事项
模块内构建：
cd E:\workspace\server\future-server\fmode-server\modules\voc-e-commerce
npm test
npm run build
构建产物：
E:\workspace\server\future-server\fmode-server\modules\voc-e-commerce\dist\0.1.0\voc-e-commerce.min.cjs
本地 server.js 与线上部署使用的包路径是 .modules 下的 CJS 包。更新时需要确保替换：
E:\workspace\server\future-server\.modules\voc-e-commerce.min.cjs
线上同理应替换服务实际加载的：
.modules/voc-e-commerce.min.cjs
若只更新 dist/0.1.0，但没有同步 .modules/voc-e-commerce.min.cjs，server.js 不会加载到最新修复。
排查记录
曾遇到的问题：
线上 health/test 正常，但业务接口 403
APIGAuth 数据存在且余额充足
原因：
旧包中 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 追加排查：
现象：某 user 维度 APIGAuth 有 1000+ 次余额，但请求仍扣 company 账套。
原因：旧逻辑在用户有 company 时把 userId 置空，只查 company APIGAuth。
修复：user APIGAuth 优先；user 不存在或余额不足时 fallback company APIGAuth。
测试：新增单测覆盖 user 授权优先、company fallback 两种路径。
安全说明
文档中不记录真实 masterKey、sessionToken、JustOne token。调试时从安全配置或临时沟通渠道获取，不建议写入仓库文档。