139 lines
8.1 KiB
Markdown
139 lines
8.1 KiB
Markdown
# 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% 通过）
|
||
|
||
```bash
|
||
$ 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. **真实调用验证证据**：
|
||
```text
|
||
[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
|
||
```
|