# 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
```