taiyi/dingdanquanliucheng
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4e47386e56
dingdanquanliucheng/缺口定位清单.md

20 KiB
Raw Blame History

缺口定位清单

说明：本清单基于《确定版需求说明书.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 排序的修复计划
  • 按文件拆分的改造任务卡
  • 按模块输出的逐项代码修改建议