升鲜宝AI助手项目源码集成开发步骤（一）---升鲜宝生鲜配送供应链管理系统源代码服务

升鲜宝AI助手

项目源码集成开发步骤

后端 Spring Boot + 前端后台管理项目集成实施文档

适用范围：升鲜宝供应链系统 AI助手模块开发、联调、上线与运维

|-----------------------------------------------------------------------------|
| **核心原则：**AI助手是升鲜宝供应链系统中的一个一级功能菜单，不是独立系统。后端与前端都应作为现有项目中的业务模块集成开发，避免拆成新的独立工程。 |

项目接入原则
开发总体流程
数据库导入与通用字段规范
菜单与权限接入
后端源码目录结构
后端基础代码生成
后端业务服务拆分
真实业务数据源接入
后端接口规范
前端源码目录结构
前端页面开发方式
AI大模型调用流程
自然语言问数安全控制
定时任务设计
权限、日志、多语言打通
分阶段开发计划
联调、测试与验收
上线部署与运维监控
交付清单与检查表

1. 项目接入原则

升鲜宝AI助手需要按现有升鲜宝系统的业务模块方式接入。后端继续使用现有 Spring Boot、MyBatis-Plus、XML、Redis、定时任务和权限体系；前端继续使用现有后台管理工程、菜单路由、权限按钮和页面布局。

|---------|----------------------------|---------------------------------------------------------------|
| 接入项 | 要求 | 说明 |
| 模块定位 | AI助手是升鲜宝一级菜单 | 不能将 AI助手包装成独立系统、独立平台或独立产品。 |
| 后端接入 | 放入现有后端源码 | 按 controller、service、service/impl、dao、entity、xml、req、resp 分层。 |
| 前端接入 | 放入现有前端源码 | 按 src/views/aiassistant 与 src/api/aiassistant 管理。 |
| 菜单接入 | 走 sys_menu / sys_role_menu | 一级菜单为 AI助手，二级为业务栏目，三级为可点击功能页面。 |
| 权限接入 | 走现有权限编码 | 按钮权限作为 sys_menu 的按钮类型，不作为页面菜单显示。 |
| 数据接入 | 不复制业务主数据 | AI助手从 oms、pur、wms、tms、fin 等真实业务表取数。 |

2. 开发总体流程

建议按以下顺序推进，避免前后端并行时接口口径、权限和数据口径混乱。

|--------|---------------|------------------------------------------------------------|
| 步骤 | 工作项 | 开发说明 |
| 1 | 导入 AI 数据库 SQL | 执行 AI助手建表 SQL，确认 ai_* 表、通用字段和索引。 |
| 2 | 插入菜单与按钮权限 | 将 AI助手作为一级菜单，三级功能作为页面，按钮作为权限点。 |
| 3 | 生成后端基础代码 | 生成 Entity、Dao、XML、Req、Resp、Service、ServiceImpl、Controller。 |
| 4 | 开发模型配置闭环 | 先完成 ai_model、ai_api_key、调用日志、模型连通性测试。 |
| 5 | 开发指标中心 | 完成指标定义、指标口径、指标 SQL、指标结果快照。 |
| 6 | 开发预警中心 | 完成预警规则、扫描、事件、处理、推送策略。 |
| 7 | 开发报表中心 | 完成模板、日报、周报、月报、专题报告和报表任务。 |
| 8 | 开发知识库/RAG/问数 | 完成知识库、文档、分段、检索、问数评测和 SQL 安全。 |
| 9 | 开发前端页面 | 按三级页面逐个接入接口，优先公共组件复用。 |
| 10 | 联调验收上线 | 完成权限、日志、多语言、数据权限、定时任务和监控。 |

3. 数据库导入与通用字段规范

先执行《升鲜宝AI助手_完整数据库建表SQL.sql》。所有 AI 表必须使用升鲜宝统一通用字段，避免出现 create_time、update_time、tenant_id、deleted、status 等不统一字段。

|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| SHOW TABLES LIKE 'ai_%'; -- 核心通用字段 sort_code int NOT NULL DEFAULT 1 COMMENT '排序码' del_flag int NOT NULL DEFAULT 0 COMMENT '删除标记 0正常 1删除' enabled int NOT NULL DEFAULT 1 COMMENT '状态 0禁用 1正常' creator bigint NOT NULL DEFAULT 0 COMMENT '创建人id' create_date bigint NULL COMMENT '创建时间' updater bigint NOT NULL DEFAULT 0 COMMENT '修改人id' update_date bigint NULL COMMENT '修改时间' remark varchar(255) NULL COMMENT '备注' dept_id bigint NULL DEFAULT 0 COMMENT '机构id' |

|------------------------------------------------------------------------------------------------------------------------|
| **命名规范：**业务状态字段不要再使用 status。建议使用 metric_state、warning_state、report_state、task_state、call_state、audit_state 等明确业务语义的字段。 |

|--------|---------------------------------------------------------|-----------------------------------|
| 表类 | 核心表 | 作用 |
| 模型配置 | ai_model、ai_api_key、ai_model_call_log | 管理大模型、API Key、调用日志、Token 消耗和调用结果。 |
| 知识库 | ai_knowledge、ai_knowledge_document、ai_knowledge_segment | 管理知识库、文档、分段、向量索引和 RAG 检索。 |
| 数据资产 | ai_scm_data_asset、ai_scm_field_semantic | 登记真实业务表、字段语义、问数白名单和数据权限。 |
| 指标中心 | ai_scm_metric、ai_scm_metric_snapshot | 定义指标、计算口径、SQL、指标结果快照。 |
| 预警中心 | ai_scm_warning_rule、ai_scm_warning_event | 配置预警规则、生成预警事件、跟踪处理闭环。 |
| 报表中心 | ai_scm_report_template、ai_scm_report_task | 管理 AI 报表模板、生成任务、日报、周报、月报和专题报告。 |
| 自然语言问数 | ai_scm_nlq_log | 记录自然语言问题、生成 SQL、执行结果和 AI 解释。 |

4. 菜单与权限接入

AI助手是升鲜宝后台中的一级菜单。二级菜单用于业务分组，三级菜单才是可以点击打开的功能页面。新增、修改、删除、导出、审核、处理等动作属于按钮权限，不应该做成菜单层级。

|----------|------------|---------------------------------|
| 一级菜单 | 二级菜单示例 | 三级功能页面示例 |
| AI助手 | 智能工作台 | AI经营驾驶舱、AI智能快报、常用问数、我的订阅消息 |
| AI助手 | 经营分析 | 采购分析、销量订单分析、库存周转分析、毛利异常分析 |
| AI助手 | 指标中心 | 指标分类、指标定义、指标口径维护、指标数据SQL、指标结果 |
| AI助手 | 预警中心 | 预警规则、预警事件、超期预警、缺货异常、推送策略 |
| AI助手 | 报表中心 | 报表模板、AI日报、AI周报、AI月报、专题分析报告、报表任务 |
| AI助手 | 知识库 | 知识库管理、文档管理、全文检索、RAG检索测试 |
| AI助手 | 模型配置 | API密钥配置、大模型配置、模型调用日志 |
| AI助手 | 权限与审计 | 用户管理、角色管理、操作日志 |

|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| aiassistant:metric:list aiassistant:metric:save aiassistant:metric:update aiassistant:metric:delete aiassistant:metric:export aiassistant:warning:list aiassistant:warning:handle aiassistant:warning:close aiassistant:warning:export aiassistant:report:list aiassistant:report:generate aiassistant:report:download aiassistant:report:subscribe aiassistant:model:list aiassistant:model:test aiassistant:model:enable aiassistant:model:disable |

5. 后端源码目录结构

后端建议在现有项目中新增 aiassistant 业务模块目录，不拆独立工程。目录保持升鲜宝现有工程习惯，便于合并、维护和权限扫描。

|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| src/main/java/com/sxb/aiassistant/ ├── constant ├── controller ├── service ├── service/impl ├── dao ├── entity ├── req ├── resp ├── enums ├── converter ├── task ├── integration ├── excel └── xml src/main/resources/mapper/aiassistant/ ├── AiModelDao.xml ├── AiApiKeyDao.xml ├── AiScmMetricDao.xml ├── AiScmWarningRuleDao.xml ├── AiScmWarningEventDao.xml ├── AiScmReportTemplateDao.xml └── AiScmReportTaskDao.xml |

6. 后端基础代码生成

基础代码按照表结构生成 Entity、Dao、XML、Req、Resp、Service、ServiceImpl 和 Controller。入参主体统一使用 Req 前缀，返回主体统一使用 Resp 前缀。

|-------------|-------------------------------------------|-----------------------------|
| 层级 | 命名示例 | 说明 |
| Entity | AiScmMetricEntity | 与数据库字段一一对应，包含通用字段。 |
| Dao | AiScmMetricDao | 继承 BaseMapper 或使用现有 Dao 规范。 |
| XML | AiScmMetricDao.xml | 复杂查询、统计、报表 SQL 放在 XML 中。 |
| Req | ReqAiScmMetricPage、ReqAiScmMetricSave | 接口请求对象，不使用 DTO/VO 作为主要命名。 |
| Resp | RespAiScmMetricPage、RespAiScmMetricDetail | 接口返回对象，避免直接返回 Entity。 |
| Service | AiScmMetricService | 定义业务接口。 |
| ServiceImpl | AiScmMetricServiceImpl | 实现业务逻辑、权限和日志。 |
| Controller | AiScmMetricController | 统一前缀 /aiassistant/metric。 |

|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| @RestController @RequestMapping("/aiassistant/metric") public class AiScmMetricController { @PostMapping("/page") public Result<PageResp<RespAiScmMetricPage>> page(@RequestBody ReqAiScmMetricPage req) { return Result.ok(metricService.page(req)); } @GetMapping("/info/{id}") public Result<RespAiScmMetricDetail> info(@PathVariable Long id) { return Result.ok(metricService.info(id)); } @PostMapping("/save") public Result<Boolean> save(@RequestBody ReqAiScmMetricSave req) { metricService.save(req); return Result.ok(true); } } |

7. 后端业务服务拆分

|----------------------------------|------------------------------|-----------------|
| 服务类 | 负责功能 | 核心页面 |
| AiModelService / AiApiKeyService | 模型配置、API Key、连通性测试、默认模型、模型启停 | API密钥配置、大模型配置 |
| AiModelCallService | 统一大模型调用、Token统计、调用日志、异常重试 | 模型调用日志 |
| AiKnowledgeService | 知识库、文档、分段、全文检索、向量检索 | 知识库管理、文档管理、全文检索 |
| AiRagSearchService | RAG检索、TopK、相似度、检索测试 | RAG检索测试、分段向量检索 |
| AiScmMetricService | 指标分类、指标定义、口径、SQL、结果快照 | 指标中心所有页面 |
| AiScmWarningService | 预警规则、扫描、事件、处理、关闭、推送 | 预警中心所有页面 |
| AiScmReportService | 模板、任务、日报、周报、月报、专题报告、订阅 | 报表中心所有页面 |
| AiScmNlqService | 自然语言问数、SQL生成、SQL安全、结果解释 | 常用问数、问数评测集 |
| AiAuditService | 操作日志、模型调用日志、重要配置变更审计 | 操作日志、模型调用日志 |

8. 真实业务数据源接入

AI助手不重复保存采购、销售、库存、配送、财务等业务明细数据。分析、预警、报表和问数应从真实业务表读取，AI 表只保存配置、规则、快照、任务、日志和结果。

|---------|-------------------------------------------------------------------------------------------------|-----------------------------|
| 业务域 | 主要业务表 | AI用途 |
| 销售订单 | oms_order_bill、oms_order_bill_info | 销售额、订单数、客单价、客户数、取消率、销量排行。 |
| 采购 | pur_bill、pur_bill_info、pur_daily_purchase_price | 采购金额、采购价异常、供应商贡献、到货率。 |
| 库存 | wms_goods_inventory、wms_goods_inventory_info、wms_inv_stockin、wms_inv_stockout、wms_loss_overflow | 库存金额、库存周转、缺货异常、滞销异常、安全库存预警。 |
| 配送物流 | tms_waybill、tms_orderbill_map_circle | 配送准时率、线路履约、司机履约、签收异常。 |
| 财务 | fin_collection_order、fin_payment_order、fin_customer_bill、fin_supplier_bill | 应收、应付、毛利、账期风险、资金预警。 |
| 商品主数据 | pms_goods、pms_goods_sku、pms_goods_sku_unit | 商品维度、SKU维度、单位维度、品类分析。 |
| 客户/供应商 | cus_customer、sup_supplier | 客户画像、供应商画像、履约评分。 |

9. 后端接口规范

每个三级功能页面至少提供分页、详情、保存、修改、删除/作废、启用/禁用、导出等基础接口。统计类页面额外提供概览卡片、图表数据、AI建议和导出接口。

|----------|--------------------------------|--------------------|
| 接口类型 | 路径示例 | 说明 |
| 分页查询 | /aiassistant/warning/page | 用于列表页面。 |
| 详情查询 | /aiassistant/warning/info/{id} | 用于详情、编辑前回显。 |
| 新增保存 | /aiassistant/warning/save | 新增规则、模板、指标等。 |
| 修改保存 | /aiassistant/warning/update | 修改规则、模板、指标等。 |
| 启用禁用 | /aiassistant/warning/enable | enabled 字段更新。 |
| 导出 | /aiassistant/warning/export | Excel 导出，写入导出日志。 |
| 概览统计 | /aiassistant/dashboard/summary | 首页卡片指标。 |
| 图表数据 | /aiassistant/dashboard/chart | 折线图、柱状图、饼图。 |
| AI建议 | /aiassistant/analysis/advice | 返回 AI 经营建议或预警处理建议。 |

10. 前端源码目录结构

前端作为现有后台管理项目的一个模块集成，页面路径建议以 aiassistant 为根目录。API 文件与 views 目录按业务域对应，便于维护。

|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| src/views/aiassistant/ ├── dashboard ├── analysis ├── metric ├── warning ├── report ├── knowledge ├── model ├── message ├── profile ├── audit └── components src/api/aiassistant/ ├── dashboard.js ├── analysis.js ├── metric.js ├── warning.js ├── report.js ├── knowledge.js ├── model.js ├── message.js ├── profile.js └── audit.js |

11. 前端页面开发方式

每个三级功能页面建议采用"列表页 + 新增/修改共用页"的模式，不要为新增、编辑、详情拆过多页面。统计分析页面可使用单页结构，配合弹窗或抽屉做配置和详情。

|----------|-------------------------------|--------------------------|
| 页面类型 | 推荐文件 | 说明 |
| 列表维护类 | xxx.vue、xxx-add-or-update.vue | 如指标定义、预警规则、报表模板、模型配置。 |
| 统计分析类 | xxx.vue | 如采购分析、库存周转分析、毛利异常分析。 |
| 详情处理类 | xxx-detail.vue 或列表内抽屉 | 如预警事件详情、告警处理详情。 |
| 配置类 | xxx.vue + 弹窗组件 | 如API密钥配置、大模型配置、通知设置。 |
| 公共组件 | components/AiMetricCard.vue 等 | 指标卡片、图表、查询表单、AI建议面板统一封装。 |

12. AI大模型调用流程

|--------------|-----------------------------------------------|
| 步骤 | 处理逻辑 |
| 1. 用户操作页面 | 用户在问数、报表、预警、经营分析等页面触发 AI 分析。 |
| 2. 后端接收请求 | Controller 接收 Req，校验权限、参数、数据范围。 |
| 3. 读取业务数据 | 从真实业务表、指标快照、知识库或预警事件读取上下文数据。 |
| 4. 组装 Prompt | 按场景模板拼接业务数据、用户问题、约束和输出格式。 |
| 5. 选择模型 | 根据 ai_model、ai_api_key、默认模型配置选择模型。 |
| 6. 调用模型 | 统一通过 AiModelCallService 调用。 |
| 7. 记录日志 | 写入 ai_scm_model_call_log，包括 token、耗时、结果、失败原因。 |
| 8. 返回结果 | 返回 AI分析、建议、摘要或结构化数据给前端。 |

13. 自然语言问数安全控制

自然语言问数不能直接执行大模型生成的 SQL。必须经过白名单、SQL 类型、关键字、行数、字段权限和数据权限校验。

|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 自然语言问题 ↓ 大模型生成候选 SQL ↓ SQL 安全校验 - 只允许 SELECT - 禁止 DELETE / UPDATE / INSERT / DROP / TRUNCATE - 只允许访问 ai_scm_data_asset 登记的数据表 - 限制最大返回行数 - 按 dept_id 和数据权限追加过滤条件 ↓ 执行只读查询 ↓ 返回数据结果 ↓ AI 总结解释 |

14. 定时任务设计

|-----------------------|-----------------------------------|-------------|
| 任务类 | 作用 | 建议频率 |
| AiMetricSnapshotTask | 计算指标快照，写入 ai_scm_metric_snapshot。 | 每5分钟/每小时/每日 |
| AiWarningScanTask | 扫描预警规则，生成预警事件。 | 每5分钟/每15分钟 |
| AiReportGenerateTask | 生成日报、周报、月报和专题报告。 | 按报表模板配置 |
| AiKnowledgeVectorTask | 解析文档、分段、向量化。 | 异步队列/定时补偿 |
| AiModelStatTask | 统计模型调用次数、耗时、token 消耗。 | 每小时/每日 |
| AiMessagePushTask | 发送预警、报表、订阅消息。 | 每分钟/按策略 |

15. 权限、日志、多语言打通

|---------|---------------------------------------------------------------------|
| 集成项 | 开发要求 |
| 权限控制 | 前端按钮使用权限编码控制，后端接口也必须校验权限。 |
| 数据权限 | 根据 dept_id、机构、门店、部门、角色控制可访问数据范围。 |
| 操作日志 | 指标、规则、模型、API Key、报表、问数等关键操作写入业务日志。 |
| 字段级日志 | 重要配置变更记录字段变更前值、变更后值、操作人、操作时间。 |
| 多语言 | 菜单名称、字段说明、报表标题可接入 sys_static_translation / sys_dynamic_translation。 |
| 导出安全 | 报表导出、指标导出、预警导出需要记录导出任务和操作日志。 |

16. 分阶段开发计划

|-------------|-------------------------------------------|---------------------------------|
| 阶段 | 开发范围 | 目标 |
| 第一阶段：基础闭环 | 模型配置、API Key、模型调用日志、指标定义、预警规则、报表模板、AI经营日报 | 让 AI助手具备可配置、可计算、可预警、可生成报表的基础能力。 |
| 第二阶段：供应链分析 | 采购分析、销量订单分析、库存周转、毛利异常、配送履约、供应商贡献、畅销滞销 | 接入真实业务表，形成核心经营分析能力。 |
| 第三阶段：知识库与问数 | 知识库、文档管理、全文检索、RAG检索、自然语言问数、问数评测集 | 让 AI助手具备知识问答和自然语言分析能力。 |
| 第四阶段：消息与审计 | 消息中心、我的订阅、通知设置、个人中心、用户管理、角色管理、操作日志 | 完善权限、消息、审计和运维管理。 |

17. 联调、测试与验收

|---------|---------------------------------|
| 测试项 | 验收标准 |
| 菜单路由 | AI助手一级菜单显示正常，二级分组正常，三级页面可打开。 |
| 权限按钮 | 无权限用户看不到按钮，后端接口不可越权调用。 |
| 数据取数 | 销售、采购、库存、配送、财务分析结果与真实业务表一致。 |
| 指标计算 | 指标口径清晰，快照任务可重复执行且结果正确。 |
| 预警扫描 | 规则触发准确，事件状态可流转，处理记录完整。 |
| 报表生成 | 日报、周报、月报和专题报告可生成、查看、下载。 |
| 模型调用 | 模型可配置、可测试，调用日志记录 token、耗时、失败原因。 |
| 问数安全 | 只能执行白名单 SELECT 查询，禁止危险 SQL。 |
| 日志审计 | 关键操作有操作日志，重要配置有字段级变更日志。 |

18. 上线部署与运维监控

|---------|--------------------------------------|
| 上线项 | 说明 |
| 数据库脚本 | 先执行建表 SQL，再执行菜单、权限、基础配置初始化脚本。 |
| 后端配置 | 配置模型服务地址、API Key 加密密钥、Redis、任务调度开关。 |
| 前端部署 | 合并 aiassistant 页面、API、路由、菜单权限配置。 |
| 灰度开关 | 按角色或机构开放 AI助手，先给内部运营和管理员使用。 |
| 监控指标 | 模型调用成功率、平均耗时、Token消耗、预警扫描耗时、报表生成成功率。 |
| 异常处理 | 模型调用失败、SQL执行失败、报表生成失败要有重试和告警。 |

19. 交付清单与检查表

|---------|------------------------------------------------------------|
| 交付物 | 完成标准 |
| 数据库 SQL | AI助手完整建表 SQL、菜单 SQL、初始化数据 SQL 可执行。 |
| 后端源码 | controller、service、serviceImpl、dao、entity、xml、req、resp 完整。 |
| 前端源码 | views、api、router、权限按钮、公共组件完整。 |
| 接口文档 | 每个接口有路径、入参、出参、权限编码和异常说明。 |
| 功能页面 | 70个三级功能页面按最终菜单口径接入。 |
| 测试报告 | 权限、数据、指标、预警、报表、问数、模型调用全部测试通过。 |
| 部署说明 | 包含数据库、后端、前端、定时任务和模型服务配置。 |