升鲜宝 AI助手模块功能关联、调用关系与软件开发说明（二）---升鲜宝生鲜配送供应链管理系统源代码服务

升鲜宝 AI助手模块

功能关联、调用关系与软件开发说明

适用范围：升鲜宝供应链系统内置一级功能菜单「AI助手」

覆盖智能工作台、经营分析、指标中心、预警中心、报表中心、预测决策、知识库与语义、模型配置、审计与权限九大栏目

版本：V1.0 输出：开发说明文档数据库口径：升鲜宝通用字段结构

1. 模块定位与建设目标

AI助手是升鲜宝供应链系统中的一个一级功能菜单，不是独立系统。它依托现有商品、采购、销售、库存、仓储、物流、财务、客户、供应商、质检溯源等业务数据，向业务人员提供经营分析、自然语言问数、指标计算、预警识别、报表生成、预测建议、知识库问答、模型配置和审计追踪能力。

开发时必须遵循现有升鲜宝后端、前端、权限、菜单、多语言、通用字段、数据权限和字段级日志规范。AI助手只做业务智能增强层，不重复改造核心交易链路，不把采购单、销售单、库存流水、配送单据复制成另一套业务系统。

|--------|---------|---------------------------------------------------|
| 项目 | 口径 | 说明 |
| 一级菜单 | AI助手 | 作为升鲜宝后台的一级业务入口，和商品、采购、库存、订单、物流、财务等菜单并列。 |
| 二级栏目 | 9个 | 智能工作台、经营分析、指标中心、预警中心、报表中心、预测决策、知识库与语义、模型配置、审计与权限。 |
| 三级功能页面 | 70个 | 三级页面为最终可点击页面；新增、编辑、导出、处理、启用、禁用等作为按钮权限，不再作为菜单层级。 |
| 数据原则 | 引用真实业务表 | 通过数据资产、字段语义、指标SQL、快照表读取业务数据，不重复建设业务主数据。 |
| AI原则 | 可控调用 | 所有模型调用必须经过模型配置、API密钥、提示词模板、工具函数、敏感词脱敏、SQL审计与调用日志。 |

2. 总体模块关系架构

2.1 AI助手九大栏目总体调用链

|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 升鲜宝真实业务数据层商品 PMS / 采购 PUR / 销售 OMS / 库存 WMS-HWMS / 配送 TMS / 财务 FIN / 客户 CUS / 供应商 SUP / 质检溯源 CHECK-TS ↓ 数据资产与语义层数据资产登记 → 表字段语义 → 业务表映射 → 业务术语库 → 问数样例库 ↓ 指标中心指标分类 → 指标定义 → 指标口径维护 → 指标取数SQL → 指标快照 → 指标看板配置 → 指标权限 ↓ 业务智能层经营分析 ← 指标快照 / 真实业务表 / 预测结果预警中心 ← 指标快照 / 预警规则 / 预测结果 / 业务异常数据报表中心 ← 指标快照 / 经营分析 / 预警事件 / 大模型总结预测决策 ← 历史指标 / 业务趋势 / 经营目标 / 库存采购约束 ↓ 智能工作台 AI经营驾驶舱 / 今日异常待办 / AI智能问数 / AI经营日报 / AI预警概览 / 常用问题收藏 / 我的订阅推送 ↓ 模型配置与审计权限横向支撑 API密钥 / 大模型配置 / 提示词模板 / 工具函数配置 / 敏感词脱敏 / 调用日志 / SQL审计 / 成本Token统计 / 菜单授权 / 多语言菜单 |

3. 二级栏目作用与上下游关系

|----------|--------------------------------|----------------------------------------|----------------------------|---------------------------------|
| 二级栏目 | 核心作用 | 上游输入 | 下游输出/调用方 | 开发说明 |
| 智能工作台 | 统一入口和经营总览 | 指标快照、预警事件、报表任务、问数日志、订阅消息 | 经营分析、指标中心、预警中心、报表中心、模型调用服务 | 展示驾驶舱、待办、快报、问数入口、日报概览和订阅推送。 |
| 经营分析 | 面向采购、销售、库存、配送、财务、供应商、质检溯源的业务分析 | 真实业务源表、指标快照、预测结果 | 指标中心、预警中心、报表中心、预测决策 | 输出业务分析结论，为预警、报表和经营建议提供基础。 |
| 指标中心 | AI助手的数据口径和指标计算核心 | 数据资产、字段语义、业务表映射、指标SQL | 经营分析、预警中心、报表中心、预测决策、智能工作台 | 统一指标定义、口径、SQL、快照和权限，避免各页面口径不一致。 |
| 预警中心 | 异常识别、规则扫描和闭环处理 | 指标快照、业务实时数据、预测结果、预警规则 | 智能工作台、报表中心、消息推送、审计日志 | 将缺货、临期、采购价、毛利、损耗等异常转为可处理事件。 |
| 报表中心 | AI日报、周报、月报和专项报告生成 | 指标快照、经营分析结果、预警事件、AI模型 | 智能工作台、订阅推送、下载导出、审计日志 | 生成可订阅、可导出、可追溯的经营报表。 |
| 预测决策 | 销量预测、补货、库存、采购、调拨和经营建议 | 历史指标、订单趋势、库存约束、供应商履约 | 预警中心、经营分析、报表中心、工作台 | 从"看数据"升级为"给建议、看采纳、评估效果"。 |
| 知识库与语义 | RAG、问数、字段解释和业务术语支撑 | 文档、业务术语、字段语义、表映射、问数样例 | AI智能问数、报表生成、模型提示词、SQL生成 | 让大模型理解升鲜宝业务语言和数据库字段。 |
| 模型配置 | 统一管理大模型、密钥、参数、角色、提示词和工具函数 | 模型服务商、API Key、提示词、工具配置、脱敏规则 | 所有AI调用、RAG、问数、报告总结、预测建议 | 为AI能力提供可替换、可审计、可限额的模型底座。 |
| 审计与权限 | 安全、合规、成本和操作留痕 | 模型调用、问数、工具调用、SQL、Token成本、异常调用、菜单权限、多语言 | 全部模块 | 控制谁能看、谁能问、谁能导出、谁能配置模型，并追踪成本和风险。 |

4. 跨模块内在调用关系说明

4.1 智能工作台聚合调用关系

4.2 AI智能问数调用关系

4.3 指标计算调用关系

|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 指标定义维护 → MetricService 保存指标分类、编码、口径、取数SQL → SqlAuditService 校验SQL安全性 → MetricSnapshotTask 定时执行指标SQL → MetricSnapshotService 保存快照结果 → 经营分析、预警规则、报表任务、驾驶舱读取快照结果。 |

4.4 预警扫描与处理闭环

4.5 AI报表生成调用关系

|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 报表任务触发 → ReportTemplateService 读取模板和指标配置 → MetricSnapshotService 读取指标结果 → AnalysisService 读取经营分析明细 → WarningEventService 读取异常事件 → LLMService 按提示词生成摘要、结论和建议 → ReportTaskService 保存生成记录和下载文件 → MessagePushService 向订阅人推送报表。 |

4.6 预测决策调用关系

5. 70个三级功能页面作用、输入输出与调用关系

5.1 智能工作台

|--------|----------|--------------------------------|-------------------------|--------------------------------------|------------------|
| 序号 | 三级功能 | 作用说明 | 上游输入 | 核心调用/处理 | 输出/下游 |
| 1 | AI经营驾驶舱 | 汇聚销售、采购、库存、毛利、预警、报表和模型成本等核心指标。 | 指标快照、预警事件、报表任务、模型调用日志 | DashboardService 聚合查询并缓存页面指标 | 经营日报、预警概览、经营分析详情 |
| 2 | 今日异常待办 | 展示当前需要处理的业务异常和AI待办。 | 预警事件、任务记录、处理状态 | WarningEventService 按风险等级、负责人、时效过滤 | 预警处理、告警对策、消息推送 |
| 3 | AI智能问数 | 通过自然语言查询经营数据。 | 业务术语、字段语义、表映射、问数样例、模型配置 | NLQService 生成SQL、审计SQL、执行查询、AI解释 | 问数日志、常用问题收藏、报表引用 |
| 4 | AI经营日报 | 展示当天经营日报摘要和明细。 | 指标快照、销售订单、采购、库存、财务、预警事件 | ReportService 生成日报，LLM生成摘要 | 报表中心、订阅推送、下载导出 |
| 5 | AI预警概览 | 按模块和等级展示全局预警态势。 | 预警规则、预警事件、指标快照 | WarningDashboardService 聚合预警数量、趋势、等级 | 预警事件、缺货预警、采购价异常等 |
| 6 | 常用问题收藏 | 管理高频问数问题和收藏模板。 | 问数日志、用户收藏、问数样例库 | QuestionFavoriteService 保存、排序、调用常用问题 | AI智能问数、工作台入口 |
| 7 | 我的订阅推送 | 查看个人订阅的报表、预警和消息推送。 | 报表订阅、预警推送、消息记录 | SubscriptionService 维护订阅关系与推送记录 | 消息中心、报表生成、预警推送 |

5.2 经营分析

|--------|----------|-------------------------|----------------------------------------------|-------------------------------------|------------------|
| 序号 | 三级功能 | 作用说明 | 上游输入 | 核心调用/处理 | 输出/下游 |
| 1 | 采购分析 | 分析采购金额、到货率、价格波动和供应商贡献。 | pur_bill、pur_bill_info、供应商、采购价历史 | PurchaseAnalysisService 汇总采购指标 | 采购价异常、采购建议、供应商评分 |
| 2 | 销售订单分析 | 分析销售额、订单数、客户、渠道和退货取消情况。 | oms_order_bill、oms_order_bill_info、客户、商品 | SalesAnalysisService 汇总销售趋势 | 销量预测、报表中心、经营日报 |
| 3 | 库存周转分析 | 分析库存金额、周转天数、缺货和积压。 | wms_goods_inventory、出入库流水、销售成本 | InventoryAnalysisService 计算周转和库存健康度 | 库存优化、缺货预警、滞销分析 |
| 4 | 缺货与滞销分析 | 识别缺货、积压、长时间未动销商品。 | 库存、销售、采购计划、安全库存 | StockoutSlowMovingService 计算缺货和滞销等级 | 补货建议、调拨建议、预警事件 |
| 5 | 配送履约分析 | 分析线路、司机、签收、迟到和履约准时率。 | tms_waybill、配送任务、签收记录 | DeliveryAnalysisService 计算履约指标 | 配送异常预警、日报周报 |
| 6 | 财务毛利分析 | 分析收入、成本、毛利、费用、应收应付。 | fin_customer_bill、fin_supplier_bill、oms、采购成本 | FinanceProfitService 计算毛利和资金风险 | 毛利异常、财务报表、经营建议 |
| 7 | 供应商履约分析 | 评价供应商交付、质量、价格、稳定性。 | 采购单、到货、质检、结算、异常事件 | SupplierPerformanceService 生成履约评分 | 供应商评分、采购建议、预警中心 |
| 8 | 质检溯源分析 | 分析批次、质检结果、溯源信息和质量风险。 | check_report、ts_lot、ts_trace_source | TraceQualityService 串联批次、供应商、客户和订单 | 质量预警、专项报告、知识库 |

5.3 指标中心

|--------|----------|-----------------------|-----------------|----------------------------------------|----------------|
| 序号 | 三级功能 | 作用说明 | 上游输入 | 核心调用/处理 | 输出/下游 |
| 1 | 指标分类 | 维护销售、采购、库存、财务等指标分类。 | 指标表、业务域配置 | MetricCategoryService 管理分类树 | 指标定义、指标权限、看板配置 |
| 2 | 指标定义 | 定义指标编码、名称、单位、维度、业务含义。 | 数据资产、字段语义 | MetricService 维护指标主数据 | 口径维护、SQL、快照、报表 |
| 3 | 指标口径维护 | 维护指标计算说明、版本和口径变更。 | 指标定义、业务规则 | MetricDefinitionService 保存口径版本 | SQL生成、审计、报表说明 |
| 4 | 指标取数SQL | 维护指标从真实业务表取数的SQL。 | 指标口径、数据资产、表字段语义 | MetricSqlService 校验并保存SQL | 指标快照任务、SQL审计 |
| 5 | 指标快照 | 保存按时间周期计算出来的指标结果。 | 指标SQL、调度任务 | MetricSnapshotTask 执行并落库 | 驾驶舱、预警、报表、预测 |
| 6 | 指标看板配置 | 配置哪些指标显示在看板和驾驶舱。 | 指标定义、权限配置 | MetricDashboardConfigService 保存布局和显示规则 | 智能工作台、看板中心 |
| 7 | 指标权限配置 | 控制不同角色可访问的指标和数据范围。 | 角色、部门、指标分类、数据权限 | MetricPermissionService 生成权限规则 | 问数、报表、看板、导出控制 |

5.4 预警中心

|--------|----------|----------------------|-----------------------------|------------------------------------|----------------|
| 序号 | 三级功能 | 作用说明 | 上游输入 | 核心调用/处理 | 输出/下游 |
| 1 | 预警规则 | 定义预警对象、触发条件、等级、处理策略。 | 指标定义、业务表、阈值配置 | WarningRuleService 保存规则并供扫描任务读取 | 预警事件、推送策略 |
| 2 | 预警事件 | 记录规则触发后的异常事件。 | 预警规则、指标快照、业务数据 | WarningEventService 生成、查询、处理事件 | 待办、日报、异常监控 |
| 3 | 缺货预警 | 监控库存低于安全库存或预测缺货。 | 库存、销售预测、安全库存 | StockoutWarningService 识别缺货风险 | 补货建议、调拨建议 |
| 4 | 临期预警 | 监控商品效期、批次到期和临期风险。 | 批次、库存、入库日期、保质期 | ExpiryWarningService 生成临期事件 | 促销建议、损耗异常 |
| 5 | 采购价异常 | 监控采购价相对历史均价和市场价波动。 | 采购价历史、供应商报价、采购单 | PurchasePriceWarningService 识别异常波动 | 采购分析、供应商评分 |
| 6 | 毛利异常 | 监控负毛利、低毛利、毛利突降。 | 销售、成本、促销、采购价 | ProfitWarningService 计算毛利偏差 | 财务毛利分析、经营建议 |
| 7 | 损耗异常 | 监控报损、报溢、损耗率异常。 | wms_loss_overflow、库存流水、销售数据 | LossWarningService 识别异常损耗 | 库存优化、专项报告 |
| 8 | 推送策略 | 配置预警和报表推送渠道、对象和频率。 | 预警规则、角色、用户、订阅关系 | PushStrategyService 生成推送任务 | 站内信、短信、邮件、企业微信 |

5.5 报表中心

|--------|----------|----------------------|------------------|-----------------------------|-------------|
| 序号 | 三级功能 | 作用说明 | 上游输入 | 核心调用/处理 | 输出/下游 |
| 1 | 报表模板 | 维护报表字段、指标、图表、AI摘要规则。 | 指标定义、模板配置 | ReportTemplateService 保存模板 | 日报周报月报、专项报告 |
| 2 | AI日报 | 自动生成日经营报告。 | 指标快照、经营分析、预警事件 | ReportGenerateService 日任务生成 | 订阅推送、下载导出 |
| 3 | AI周报 | 自动生成周经营复盘。 | 周指标快照、异常趋势、AI建议 | WeeklyReportService 汇总周数据 | 经营建议、专项分析 |
| 4 | AI月报 | 自动生成月经营总结。 | 月指标快照、财务毛利、供应商履约 | MonthlyReportService 生成月报 | 管理层报表、导出 |
| 5 | 专项分析报告 | 按主题生成深度分析。 | 业务筛选条件、指标、预警、模型 | SpecialReportService 生成专题报告 | 经营建议闭环 |
| 6 | 报表任务 | 管理生成任务、重试、失败原因。 | 报表模板、调度配置 | ReportTaskService 调度与状态管理 | 生成记录、下载导出 |
| 7 | 报表生成记录 | 记录每次报表生成结果和版本。 | 报表任务、文件记录 | ReportRecordService 保存历史版本 | 审计、下载、订阅 |
| 8 | 报表导出下载 | 提供Excel、PDF、Word等下载。 | 报表记录、文件存储 | ReportExportService 生成下载文件 | 操作日志、成本统计 |

5.6 预测决策

|--------|----------|--------------------|-------------------|---------------------------------|--------------|
| 序号 | 三级功能 | 作用说明 | 上游输入 | 核心调用/处理 | 输出/下游 |
| 1 | 销量预测 | 预测未来销量和订单趋势。 | 历史销售、节假日、客户、商品 | SalesForecastService 计算预测结果 | 补货建议、采购建议 |
| 2 | 补货建议 | 根据库存和预测销量建议补货。 | 销量预测、库存、安全库存、采购周期 | ReplenishmentService 生成补货清单 | 采购建议、缺货预警 |
| 3 | 库存优化 | 优化库存结构、周转和仓库分布。 | 库存快照、销售趋势、损耗、滞销 | InventoryOptimizeService 计算优化方案 | 调拨建议、滞销处理 |
| 4 | 采购建议 | 建议采购商品、数量、供应商和时间。 | 补货建议、采购价、供应商履约 | PurchaseRecommendService 生成采购建议 | 采购分析、供应商评分 |
| 5 | 调拨建议 | 建议仓库、门店、线路之间的库存调拨。 | 库存分布、订单需求、配送能力 | TransferRecommendService 生成调拨方案 | 缺货预警、配送履约 |
| 6 | 供应商评分 | 形成供应商综合评分。 | 采购、到货、质检、价格、结算 | SupplierScoreService 计算评分 | 采购建议、供应商履约分析 |
| 7 | 经营建议闭环 | 跟踪AI建议的采纳、执行、反馈。 | 建议记录、执行单据、处理结果 | RecommendationService 管理建议状态 | 采纳效果评估、报表中心 |
| 8 | 采纳效果评估 | 评估AI建议带来的效果。 | 采纳记录、前后指标快照 | AdoptionEffectService 做前后对比 | 模型优化、经营复盘 |

5.7 知识库与语义

|--------|----------|-------------------|---------------------|-------------------------------|--------------|
| 序号 | 三级功能 | 作用说明 | 上游输入 | 核心调用/处理 | 输出/下游 |
| 1 | 知识库管理 | 管理业务知识库。 | 知识库主表、权限、业务域 | KnowledgeService 管理知识库 | 文档管理、RAG检索 |
| 2 | 文档管理 | 上传、解析、审核、发布文档。 | PDF、Word、Excel、业务制度 | KnowledgeDocumentService 解析文档 | 分段向量、全文检索 |
| 3 | 分段向量检索 | 检索向量化分段。 | 文档分段、Embedding模型 | VectorSearchService 检索相似片段 | RAG测试、问数解释 |
| 4 | 业务术语库 | 维护业务名词、别名、解释。 | 术语表、业务域 | TermService 标准化业务表达 | 问数、报表、提示词 |
| 5 | 表字段语义 | 维护数据库字段中文含义和敏感级别。 | 真实业务表字段 | FieldSemanticService 管理字段语义 | SQL生成、脱敏、权限 |
| 6 | 业务表映射 | 维护页面、业务域与真实表的映射。 | 数据资产、字段语义 | TableMappingService 管理映射关系 | 问数、指标SQL、报表 |
| 7 | 问数样例库 | 维护自然语言问题和标准SQL样例。 | 历史问数、标准SQL | NlqSampleService 训练问数提示词 | AI智能问数、SQL审计 |
| 8 | RAG检索测试 | 测试知识库检索质量。 | 问题、知识库、检索策略 | RagTestService 评估命中率和回答质量 | 知识库优化、模型提示词 |

5.8 模型配置

|--------|----------|-------------------------|------------------|--------------------------------|----------------|
| 序号 | 三级功能 | 作用说明 | 上游输入 | 核心调用/处理 | 输出/下游 |
| 1 | API密钥配置 | 管理模型服务商Key。 | 服务商、环境、密钥、额度 | ApiKeyService 加密保存和连通性测试 | 模型调用、成本统计 |
| 2 | 大模型配置 | 维护大模型名称、接口、上下文、默认模型。 | API Key、服务商、模型参数 | ModelService 管理模型配置 | 所有AI调用 |
| 3 | 模型参数方案 | 维护温度、TopP、最大Token等参数方案。 | 模型配置、业务场景 | ModelParamPlanService 管理参数模板 | 报表、问数、RAG、预测 |
| 4 | 助手角色配置 | 配置AI助手角色、系统提示词和权限。 | 角色、提示词、模型方案 | AssistantRoleService 管理助手角色 | 智能问数、经营建议 |
| 5 | 提示词模板 | 维护各场景Prompt模板。 | 业务场景、模型参数、术语库 | PromptTemplateService 渲染Prompt | 报表生成、SQL生成、RAG |
| 6 | 工具函数配置 | 配置可被AI调用的内部工具。 | 接口、权限、参数Schema | ToolFunctionService 管理工具调用 | 智能问数、经营建议 |
| 7 | 调用额度配置 | 控制模型调用限额、频率和预算。 | 用户、角色、模型、Token规则 | QuotaService 检查额度 | 审计、成本统计 |
| 8 | 敏感词与脱敏 | 配置敏感词、字段脱敏和输出过滤。 | 字段语义、敏感词库 | SensitiveService 执行脱敏与过滤 | 问数、报表、模型调用 |

5.9 审计与权限

|--------|------------|--------------------|-----------------|--------------------------|------------|
| 序号 | 三级功能 | 作用说明 | 上游输入 | 核心调用/处理 | 输出/下游 |
| 1 | 模型调用日志 | 记录模型输入输出摘要和Token。 | 模型调用请求 | ModelCallLogService 落库 | 成本统计、异常监控 |
| 2 | 问数日志 | 记录自然语言问题、SQL和结果摘要。 | 问数请求 | NlqLogService 落库 | 常用问题、SQL审计 |
| 3 | 工具调用日志 | 记录AI工具函数调用。 | 工具函数配置、调用参数 | ToolCallLogService 落库 | 异常调用监控 |
| 4 | 生成SQL审计 | 审计大模型生成SQL是否安全。 | 候选SQL、字段权限、表白名单 | SqlAuditService 审计和拦截 | 问数执行、风险监控 |
| 5 | 成本与Token统计 | 统计模型调用成本和Token消耗。 | 模型调用日志、额度配置 | TokenCostService 汇总 | 额度控制、财务统计 |
| 6 | 异常调用监控 | 监控失败、超时、越权调用。 | 模型日志、工具日志、SQL审计 | AbnormalCallService 识别异常 | 预警中心、审计报表 |

6. 后端服务划分与调用边界

|------------------|----------|---------------------------------------|---------------------------------------------------------------------------|
| 后端服务 | 对应栏目 | 服务职责 | 主要依赖/被依赖 |
| DashboardService | 智能工作台 | 聚合指标快照、预警、报表、订阅消息和模型成本。 | MetricSnapshotService、WarningEventService、ReportTaskService、NlqLogService |
| AnalysisService | 经营分析 | 统一封装采购、销售、库存、配送、财务、供应商、质检分析入口。 | BusinessSourceService、MetricSnapshotService |
| MetricService | 指标中心 | 维护指标分类、定义、口径、SQL、快照和权限。 | DataAssetService、SqlAuditService、MetricSnapshotTask |
| WarningService | 预警中心 | 管理规则、事件、阈值、推送、处理闭环。 | MetricService、BusinessSourceService、PushService |
| ReportService | 报表中心 | 管理模板、任务、生成记录、导出下载。 | MetricSnapshotService、WarningEventService、LLMService |
| ForecastService | 预测决策 | 销量预测、补货、采购、调拨、库存优化和建议评估。 | AnalysisService、MetricSnapshotService、ModelService |
| KnowledgeService | 知识库与语义 | 管理知识库、文档、分段、向量、术语、字段语义和表映射。 | EmbeddingService、RagSearchService |
| ModelService | 模型配置 | 统一模型、密钥、参数、角色、提示词、工具和脱敏配置。 | ApiKeyService、QuotaService、PromptService |
| AuditService | 审计与权限 | 记录模型调用、问数、工具、SQL、Token、异常、菜单授权和多语言维护。 | 所有业务服务 |

7. 数据库表与模块映射

|------------------------|----------------|-----------------------------|
| 表名 | 关联模块 | 作用说明 |
| ai_model | 模型配置 | 大模型配置、默认模型、接口地址、上下文长度、模型类型。 |
| ai_api_key | 模型配置 | 服务商密钥、环境、加密Key、有效期、启停状态。 |
| ai_prompt_template | 模型配置 | 提示词模板、业务场景、变量、版本、启用状态。 |
| ai_tool_function | 模型配置/审计 | 工具函数配置、接口、参数Schema、权限编码。 |
| ai_knowledge | 知识库与语义 | 知识库主表，按业务域、权限和语言管理。 |
| ai_knowledge_document | 知识库与语义 | 文档管理、解析状态、文件类型、审核发布状态。 |
| ai_knowledge_segment | 知识库与语义 | 文档分段、向量索引、片段文本、命中次数。 |
| ai_scm_data_asset | 知识库与语义/指标中心 | 真实业务表登记和数据资产白名单。 |
| ai_scm_field_semantic | 知识库与语义/问数 | 字段中文含义、敏感级别、脱敏规则、可问数字段。 |
| ai_scm_table_mapping | 知识库与语义/指标中心 | 页面、业务域、指标与真实业务表的映射关系。 |
| ai_scm_metric | 指标中心 | 指标分类、定义、单位、维度、口径说明。 |
| ai_scm_metric_sql | 指标中心 | 指标取数SQL、数据源、执行周期和SQL审计状态。 |
| ai_scm_metric_snapshot | 指标中心/工作台/预警/报表 | 指标计算快照，供驾驶舱、分析、预警、报表读取。 |
| ai_scm_warning_rule | 预警中心 | 预警规则、触发条件、等级、处理时限和推送策略。 |
| ai_scm_warning_event | 预警中心/工作台 | 预警事件、处理状态、责任人、处理结果。 |
| ai_scm_report_template | 报表中心 | 报表模板、指标清单、图表配置、AI摘要规则。 |
| ai_scm_report_task | 报表中心 | 报表生成任务、周期、状态、失败原因和重试次数。 |
| ai_scm_report_record | 报表中心 | 报表生成记录、文件地址、版本、下载次数。 |
| ai_scm_forecast_result | 预测决策 | 销量、补货、采购、调拨、库存优化预测结果。 |
| ai_scm_recommendation | 预测决策 | 经营建议、采纳状态、执行记录、效果评估。 |
| ai_scm_nlq_log | 智能问数/审计 | 自然语言问数、生成SQL、执行结果摘要、耗时。 |
| ai_scm_model_call_log | 模型配置/审计 | 模型调用日志、Token、成本、失败原因。 |
| ai_scm_sql_audit_log | 审计与权限 | 生成SQL审计、拦截原因、风险级别、执行状态。 |
| ai_scm_token_cost_stat | 审计与权限 | 按用户、模型、场景统计成本和Token消耗。 |

8. 主要业务流程开发说明

|--------|-----------------|---------------------------------------------------------------|-------------------------|
| 流程 | 触发入口 | 内部调用关系 | 开发要点 |
| 驾驶舱初始化 | 前端进入AI经营驾驶舱 | 调用/dashboard/summary、/warning/todo、/report/latest、/model/cost | 所有结果均按dept_id和数据权限过滤。 |
| 指标快照生成 | 定时任务或手动重算 | 读取ai_scm_metric_sql，审计SQL，通过后执行并写入ai_scm_metric_snapshot | 失败要写任务日志并通知管理员。 |
| 预警事件生成 | 指标或业务数据达到规则阈值 | WarningScanTask读取规则并生成ai_scm_warning_event | 同一对象同一规则需去重，避免重复告警。 |
| AI报表生成 | 手动生成、定时生成或订阅触发 | ReportTaskService拉取指标、预警、分析数据，再调用模型生成摘要 | 报表文件、摘要、生成记录都要可追溯。 |
| 自然语言问数 | 用户输入问题 | 术语解析→表映射→SQL生成→SQL审计→执行查询→AI解释 | 禁止执行写操作SQL，必须限制表白名单和行数。 |
| RAG问答 | 用户提问或报表生成需要知识补充 | 检索知识库分段→重排→组装Prompt→模型回答 | 需要记录命中文档、分段、相似度。 |
| 经营建议闭环 | 预测或规则产生建议 | 生成建议→用户采纳/驳回→关联业务动作→评估效果 | 形成AI建议效果评估，用于后续优化。 |

9. 权限、审计、安全与多语言要求

|---------|-------------------------------------------------------------------------------------------------|
| 控制项 | 开发要求 |
| 菜单权限 | 一级AI助手、二级栏目、三级功能页面写入sys_menu；按钮权限不作为菜单展示。 |
| 数据权限 | 所有查询必须带dept_id、用户数据范围、角色权限和指标权限。 |
| SQL安全 | AI生成SQL仅允许SELECT；禁止INSERT、UPDATE、DELETE、DROP、TRUNCATE、ALTER；限制表白名单和最大返回行数。 |
| 模型安全 | API Key加密存储；模型输出需脱敏；调用额度按用户、角色、模型、场景控制。 |
| 日志审计 | 模型调用、问数、工具函数、报表生成、预警处理、SQL审计必须落库。 |
| 多语言 | 菜单名称、字段说明、报表标题和知识库内容可通过翻译表维护。 |
| 通用字段 | AI助手所有业务表统一使用sort_code、del_flag、enabled、creator、create_date、updater、update_date、remark、dept_id。 |

10. 开发落地顺序

|--------|------------------------------------------------|----------------------|
| 阶段 | 开发范围 | 目标 |
| 第一阶段 | 模型配置、API密钥、提示词模板、模型调用日志、指标分类、指标定义、指标取数SQL、指标快照 | 先打通AI调用和指标计算底座。 |
| 第二阶段 | AI经营驾驶舱、经营日报、预警规则、预警事件、推送策略 | 形成指标→预警→工作台→消息的闭环。 |
| 第三阶段 | 采购、销售、库存、配送、财务、供应商、质检溯源分析 | 接入真实供应链业务表，形成经营分析能力。 |
| 第四阶段 | 报表模板、AI日报、AI周报、AI月报、专项报告、导出下载 | 形成AI报表交付能力。 |
| 第五阶段 | 知识库、文档、分段向量、业务术语、表字段语义、RAG测试、智能问数 | 形成自然语言问数和知识增强能力。 |
| 第六阶段 | 销量预测、补货建议、库存优化、采购建议、调拨建议、供应商评分、经营建议闭环、采纳效果评估 | 形成预测决策和建议闭环。 |
| 第七阶段 | SQL审计、Token成本、异常调用、菜单授权、多语言菜单维护 | 形成安全审计、成本控制和权限治理。 |

11. 验收重点

|---------|-----------------------------------------|
| 验收项 | 验收标准 |
| 功能验收 | 70个三级页面可从AI助手菜单进入，页面只显示具体功能，不再显示弹出导航菜单。 |
| 数据验收 | 经营分析、指标快照、预警事件、报表数据均能从真实业务表或AI配置表追溯来源。 |
| 权限验收 | 不同角色只能查看授权菜单、按钮、指标、数据范围。 |
| AI验收 | 问数、RAG、报表摘要、经营建议均有模型调用日志和Token成本。 |
| 安全验收 | 生成SQL可被审计，危险SQL会被拦截；敏感字段可脱敏。 |
| 性能验收 | 驾驶舱常规查询3秒内，指标快照和报表任务异步执行，失败可重试。 |
| 审计验收 | 预警处理、报表生成、模型配置修改、API密钥变更等均有操作日志。 |