# 陇耘鲜达项目代码层面检查报告 ## 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 即使类存在，也可能无法正常工作）。