# 市民请集合 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 口径、导出文件来源。