dingdanquanliucheng/缺口定位清单.md

# 缺口定位清单

> 说明：本清单基于《确定版需求说明书.md》《开发细节/》系列文档，并结合当前代码扫描结果，按“未完成项 → 具体文件 → 具体函数/页面位置”的方式定位。目的不是复述需求，而是明确“缺口落点在哪里”，方便后续逐项补齐。

---

## 1. 订单流程缺口

### 1.1 订单编辑 / 草稿保存已补齐部分闭环

- **当前状态**：已完成后端更新接口和服务层骨架，仍需继续补前端联动与更完整的状态校验。
- **已落点文件**：
  - `backend/app/api/orders.py`
  - `backend/app/schemas/orders.py`
  - `backend/app/services/order_service.py`
  - `backend/app/repositories/order_repository.py`
- **已落点位置**：
  - `backend/app/api/orders.py` 新增 `update_order()`，对应 `PUT /api/orders/{order_id}`。
  - `backend/app/schemas/orders.py` 新增 `UpdateOrderRequest`。
  - `backend/app/services/order_service.py` 新增 `OrderService.update_order()`，支持草稿/驳回单编辑。
  - `backend/app/repositories/order_repository.py` 新增 `update_order_with_items()`。
- **仍待继续完善**：
  - `frontend/web-sales/src/views/OrderFormPage.vue`
  - `frontend/web-sales/src/views/OrdersPage.vue`
  - `frontend/web-sales/src/views/OrderDetailPage.vue`
- **相关函数**：
  - `OrderService.update_order()`
  - `OrderRepository.update_order_with_items()`
  - `OrderService.create_order()`
  - `OrderService.submit_order()`
  - `OrderService.cancel_order()`

### 1.2 订单审批退回后的通知缺口

- **缺口描述**：需求要求审批退回后通知业务员；当前只有审批日志和审计日志，没有看到完整通知联动。
- **定位文件**：
  - `backend/app/services/order_service.py`
  - `backend/app/services/reminder_service.py`
  - `backend/app/api/reminders.py`
- **具体位置**：
  - `OrderService.approve_order()` 里写了审批日志，但未触发提醒创建或消息推送。
  - `reminder_service` 目前只实现了欠款、沉默客户、物流超时三类提醒检查，没有订单审批通知入口。
- **相关函数**：
  - `OrderService.approve_order()`
  - `ReminderService.check_all()`
  - `ReminderService.list_reminders()`

### 1.3 取消订单的特殊审批链路仍不完整

- **缺口描述**：需求要求草稿/待审直接取消，已通过/履约中进入 `cancel_pending`，并支持取消审批通过/驳回恢复原状态；当前逻辑有状态字段，但完整业务规则还不够严密。
- **定位文件**：
  - `backend/app/api/orders.py`
  - `backend/app/services/order_service.py`
  - `backend/app/repositories/order_repository.py`
- **具体位置**：
  - `backend/app/services/order_service.py` 中 `cancel_order()`、`cancel_approve_order()` 已有基础实现，但对 `cancel_previous_status`、审批拒绝恢复、流程通知的闭环不完整。
  - `backend/app/api/orders.py` 中虽有 `/cancel` 与 `/cancel-approve`，但前端取消弹窗、审批页与状态机联动仍需补齐。
- **相关函数**：
  - `OrderService.cancel_order()`
  - `OrderService.cancel_approve_order()`
  - `OrderRepository.update_cancel_fields()`

### 1.4 确认下发工厂文本的落库与留痕缺口

- **缺口描述**：需求要求生成工厂文本、复制、确认下发，并记录文本日志；当前接口返回文本和确认结果，但日志表/历史记录链路未完全形成闭环。
- **定位文件**：
  - `backend/app/api/orders.py`
  - `backend/app/services/order_service.py`
  - `backend/app/repositories/order_repository.py`
  - `frontend/mini-manager/pages/supplier-text.js`
- **具体位置**：
  - `OrderService.get_supplier_text()` 仅返回文本内容，没有看到明确写入 `order_supplier_text_log` 的持久化动作。
  - `OrderService.confirm_supplier_text()` 只更新订单状态，文本内容、模板类型、确认人/时间的完整日志留痕还不充分。
  - `frontend/mini-manager/pages/supplier-text.js` 需要对照确认下发流程做页面联动。
- **相关函数**：
  - `OrderService.get_supplier_text()`
  - `OrderService.confirm_supplier_text()`

### 1.5 订单状态机仍偏“手动改状态”

- **缺口描述**：需求中的订单状态是严格流程型状态机；当前有通用状态变更接口，但校验和联动不足。
- **定位文件**：
  - `backend/app/services/order_service.py`
  - `backend/app/api/orders.py`
- **具体位置**：
  - `OrderService.change_order_status()` 允许多个目标状态直接切换，但没有严格限制状态路径。
  - `backend/app/api/orders.py` 的 `/status` 接口暴露了通用状态修改能力。
- **相关函数**：
  - `OrderService.change_order_status()`

---

## 2. 司机任务与物流缺口

### 2.1 司机任务创建后订单联动已补齐部分闭环

- **当前状态**：已补充任务取消接口，并继续强化创建/接单/揽货/送达的状态联动与审计。
- **已落点文件**：
  - `backend/app/api/logistics.py`
  - `backend/app/services/logistics_service.py`
  - `backend/app/repositories/logistics_repository.py`
  - `backend/app/models/business.py`
- **已落点位置**：
  - `LogisticsService.create_task()`：创建任务后将订单状态切到 `pending_driver`。
  - `LogisticsService.accept_task()` / `pickup_task()` / `deliver_task()`：形成司机状态流转闭环。
  - `LogisticsService.cancel_task()`：新增任务取消入口，并回写订单状态。
  - `backend/app/api/logistics.py` 新增 `/api/logistics/tasks/{task_id}/cancel`。
  - `backend/app/models/business.py` 新增 `OrderSupplierTextLog` 之外的任务取消字段模型支撑。
- **仍待继续完善**：
  - `frontend/mini-manager/pages/task-create.js`
  - `frontend/web-admin/src/views/BusinessPage.vue`
  - `frontend/mini-driver/pages/task-list.js`
  - `frontend/mini-driver/pages/task-detail.js`
- **相关函数**：
  - `LogisticsService.create_task()`
  - `LogisticsService.accept_task()`
  - `LogisticsService.pickup_task()`
  - `LogisticsService.deliver_task()`
  - `LogisticsService.cancel_task()`

### 2.2 司机端任务可见字段与权限隔离仍需加强

- **缺口描述**：司机只能看到本人任务和脱敏信息；目前有基础限制，但页面与接口的字段控制仍不完全统一。
- **定位文件**：
  - `backend/app/services/logistics_service.py`
  - `backend/app/api/logistics.py`
  - `frontend/mini-driver/pages/task-detail.js`
  - `frontend/mini-driver/pages/task-list.js`
- **具体位置**：
  - `LogisticsService._ensure_task_access()`、`LogisticsService._ensure_trace_access()` 已做基础权限控制。
  - `LogisticsService._map_task_detail()` 仍返回较多业务字段，司机端页面是否完全隐藏敏感字段需要继续核对。
- **相关函数**：
  - `LogisticsService._ensure_task_access()`
  - `LogisticsService._ensure_trace_access()`
  - `LogisticsService._map_task_detail()`

### 2.3 物流轨迹第三方对接未完整上线

- **缺口描述**：需求提到快递100/第三方物流轨迹；当前代码仅保留了远程抓取能力，更多是占位式接入。
- **定位文件**：
  - `backend/app/services/logistics_service.py`
  - `backend/app/repositories/logistics_repository.py`
- **具体位置**：
  - `LogisticsService._load_third_party_traces()`
  - `LogisticsService._fetch_remote_traces()`
  - `LogisticsService.get_trace()`
- **相关函数**：
  - `LogisticsService._fetch_remote_traces()`
  - `LogisticsService._merge_trace_list()`

### 2.4 司机揽货附件上传与 OSS 元数据未完全统一

- **缺口描述**：需求要求图片/视频上传到 OSS，写入附件元数据；当前已有附件写入，但字段级元数据与实际 OSS 约束仍需核对。
- **定位文件**：
  - `backend/app/services/logistics_service.py`
  - `backend/app/services/file_service.py`
  - `backend/app/api/files.py`
- **具体位置**：
  - `LogisticsService._persist_task_attachments()` 将图片/视频落到附件表，但未完全看出对 `storage_provider`、`bucket_name`、`object_key` 的全链路使用。
  - `file_service` 负责附件封装，需核对是否满足需求中的 OSS 字段。
- **相关函数**：
  - `LogisticsService._persist_task_attachments()`
  - `FileService.build_attachment_payload()`

---

## 3. 提醒与配置缺口

### 3.1 提醒中心页面与接口联动已补齐

- **当前状态**：提醒列表筛选与已读操作已补齐前端联动，后端读接口已接通。
- **已落点文件**：
  - `backend/app/api/reminders.py`
  - `backend/app/services/reminder_service.py`
  - `frontend/web-sales/src/views/RemindersPage.vue`
  - `frontend/web-sales/src/mockApi.js`
- **已落点位置**：
  - `ReminderService.list_reminders()`、`ReminderService.read_reminder()` 已支持列表与已读闭环。
  - `frontend/web-sales/src/views/RemindersPage.vue` 已支持筛选和标记已读。
- **相关函数**：
  - `ReminderService.list_reminders()`
  - `ReminderService.read_reminder()`
  - `readReminder()`

### 3.2 欠款生成与提醒口径未完全固化

- **缺口描述**：需求明确欠款按 `shipped/delivered` 配置生成，且提醒只生成一次；当前提醒逻辑有雏形，但需要和订单状态/欠款状态完全对齐。
- **定位文件**：
  - `backend/app/services/reminder_service.py`
  - `backend/app/services/arrears_service.py`
  - `backend/app/repositories/config_repository.py`
  - `backend/app/api/configs.py`
- **具体位置**：
  - `ReminderService.check_arrears()`、`check_inactive_customers()`、`check_logistics_timeout()` 有基本规则。
  - 配置读取依赖 `ConfigRepository.get_by_key()`，需要确认欠款起算、物流超时、沉默客户阈值已在所有业务点统一引用。
- **相关函数**：
  - `ReminderService.check_arrears()`
  - `ReminderService.check_inactive_customers()`
  - `ReminderService.check_logistics_timeout()`
  - `ReminderService._get_config_value()`

### 3.3 配置中心页面与即时生效闭环不足

- **缺口描述**：需求要求系统配置可视化管理并即时生效；当前后端有配置服务，但页面与缓存刷新未完全闭合。
- **定位文件**：
  - `backend/app/api/configs.py`
  - `backend/app/services/config_service.py`
  - `frontend/web-admin/src/views/SystemPage.vue`
- **具体位置**：
  - `ConfigService` 负责读取/写入配置，但前端系统配置页是否覆盖全部配置项、是否支持联动刷新，还需继续补齐。
- **相关函数**：
  - `ConfigService.get_config()`
  - `ConfigService.update_config()`

---

## 4. 客户、产品、供应商缺口

### 4.1 客户导入接口未形成完整闭环

- **缺口描述**：需求要求客户导入、去重、失败返回；当前代码中客户创建和详情存在，但导入链路缺口明显。
- **定位文件**：
  - `backend/app/api/customers.py`
  - `backend/app/services/customer_service.py`
  - `frontend/web-admin/src/views/BusinessPage.vue`
- **具体位置**：
  - `CustomerService` 需要核对是否存在批量导入函数；从当前代码扫描看，导入链路未形成完整页面与接口闭环。
- **相关函数**：
  - `CustomerService.create_customer()`
  - `CustomerService.list_customers()`
  - `CustomerService.get_customer()`

### 4.2 产品分类独立维护未完全落地

- **缺口描述**：需求要求独立产品分类管理页面和接口；当前产品模块存在分类字段，但独立 CRUD 与前端页面还需补齐。
- **定位文件**：
  - `backend/app/api/products.py`
  - `backend/app/services/product_service.py`
  - `backend/app/repositories/product_repository.py`
  - `frontend/web-admin/src/views/MasterDataPage.vue`
- **具体位置**：
  - `ProductService` 负责产品列表/详情/创建，但分类独立维护能力仍需核对。
  - `frontend/web-admin/src/views/MasterDataPage.vue` 承担主数据页，分类管理是否完整展示需要补齐。
- **相关函数**：
  - `ProductService.list_products()`
  - `ProductService.create_product()`
  - `ProductService.get_product()`

### 4.3 工厂/供应商模板类型差异未完全实现

- **缺口描述**：需求要求工厂模板类型可配置并参与下发文案生成；当前只有基础 supplier 管理。
- **定位文件**：
  - `backend/app/api/suppliers.py`
  - `backend/app/services/supplier_service.py`
  - `backend/app/repositories/supplier_repository.py`
- **具体位置**：
  - `SupplierService` 负责供应商 CRUD，但模板类型、下发文本模板差异的业务规则需要继续确认。
- **相关函数**：
  - `SupplierService.list_suppliers()`
  - `SupplierService.create_supplier()`
  - `SupplierService.update_supplier()`

---

## 5. 系统管理缺口

### 5.1 用户管理列表分页已补齐前端联动，后端仍保留简化分页

- **当前状态**：前端用户/角色/菜单管理页已接通真实接口；后端仍采用接口层切片分页，但已满足当前功能闭环。
- **已落点文件**：
  - `backend/app/api/system.py`
  - `backend/app/services/system_service.py`
  - `frontend/web-admin/src/views/SystemPage.vue`
  - `frontend/web-admin/src/mockApi.js`
- **已落点位置**：
  - `SystemPage.vue` 已支持用户、角色、菜单的查询、新增、编辑、授权、重置密码。
  - `mockApi.js` 已按真实接口路径完成联调封装。
- **相关函数**：
  - `SystemService.list_users()`
  - `SystemService.list_roles()`
  - `SystemService.list_menus()`

### 5.2 用户停用/启用与重置密码以外的生命周期未完整

- **缺口描述**：需求要求用户、角色、菜单的停用启用、权限变更、异常约束完整；当前实现还偏基础。
- **定位文件**：
  - `backend/app/services/system_service.py`
  - `backend/app/api/system.py`
- **具体位置**：
  - `SystemService.create_user()`、`update_user()`、`reset_password()` 有实现，但用户停用/启用、批量操作等未完整。
  - `SystemService.update_role()` 已拦截管理员角色停用，但其他角色生命周期还需补齐。
- **相关函数**：
  - `SystemService.create_user()`
  - `SystemService.update_user()`
  - `SystemService.reset_password()`
  - `SystemService.update_role()`

### 5.3 菜单权限即时生效/缓存刷新缺口

- **缺口描述**：需求要求角色授权后菜单和按钮权限立即生效；当前代码能授权，但没有看到 token/缓存层的即时刷新。
- **定位文件**：
  - `backend/app/services/system_service.py`
  - `backend/app/api/auth.py`
  - `frontend/web-admin/src/store.js`
- **具体位置**：
  - `SystemService.assign_role_menus()` 写库后未见缓存失效逻辑。
  - 登录后前端 store/路由刷新机制需继续核对。
- **相关函数**：
  - `SystemService.assign_role_menus()`
  - `SystemService.get_role_menu_assignment()`

---

## 6. 报表、审计、导出缺口

### 6.1 报表口径与导出前端闭环已接通，细分口径仍可继续优化

- **当前状态**：报表查询与导出接口已接通前端；口径统一已作为后续优化项保留。
- **已落点文件**：
  - `backend/app/api/reports.py`
  - `backend/app/services/report_service.py`
  - `backend/app/repositories/report_repository.py`
  - `frontend/web-admin/src/views/ReportsPage.vue`
  - `frontend/web-admin/src/mockApi.js`
- **已落点位置**：
  - `ReportService.get_performance_report()`
  - `ReportService.export_performance_report()`
  - `fetchPerformanceReport()`
  - `exportPerformanceReport()`
- **相关函数**：
  - `ReportService.get_performance_report()`
  - `ReportService.export_performance_report()`

### 6.2 审计日志覆盖面已覆盖主要闭环，细节仍可继续增强

- **当前状态**：订单、物流、提醒、系统管理、报表导出均已具备审计写入；后续可继续扩展到更多细粒度场景。
- **已落点文件**：
  - `backend/app/services/audit_service.py`
  - `backend/app/api/audit_logs.py`
  - `backend/app/services/order_service.py`
  - `backend/app/services/logistics_service.py`
  - `backend/app/services/reminder_service.py`
  - `backend/app/services/report_service.py`
  - `backend/app/services/system_service.py`
- **已落点位置**：
  - `OrderService.create_order()` / `approve_order()` / `cancel_order()` / `update_order()`
  - `LogisticsService.create_task()` / `_persist_task_attachments()` / `cancel_task()`
  - `ReminderService.read_reminder()`
  - `ReportService.export_performance_report()`
  - `SystemService.create_user()` / `update_user()` / `reset_password()` / `create_role()` / `update_role()` / `assign_role_menus()` / `create_menu()` / `update_menu()`
- **相关函数**：
  - `audit_service.write_log()` 的各调用点

---

## 7. 前端页面缺口

### 7.1 业务员端订单编辑与提醒中心已补齐主要闭环

- **当前状态**：业务员端已支持订单新建、编辑、详情、提交、取消，以及提醒筛选和已读。
- **已落点文件**：
  - `frontend/web-sales/src/views/OrderFormPage.vue`
  - `frontend/web-sales/src/views/OrdersPage.vue`
  - `frontend/web-sales/src/views/OrderDetailPage.vue`
  - `frontend/web-sales/src/views/RemindersPage.vue`
- **已落点位置**：
  - 订单编辑/草稿保存按钮已接通更新链路。
  - 订单详情页已补充编辑入口。
  - 提醒中心已补充筛选、已读和状态展示。

### 7.2 管理后台主数据、业务、系统页已补入订单相关信息

- **当前状态**：管理后台已补入订单业务入口、订单详情入口和物流调度信息，不再只停留在客户/产品/系统配置层。
- **已落点文件**：
  - `frontend/web-admin/src/views/MasterDataPage.vue`
  - `frontend/web-admin/src/views/SystemPage.vue`
  - `frontend/web-admin/src/views/BusinessPage.vue`
  - `frontend/web-admin/src/views/ReportsPage.vue`
  - `frontend/web-admin/src/views/ApprovalDetailPage.vue`
- **已落点位置**：
  - `BusinessPage.vue` 现可查看待发厂订单、订单详情入口、生成发厂文案、确认下发、创建司机任务，并支持订单/任务状态筛选。
  - `SystemPage.vue` 已覆盖用户、角色、菜单的查询、新增、编辑、授权、重置密码。
  - `ReportsPage.vue` 已接通真实导出查看入口。
  - `MasterDataPage.vue` 已新增订单快捷入口，客户详情可直达审批与履约。
  - `ApprovalDetailPage.vue` 已补充取消上下文、审批后去向说明及订单/履约/报表联动入口。
- **仍待继续优化**：
  - 主数据页的分类/产品细节与订单联动统计
  - 任务详情页与业务调度页的更深跳转联动

### 7.3 小程序管理层与司机端页面已接入主流程，仍可继续细化

- **当前状态**：管理层小程序和司机端已接入发厂文案、司机任务创建与执行主流程。
- **定位文件**：
  - `frontend/mini-manager/pages/approve-list.js`
  - `frontend/mini-manager/pages/approve-detail.js`
  - `frontend/mini-manager/pages/supplier-text.js`
  - `frontend/mini-manager/pages/task-create.js`
  - `frontend/mini-manager/pages/dashboard.js`
  - `frontend/mini-driver/pages/task-list.js`
  - `frontend/mini-driver/pages/task-detail.js`
- **仍待继续优化**：
  - 按订单状态控制按钮显隐
  - 附件上传的错误提示与重试
  - 审批意见与取消上下文的展示密度

---

## 8. 可直接作为后续开发入口的优先文件

如果要按优先级补齐，建议先从以下文件开始：

1. `backend/app/services/order_service.py`
2. `backend/app/api/orders.py`
3. `backend/app/services/logistics_service.py`
4. `backend/app/api/logistics.py`
5. `backend/app/services/reminder_service.py`
6. `backend/app/services/system_service.py`
7. `frontend/web-sales/src/views/OrderFormPage.vue`
8. `frontend/web-admin/src/views/SystemPage.vue`
9. `frontend/mini-manager/pages/supplier-text.js`
10. `frontend/mini-driver/pages/task-detail.js`

---

## 9. 说明

本清单是“定位清单”，不是最终修复方案。下一步如果需要，我可以继续把这些缺口整理成：

- **按 P0/P1/P2 排序的修复计划**
- **按文件拆分的改造任务卡**
- **按模块输出的逐项代码修改建议**