sqxp/docs/代码层面检查报告.md

叁强鲜配项目代码层面检查报告

1. 检查依据

• 叁强鲜配项目的需求.md
• 叁强鲜配功能点梳理.md
• docs/sql/sanqiang.sql
• docs/原型图/（并参考已有的 docs/原型图/原型图完整性比对报告.md）

2. 检查方法概述

• 功能点（1-15）层面：按“是否存在对应后端接口/CRUD/前端页面/数据表”进行核对。
• 数据库层面：对比 docs/sql/sanqiang.sql 中的 CREATE TABLE 表清单与 backend/app/models/models.py 的 __tablename__/ORM Model 定义是否一致。
• 历史留痕层面：重点检查 CRUD 中是否引用了 *_his ORM Model；若 ORM Model 缺失，则说明“历史表复制/更新留痕”逻辑无法落地。

3. 总体结论

UI 侧：参考 docs/原型图/原型图完整性比对报告.md，其结论为 Web 与小程序页面均已覆盖核心原型页面。

代码侧（严重问题）：存在影响关键业务的“数据库历史表留痕机制”缺口。
docs/sql/sanqiang.sql 中大量业务表都带 *_his 历史表，但在 backend/app/models/models.py 中仅实现了部分历史表 ORM Model（例如 sys_user_his、sys_region_his、bas_product_his、biz_deliverer_review_his、biz_delivery_warning_his 等）。
同时，多处 CRUD/业务逻辑在导入或创建历史表时引用了缺失的 Biz*His Model（例如 BizPriceListHis、BizInquiryHis、BizQuotationHis、BizDeliveryTaskHis、BizOrderHis、BizOrderAdjustHis、BizSettlementHis、BizRefundHis 等）。因此这些“更新留痕/删除留痕/历史复制”路径在当前代码状态下无法正确运行（至少会在导入阶段或历史写入阶段触发 ImportError/AttributeError）。

4. 功能点逐项核对（1-15）

说明：下表的“实现情况”以“代码结构是否具备落地路径”为准；若依赖 *_his ORM Model 缺失，则标记为“未完成/风险”。

1. 基础数据管理（区域/商品/单位码表/基础资料）

   • 代码结构：存在对应 API 与 CRUD（例如 backend/app/api/admin.py、backend/app/crud/region.py、backend/app/crud/product.py、backend/app/crud/unit.py、backend/app/crud/address.py）
   • 历史表 ORM：该类基础表的 _his Model 在 backend/app/models/models.py 中可找到（如 BasProductHis、BasProductCategoryHis、BasProductUnitHis、BasAddressHis 等）
   • 结论：相对可用，风险较低

2. 账号与登录安全管理（创建/加密存储/修改密码/重置密码/登录日志）

   • 代码结构：backend/app/api/public.py 已实现 Web 登录、Refresh/Logout/Current User 等登录链路
   • 历史表 ORM：sys_password_history_his、sys_login_log_his 等在 backend/app/models/models.py 中可找到
   • 结论：相对可用，风险较低

3. 角色与区域权限管理（角色 + 区域过滤、越权禁止）

   • 代码结构：存在按角色分层的接口路由（/web/admin、/supplier、/client、/deliver 等）
   • 结论：路由与角色校验逻辑存在；但由于本次主要发现历史留痕缺口，未对每个查询接口的“严格 region_id 过滤覆盖率”做完备审计

4. 询价管理（运营发布询价；供应商查看；状态/进度）

   • CRUD：backend/app/crud/inquiry.py 引入了 BizInquiryHis、BizInquiryItemHis
   • 历史留痕依赖：backend/app/models/models.py 中未找到 BizInquiryHis / BizInquiryItemHis 等历史 ORM Model
   • 结论：历史留痕路径未完成/高风险

5. 供应商报价管理（供应商提交报价；运营比价/对比/审核）

   • CRUD：backend/app/crud/quotation.py 引入了 BizQuotationHis、BizQuotationItemHis
   • 历史留痕依赖：backend/app/models/models.py 中未找到 BizQuotationHis / BizQuotationItemHis 等历史 ORM Model
   • 结论：历史留痕路径未完成/高风险

6. 区域定价与价格发布管理（版本管理；发布/失效；订单冻结价格版本）

   • CRUD：backend/app/crud/price_list.py 引入了 BizPriceListHis
   • 历史留痕依赖：backend/app/models/models.py 中未找到 BizPriceListHis（以及价格清单项历史 Model 的 _his 相关定义）
   • 结论：历史留痕路径未完成/高风险（价格发布/修改类接口也会受影响）

7. 客户下单与支付管理（线上微信/线下；订单列表与详情）

   • 订单 CRUD 存在：backend/app/crud/order.py 提供订单创建/列表/取消/状态变更等能力
   • 历史留痕依赖：backend/app/crud/order.py 引入了 BizOrderHis，但 backend/app/models/models.py 未找到 BizOrderHis（订单历史/更新留痕不完整）
   • 结论：订单状态变更留痕存在高风险

8. 订单审核与状态流转管理（取消审核、状态锁定/留痕、状态机约束）

   • 历史留痕依赖：同样依赖订单历史表（BizOrderHis 等缺失）
   • 结论：状态流转“留痕链路”未完成/高风险

9. 配送任务管理（运营分配配送；配送员取货/送达任务；1小时预警）

   • CRUD：backend/app/crud/delivery.py 引入了 BizDeliveryTaskHis
   • 历史留痕依赖：backend/app/models/models.py 未找到 BizDeliveryTaskHis（同时配送任务明细历史 Model 也缺失）
   • 结论：配送任务修改留痕未完成/高风险

10. 配送凭证与备注管理（取货/送达图片凭证 + 备注）

    • 接口结构：存在配送员确认取货/送达等接口与附件上传链路（例如 backend/app/api/deliver.py、backend/app/api/upload.py、backend/app/api/attachment.py）
    • 历史表 ORM：附件 _his Model 缺失（docs/sql/sanqiang.sql 有 biz_attachment_his，但 backend/app/models/models.py 未找到 BizAttachmentHis）
    • 结论：若存在“附件更新留痕”诉求，则未完成；否则仍存在一致性风险

11. 异常订单处理（部分送达；订单行减量/替代；重算应收；退款/冲销依据差异）

    • CRUD：backend/app/crud/order_adjust.py 引入 BizOrderAdjustHis
    • 历史留痕依赖：backend/app/models/models.py 未找到 BizOrderAdjustHis
    • 结论：异常调整留痕链路未完成/高风险

12. 结算与退款管理（微信退款；线下结算列表/确认；失败异常标记）

    • CRUD：backend/app/crud/settlement.py 引入 BizSettlementHis、BizRefundHis
    • 历史留痕依赖：backend/app/models/models.py 未找到 BizSettlementHis / BizRefundHis
    • 结论：结算/退款留痕链路未完成/高风险

13. 附件与单据管理（业务单据关联附件上传与查看）

    • 接口结构：backend/app/api/attachment.py、backend/app/api/upload.py 存在附件上传与查询能力
    • 但：biz_attachment_his 的历史 ORM 未实现
    • 结论：附件功能“查询/写入”可能可用，但“历史留痕一致性”未完成

14. 审计日志与运营追踪（账号创建与重置、价格发布、订单审核、异常调整、结算确认、退款处理等）

    • 历史表 ORM：sys_audit_log_his 在 backend/app/models/models.py 中可找到
    • 结论：审计留痕基础模型可用；但“每个关键业务节点是否都写入审计日志”需要进一步按接口逐条验证（本次重点在历史 ORM 缺口）

15. 多端应用支持（Web 管理端 + 微信小程序端）

    • UI 侧：已存在 web-admin/src/views/**、miniprogram/src/pages/** 等页面实现
    • 结论：UI 覆盖“存在”，但后端历史留痕缺口会影响部分关键流程的稳定性

5. 数据库层面一致性检查（SQL vs ORM）

对比：docs/sql/sanqiang.sql 的表清单（包含 *_his） vs backend/app/models/models.py 的 __tablename__ 定义。

发现：docs/sql/sanqiang.sql 中存在以下历史表，但在 backend/app/models/models.py 中未找到对应历史 ORM Model（导致 CRUD 中的 history 写入/复制逻辑无法落地）：

• biz_attachment_his
• biz_delivery_task_his
• biz_delivery_task_item_his
• biz_inquiry_his
• biz_inquiry_item_his
• biz_order_adjust_his
• biz_order_his
• biz_order_item_his
• biz_price_list_his
• biz_price_list_item_his
• biz_quotation_his
• biz_quotation_item_his
• biz_refund_his
• biz_settlement_his
• biz_wechat_pay_his

（注：本次对比以 ORM 是否存在为准；不代表数据库表一定“没有”，SQL 文档中这些表是存在的。）

6. 代码证据（CRUD 引用缺失的历史 Model）

以下 CRUD 明确导入了缺失的历史 Model（在 backend/app/models/models.py 中找不到对应 class），属于“编译/运行时高风险”：

• backend/app/crud/price_list.py 导入 BizPriceListHis
• backend/app/crud/inquiry.py 导入 BizInquiryHis、BizInquiryItemHis
• backend/app/crud/quotation.py 导入 BizQuotationHis、BizQuotationItemHis
• backend/app/crud/order.py 导入 BizOrderHis
• backend/app/crud/delivery.py 导入 BizDeliveryTaskHis
• backend/app/crud/order_adjust.py 使用 BizOrderAdjustHis
• backend/app/crud/settlement.py 导入 BizSettlementHis、BizRefundHis

7. 与原型图比对报告的冲突点

docs/原型图/原型图完整性比对报告.md 结论为 Web/小程序页面均已完成覆盖。
本次“代码层面”额外发现了关键后端历史留痕链路的 ORM 缺口，二者并不必然互斥：原型覆盖可以指“页面与接口骨架存在”，但“业务可运行的留痕/历史复制”仍可能缺失或在特定路径失败。

8. 其他发现

• docs/原型图/原型图完整性比对报告.md 的比对依据中引用了 docs/sql/sanqiang_init.sql，但当前仓库中未发现该文件（仅存在 docs/sql/sanqiang.sql）。

9. 运行时导入校验（快速验证）

我尝试在当前环境中 import backend/app/crud/* 相关模块进行快速校验，结果存在直接失败点（属于更高优先级的问题）：

• app.crud.price_list 导入失败，错误信息显示：Mapper[SysUserHis(sys_user_his)] could not assemble any primary key columns for mapped table 'sys_user_his'
  • 结论：backend/app/models/models.py 中 SysUserHis 的主键配置不满足 SQLAlchemy 映射要求（历史表 ORM 即使类存在，也可能无法正常工作）。