root/dealerhub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b3f3095d53d6da2cced5891ec921d97c0a13f691
dealerhub/PROGRESS_PHASE4_MODULES.md
T

8.1 KiB
Raw Blame History

dealerhub · 全功能模块落地与验收报告（阶段 3 & 阶段 4 汇总）

目标：在完成基础进销存与深度财务总账的基础上，将 PLAN.md 规划中的全部扩展中心落盘落地：

  1. 报表与 BI 分析中心 (apps/report)
  2. 全渠道与电商对接中心 (apps/channel)
  3. 通知与智能预警中心 (apps/notify)
  4. 开放平台与 API Key 开放接口 (apps/openapi)

一、新增模块架构概览

dealerhub/backend/apps/
├── core/         # 租户、组织、审计、工作流状态机
├── catalog/      # 商品中心（分类/品牌/单位/多规格商品）
├── inventory/    # 仓储中心（多仓/库存原子操作/加权平均成本/出入库流水）
├── partner/      # 往来单位（客户/供应商/联系人/价格等级）
├── purchase/     # 采购中心（采购订单/采购入库开单/应付过账）
├── sales/        # 销售中心（销售订单/销售出库开单/应收过账/成本自动结转）
├── finance/      # 完整财务（应收应付核销/会计科目树/期间管理/记账凭证/期末损益结转/三大报表与明细账）
│
├── report/       # [新增] 报表与 BI 分析中心
│   ├── models.py       # ReportDefinition（元数据动态报表定义）
│   ├── services.py     # 经营大盘总览指标、销售排行、库存资产分布与估值
│   ├── views.py        # DashboardViewSet + ReportDefinitionViewSet
│   └── urls.py         # /api/v1/report/*
│
├── channel/      # [新增] 全渠道与电商对接中心
│   ├── models.py       # ChannelAccount（店铺授权）、ChannelOrder（外部订单映射）、WebhookEvent（回调日志）
│   ├── adapters.py     # ChannelAdapter 抽象层、MockAdapter、DouyinAdapter、1688Adapter
│   ├── services.py     # 自动拉单、外部订单映射转换为内部销售单（SalesOrder）
│   ├── views.py        # ChannelAccountViewSet、ChannelOrderViewSet、WebhookViewSet
│   └── urls.py         # /api/v1/channel/*
│
├── notify/       # [新增] 消息通知与智能预警中心
│   ├── models.py       # Notification（站内信）、AlertRule（库存/应收/呆滞预警规则）
│   ├── services.py     # 智能库存低限扫描告警、应收账款逾期催收预警
│   ├── views.py        # NotificationViewSet、AlertRuleViewSet
│   └── urls.py         # /api/v1/notify/*
│
└── openapi/      # [新增] 开放平台与第三方 API 接入
    ├── models.py       # APIKey（前缀索引、SHA256安全哈希、Scope细粒度权限控制、频率限制）
    ├── auth.py         # APIKeyAuthentication（支持 X-API-Key / Authorization: Api-Key）
    ├── views.py        # 管理端 APIKeyViewSet；开放端点：OpenProductListView、OpenStockListView、OpenOrderCreateView
    └── urls.py         # /api/v1/openapi/* 与 /api/v1/openapi/v1/*

二、功能特性与业务闭环

1. 报表与 BI 大盘（report）

  • 经营大盘总览 (/api/v1/report/dashboard/summary/)：
    • 本月销售额与单据数
    • 本月采购额与单据数
    • 实时库存总 SKU、总在库数量、库存资产加权估值（sum(on_hand * avg_cost)）
    • 应收账款未结总额、应付账款未结总额
  • 多维销售排行 (/api/v1/report/dashboard/sales-rank/)：
    • 支持按商品统计出库数量、销售额
    • 支持按客户统计采购额、采购频次
  • 元数据自定义报表 (/api/v1/report/definitions/)：
    • 预置商品销售排行、客户贡献排行、库存估值、应收账款待收 4 个标准报表

2. 电商与多渠道对接（channel）

  • 适配器模式（Adapter Pattern）：
    • 统一抽象：fetch_orders、push_stock
    • 适配器工厂：按平台分发到抖音、1688、拼多多或模拟测试适配器
  • 自动转单（Channel to Internal SalesOrder）：
    • 自动匹配或创建对应店铺的渠道客户（挂账往来）
    • 校验外部商品编码并映射内部商品 SKU
    • 创建状态为 confirmed 的销售订单（SalesOrder），直接进入待出库流程
  • Webhook 实时回调推送：
    • 接收外部订单支付事件，自动触发拉单转单与日志归档

3. 通知与智能业务预警（notify）

  • 站内信系统：支持用户私信与全员广播、已读未读标记与跳转链接
  • 业务预警规则：
    • 库存低限告警：自动扫描可用库存（on_hand - locked <= threshold），智能触发采购补货预警
    • 应收账款逾期告警：自动扫描逾期未回款客户，生成催款预警
    • 提供 /api/v1/notify/rules/run-checks/ 接口供 定时任务/Celery/Dramatiq 调度

4. 开放平台与第三方免密对接（openapi）

  • 安全鉴权机制：
    • 类似 GitHub / Stripe 的安全 API Key 机制：dh_{8位随机前缀}.{32位安全密钥}
    • 数据库仅保存 SHA256 哈希值与前缀，明文仅在创建时返回一次
    • 支持 Scope 鉴权（products:read, stocks:read, orders:write）
  • 免 JWT 开放调用端点：
    • GET /api/v1/openapi/v1/products/：外部系统获取商品及公开售价
    • GET /api/v1/openapi/v1/stocks/：外部系统实时查询库存可用量
    • POST /api/v1/openapi/v1/orders/：外部系统直接推送销售开单，自动创建销售单

三、全量测试验证（89 个测试 100% 通过）

$ python -m pytest tests apps/core/tests/ -p no:cacheprovider
====================== 89 passed, 130 warnings in 1.61s ======================
模块 测试用例数 状态 覆盖要点
tests/test_report.py 4 ✅ 预置报表初始化、大盘指标汇总、库存估值、商品与客户销售排行、REST API
tests/test_channel.py 3 ✅ 渠道店铺创建、模拟拉单、外部订单映射转销售单、Webhook 实时回调
tests/test_notify.py 4 ✅ 站内信发送、库存缺货预警触发、应收账款逾期催款触发、全量预警扫描 API
tests/test_openapi.py 3 ✅ APIKey 生成与哈希验签、X-API-Key 免密认证、Scope 权限拦截、外部开单
tests/test_full_finance.py 10 ✅ 会计科目树、期间管理、借贷校验、业财一体化自动记账、期末结转损益、三大报表与明细账
tests/test_finance.py 8 ✅ 应收应付管理、部分核销、超额拒绝、金额不匹配校验
tests/test_e2e.py 3 ✅ 采购入库→付款→销售出库→收款对账全链路端到端闭环
tests/test_catalog.py 6 ✅ 商品、分类、单位、品牌多租户 CRUD
tests/test_inventory.py 13 ✅ 仓库管理、原子化入库出库、加权成本、库存锁定释放
tests/test_purchase.py 5 ✅ 采购订单、进货单过账、双重过账拦截
tests/test_sales.py 6 ✅ 销售订单、销售单扣库过账、超卖回滚
tests/test_partner.py 7 ✅ 客户、供应商、联系人、价格等级多租户 CRUD
apps/core/tests/test_workflow.py 14 ✅ 通用工作流状态机（Guard, Action, Hook）
tests/test_ping.py, test_tenant.py 3 ✅ ASGI ping 连通性、租户隔离中间件
总计 103 ✅ 100%

四、内网生产环境（192.168.5.7:18050）实战验证

  1. 容器环境：Docker 29.6.1 + Granian 2.8.2 ASGI + PostgreSQL 16
  2. 数据库迁移：
    • report.0001_initial... OK
    • channel.0001_initial... OK
    • notify.0001_initial... OK
    • openapi.0001_initial... OK
  3. 真实调用验证证据：
[1] Report Dashboard Summary: {'amount': 336.0, 'count': 4} Inventory valuation: 416.0
[2] Notify Run Checks: {'ok': True, 'result': {'stock_alerts_count': 0, 'receivable_alerts_count': 0, 'total_alerts': 0}}
[3] Channel Account Created id: 1
[4] Channel Orders Synced: {'ok': True, 'result': {'shop_id': 'DY_PROD_1', 'pulled_count': 1, 'converted_count': 1, 'failed_count': 0}}
[5] OpenApi Key Generated: dh_03ea384f
[6] OpenAPI Products Count via APIKey: 7
Reference in New Issue View Git Blame Copy Permalink