smqjh-agent/docs/AI_PHASE1_FEASIBILITY.md

市民请集合 AI 第一期需求可行性分析

日期：2026-06-30

结论

第一期需求可以做，但要拆成三类能力落地：

1. 可直接支持：订单、商品、会员、物流、积分、充值、月结企业清单等查询类能力。业务系统已有接口和数据库表，Agent 可以通过 MCP 做只读查询并输出表格。
2. 可半自动支持：月结报告、充值导入、商品名称对应、报价单生成。需要 Agent 先生成预览、差异清单、Excel 文件，再由管理员确认。
3. 暂不应直接自动执行：上架、下架、批量改价、充值正式导入、结算确认等写操作。需要业务系统提供带审批/幂等/审计的 MCP Action 入口，Agent 不能直接写库。

已确认的业务系统依据

订单与物流

业务入口：

• smqjh-oms/oms-boot/src/main/java/com/smqjh/mall/oms/controller/xsb/OrderController.java
• 后台列表：GET /api/v1/order/backendOrderList
• 订单详情：GET /api/v1/order/backendOrderInfo
• 物流节点：GET /api/v1/order/deliveryNode
• 骑手信息：GET /api/v1/order/riderInfo
• 物流轨迹：GET /api/v1/order/queryTrace
• 导出：POST /api/v1/order/export?exportType=ORDER|PRODUCT

关键表：

• smqjh_oms.oms_order
• smqjh_oms.oms_order_item

关键字段：

• 订单号：order_number
• 企业渠道：channel_id, channel_name
• 支付：is_payed, pay_time
• 金额：order_money, total, actual_total, freight_amount, offset_points
• 物流：hb_logistic_status, dvy_type, dvy_flow_id, dvy_no, dvy_name, dvy_time, arrive_time, complete_time
• 收货人：consignee_name, consignee_mobile, consignee_address
• 过滤：COALESCE(delete_status,0)=0

可支持：

• 查询某订单物流状态。
• 按手机号、企业、时间统计订单数和销售额。
• 导出订单表、商品订单表。
• 月结中计算商品总额、现金支付、积分抵扣、运费等。

商品、SKU 与渠道价

业务入口：

• smqjh-pms/pms-boot/src/main/java/com/smqjh/pms/controller/admin/ShopSkuController.java
• GET /api/v1/shopSku/export
• smqjh-pms/pms-boot/src/main/java/com/smqjh/pms/controller/admin/ChannelProdController.java

关键表：

• smqjh_pms.tz_prod
• smqjh_pms.tz_sku
• smqjh_pms.tz_channel_prod
• smqjh_pms.tz_shop_sku

关键字段：

• 商品：prod_id, prod_name, brand_name, brief, price, ori_price, status, is_delete
• SKU：sku_id, sku_name, sku_code, price, ori_price, status, is_delete
• 渠道价：channel_id, sku_id, shop_id, purchase_price, delivery_price, channel_prod_price, is_delete
• 门店 SKU：shop_sku_price, shop_sku_stocks, sale_status, is_delete

可支持：

• 查询商品描述、系统价、SKU、品牌和状态。
• 报价单中补齐商品编码、SKU 编码、渠道价。
• 月结商品明细补齐商品信息。

需要谨慎：

• 上架、下架、批量改价是写操作，必须走审批型 Action，不能直接数据库写入。

会员、渠道与企业

业务入口：

• 企业会员导出：/api/v1/members/enterprise/export
• 用户提供的后台入口：https://shop.backend.zswlgz.com/plt/admin/enterprise/export?channelIdList%5B0%5D=0

关键表：

• smqjh_system.sm_member
• smqjh_system.sm_channel

已确认月结企业：

channelId	channelNo	企业
54	1	招商银行贵阳分行
55	2	中数未来
58	5	铜仁移动

可支持：

• 根据手机号查会员归属企业。
• 按企业渠道生成月结筛选条件。
• 顶级 admin 不需要 tenantCode，非 admin 后续仍要保留租户上下文。

积分充值与积分流水

业务入口：

• smqjh-system/system-boot/src/main/java/com/smqjh/system/controller/PointsRechargeController.java
• GET /api/v1/pointsRecharge/page
• GET /api/v1/pointsRecharge/statisticsList
• POST /api/v1/pointsRecharge/import
• GET /api/v1/pointsRecharge/exportTemplate
• GET /api/v1/pointsRecharge/export
• smqjh-system/system-boot/src/main/java/com/smqjh/system/controller/PointsRecordController.java
• GET /app-api/v1/pointsRecord/backendPointsRecordList
• GET /app-api/v1/pointsRecord/backendPointsRecordListExport

关键表：

• smqjh_system.sm_points_recharge
• smqjh_system.sm_points_record

关键字段：

• 充值：user_id, user_name, user_phone, channel_id, channel_name, recharge_number, points, available_points, consume_points, expiry_points, expiry_date
• 流水：order_number, points_id, variable_points, points_type, currently_available_points, creation_date, is_adjust

可支持：

• 充值信息表整理、查重、排错。
• 生成导入预览和上账凭据。
• 月结核对积分抵扣和消费流水。

需要谨慎：

• POST /pointsRecharge/import 是写操作，必须先预览、校验、人工确认。

第一期功能支持矩阵

需求	可行性	推荐实现方式	风险/缺口
平台生成结算报告	可做	MCP 读取订单、商品明细、积分、运费导出，Python 生成 Excel 汇总与蓝色核对区	运费账单需确认是否稳定包含订单号或配送单号
补齐编码	可做	从 tz_prod/tz_sku/tz_channel_prod 补齐商品、SKU、渠道价	供应商发票名称和商品名不一致时需要名称映射
价格浮动人工确认	可做	生成差异表，标记“需人工确认”	不能自动改业务系统
发送客户核对/打印盖章/开票/待付款状态	可做流程管理	Agent 生成状态记录和提醒，不直接财务确认	需要后续状态表或任务记录表
充值信息调整排错	可做	上传企业表格后，Agent 校验手机号、企业、金额、重复记录，输出预览	正式导入前必须人工确认
导入业务系统	部分可做	调用后端导入接口，前置审批	需要带审计、幂等、回滚/失败报告
企业用户统一发货	部分可做	导出订单分仓，生成供应商/仓库/配送建议表	入库、配送、闪送/快递写操作需业务系统 Action
商品名称对应	部分可做	OCR + 商品库模糊匹配 + 人工确认后保存映射	需要新增映射表或业务接口
报价单生成	部分可做	读取商品、渠道价、外部报价线索，生成报价 Excel	外部市场价来源需要稳定接口或采集源

对话响应优化方案

本轮已在 Web Agent 中加入流式进度事件：

• 后端新增 /api/chat/stream，按 NDJSON 返回阶段事件。
• LangGraph 节点在加载工具、分析需求、执行工具、整理结果时即时发出 trace。
• 前端先显示“正在分析需求/正在执行工具/正在整理结果”等文本，再用最终答案替换进度气泡。
• 如果流式接口不可用，前端自动降级到原 /api/chat。

推荐后续继续增强：

• 每个 MCP 工具返回 progressLabel 和 evidence。
• 长任务输出 taskId，前端可轮询状态。
• 生成 Excel/Word 后返回文件路径、文件大小、生成时间。
• 对写操作统一展示“预览 -> 人工确认 -> 执行 -> 审计记录”的状态链。

MCP 工具规划建议

优先新增或完善这些 MCP 工具：

工具	作用
smqjh.settlement.monthly.preview	已实现：生成月结只读预览，包含订单、商品、积分、充值、运费、差异
smqjh.settlement.monthly.exportExcel	输出结算报告 Excel
smqjh.recharge.import.preview	上传充值表后校验并生成导入预览
smqjh.recharge.import.commit	人工确认后调用业务系统导入接口
smqjh.product.match.preview	发票/OCR/供应商名称与商品库匹配
smqjh.product.mapping.confirm	人工确认后保存名称映射
smqjh.fulfillment.enterprise.plan	企业统一发货订单分仓、入库、配送建议
smqjh.task.status.record	记录“待核对/待盖章/待开票/待付款/已完成”等状态

当前结论

第一期不是“能不能做”的问题，而是要按成熟 Agent 的方式做边界：

• 查询和报表：Agent 可以自动完成。
• 结算、充值、上架、下架：Agent 先生成可审计预览，管理员确认后由受控 Action 执行。
• 所有结果必须带依据：业务接口、数据库表、SQL 口径、导出文件来源。