docs(api): 同步 system.json 接口文档与变更记录(returnReceived 登记时间筛选与 is_urgent、dashboard.hot_order_rank 文档恢复),版本升至 0.3.176
This commit is contained in:
parent
beb9e06a08
commit
361e97236a
@ -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",
|
||||
|
||||
1127
methods/system.json
1127
methods/system.json
File diff suppressed because it is too large
Load Diff
Loading…
x
Reference in New Issue
Block a user