diff --git a/methods/changes/system.json b/methods/changes/system.json index cb92dd1..22c1576 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,233 @@ [ + { + "version": "2026.09.23-returnReceived-create-is-urgent", + "date": "2026-09-23", + "type": "updated", + "summary": "returnReceived.create 响应新增 is_urgent 加急标记(boolean):wms_return_query_log(退回查询记录表)按 仓库+运单号 精确匹配,命中即 true,未命中或查询失败降级为 false;幂等命中(duplicated=true)与新创建(duplicated=false)两个分支均返回该字段", + "methods": [ + "returnReceived.create" + ], + "notes": [ + "代码变更:app/service/systems/return_received.js 的 create 在幂等命中与新登记两个返回分支均新增顶层 is_urgent 字段,并新增私有辅助方法 _isUrgentReturnQuery(waybillCode, warehouseId)(含 JSDoc)", + "判定口径:wms_return_query_log(退回查询记录表)中存在 warehouse_id=当前仓库且 waybill_code=登记运单号(精确匹配)的记录时为 true,否则 false;查询失败降级为 false,不影响登记主流程", + "方法层 app/service/systemMethods/returnReceived.js 无需改动;文档变更:response 新增 is_urgent(boolean,required=true);维护源 wms_method_doc_meta 与导出产物 methods/system.json 版本同步至 0.3.176(dashboard.hot_order_rank mask 变更同步入库 0.3.175,本次变更升至 0.3.176)" + ], + "module": "returnReceived" + }, + { + "version": "2026.09.23-dashboard.hot_order_rank.mask", + "date": "2026-09-23", + "type": "updated", + "summary": "dashboard.hot_order_rank 响应口径调整:data[].sku 由商品编码改为库存商品ID(stock_warehouse.id);data[].name 做脱敏处理(前2字符+***+后2字符,长度不足 4 字符时返回 ***)", + "methods": [ + "dashboard.hot_order_rank" + ], + "notes": [ + "代码变更:app/service/systemMethods/dashboard.js 中 buildHotOrderRankMap/mergeHotOrderRank 的聚合条目新增 stockId(订单明细 stock_id),并在货主端跨仓合并时保留首个非 0 值", + "代码变更:resolveHotOrderRankProduct 的 sku 改为返回库存商品ID(number,stock_warehouse.id),仅当 stock_id 缺失时回退商品编码字符串;新增 maskHotOrderRankName 对最终展示名称统一脱敏(长度>=4 时前2字符+***+后2字符,否则返回 ***)", + "文档变更:data[].sku 类型改为 number 并更新描述;data[].name 描述补充脱敏规则;根版本 0.3.174 -> 0.3.175" + ], + "module": "dashboard" + }, + { + "version": "2026.09.23-returnReceived-list-created-at-filter", + "date": "2026-09-23", + "type": "updated", + "summary": "修复 returnReceived.list 登记时间(created_at)筛选不生效问题:_buildListWhere 白名单补充 created_at/updated_at,并补齐文档此前缺失但代码已支持的 where 字段(scanner_name/order_express_id/order_id);returnReceived.export 的 where 语义描述同步更新(与 list 一致)。配套新增 wms_return_received 索引 idx_warehouse_created_at(warehouse_id, created_at)(迁移 20260923180000),优化登记时间范围过滤与默认 created_at desc 排序。", + "methods": [ + "returnReceived.list", + "returnReceived.export" + ], + "notes": [ + "代码变更:app/service/systems/return_received.js _buildListWhere 的 directFields 白名单补充 created_at、updated_at(list 与 exportList 同时生效)", + "数据库变更:database/migrations/20260923180000-add-created-at-index-to-wms-return-received.js 新增 idx_warehouse_created_at(warehouse_id, created_at),已在开发库执行", + "文档变更:returnReceived.list 新增 where.created_at / where.updated_at / where.scanner_name / where.order_express_id / where.order_id 参数说明,description 更新;returnReceived.export 的 where 参数描述补充 created_at/updated_at 范围", + "文档库版本 0.3.173 -> 0.3.174(wms_method_doc_meta.version),methods/system.json 为导出产物" + ] + }, + { + "version": "2026.09.23-dashboard.hot_order_rank.realtime", + "date": "2026-09-23", + "type": "updated", + "summary": "dashboard.hot_order_rank 由演示数据改为真实数据库查询:统计今日(00:00 至当前时刻)销量 Top10 商品及环比昨日趋势;仓库端单仓统计,货主端跨已签约仓库聚合", + "methods": [ + "dashboard.hot_order_rank" + ], + "notes": [ + "核实 app/service/systemMethods/dashboard.js 实现后更新:废弃旧版 mock 数据,改为查询订单常用表/配送分表(OrderDeliveryFactory/OrderItemsFactory 的 current 与 dispatch)聚合", + "口径:今日窗口 [今日 00:00, 当前时刻),昨日窗口 [昨日 00:00, 今日 00:00);value 为窗口内非取消、非异常、未删除订单的商品计划数量(plan_qty)合计;trend 为环比昨日百分比(保留 1 位小数,昨日为 0 且今日 >0 时按 100)", + "仓库端使用 ctx.user.store_id 单仓统计;货主端(store_type=store)跨已签约仓库(auth_status=2)并行统计并按商品聚合;按今日销量降序取前 10 条,无数据时返回空数组", + "响应更新:data[].name 无名称回退商品编码/商品+库存ID、data[].sku 无编码回退 SKU+库存ID;错误码补充 code=0(缺少仓库/货主上下文),500 改为订单数据查询失败", + "文档库表同步:method-doc-update.cjs 更新 description/response/errors 并 --bump,method-doc-export.cjs 回写 methods/system.json" + ], + "module": "dashboard" + }, + { + "version": "2026.09.23-dashboard.charts.doc", + "date": "2026-09-23", + "type": "updated", + "summary": "补齐看板模块其余 5 个接口文档:express_ratio/platform_distribution/order_trend 为实时统计接口,warehouseStats/hot_order_rank 为演示数据接口(描述已标注);均无业务入参", + "methods": [ + "dashboard.express_ratio", + "dashboard.platform_distribution", + "dashboard.order_trend", + "dashboard.warehouseStats", + "dashboard.hot_order_rank" + ], + "notes": [ + "核实 app/service/systemMethods/dashboard.js 实现后补齐", + "express_ratio/platform_distribution 货主端跨已签约仓库(auth_status=2)汇总,返回 name/value/itemStyle.color 结构", + "order_trend 按小时统计 08:00 至当前小时,返回 summary/categories/orders/shipments", + "warehouseStats/hot_order_rank 当前为固定演示数据,待业务接入真实统计后需同步更新文档" + ] + }, + { + "version": "2026.09.23-dashboard.storeStats.doc", + "date": "2026-09-23", + "type": "updated", + "summary": "补齐 dashboard.storeStats 接口文档:补充描述、13 个响应统计字段与错误码(无业务入参,依据登录用户上下文区分仓库端/货主端)", + "methods": [ + "dashboard.storeStats" + ], + "notes": [ + "核实 app/service/systemMethods/dashboard.js 实现后补齐", + "仓库端按当前用户 store_id 单仓统计;货主端跨已签约仓库(auth_status=2)汇总" + ] + }, + { + "version": "2026.09.23-index.tryAutoTranslateNewKeys.doc", + "date": "2026-09-23", + "type": "updated", + "summary": "补全 index.tryAutoTranslateNewKeys 文档:明确其为 putI18nCollect 的内部辅助方法,补充 project/targetLanguage 参数说明,注明无对外返回值、异常仅记日志、不建议作为 HTTP API 直接调用", + "methods": [ + "index.tryAutoTranslateNewKeys" + ], + "notes": [ + "代码事实:app/service/systemMethods/index.js:1512 async tryAutoTranslateNewKeys(project, targetLanguage),仅被 putI18nCollect(1451 行)内部调用;目标语言为 zh-CN 直接返回;为 zh-CN 已有翻译的键批量创建目标语言占位(translation=null、translation_status=0、auto_generated=1、translator=auto-translate);无返回值,异常被内部 try/catch 吞掉仅记日志。", + "文档库表同步:method-doc-update.cjs 更新 description/params 并 --bump(版本 0.3.169 -> 0.3.170),method-doc-export.cjs 回写 methods/system.json(562 个方法)。", + "说明:/system 通用分发不区分 public 与内部函数,该方法理论上可被直接调用,文档已注明不建议直接调用。" + ], + "module": "index" + }, + { + "version": "2026.09.23-wechat.dropAgreementVersionNumber", + "date": "2026-09-23", + "type": "updated", + "summary": "用户须知版本表去掉 version 数字版本号,直接使用 id 自增:最新版判定改 ORDER BY id DESC,提交即插入新行(去掉 max+1 与并发重试),接口响应只保留 version_id", + "methods": [ + "wechat.getUserAgreementText", + "wechat.getUserAgreement", + "wechat.setUserAgreement", + "wechat.getAgreementVersion", + "wechat.loginByCode" + ], + "notes": [ + "迁移 20260923140000-drop-version-from-wechat-agreement-version(开发+生产均执行):removeIndex uk_appid_version + removeColumn version;down 为加回列与唯一索引。同步 app/model/wechat_agreement_version.js 删 version 字段与唯一索引(仅保留 idx_appid)。", + "最新版判定统一为 ORDER BY id DESC(loginByCode/getUserAgreementText/getUserAgreement/findLatestAgreementVersion/cleanupUnusedAgreementVersions 的最终版=max(id));setUserAgreement 改为直接 create(appid+content),无并发重试;getUserAgreementText 缓存 JSON 仅 {version_id,text}。", + "接口响应精简:getUserAgreementText/getUserAgreement/setUserAgreement 去掉 version 字段、getAgreementVersion 去掉 version 字段,均保留 version_id(=记录 id)。" + ], + "module": "wechat" + }, + { + "version": "2026.09.23-wechat.getAgreementVersion", + "date": "2026-09-23", + "type": "added", + "summary": "新增 wechat.getAgreementVersion(按协议版本 id 获取协议内容,需登录免权限+校验仓库);wechat.userList 响应新增 agreement_version_id(协议id)", + "methods": [ + "wechat.getAgreementVersion", + "wechat.userList" + ], + "notes": [ + "wechat.getAgreementVersion:入参 id(wms_wechat_agreement_version.id,来源 userList 的 agreement_version_id),按 id 查版本 → 校验该版本 appid 属于当前仓库启用小程序(warehouse_id=ctx.user.store_id, is_enabled=1),不属于则提示「该协议版本不属于当前仓库的小程序」;返回 id/appid/nickname/version/text/created_at。需登录免权限(systemInit 第2/4参)。", + "wechat.userList:响应行新增 agreement_version_id(数值化,null 保持 null),sortField 白名单新增 agreement_version_id;该字段由 loginByCode 自动回写,供前端按版本 id 拉取协议内容。", + "代码变更:app/service/systems/wechat.js 新增 getAgreementVersion + userList 响应数值化/排序白名单;app/service/systemMethods/wechat.js 白名单与出口同步。" + ], + "module": "wechat" + }, + { + "version": "2026.09.23-wechat.agreementVersionCleanup", + "date": "2026-09-23", + "type": "updated", + "summary": "新增定时任务:每 1 小时扫描 wms_wechat_agreement_version,真实删除未使用且非对应 appid 最终版的历史版本,释放 MySQL 磁盘", + "methods": [], + "notes": [ + "保留规则:① 各 appid 的最终版(version 最大)永久保留;② 被 wms_user_oauth.agreement_version_id 引用的版本保留(老用户仍停留在旧协议);其余版本真实删除(模型 paranoid=false)。", + "触发:app/schedule/wechat_agreement_cleanup.js,cron 从 config.wechatAgreementCleanup.cron 读取(默认 0 0 * * * * = 每 1 小时整点,type=worker 单 worker 防重入,enable=false 不注册);清理逻辑收敛在 service.systems.wechat.cleanupUnusedAgreementVersions(batchSize 默认 500,按 id 分批删走主键索引)。", + "每次任务完成后输出日志:deleted/kept_latest/kept_in_use/total;失败仅记 error 日志不抛出。" + ], + "module": "wechat" + }, + { + "version": "2026.09.23-wechat.userAgreement.versioning", + "date": "2026-09-23", + "type": "updated", + "summary": "用户须知改为副表版本管理:移除 wms_wechat_app.user_agreement;新增 wms_wechat_agreement_version(appid+数字版本号+富文本,提交一次自动新增版本,拉取只取最新);wms_user_oauth 加 agreement_version_id,loginByCode 自动更新到最新协议版本", + "methods": [ + "wechat.getUserAgreementText", + "wechat.getUserAgreement", + "wechat.setUserAgreement", + "wechat.loginByCode" + ], + "notes": [ + "迁移 20260923130000-user-agreement-versioning(开发+生产均执行):① removeColumn wms_wechat_app.user_agreement;② createTable wms_wechat_agreement_version(id/appid/version INT/content LONGTEXT/时间戳,uk_appid_version(appid,version) 唯一 + idx_appid);③ addColumn wms_user_oauth.agreement_version_id(BIGINT UNSIGNED 可空,关联版本表 id)。同步 app/model/wechat_agreement_version.js 新增、wechat_app.js/user_oauth.js 字段同步。", + "wechat.setUserAgreement:提交一次自动新增版本——查该 appid 最大 version 后 +1 插入(并发撞唯一键时重算重试最多 3 次),成功后 cacheDel 清 24h 缓存;返回 version_id/version/text。", + "wechat.getUserAgreementText/getUserAgreement:拉取只拉最新版本(ORDER BY version DESC);getUserAgreementText 缓存 24h 存 JSON {version_id,version,text},命中 from_cache=true;无版本分别提示「未找到对应小程序或该小程序暂无用户须知」/「该小程序暂无用户须知」。", + "wechat.loginByCode:查该小程序 appid 最新协议版本 id,oauth 新增/更新时自动写入 agreement_version_id(无需前端传入,为空版本表时为 null)。", + "代码变更:app/service/systems/wechat.js loginByCode/getUserAgreementText/getUserAgreement/setUserAgreement 改版并新增 findLatestAgreementVersion;systemMethods 无签名变化。" + ], + "module": "wechat" + }, + { + "version": "2026.09.23-wechat.userAgreement", + "date": "2026-09-23", + "type": "added", + "summary": "新增用户须知三接口:wms_wechat_app 加 user_agreement(LONGTEXT)字段;wechat.getUserAgreementText(免登录,appId 查询 + 24h Redis 缓存)、wechat.getUserAgreement(需登录,当前仓库)、wechat.setUserAgreement(需登录,更新并清缓存)", + "methods": [ + "wechat.getUserAgreementText", + "wechat.getUserAgreement", + "wechat.setUserAgreement" + ], + "notes": [ + "迁移 20260923120000-add-user-agreement-to-wms-wechat-app:wms_wechat_app 仅加 user_agreement 字段(Sequelize TEXT('long') = LONGTEXT,allowNull,comment 用户须知富文本),同步 app/model/wechat_app.js。开发+生产均需执行(生产:$env:NODE_ENV='production'; npx sequelize-cli db:migrate --migrations-path database/migrations --env production)。", + "wechat.getUserAgreementText:免登录(systemInit 第1参),入参 appId;Redis key wechat:userAgreement:{appid},TTL 24h,命中直接返回 from_cache=true;未命中查 wms_wechat_app.user_agreement 并回写缓存;无该 appid 返回「未找到对应小程序」。", + "wechat.getUserAgreement/setUserAgreement:需登录免权限(systemInit 第2/4参),按 ctx.user.store_id 取启用小程序(is_enabled=1),无则提示「无小程序,需要先绑定」;set 校验 text 为字符串(可空串清空)→ update 后 cacheDel 清除 24h 缓存。", + "代码变更:app/service/systems/wechat.js 新增 getUserAgreementText/getUserAgreement/setUserAgreement/findWarehouseWechatApp;app/service/systemMethods/wechat.js 白名单与出口同步。" + ], + "module": "wechat" + }, + { + "version": "2026.09.23-wechat.bindByEmployee", + "date": "2026-09-23", + "type": "added", + "summary": "新增 wechat.bindByEmployee:管理员按工号绑定微信(需登录需权限),传工号 id + 微信绑定记录 id,查工号账号 id 写入 wms_user_oauth.user_id", + "methods": [ + "wechat.bindByEmployee" + ], + "notes": [ + "新增接口 wechat.bindByEmployee(需登录需权限,区别于中间层 wechat.bindUser 的用户名密码自绑定):入参 id(工号 id=wms_account_store_employee.id,必填正整数)与 oauth_id(微信绑定记录 id=wms_user_oauth.id,必填正整数,来自 wechat.userList 结果)。", + "业务:工号存在且 status=1 → account_id;工号须属于当前仓库(store_id=ctx.user.store_id);oauth 须存在、provider=wechat、未绑定或已绑定同一账号(已绑其他账号拒绝换绑);oauth.app_id 存在时校验对应 wms_wechat_app 属于当前仓库;账号存在且 status=1。校验通过后 wms_user_oauth.user_id=account_id,幂等返回 already_bound。不签发 token。", + "鉴权:不加入 systemInit 任何白名单 → 需正常登录 token 且需 wms_permission 接口权限(path=wechat.bindByEmployee,type=api,需在开发库插入该权限记录并由管理员在角色中勾选后生效)。", + "代码变更:app/service/systems/wechat.js 新增 bindByEmployee;app/service/systemMethods/wechat.js 新增 bindByEmployee 出口。" + ], + "module": "wechat" + }, + { + "version": "2026.09.23-wechat.wxaauth-new-api", + "date": "2026-09-23", + "type": "updated", + "summary": "wechat.wxaauth 迁移到微信新版认证接口:旧接口 /wxa/sec/wxaapi/wxaauth、/wxa/sec/wxaapi/uploadmedia 已下线(40066 invalid url),改为 POST /wxa/sec/wxaauth(auth_data 包裹)+ POST /wxa/sec/uploadauthmaterial(mediaid)", + "methods": [ + "wechat.wxaauth" + ], + "notes": [ + "根因:微信下线旧版小程序认证接口,调用 /wxa/sec/wxaapi/wxaauth 与 /wxa/sec/wxaapi/uploadmedia 返回 40066 invalid url(与 queryauth 当年同因:路径不存在,详见 2026.09.22-wechat.queryauth-fix 记录)。", + "发起认证改为 POST /wxa/sec/wxaauth,请求体 { auth_data }:customer_type(1 企业/12 个体户/15 个人)、account_name、account_name_type(1 自选词汇/2 商标)、pay_type(1 服务商预购包/2 自行支付)、third_party_phone、contact_info{name,email,mobile?} 必填;invoice_info/qualification/qualification_other(≤10)/account_supplemental/auth_identification/auth_ident_material/service_appid(代缴必填)/taskid 可选。", + "上传材料改为 POST /wxa/sec/uploadauthmaterial(multipart media=文件,图片 ≤2M,PNG/JPEG/JPG/GIF),返回 mediaid(lib 层归一化为 media_id)。自动换 mediaid 的图片字段:qualification(单张)、qualification_other[]/account_supplemental[]/auth_ident_material[](数组),支持传 COS URL。", + "破坏性变更:入参由旧扁平字段(contact_type/contact_name/contact_cert_photo/business_license_*/legal_persona_*/pic_list/qualification_list/statement_list 等 33 字段白名单)改为新版 auth_data 字段,前端需同步切换。打回重填走新接口 POST /wxa/sec/reauth(同 auth_data + taskid,暂未接入,可后续补 wechat.reauth)。", + "代码变更:app/lib/wechat_open_client.js wxaauth/uploadAuthMedia 路径与 mediaid 归一化;app/service/systems/wechat.js wxaauth/resolveBodyMedia/resolveMediaValue 换新字段;app/service/systemMethods/wechat.js 注释同步。" + ], + "module": "wechat" + }, { "version": "2026.09.22-wechat.wxaauth-cos-url", "date": "2026-09-22", diff --git a/methods/system.json b/methods/system.json index 2db95c6..f239a89 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.169", - "updatedAt": "2026-09-22", + "version": "0.3.176", + "updatedAt": "2026-09-23", "headers": [ { "name": "platform", @@ -209,7 +209,7 @@ "list": [ { "method": "dashboard.storeStats", - "description": "dashboard.storeStats 接口", + "description": "仓库/货主看板-仓库发货统计:统计待处理、今日新增、发货进度、出库率及拦截、异常、复核、打包订单数量;货主端自动跨已签约仓库汇总。无业务入参,依据登录用户上下文区分仓库端与货主端。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -221,185 +221,603 @@ } ], "params": [], - "response": [], - "errors": [] - }, - { - "method": "dashboard.warehouseStats", - "description": "dashboard.warehouseStats 接口", - "isNeedAuth": false, - "isNeedLogin": true, - "headers": [ - { - "name": "Authorization", - "type": "string", - "required": true, - "description": "Bearer token" - } - ], - "params": [], - "response": [], - "errors": [] - }, - { - "method": "dashboard.hot_order_rank", - "description": "dashboard.hot_order_rank 接口", - "isNeedAuth": false, - "isNeedLogin": true, - "headers": [ - { - "name": "Authorization", - "type": "string", - "required": true, - "description": "Bearer token" - } - ], - "params": [], - "response": [], - "errors": [] - }, - { - "method": "dashboard.express_ratio", - "description": "dashboard.express_ratio 接口", - "isNeedAuth": false, - "isNeedLogin": true, - "headers": [ - { - "name": "Authorization", - "type": "string", - "required": true, - "description": "Bearer token" - } - ], - "params": [], - "response": [], - "errors": [] - }, - { - "method": "dashboard.platform_distribution", - "description": "dashboard.platform_distribution 接口", - "isNeedAuth": false, - "isNeedLogin": true, - "headers": [ - { - "name": "Authorization", - "type": "string", - "required": true, - "description": "Bearer token" - } - ], - "params": [], - "response": [], - "errors": [] - }, - { - "method": "dashboard.order_trend", - "description": "订单趋势统计:按小时统计当日订单数与发货数,包含汇总信息(订单总数、发货总数、发货率、峰值时段)。数据来源于真实数据库查询,已废弃旧版 mock 数据。", - "isNeedAuth": false, - "isNeedLogin": true, - "headers": [ - { - "name": "Authorization", - "type": "string", - "required": true, - "description": "Bearer token,从中解析 warehouseId(仓库上下文)" - } - ], - "params": [], "response": [ + { + "name": "flag", + "type": "string", + "required": true, + "description": "请求结果标记,成功为 success" + }, { "name": "code", "type": "number", "required": true, - "description": "业务状态码,200 表示成功" + "description": "业务码,成功为 200" }, { "name": "message", "type": "string", "required": true, - "description": "业务提示信息" + "description": "提示信息,成功为 成功" }, { - "name": "data", - "type": "object", + "name": "data.todayOrders", + "type": "number", "required": true, - "description": "成功时返回的趋势数据对象", - "children": [ - { - "name": "range", - "type": "string", - "required": true, - "description": "统计范围,固定为 'day'" - }, - { - "name": "date", - "type": "string", - "required": true, - "description": "统计日期,格式 YYYY-MM-DD" - }, - { - "name": "summary", - "type": "object", - "required": true, - "description": "汇总统计信息", - "children": [ - { - "name": "total_orders", - "type": "number", - "required": true, - "description": "当日订单总数(step in [1,2,3],排除 outbound_status='padding' 和 status='cancel' 的订单)" - }, - { - "name": "total_shipments", - "type": "number", - "required": true, - "description": "当日发货总数(dispatch_lane='m4' 的发货记录数)" - }, - { - "name": "shipment_rate", - "type": "number", - "required": true, - "description": "发货率百分比(total_shipments / total_orders × 100,保留一位小数)" - }, - { - "name": "peak_hour", - "type": "string", - "required": true, - "description": "订单峰值时段,格式 HH:00" - }, - { - "name": "peak_orders", - "type": "number", - "required": true, - "description": "峰值时段订单数" - } - ] - }, - { - "name": "categories", - "type": "array", - "required": true, - "description": "时段列表,从 08:00 到当前小时(最晚 23:00),格式 ['08:00', '09:00', ...]" - }, - { - "name": "orders", - "type": "array", - "required": true, - "description": "各时段订单数,与 categories 一一对应" - }, - { - "name": "shipments", - "type": "array", - "required": true, - "description": "各时段发货数,与 categories 一一对应" - } - ] + "description": "今日订单数(待处理 + 今日已出库)" + }, + { + "name": "data.orderTrend", + "type": "number", + "required": true, + "description": "今日新增较昨日增长率(%),昨日为 0 时按 100 或 0 计算" + }, + { + "name": "data.unassignedOrders", + "type": "number", + "required": true, + "description": "未分配快递号订单数" + }, + { + "name": "data.unprintedOrders", + "type": "number", + "required": true, + "description": "未打印订单数" + }, + { + "name": "data.unpickedOrders", + "type": "number", + "required": true, + "description": "未拣货订单数" + }, + { + "name": "data.pendingShipments", + "type": "number", + "required": true, + "description": "待发货订单数" + }, + { + "name": "data.shipmentProgress", + "type": "number", + "required": true, + "description": "发货进度(%),(待处理-待发货)/待处理" + }, + { + "name": "data.todayOutbound", + "type": "number", + "required": true, + "description": "今日已出库订单数" + }, + { + "name": "data.outboundRate", + "type": "number", + "required": true, + "description": "出库完成率(%),今日出库/(待发货+今日出库)" + }, + { + "name": "data.interceptedOrders", + "type": "number", + "required": true, + "description": "拦截订单数" + }, + { + "name": "data.exceptionOrders", + "type": "number", + "required": true, + "description": "异常订单数(step=3)" + }, + { + "name": "data.recheckedOrders", + "type": "number", + "required": true, + "description": "已复核订单数" + }, + { + "name": "data.packedOrders", + "type": "number", + "required": true, + "description": "已打包订单数" + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" } ], "errors": [ { - "code": "fail", - "message": "缺少仓库上下文(token 中未解析到有效的 warehouseId),返回 { flag: 'fail', message: '缺少仓库上下文' }" + "code": "0", + "message": "缺少仓库上下文(仓库端未绑定仓库)或缺少货主上下文(货主端未绑定货主),返回 flag=failure" + }, + { + "code": "401", + "message": "未登录或 token 无效" + }, + { + "code": "500", + "message": "订单数据查询失败" + } + ] + }, + { + "method": "dashboard.warehouseStats", + "description": "仓库发货统计(演示数据):返回固定的演示统计值,非实时查询结果,仅供前端展示与调试使用。无业务入参。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [], + "response": [ + { + "name": "flag", + "type": "string", + "required": true, + "description": "请求结果标记,成功为 success" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码,成功为 200" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息,成功为 成功" + }, + { + "name": "data.todayOrders", + "type": "number", + "required": true, + "description": "今日订单数(演示值 153023)" + }, + { + "name": "data.orderTrend", + "type": "number", + "required": true, + "description": "较昨日增长率(%,演示值 3)" + }, + { + "name": "data.unassignedOrders", + "type": "number", + "required": true, + "description": "未分配快递号订单数(演示值 3060)" + }, + { + "name": "data.unprintedOrders", + "type": "number", + "required": true, + "description": "未打印订单数(演示值 4591)" + }, + { + "name": "data.unpickedOrders", + "type": "number", + "required": true, + "description": "未拣货订单数(演示值 7651)" + }, + { + "name": "data.pendingShipments", + "type": "number", + "required": true, + "description": "待发货订单数(演示值 45907)" + }, + { + "name": "data.shipmentProgress", + "type": "number", + "required": true, + "description": "发货进度(%,演示值 70)" + }, + { + "name": "data.todayOutbound", + "type": "number", + "required": true, + "description": "今日已出库订单数(演示值 107116)" + }, + { + "name": "data.outboundRate", + "type": "number", + "required": true, + "description": "出库完成率(%,演示值 70)" + }, + { + "name": "data.interceptedOrders", + "type": "number", + "required": true, + "description": "拦截订单数(演示值 306)" + }, + { + "name": "data.exceptionOrders", + "type": "number", + "required": true, + "description": "异常订单数(演示值 1530)" + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" + } + ], + "errors": [ + { + "code": "401", + "message": "未登录或 token 无效" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + }, + { + "method": "dashboard.hot_order_rank", + "description": "热销商品排行:统计今日(00:00 至当前时刻)销量 Top10 商品及环比昨日趋势。仓库端按当前仓库统计,货主端跨全部签约仓库聚合。数据来源于真实数据库查询(订单明细/配送分表)。data[].sku 为库存商品ID(stock_warehouse.id),data[].name 已做脱敏处理(前2字符+***+后2字符)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [], + "response": [ + { + "name": "flag", + "type": "string", + "required": true, + "description": "请求结果标记,成功为 success" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码,成功为 200" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息,成功为 成功" + }, + { + "name": "data", + "type": "array", + "required": true, + "description": "热销商品排行列表(按今日销量降序,最多 10 条,无数据时为空数组)" + }, + { + "name": "data[].id", + "type": "number", + "required": true, + "description": "排行序号(从 1 开始)" + }, + { + "name": "data[].name", + "type": "string", + "required": true, + "description": "脱敏后的商品名称:保留前两个字符与后两个字符,中间以三个星号替代;长度不足 4 个字符时返回 ***;无名称时回退商品编码/商品+库存ID 后同样脱敏" + }, + { + "name": "data[].sku", + "type": "number", + "required": true, + "description": "库存商品ID(stock_warehouse.id);极端情况下订单明细无库存商品ID时回退商品编码字符串" + }, + { + "name": "data[].value", + "type": "number", + "required": true, + "description": "今日销量(件数)" + }, + { + "name": "data[].trend", + "type": "number", + "required": true, + "description": "环比昨日百分比(保留 1 位小数,昨日为 0 且今日 >0 时为 100)" + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" + } + ], + "errors": [ + { + "code": "0", + "message": "缺少仓库上下文(仓库端未绑定仓库)或缺少货主上下文(货主端未绑定货主),返回 flag=failure" + }, + { + "code": "401", + "message": "未登录或 token 无效" + }, + { + "code": "500", + "message": "订单数据查询失败" + } + ] + }, + { + "method": "dashboard.express_ratio", + "description": "快递占比统计(饼图):按快递公司统计待处理订单数量及占比,按订单数降序返回;货主端自动跨已签约仓库汇总。无业务入参,依据登录用户上下文区分仓库端与货主端。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [], + "response": [ + { + "name": "flag", + "type": "string", + "required": true, + "description": "请求结果标记,成功为 success" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码,成功为 200" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息,成功为 成功" + }, + { + "name": "data", + "type": "array", + "required": true, + "description": "快递占比列表(按订单数降序,无数据时为空数组)" + }, + { + "name": "data[].name", + "type": "string", + "required": true, + "description": "快递公司名称(未填写时为 未指定快递)" + }, + { + "name": "data[].value", + "type": "number", + "required": true, + "description": "该快递公司的待处理订单数" + }, + { + "name": "data[].itemStyle.color", + "type": "string", + "required": true, + "description": "图表配色(十六进制色值)" + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" + } + ], + "errors": [ + { + "code": "0", + "message": "缺少仓库上下文(仓库端未绑定仓库)或缺少货主上下文(货主端未绑定货主),返回 flag=failure" + }, + { + "code": "401", + "message": "未登录或 token 无效" + }, + { + "code": "500", + "message": "订单数据查询失败" + } + ] + }, + { + "method": "dashboard.platform_distribution", + "description": "平台分布统计(饼图):按系统平台统计待处理订单数量及占比,按订单数降序返回;货主端自动跨已签约仓库汇总。无业务入参,依据登录用户上下文区分仓库端与货主端。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [], + "response": [ + { + "name": "flag", + "type": "string", + "required": true, + "description": "请求结果标记,成功为 success" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码,成功为 200" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息,成功为 成功" + }, + { + "name": "data", + "type": "array", + "required": true, + "description": "平台占比列表(按订单数降序,无数据时为空数组)" + }, + { + "name": "data[].name", + "type": "string", + "required": true, + "description": "平台名称(未填写时为 未指定平台)" + }, + { + "name": "data[].value", + "type": "number", + "required": true, + "description": "该平台的待处理订单数" + }, + { + "name": "data[].itemStyle.color", + "type": "string", + "required": true, + "description": "图表配色(十六进制色值)" + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" + } + ], + "errors": [ + { + "code": "0", + "message": "缺少仓库上下文(仓库端未绑定仓库)或缺少货主上下文(货主端未绑定货主),返回 flag=failure" + }, + { + "code": "401", + "message": "未登录或 token 无效" + }, + { + "code": "500", + "message": "订单数据查询失败" + } + ] + }, + { + "method": "dashboard.order_trend", + "description": "订单趋势统计:按小时统计当日 08:00 至当前小时的订单数与发货数,并返回发货率、峰值时段等汇总指标;依据当前用户绑定仓库统计。无业务入参。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [], + "response": [ + { + "name": "flag", + "type": "string", + "required": true, + "description": "请求结果标记,成功为 success" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码,成功为 200" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息,成功为 成功" + }, + { + "name": "data.range", + "type": "string", + "required": true, + "description": "统计范围,固定为 day" + }, + { + "name": "data.date", + "type": "string", + "required": true, + "description": "统计日期(YYYY-MM-DD)" + }, + { + "name": "data.summary.total_orders", + "type": "number", + "required": true, + "description": "当日订单总数" + }, + { + "name": "data.summary.total_shipments", + "type": "number", + "required": true, + "description": "当日发货总数" + }, + { + "name": "data.summary.shipment_rate", + "type": "number", + "required": true, + "description": "发货率(%,1 位小数)" + }, + { + "name": "data.summary.peak_hour", + "type": "string", + "required": true, + "description": "订单峰值时段(如 08:00)" + }, + { + "name": "data.summary.peak_orders", + "type": "number", + "required": true, + "description": "峰值时段订单数" + }, + { + "name": "data.categories", + "type": "array", + "required": true, + "description": "时段列表(08:00 至当前小时,如 ['08:00','09:00'])" + }, + { + "name": "data.orders", + "type": "array", + "required": true, + "description": "各时段订单数(与 categories 一一对应)" + }, + { + "name": "data.shipments", + "type": "array", + "required": true, + "description": "各时段发货数(与 categories 一一对应)" + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" + } + ], + "errors": [ + { + "code": "0", + "message": "缺少仓库上下文(当前用户未绑定仓库),返回 flag=failure" + }, + { + "code": "401", + "message": "未登录或 token 无效" + }, + { + "code": "500", + "message": "订单数据查询失败" } ] } @@ -861,7 +1279,7 @@ }, { "method": "index.tryAutoTranslateNewKeys", - "description": "index.tryAutoTranslateNewKeys 接口", + "description": "index.putI18nCollect 的内部辅助方法:目标语言非 zh-CN 时,为该项目在 zh-CN 已有翻译的键批量创建目标语言的翻译占位记录(translation=null、translation_status=0、auto_generated=1、translator=auto-translate),不调用翻译 API;无对外返回值,异常仅记日志,不建议作为 HTTP API 直接调用", "isNeedAuth": true, "isNeedLogin": true, "headers": [ @@ -872,7 +1290,22 @@ "description": "Bearer token" } ], - "params": [], + "params": [ + { + "name": "project", + "type": "string", + "required": false, + "source": "body", + "description": "项目标识(如 wms);该方法为 putI18nCollect 的内部辅助函数,project 由 putI18nCollect 内部传入,不建议直接调用本接口传参" + }, + { + "name": "targetLanguage", + "type": "string", + "required": false, + "source": "body", + "description": "目标语言代码(如 en-US);为 zh-CN 时方法直接返回,不生成任何翻译占位记录" + } + ], "response": [], "errors": [] }, @@ -43262,7 +43695,7 @@ "list": [ { "method": "returnReceived.create", - "description": "退回包裹扫码登记。30日内同仓库同单号只写一次(以第一次为准);反查 wms_order_express 判定是否原单退回,命中则回填 order_express_id/order_id/store_id 并同步标记 is_back='Y',同步处理关联拦截工单、更新订单拦截状态(不释放拦截锁定库存,拦截锁回落由后续入库处理链路接管)。仓库隔离:warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入。", + "description": "退回包裹扫码登记。30日内同仓库同单号只写一次(以第一次为准);反查 wms_order_express 判定是否原单退回,命中则回填 order_express_id/order_id/store_id 并同步标记 is_back='Y',同步处理关联拦截工单、更新订单拦截状态(不释放拦截锁定库存,拦截锁回落由后续入库处理链路接管)。仓库隔离:warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入。响应新增 is_urgent 加急标记(boolean):wms_return_query_log(退回查询记录表)中存在 warehouse_id=当前仓库且 waybill_code=登记运单号(精确匹配)的记录时为 true,否则 false;查询失败时降级为 false。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], @@ -43301,6 +43734,12 @@ "required": true, "description": "货主的合约货主备注名称(wms_store_warehouse.store_remask),非原单退回时为空字符串" }, + { + "name": "is_urgent", + "type": "boolean", + "required": true, + "description": "加急标记:wms_return_query_log(退回查询记录表)中存在 warehouse_id=当前仓库且 waybill_code=登记运单号(精确匹配)的记录时为 true,否则 false;查询失败时降级为 false。幂等命中(duplicated=true)与新创建(duplicated=false)均返回" + }, { "name": "duplicated", "type": "boolean", @@ -43333,7 +43772,7 @@ }, { "method": "returnReceived.list", - "description": "退回收到登记分页列表。仓库隔离(服务端自动注入 warehouse_id = ctx.user.store_id,禁止前端传入)。支持按运单号模糊、扫描日期范围、扫描人员、货主、是否原单退回筛选。", + "description": "退回收到登记分页列表。仓库隔离(服务端自动注入 warehouse_id = ctx.user.store_id,禁止前端传入)。支持按运单号模糊、扫描日期/登记时间/更新时间范围、扫描人员(ID/名称)、货主、运单/订单ID、是否原单退回筛选。", "isNeedAuth": true, "isNeedLogin": true, "headers": [], @@ -43366,6 +43805,20 @@ "source": "body.where", "description": "扫描日期范围 { operator:'between'|'gte'|'lte', value:[start,end] 或单值 }" }, + { + "name": "where.created_at", + "type": "object", + "required": false, + "source": "body.where", + "description": "登记时间范围 { operator:'between'|'gte'|'lte', value:[start,end] 或单值 }" + }, + { + "name": "where.updated_at", + "type": "object", + "required": false, + "source": "body.where", + "description": "更新时间范围 { operator:'between'|'gte'|'lte', value:[start,end] 或单值 }" + }, { "name": "where.scanner_id", "type": "number", @@ -43373,6 +43826,13 @@ "source": "body.where", "description": "扫描人员工号ID(等值)" }, + { + "name": "where.scanner_name", + "type": "string", + "required": false, + "source": "body.where", + "description": "扫描人员名称快照(等值)" + }, { "name": "where.store_id", "type": "number", @@ -43380,6 +43840,20 @@ "source": "body.where", "description": "货主ID(等值)" }, + { + "name": "where.order_express_id", + "type": "number", + "required": false, + "source": "body.where", + "description": "运单ID(等值,原单退回时回填)" + }, + { + "name": "where.order_id", + "type": "number", + "required": false, + "source": "body.where", + "description": "订单ID(等值,原单退回时回填)" + }, { "name": "where.is_original_return", "type": "boolean", @@ -43528,7 +44002,7 @@ "type": "object", "required": false, "source": "body", - "description": "查询条件,语义与 returnReceived.list 的 where 一致(支持 {operator,value} 标准结构或直接值;字段含 waybill_code 模糊、scan_date 范围、scanner_id/store_id/order_express_id/order_id/scanner_name 等值、is_original_return 是否原单退回);禁止传入 warehouse_id/warehouseId(服务端注入)" + "description": "查询条件,语义与 returnReceived.list 的 where 一致(支持 {operator,value} 标准结构或直接值;字段含 waybill_code 模糊、scan_date/created_at/updated_at 范围、scanner_id/scanner_name/store_id/order_express_id/order_id 等值、is_original_return 是否原单退回);禁止传入 warehouse_id/warehouseId(服务端注入)" }, { "name": "sort", @@ -47026,6 +47500,72 @@ } ] }, + { + "method": "wechat.bindByEmployee", + "description": "按工号绑定微信(需登录需权限,PC 管理员操作):传入工号 id(wms_account_store_employee.id)与微信绑定记录 id(wms_user_oauth.id,来自 wechat.userList 的 id),查工号关联的账号 id(account_id)后写入 wms_user_oauth.user_id 完成绑定;已绑定同一账号幂等返回;该微信已绑定其他账号、工号已解除或不属于当前仓库、微信记录不属于当前仓库小程序、账号禁用时拒绝", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文;需拥有 wechat.bindByEmployee 接口权限)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "source": "body", + "required": true, + "description": "工号 id(wms_account_store_employee.id)" + }, + { + "name": "oauth_id", + "type": "number", + "source": "body", + "required": true, + "description": "微信绑定记录 id(wms_user_oauth.id,可在 wechat.userList 结果中获取)" + } + ], + "response": [ + { + "name": "oauth_id", + "type": "number", + "required": true, + "description": "微信绑定记录 id" + }, + { + "name": "already_bound", + "type": "boolean", + "required": true, + "description": "是否此前已绑定同一账号(幂等调用)" + }, + { + "name": "employee", + "type": "object", + "required": true, + "description": "工号信息(id/account_id/store_id/real_name)" + }, + { + "name": "account", + "type": "object", + "required": true, + "description": "绑定的账号信息(id/username/real_name)" + } + ], + "errors": [ + { + "code": "400", + "message": "工号不存在/已解除/未关联账号/微信记录不存在或非微信记录/已绑定其他账号/账号禁用" + }, + { + "code": "403", + "message": "未登录/无权访问该接口(需 wechat.bindByEmployee 接口权限)" + } + ] + }, { "method": "wechat.pushLoginCode", "description": "确认登录码(需登录,PC/Web 已登录用户):传入旧链路 user.getLoginWechatCode 生成的 6 位登录码(字母+数字),使用当前鉴权账号反查 ye4s 绑定并将 ye4s_user_id 双写旧登录码缓存(user:wechat:login:code:{code} 与 client key),小程序端按旧链路轮询到后直接返回登录成功", @@ -47152,9 +47692,57 @@ } ] }, + { + "method": "wechat.getUserAgreementText", + "description": "获取小程序用户须知富文本(免登录):传入 appId(小程序 AppID),从副表 wms_wechat_agreement_version 拉取最新版本(id 自增即最新);Redis 缓存 24 小时(key wechat:userAgreement:{appid}),有缓存直接使用缓存;无版本返回错误", + "isNeedAuth": false, + "isNeedLogin": false, + "headers": [], + "params": [ + { + "name": "appId", + "type": "string", + "source": "body", + "required": true, + "description": "小程序 AppID(wx...)" + } + ], + "response": [ + { + "name": "appid", + "type": "string", + "required": true, + "description": "小程序 AppID" + }, + { + "name": "version_id", + "type": "number", + "required": true, + "description": "最新协议版本记录 id(wms_wechat_agreement_version.id)" + }, + { + "name": "text", + "type": "string", + "required": true, + "description": "用户须知富文本内容" + }, + { + "name": "from_cache", + "type": "boolean", + "required": true, + "description": "是否命中缓存" + } + ], + "errors": [ + { + "code": "400", + "message": "appId 必填/未找到对应小程序或该小程序暂无用户须知" + } + ] + }, { "method": "wechat.wxaauth", - "description": "发起小程序认证(需登录,后端分步):前端把材料图片上传 COS 后传文件 URL,后端下载图片 → POST /wxa/sec/wxaapi/uploadmedia 换 media_id → 替换请求体 → POST /wxa/sec/wxaapi/wxaauth(authorizer_access_token,权限集 18)一步提交;成功回写 wms_wechat_app.auth_task_id/auth_apply_status,返回 taskid(供 wechat.queryauth 查进度)与 auth_url;小程序已认证时拒绝重复发起", + "description": "发起小程序认证(需登录,后端分步):前端把材料图片上传 COS 后传文件 URL,后端下载图片 → POST /wxa/sec/uploadauthmaterial 换 mediaid → 替换请求体 → 以 { auth_data } 包裹 POST /wxa/sec/wxaauth(authorizer_access_token,权限集 18)一步提交;成功回写 wms_wechat_app.auth_task_id/auth_apply_status,返回 taskid(供 wechat.queryauth 查进度)与 auth_url;小程序已认证时拒绝重复发起", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -47167,25 +47755,53 @@ ], "params": [ { - "name": "contact_type", + "name": "customer_type", "type": "number", "required": true, "source": "body", - "description": "联系人类型:1 法人、2 管理员" + "description": "账号主体类型:1 企业、12 个体工商户、15 个人" }, { - "name": "contact_name", + "name": "account_name", "type": "string", "required": true, "source": "body", - "description": "联系人姓名" + "description": "小程序账号名称" + }, + { + "name": "account_name_type", + "type": "number", + "required": true, + "source": "body", + "description": "命名类型:1 基于自选词汇、2 基于商标" + }, + { + "name": "pay_type", + "type": "number", + "required": true, + "source": "body", + "description": "支付方式:1 消耗服务商预购包、2 小程序开发者自行支付" + }, + { + "name": "third_party_phone", + "type": "string", + "required": true, + "source": "body", + "description": "第三方联系电话" + }, + { + "name": "contact_info", + "type": "object", + "required": true, + "source": "body", + "description": "联系人信息:{ name 必填, email 必填, mobile 选填 }" }, { "name": "其他字段", "type": "object", "required": false, "source": "body", - "description": "白名单透传微信 wxaauth 请求体:contact_idcard_number/contact_mobile/contact_cert_photo/contact_nationality/contact_address/contact_email、business_license_copy/business_license_number/business_license_address/business_license_expiration_date、legal_persona_media/legal_persona_idcard_copy/legal_persona_name/legal_persona_idcard_number/legal_persona_address/legal_persona_idcard_expiration_date、business_license_type/apply_type/extra_wxa_secure_info/nickname、pic_list/qualification_list/qualification_extra/license_list/statement_list、store_name/store_main_industry/store_scale/store_floor/store_address/open_type/pay_type。图片字段(contact_cert_photo/business_license_copy/legal_persona_idcard_copy/legal_persona_media、pic_list 项的 pic_url、qualification_list 项 licence_list/certificate_list 的 value、statement_list 项的 value)支持传 COS 文件 URL(http/https),后端自动下载并换 media_id;传非 URL 时视为已传 media_id 原样透传" + "description": "白名单透传新版 wxaauth auth_data:invoice_info(发票信息,服务商代缴可不传)、qualification(主体资质材料 mediaid,非个人必填,单张)、qualification_other(资质其他材料 mediaid 数组,≤10 张)、account_supplemental(名称关键词补充材料 mediaid 数组)、auth_identification/auth_ident_material(个人认证身份,选填)、service_appid(服务商代缴必填)、taskid(打回重填 reauth 时必填)。图片字段 qualification/qualification_other[]/account_supplemental[]/auth_ident_material[] 支持传 COS 文件 URL(http/https),后端自动下载并换 mediaid;传非 URL 时视为已传 mediaid 原样透传" } ], "response": [ @@ -47211,7 +47827,7 @@ "errors": [ { "code": "400", - "message": "未识别仓库/未授权小程序/已认证/未授权权限集 18/缺少 contact_type 或 contact_name/微信失败(errcode 透传)" + "message": "未识别仓库/未授权小程序/已认证/未授权权限集 18/缺少必填字段(customer_type/account_name/account_name_type/pay_type/third_party_phone/contact_info.name/contact_info.email)/微信失败(errcode 透传)" } ] }, @@ -47260,6 +47876,53 @@ } ] }, + { + "method": "wechat.getUserAgreement", + "description": "获取当前仓库小程序用户须知最新版本(需登录):按当前登录仓库取启用小程序(wms_wechat_app),从副表拉取最新版本(id 自增即最新);仓库未绑定小程序时提示「无小程序,需要先绑定」,无版本提示「该小程序暂无用户须知」", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [], + "response": [ + { + "name": "appid", + "type": "string", + "required": true, + "description": "当前仓库小程序 AppID" + }, + { + "name": "nickname", + "type": "string", + "required": false, + "description": "小程序名称" + }, + { + "name": "version_id", + "type": "number", + "required": true, + "description": "最新协议版本记录 id" + }, + { + "name": "text", + "type": "string", + "required": true, + "description": "用户须知富文本内容" + } + ], + "errors": [ + { + "code": "400", + "message": "无小程序,需要先绑定/该小程序暂无用户须知" + } + ] + }, { "method": "wechat.registerMiniprogram", "description": "快速注册企业小程序(需登录):调微信 fastregisterweapp?action=create(component_access_token),提交企业信息创建注册任务,法人微信收到模板消息做人脸核身;审核结果通过 notify_third_fasteregister 事件推送到授权事件接收 URL", @@ -47398,6 +48061,55 @@ } ] }, + { + "method": "wechat.setUserAgreement", + "description": "设置当前仓库小程序用户须知(需登录):提交一次自动新增版本(直接插入,id 自增即最新,写入副表 wms_wechat_agreement_version),并清除 getUserAgreementText 的 24h 缓存;仓库未绑定小程序时提示「无小程序,需要先绑定」", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "text", + "type": "string", + "source": "body", + "required": true, + "description": "用户须知富文本内容(可传空字符串)" + } + ], + "response": [ + { + "name": "appid", + "type": "string", + "required": true, + "description": "当前仓库小程序 AppID" + }, + { + "name": "version_id", + "type": "number", + "required": true, + "description": "新增版本的记录 id" + }, + { + "name": "text", + "type": "string", + "required": true, + "description": "本次提交的用户须知内容" + } + ], + "errors": [ + { + "code": "400", + "message": "text 必填且须为字符串/无小程序,需要先绑定" + } + ] + }, { "method": "wechat.uploadHeadimg", "description": "上传微信账号头像(微信登录态中间层,至少微信登录即可,未绑定也可):前端裁剪后以 base64 上传(data URL 或裸 base64),限制仅 PNG、大小小于 500K;校验 PNG 文件头魔数后经 COS 上传(key=headimg/wechat/{yyyymmdd}/{timestamp}{random}.png),并回写 wms_user_oauth.headimgurl,返回 URL", @@ -47664,7 +48376,7 @@ }, { "method": "wechat.userList", - "description": "拉取当前仓库小程序(wms_wechat_app)的用户列表(wms_user_oauth,需登录):按 ctx.user.store_id 取仓库启用小程序(可选 app_id 指定单个,须属于当前仓库),支持 where(operator 结构)、pagination(page/pageSize)、sort(sortField/sortOrder);响应排除 session_key/access_token/refresh_token 等敏感字段,附 is_bound(user_id>0 已绑定真实账号)", + "description": "拉取当前仓库小程序(wms_wechat_app)的用户列表(wms_user_oauth,需登录):按 ctx.user.store_id 取仓库启用小程序(可选 app_id 指定单个,须属于当前仓库),支持 where(operator 结构)、pagination(page/pageSize)、sort(sortField/sortOrder);响应排除 session_key/access_token/refresh_token 等敏感字段,附 is_bound(user_id>0 已绑定真实账号)与 agreement_version_id(协议版本id,loginByCode 自动回写,可供 wechat.getAgreementVersion 拉取协议内容)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -47702,7 +48414,7 @@ "type": "object", "required": false, "source": "body", - "description": "排序参数 { sortField, sortOrder },sortField 白名单 id/user_id/app_id/openid/unionid/nickname/sex/login_time/login_count/created_at/updated_at,默认 updated_at DESC" + "description": "排序参数 { sortField, sortOrder },sortField 白名单 id/user_id/app_id/openid/unionid/nickname/sex/login_time/login_count/agreement_version_id/created_at/updated_at,默认 updated_at DESC" } ], "response": [ @@ -47710,7 +48422,7 @@ "name": "list", "type": "array", "required": true, - "description": "用户列表(id/user_id/app_id/openid/unionid/nickname/sex/headimgurl/login_time/login_count/is_bound/created_at/updated_at)" + "description": "用户列表(id/user_id/app_id/openid/unionid/nickname/sex/headimgurl/login_time/login_count/agreement_version_id/is_bound/created_at/updated_at)" }, { "name": "pagination", @@ -47731,6 +48443,61 @@ "message": "未识别到当前仓库/当前仓库未授权小程序/指定小程序不属于当前仓库或已停用/where 参数解析失败" } ] + }, + { + "method": "wechat.getAgreementVersion", + "description": "获取指定协议版本内容(需登录免权限):传入版本记录 id(wms_wechat_agreement_version.id,可在 wechat.userList 的 agreement_version_id 获取),校验该版本对应 appid 属于当前仓库的启用小程序后返回协议内容(text 等)", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "source": "body", + "required": true, + "description": "协议版本记录 id(wms_wechat_agreement_version.id)" + } + ], + "response": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "协议版本记录 id" + }, + { + "name": "appid", + "type": "string", + "required": true, + "description": "小程序 AppID" + }, + { + "name": "nickname", + "type": "string", + "required": false, + "description": "小程序名称" + }, + { + "name": "text", + "type": "string", + "required": true, + "description": "协议富文本内容" + } + ], + "errors": [ + { + "code": "400", + "message": "id 必填/协议版本不存在/未识别到当前仓库/该协议版本不属于当前仓库的小程序" + } + ] } ] }