# dealerhub · 批次 B + C 实施报告（AI 差异化 + 商业化闭环）

> **依据**：《后续改造实施计划.md》批次 B（P1 AI 差异化 #7–9）与批次 C（P2 商业化基建 #10–13）。
> **结果**：两批次全部落地。全量回归 **268 passed**（批次 A 后 160 → 新增 108 例），
> `manage.py check` 0 issues，`makemigrations --check` 无待生成迁移，`npm run build` 通过，
> Playwright 真实浏览器逐项验证。**最小可售闭环达成**（P0 引擎 + 前端可见 + 套餐计费 + 官网 + 演示账套）。

---

## 批次 B · AI 差异化（新增 `apps/ai/`）

### B1 · AI 应收风险预警 ★ 主打差异化

**对外话术**：唯一做应收风控的进销存——竞品 AI 全在开单/问答，没人做应收风险。

**三因子加权评分（`apps/ai/risk.py`，纯统计，不依赖 LLM）**

| 因子 | 权重 | 算法 |
|---|---|---|
| 回款周期漂移 | 40% | 近 90 天平均回款天数 vs 历史基线（近一年、排除近期样本）；比值 ≤1 不计分，1.0→1.5 线性映射到 0→100 |
| 欠款趋势 | 35% | 本月未结 vs 上月同口径；增长 0→50% 线性映射；上月无欠款本月有 → 50 分（新增欠款） |
| 开单频次骤降 | 25% | 有欠款但 >30 天未开单；30 天 0 分，90 天 100 分，中间线性 |

**分档**：high ≥70 / medium 40–69 / low <40。**回款周期用收款核销（Allocation）的最晚核销日 − 应收开单日**近似，未结清的不参与该因子（走欠款趋势因子）。

**落点**：
- `notify` 新增 `risk_score` 规则类型（threshold = 分数线，默认 70），`check_risk_score_alerts` 按（客户+当日）去重发预警，挂入 `run_all_alert_checks`
- 默认预警规则新增 `ai_risk_score`（阈值 70）
- API：`GET /ai/risk/ranking/`（TOP N）、`/ai/risk/customer/<id>/`（三因子明细）、`/ai/risk/advice/<id>/`（催收建议）、`POST /ai/risk/scan/`
- 前端：大盘"应收风险 TOP5"卡片（风险进度条 + 档位 + 未结 + 回款周期/欠款趋势两列理由 + 催收建议弹窗）

**LLM 只做增值**：有 KEY 时把统计理由交给 LLM 生成一句人话建议；无 KEY 时 `advice` 直接返回统计理由，`llm_enhanced=false`（不 500、不空转）。

### B2 · AI 开单（`apps/ai/orders.py`）

链路：`粘贴文本 → LLM 抽取 [{name,barcode,qty,unit}] → 匹配商品档案 → 前端确认 → 回填开单表`

**匹配优先级**：`barcode 精确(100) → 商品编码精确(100) → 品名精确(100) → 品名包含(85，取最短匹配名) → 相似度兜底(difflib ≥0.6)`；未命中的进 `unmatched` 单独返回。

**单位与取价**：抽取到的单位名映射到 `UnitConversion`，命中则返回该单位的 `unit_id/unit_name/price`（价 = 基本价 × rate），前端复用 A1 的取价与最低售价逻辑。

**无 KEY 行为**（验收要求）：默认 **抛 `LlmUnavailable` → 400 + `code=llm_unavailable`**（明确报错，绝不 500）；同时提供 `allow_rule_fallback=true` 走**规则兜底**（正则抓"商品名+数量+单位"，支持中文数字"两箱/十瓶"）——前端在 400 后弹确认框，用户可选择用兜底模式。

**配额**（`apps/ai/usage.py`）：`AiUsage` 流水（租户+kind+账期），`check_quota` 超限抛 `QuotaExceeded` → **403 + `code=quota_exceeded` + 升级引导**。配额来源优先走 billing（见 C1），未装 billing 时回落 `settings.AI_FREE_MONTHLY_QUOTA`。

### B3 · AI 经营问答（`apps/ai/ask.py`）

**安全设计（计划硬要求：只读、不给 LLM 写权限）**：取数完全由**白名单工具**完成，LLM 只拿到聚合后的数字：
- 意图识别：`sales / receivable / inventory / purchase / profit / ranking / risk`，关键词命中；都没命中给"全景四项"
- 7 个工具全部只读 ORM 且强制 `tenant=tenant`（越权查他租户不可能，有专项测试）
- 无 LLM 时返回**统计口径结构化回答**（`llm_enhanced=false`），功能不空转
- 前端：大盘"🤖 老板参谋"入口 + 5 个预设问题 + 回答区（标注"AI 生成"或"统计口径"）

---

## 批次 C · 商业化基建

### C1 · 套餐/试用/配额（新增 `apps/billing/`）

**套餐定义（`Plan.limits` 是唯一事实来源）**

| | 免费版 | 基础版 | 专业版 |
|---|---|---|---|
| 价格 | ¥0 | **¥998/月** | **¥4800/月** |
| 用户 / 商品 / 月单据 | 1 / 100 / 50 | 5 / 3000 / 2000 | 50 / 100000 / 不限 |
| AI 录单 / 问答 | 10 / 20 | 200 / 500 | 2000 / 5000 |
| 批次效期 / 总账 | ✓ / ✓ | ✓ / ✓ | ✓ / ✓ |
| 订货商城 | ✗ | ✗ | ✓ |

> 定价依据（清单 #10）：卡在金蝶 698 与用友 1500 之间偏上，凭"带总账 + AI 风控"打差异。

**订阅（`Subscription`）**：`trial(30 天全功能) / active / expired`；`effective_limits()` 在试用过期或已过期时**回落 free 配额**（数据保留）。

**配额校验统一入口**：`billing.quota.check_and_count(tenant, kind, delta)`
- 数量型：`users` / `products` / `bills_monthly`
- 功能开关：`batch_managed` / `finance_ledger` / `storefront`
- AI 次数：委托 `apps.ai.usage.check_quota`（单一实现，billing 只提供配额数字）
- 超限 → `QuotaExceeded.as_dict()`：`{code, kind, detail, used, limit, plan_code, plan_name, upgrade_url}`

**真实拦截点（不是纸面）**：
1. `BaseTenantViewSet.acreate` 读 `quota_kind` 声明 → `ProductViewSet.quota_kind = "products"`
2. 销售/采购 `create-bill` 入口 → `bills_monthly`
3. AI 两个入口 → `ai_parse_order` / `ai_ask`
4. 前端 axios 拦截器 → 403 `quota_exceeded` 弹**升级引导弹窗**（列差距 + 跳套餐页，同 kind 60 秒内不重复弹）

**试用到期**：`billing.tasks.expire_trials()`（Dramatiq cron 每日）扫描试用与付费到期 → 降级 free + 发通知。

**API**：`GET /billing/plans/`（公开，官网价格页用）、`/billing/subscription/`（用量快照）、`POST /billing/subscribe/`、`GET /billing/quota/?kind=`。

**前端**：新页"套餐与用量"（当前套餐 + 试用倒计时 + 各配额进度条 + 功能开关 + 三档对比卡片一键切换）。

### C2 · 演示账套（`manage.py seed_demo`）

**食品经销商场景**，突出已交付能力：
- **5 个商品**：多单位（瓶/箱/件、箱/提）、批次管理（鲜奶 21 天/优倍 15 天保质期）、称重（kg 基本单位）、最低售价
- **5 个客户**：分层信用额度（3 万–8 万），含一个**风险户 C1005**
- **3 张进货单**：含两个批次（近效期 10 天 / 正常 14 天）用于演示临期预警
- **6 张销售单**：整件/散包混合录入 + 抹零（元/角两档）+ 批次商品 FEFO 跨批分摊 + 风险户大额赊销
- **5 笔历史应收**：覆盖账龄 **0-30 / 31-60 / 61-90 / 91-180 / 181-365** 五桶（账龄图不是一根柱）
- **幂等**：所有对象按 code/bill_no `update_or_create`；`--reset` 清空重建

**免注册体验**：
- `POST /api/v1/demo/enter/`（公开）→ 签发 2 小时 JWT + 返回只读提示；未初始化返回 503 + 明确指引
- **只读保护由中间件强制**（`DemoReadOnlyMiddleware`）：租户 `demo` 的一切非 GET 请求 → 403 `demo_read_only`，**不依赖前端自觉**（手工 curl 也拦得住，有专项测试）
- 前端登录页"🎬 免注册体验演示账套"按钮 + 侧栏"只读演示"徽标 + 403 明确提示

### C3 · 营销官网（新增 `apps/website/`，`/site/*`）

| 页面 | 内容 | SEO |
|---|---|---|
| `/site/` 首页 | H1"AI 开单 + 应收风控的经销商进销存"、三大 AI 卖点（含"独家"标注）、6 项基础能力、**6 角色价值区块**、价格预览、演示入口 | title/desc/OG/canonical/JSON-LD(SoftwareApplication) |
| `/site/pricing/` | 三档卡片 + **功能对比矩阵**（数据源 = `Plan.limits`，与配额校验同源）+ 三条说明 | 同上 |
| `/site/industry/food/` | 食品：批次账 + FEFO + 临期预警 + 多单位 + 信用额度（**均为已交付**） | 行业关键词 |
| `/site/industry/hardware/` | 五金：换算率 + 三档抹零 + 最低售价 + 价格历史参考 | 同上 |
| `/site/industry/autoparts/` | 汽配：当前可用能力 + **SN 追溯明确标注"规划中/尚未交付"** | 同上 |

**"不写纸面功能"的执行**：价格页每个勾选对应已交付代码；行业页每条卖点映射到一个已有测试；未交付的（订货商城在专业版、汽配 SN）标注规划中。测试 `test_autoparts_page_marks_unshipped_as_planned` 专门守这条。

**移动端**：全站响应式（860px 断点），viewport meta，单文件内联 CSS（无外部依赖，加载快）。

---

## 验证汇总

### 1. 后端回归
```
$ python -m pytest tests/ -p no:cacheprovider
268 passed in 5.06s        # 批次 A 后 160 → +108（B1 23 + B2/B3 25 + C1 25 + C2 14 + C3 21）
$ python manage.py check
System check identified no issues (0 silenced).
$ python manage.py makemigrations --check --dry-run
No changes detected
```

### 2. `npm run build`
```
✓ built in 5.84s
dist/assets/Dashboard-*.js     5.41 kB   ← AI 风险卡 + 老板参谋
dist/assets/SalesBills-*.js   15.95 kB   ← +AI 录单对话框
dist/assets/Billing-*.js       ~6 kB     ← 套餐与用量页
```

### 3. Playwright 真实浏览器（Granian ASGI）

| 场景 | 结果 |
|---|---|
| 大盘"应收风险 TOP5" | 王五批发 95 分/高风险/¥2,300，三因子理由分列（回款 45 天 vs 5 天、欠款 +53%、90 天未开单） |
| 催收建议弹窗 | 无 KEY → 显示统计口径理由，`llm_enhanced=false` |
| 老板参谋 | 预设"谁欠钱最多"→ 回答"本月销售额 ¥1,723.00（3 单）；应收未结 ¥4,023.00，其中 30 天以上 ¥1,500.00；库存估值 ¥1,180.06；本月净利润 ¥1,182.27"，标注"统计口径"、取数 4 项 |
| 免注册体验 | 登录页按钮 → 直进演示账套；侧栏显示"只读演示"徽标 |
| 演示只读保护 | 读接口 200（大盘/销售单/账龄/AI 风险），写接口 403 `demo_read_only` |
| 套餐与用量页 | 当前套餐"免费版/试用中"、试用期至 2026-10-10、商品 5/100 进度条、AI 录单 0/10、功能开关 ✓批次效期 ✓总账 ✗订货商城 |
| 官网首页 | H1 + 三大 AI 卖点（独家/省时/参谋）+ 6 能力卡 + 6 角色 + 价格预览 + CTA |
| 官网价格页 | 三档卡片 + 对比矩阵（1/5/50 用户、100/3,000/100,000 商品、专业版"不限"、订货商城 ✓/— 正确） |

### 4. 关键接口手测

```
POST /api/v1/demo/enter/              → 200 {tenant: demo, read_only: true, access: <JWT>}
POST /api/v1/catalog/products/ (demo) → 403 {code: demo_read_only}
GET  /api/v1/ai/risk/ranking/         → 95 分客户 + 三因子理由
POST /api/v1/ai/ask/                  → intents: [sales, receivable, inventory, profit]
POST /api/v1/ai/parse-order/ (无KEY)  → 400 {code: llm_unavailable}
GET  /api/v1/billing/plans/           → free/basic/pro（998 / 4800）
GET  /api/v1/billing/quota/?kind=products → 403 + upgrade_url（满额时）
GET  /site/pricing/                   → 200 14KB（对比矩阵与 Plan.limits 同源）
```

---

## 变更文件清单

```
backend/
├── apps/ai/                              [新] AI 应用
│   ├── risk.py          三因子应收风险评分（纯统计）
│   ├── orders.py        文本抽取 + 商品匹配 + 规则兜底
│   ├── ask.py           白名单只读工具 + 统计口径回答
│   ├── llm.py           OpenAI 兼容客户端（无 KEY 全降级）
│   ├── usage.py         AiUsage 流水 + 配额（异常类与 billing 统一）
│   ├── views.py·urls.py 7 个端点
│   └── models.py        （转发 usage.AiUsage，满足 Django 发现约定）
├── apps/billing/                         [新] 套餐与计费
│   ├── models.py        Plan / Subscription + 三档预置 + 试用/升级
│   ├── quota.py         check_and_count 统一入口 + 用量快照
│   ├── tasks.py         试用/订阅到期降级 + 通知
│   └── views.py·urls.py 4 个端点
├── apps/website/                         [新] 营销官网
│   ├── views.py         首页/价格页/3 行业页（价格读 Plan.limits）
│   └── templates/website/  base / home / pricing / industry（全响应式 + SEO）
├── apps/core/demo.py                     [新] 免注册进入演示账套
├── apps/core/middleware.py               [改] +DemoReadOnlyMiddleware
├── apps/core/viewset.py                  [改] acreate 配额拦截（quota_kind）
├── apps/core/management/commands/seed_demo.py  [新] 幂等演示账套
├── apps/catalog/views.py                 [改] ProductViewSet.quota_kind
├── apps/sales/views.py·purchase/views.py [改] 建单入口配额校验
├── apps/notify/models.py·services.py     [改] risk_score 规则 + 扫描 + 默认规则
├── config/settings/base.py               [改] +apps.ai/billing/website + AI 配置
├── config/urls.py                        [改] +/site/ 与 /demo/enter/
├── apps/*/migrations/                    [新] ai / billing
└── tests/test_ai_risk.py·test_ai_order_ask.py·test_billing.py·test_demo.py·test_website.py  [新] 108 例

frontend/src/
├── pages/Billing.vue        [新] 套餐与用量（用量进度 + 三档对比）
├── pages/Dashboard.vue      [改] +应收风险 TOP5 + 老板参谋对话框
├── pages/SalesBills.vue     [改] +AI 录单对话框（含兜底确认）
├── pages/Login.vue          [改] +免注册体验按钮
├── layouts/MainLayout.vue   [改] +只读演示徽标 + 套餐菜单
├── api/client.js            [改] +配额升级引导 + 只读演示 403 提示
└── router/index.js          [改] +/billing
frontend/dist/               [重建]
```

---

## 踩坑记录（供后续参考）

1. **异常类跨模块复用**：`billing.QuotaExceeded` 与 `ai.QuotaExceeded` 必须能被视图层一处 catch。做法是 ai 侧继承 billing 的类；但父类构造签名不同，`__init__` 里要直接调 `Exception.__init__`，否则 TypeError（本轮踩到）。
2. **服务层自生成单号 vs 幂等**：`create_sales_bill` / `create_purchase_bill` 自己生成单号，演示数据要固定单号只能创建后 `update(bill_no=...)` 回写。**若后续有更多幂等需求，建议给服务层加可选 `bill_no` 参数**。
3. **Django 模型发现约定**：模型必须定义在 `models.py`（或 `models/` 包）里才会被 `makemigrations` 发现；放在 `usage.py` 需要加一个 `models.py` 转发。另外 app 目录**必须有 `migrations/` 包**，否则 `makemigrations` 静默报 "No changes detected"。
4. **DRF `url_path` 唯一**：同一路径不能挂两个 action（后者覆盖前者，前者变 405）。同路径多方法要合并成一个 action 按 `request.method` 分派。
5. **DRF 保留参数 `format`**：`?format=` 会走内容协商，找不到对应 renderer 直接 404。自定义输出格式请换参数名（本轮用 `?view=html`）。
6. **adrf async 视图**：惰性 FK 访问与 `refresh_from_db()` 都必须包在 `sync_to_async` 里，否则 `SynchronousOnlyOperation`。
7. **Granian on Windows**：不支持多 worker（自动回落 1）；改动后重启务必 `netstat` 确认端口只有一个 PID，否则旧实例抢答会让"改了没生效"。
8. **演示数据要留额度余量**：`seed_demo` 的历史应收会占用客户信用额度，幂等重跑时可能被信用引擎拦住——演示客户额度要给足（本轮从 3 万提到 3–8 万）。

---

## 里程碑对照（计划 §五）

| 里程碑 | 计划内容 | 实际 |
|---|---|---|
| M-A | 批次 A 完成，前端接入全部 P0 能力 | ✅ `PROGRESS_BATCH_A.md`，160 passed |
| M-B | 批次 B 完成，三个 AI 卖点可演示（含无 KEY 降级） | ✅ 本报告，B1/B2/B3 全部可演示，降级路径有专项测试 |
| M-C | 批次 C 完成，**最小可售闭环达成** | ✅ 官网可访问、价格页公开、演示账套可进、free 版配额真实拦截 |
| M-D | 订货商城/移动开单随第一个付费客户上线 | ⏳ 未开始（批次 D，计划中即为"按客户驱动"） |

**最小可售闭环 = P0 引擎 + 批次 A 前端 + B1 风控 + 批次 C** → **已达成**。

---

## 下一步（批次 D，按客户驱动）

1. **D1 B2B 订货商城 H5**（`apps/storefront/`）：客户授权可见商品 + 等级价复用 `quote_price` + 自助下单生成草稿 + 接 C1 配额（`storefront` 开关已就位）
2. **D2 业务员移动开单**：H5 复用 D1 框架 + A1 取价/单位/抹零组件
3. **D3 行业专版**：序列号 SN（3C）/ 辅助属性（服装）/ 套装拆件（建材）
4. **D4 税率**：`SalesBillLine.tax_rate` + 价内价外口径 + 凭证科目拆分（**多币种建议从话术删除**，清单问题 7 要求）
5. **打印扩展**：三联送货单 / 58mm 小票 / 对账单二维码印在销售单上（串起 A3 分享链路）

> 注意：D 系列启动前建议先把**线上（192.168.5.7）镜像重建**，让批次 A/B/C 的成果先上线，再按客户反馈决定 D 的优先级。