AI 运营助手
代码在 modules/ecom/assistant(Mapper 单独登记 AssistantMapperConfig,XML 在 mapper/ecom/assistant),前端 views/ecom/ops-report、views/ecom/banned-word、components/ecom/assistant,接口 api/ecom/assistant.js,语言包 ecomAsst.js,后端消息键 ecom.*.asst.*。
| 部分 | 内容 |
|---|---|
问数工具 assistant/tool | 实现 framework/ai/AiTool:ecom_sales_compare、ecom_ads_insight、ecom_returns_reviews、ecom_order_issues、ecom_fba_insight |
运营日报 EcomOpsReportBuilder / EcomOpsReportService | 程序汇总一天的数据(不依赖 AI),AI 可用时经 AiTextGenerator 生成要点与建议 |
定时与推送 EcomOpsReportJob / EcomOpsReportPushService | 任务 ecom.opsReport(默认 0 30 8 * * *),按订阅分组生成并推送 |
违禁词 EcomBannedWordService / BannedWordMatcher | 维护、适用词、检查;EcomPublishService.validate 中拦截阻止类的词 |
AI 写 Listing EcomListingAiService | 按站点语言生成 / 优化文案,关键词来自广告搜索词报告 |
问数工具
工具由 AI 模块自动收集,只提供给有对应权限的用户;执行期间店铺数据权限切面(EcomStoreScopeAspect 拦截 AiTool.execute)生效,查询自动只含可见店铺。公共参数在 AssistantToolSupport:
store(名称 / 编码模糊匹配)、platform、marketplace:在EcomStoreService.options()(已按可见店铺过滤)中筛选;有条件但没有匹配时抛出BizException并列出可选店铺,模型据此请用户确认。startDate/endDate:默认截至昨天,跨度不超过 366 天;top最多 200 行。
ecom_sales_compare 复用 EcomReportService.byStore / bySku(利润已扣广告,与利润分析口径一致),本期与对比期在 Java 中合并;SKU 维度输出 profitChangeBreakdown(销售额、平台费用、退款、商品成本、物流、广告各项对利润的影响),模型用它解释「利润为什么下滑」。其他工具复用广告分析(EcomAdAnalysisService)、FBA(FbaHealthService、FbaClaimService)和本模块的只读汇总(EcomAssistantQueryMapper)。工具说明(.desc)里写清楚何时用哪个参数,例如「美国站用 marketplace=US,上周指上周一至周日」。
新增电商问数工具:实现 AiTool(放在 ecom 包下即可获得店铺数据权限),名称 ecom_ 开头,说明与参数的消息键写进 ecom.properties(中英文),结果用 AiToolResult,不要返回买家联系方式。
运营日报
EcomOpsReportJob (8:30) ─▶ EcomOpsReportPushService.runScheduled(昨天)
├─ 全部店铺 → EcomOpsReportService.generate
└─ 每个订阅:订阅的店铺 ∩ 订阅人可见店铺 → 按范围分组 generate → push
generate:EcomOpsReportBuilder.build(数据)→ AiTextGenerator(可选)→ 保存(同日同范围覆盖)- 存储:
ecom_ops_report(列表字段 +contentJSON + AI 建议)、ecom_ops_report_store(范围内的店铺,一店一行)、ecom_ops_report_sub(订阅,每人一条)。范围标识scope_key为全部店铺时ALL,否则为排序后店铺 ID 的 MD5,唯一约束(report_date, scope_key, tenant_id)。 - 可见性:列表 / 详情只返回店铺全部可见的日报——
ecom_ops_report_store带store_id列,会被店铺数据权限拦截器自动过滤,XML 中用r.store_count = (SELECT COUNT(*) FROM ecom_ops_report_store rs WHERE rs.report_id = r.id)判断。 - 结构化内容
OpsReportContent:kpi/prev/avg7、storeRows、abnormalSkus、badReviews、stockRisks、adAlerts、todos(OpsTodoKind带跳转地址)、highlights(只存code+args,详情接口按当前语言生成text,消息键ecom.text.asst.hl.<code>)。各列表最多 30 行,*Total为截断前的数量。 - 规则:阈值是
EcomOpsReportBuilder中的常量(类注释列出了全部规则),需要调整时改常量并同步用户手册。 - AI 建议:提示词
ecom.prompt.asst.dailyAdvice(按默认语言取,存库内容为中文),数据为日报的精简版(各列表 10 行)。不可用时状态为NONE并记录原因,调用失败为FAILED,都不影响日报本身。模型调用在事务之外。
按渠道推送
站内消息的全局推送(MessageSentEvent → SysImPushService)会发到全部已开启消息推送的平台,日报订阅要求只发到订阅人选择的渠道,因此 framework 增加了 framework/message/ChannelMessageSender(ImChannel:钉钉、企业微信、飞书),由系统模块的 SysChannelMessageSender 实现:
// 写站内消息(不触发全局推送),事务提交后异步推送到指定平台(已绑定的成员)
channelSender.send(List.of(userId), message, true, EnumSet.of(ImChannel.DINGTALK));
List<ImChannel> available = channelSender.enabledChannels(); // 已接入并开启消息推送的平台其他需要「用户自选推送渠道」的通知也可以使用它。没有系统模块时 ObjectProvider 为空,日报只发站内消息(MessageSender)。
违禁词
- 匹配规则在后端
BannedWordMatcher和前端components/ecom/assistant/bannedWords.js中各实现一份(不区分大小写;整词要求前后不是字母数字,中日韩泰文字一侧不检查边界),改规则时两边同步。 - 刊登编辑页用
useListingCompliance(form):按店铺的平台 / 站点取/ecom/banned-word/applicable,表单变化时本地检查,给a-form-item的validate-status/help和发布前确认beforePublish();CompliancePanel、HighlightText可在其他编辑页复用。 - 后端兜底:
EcomPublishService.validate调用EcomBannedWordService.blockReason,命中阻止类的词时提交失败并列出命中的词。 - 内置词在
init.sql(builtin = 1),新租户由EcomBannedWordTenantInitializer复制;类型为业务字典ecom_banned_word_type,处理方式BannedWordLevel决定是否拦截。
AI 写 Listing
EcomListingAiService.generate 组装:平台与站点、物料、品牌、类目、属性、现有文案、勾选的关键词、适用的违禁词(要求模型不要使用)、补充要求;系统提示 ecom.prompt.asst.listing 带平台和标题长度上限,输出语言默认按站点(MARKETPLACE_LANGUAGES)。模型输出 JSON(允许包在代码块中),解析后截断超长标题并再做一次合规检查返回给页面,由用户确认后填入表单。
关键词 keywords(itemId, sameCategory):投放了该物料(或同一款式)的广告组(广告日报中带 SKU 的行;没有广告组的按活动)在搜索词报告中出过单的词,同站点,按订单数排序;同物料没有时自动扩大到同品类。
测试
EcomAiAssistantTests:
- 问数工具经
AiToolRegistry调用:利润下滑的 SKU 与分解、按店铺汇总、只能看到负责店铺的用户看不到其他店铺的 SKU / 差评 / 超时订单、指定看不到的店铺报错、没有广告权限时工具不可用。 - 日报:无 AI 时的指标、销量骤降、新差评、超时未发货与要点;店铺权限下的列表与详情;本地模拟模型生成建议(提示词带日报数据)、同日同范围覆盖、模型失败时
FAILED。 - 推送:未接入的渠道不能选择;钉钉接入(接口地址改为本地桩)后定时任务推送站内消息与应用消息、同一日报不重复推送。
- 违禁词:整词 / 包含匹配、平台站点范围、停用、批量添加去重、合规检查、标题含阻止类词时提交发布失败。
- AI 写 Listing:搜索词报告中的出单词、未配置 AI 时不可用、模拟模型按站点语言生成并做合规检查。