171 lines
13 KiB
Markdown
171 lines
13 KiB
Markdown
# dealerhub 后续改造实施计划（P0 前端配套 + P1/P2/P3）
|
||
|
||
> **依据**：《差距分析与改造清单.md》全部 18 项 + 《P0改造实施计划.md》。
|
||
> **现状快照**（2026-09-10）：P0 后端六项（#1 批次效期 / #2 多单位 / #3 自动取价 / #4 最低售价+抹零 / #5 信用额度 / #6 账龄+对账单）已全部落地，专项 38 测试，全量回归 141 passed；P3 #17 打印模板引擎提前落地（+16 测试，共 157 passed）。**P0 引擎已建成但前端 12 页未接入**，竞品差距清单中剩余 P1 三项、P2 四项、P3 四项未启动。
|
||
> **本计划范围**：把清单剩余项排成四个批次（A→D），每项给出落点、具体内容、验收标准。实现顺序即优先顺序，批次内条目可并行。
|
||
|
||
---
|
||
|
||
## 〇、批次划分与执行顺序
|
||
|
||
```
|
||
批次A P0前端配套(收尾) ──→ 批次C 商业化基建(#10-13) ──→ 批次D 多端/行业(#14-16,#18)
|
||
↑ 最快见效(纯前端+少量API) ↑ 收钱的基建 ↑ 拿到客户后扩
|
||
批次B P1 AI差异化(#7-9) —————— 与A/C并行推进（AI开单演示是销售杠杆，越早越好）
|
||
```
|
||
|
||
| 批次 | 内容 | 预计量级 | 完成标志 |
|
||
|---|---|---|---|
|
||
| A | P0 六项的前端接入（开单取价/单位/抹零、信用进度条、账龄+对账单分享、批次页） | 3–5 天 | 前端可见可用，Playwright 冒烟通过 |
|
||
| B | AI 应收风险预警 / AI 开单 / AI 经营问答 | 1–2 周（可并行） | 官网可演示的三个 AI 卖点 |
|
||
| C | 套餐计费 → 演示账套 → 营销官网 → 公网上线 | 2 周 + 备案等待 | 最小可售闭环（对食品经销商开口子） |
|
||
| D | B2B 订货商城 H5 / 移动开单 / 序列号 / 税率 | 按客户驱动 | 行业专版能力 |
|
||
|
||
**最小可售闭环 = 批次A + B1（应收风控） + 批次C**：P0 引擎（后端已完成）+ 前端可见 + 套餐计费 + 官网演示账套，即具备对第一个食品经销商开口子的资格。
|
||
|
||
---
|
||
|
||
## 批次 A · P0 前端配套（引擎"可见可用"，预计 3–5 天）
|
||
|
||
> P0 后端 API 已就绪，本批次零新模型、零迁移，纯前端 + 个别 API 补口。全部接口现成：
|
||
|
||
| API | 用途 |
|
||
|---|---|
|
||
| `GET /api/v1/partner/price-quote/?customer_id=&product_ids=` | 批量取价（price/source/last/min/max） |
|
||
| `GET /api/v1/partner/credit-usage/<customer_id>/` | 信用额度占用 |
|
||
| `GET /api/v1/inventory/batches/` | 批次列表（product/warehouse/in_stock 过滤） |
|
||
| `POST/GET /api/v1/finance/statements/share/` | 对账单分享生成/吊销 |
|
||
| `GET /api/v1/open/statements/<token>/` | 公开对账单（客户侧） |
|
||
|
||
### A1 销售开单页改造（`SalesBills.vue`）★★★ 最高优先
|
||
- 选客户后商品行**自动取价预填**：调 price-quote，行内显示"上次售价/历史最低~最高"参考（智慧记同款体验）；单价可改，改后标黄提示偏离。
|
||
- 行支持**选择录入单位**：下拉列该商品 `UnitConversion`（需后端补一个 `GET /api/v1/catalog/products/<id>/units/` 轻接口，或报价 API 一并返回）；数量按录入单位填，提交带 `source_unit/source_quantity`，金额 = 录入单位价 × 录入数量。
|
||
- **抹零选项**：单据级下拉（不抹/抹分/抹角/抹元），提交带 `round_to`；实时预览"合计 → 抹零后应收"。
|
||
- **最低售价防呆**：成交价 < min_sale_price 时弹确认框，确认即行带 `allow_below_min=true`（前端"审批放行"话术）。
|
||
- **信用额度提示**：选客户后调 credit-usage 显示"已用/总额度"进度条；提交后若 402/CreditLimitExceeded，弹"超限，强制过账？"确认框走 `force=true`。
|
||
- 验收：不传价自动填充可见；2 箱×24 开单；抹零净额展示；超限弹窗流转。`npm run build` 通过。
|
||
|
||
### A2 客户档案页（`Receivables.vue` 或客户列表页）
|
||
- 客户行展开/详情显示**额度占用进度条**（<80% 绿 / 80–99% 橙 / ≥100% 红）+ 账龄六桶汇总（aging API 按 customer 过滤）。
|
||
- 验收：额度与账龄数字与后端测试口径一致。
|
||
|
||
### A3 财务页新增"账龄 + 对账单"（`FinanceReports.vue` 加标签页 或 `Receivables.vue` 扩展）
|
||
- **账龄标签**：全租户六桶柱状图 + 客户明细表（Element Plus 表格，支持 as_of 切换）。
|
||
- **对账单**：选客户 + 日期区间 → 预览期初/明细/期末 → "生成分享链接"按钮 → 复制 `GET /api/v1/open/statements/<token>/` 公开 URL（显示有效期，可吊销）。
|
||
- 验收：分享链接**无痕浏览器**可打开、过期/吊销后 404。
|
||
|
||
### A4 库存批次页（`Stocks.vue` 扩展或新 `Batches.vue`）
|
||
- 批次列表（仓库/商品/在库状态过滤）：批次号、生产/到期日期、结存、**距到期天数**着色（≤30 天橙、≤7 天红）。
|
||
- `Notify.vue`：确认 `batch_expiry` 规则可建可扫，通知类型有图标区分。
|
||
- 销售单打印模板追加"批次号"列（printing renderer 上下文补 batch_detail 分摊明细）。
|
||
- 验收：近效期批次一眼可见；打印样张含批次列。
|
||
|
||
### A5 采购开单页批次录入（`PurchaseBills.vue`）
|
||
- 行展开"批次信息"：批次号/生产日期/到期日（`is_batch_managed` 商品必填校验与后端一致；到期日留空按保质期自动推算提示）。
|
||
- 验收：带批次采购单过账后，批次页可见对应批次结存。
|
||
|
||
**批次A 总验收**：`npm run build` 通过；Playwright 冒烟（登录→开单取价→抹零→信用提示→打印）全绿；后端 pytest 不受影响。
|
||
|
||
---
|
||
|
||
## 批次 B · P1 AI 差异化（#7–9，与 A/C 并行，1–2 周）
|
||
|
||
> 对外话术：**唯一做应收风控 AI 的进销存**（竞品 AI 全在开单/问答，没人做应收风险——清单问题 4 结论）。
|
||
> 新增 `apps/ai/`；LLM 依赖做成可配置（`AI_PROVIDER=openai-compatible`，BASE_URL/KEY 走 .env），**无 KEY 时全部功能降级为纯统计版**，不阻塞测试与演示。
|
||
|
||
### B1 AI 应收风险预警（#7）★★★ 主打卖点
|
||
- `ai/risk.py` 风险评分（纯统计，不依赖 LLM）：
|
||
- 回款周期漂移：客户近 N 单实际回款天数 vs 历史均值；
|
||
- 欠款趋势：outstanding 环比连续上升标记；
|
||
- 开单频次骤降：连续 X 天无新单但欠款在账；
|
||
- 三因子加权 → 0–100 风险分 + 高/中/低档。
|
||
- 落点：`notify` 新增 `risk_score` 规则类型（threshold=分数线），`run_all_alert_checks` 挂入；首页大盘（`Dashboard.vue`）加"应收风险 TOP5"卡片。
|
||
- LLM 只做增值：有 KEY 时对 TOP 客户生成一句人话催收建议（"建议本周上门对账"级别），无 KEY 显示统计理由。
|
||
- 验收：`tests/test_ai_risk.py`——构造"回款变慢+欠款上升"客户得高分、预警去重、降级路径可用。
|
||
|
||
### B2 AI 开单（#8，演示级）
|
||
- `apps/ai/`：`POST /api/v1/ai/parse-order/`（粘贴/语音转写文本）→ LLM 抽取 `[{name, barcode?, qty}]` → 依次匹配 `barcode 精确 → name 模糊（trigram/包含）` → 返回命中+未命中清单 → 前端确认后生成 SalesOrder 草稿（复用 A1 取价）。
|
||
- **配额**：`ai/usage.py` 按租户计次（免费版 10 次/月），超限 403 引导升级——为批次C billing 预留 `billing.check_quota(tenant, 'ai_parse')` 接口。
|
||
- 前端：开单页"AI 录单"按钮 → 粘贴文本 → 确认抽选结果 → 回填表格。
|
||
- 验收：无 KEY 返回明确错误（不 500）；Mock LLM 测试抽取→匹配→草稿全链路；配额拦截。
|
||
|
||
### B3 AI 经营问答（#9）
|
||
- `POST /api/v1/ai/ask/`：预置白名单工具——把 dashboard 既有指标（销售额/应收/库存周转/欠款 TOP）按问题意图取数后交给 LLM 作答；只读、不给 LLM 写权限。
|
||
- 首页"老板参谋"入口；无 KEY 时按钮隐藏。
|
||
- 验收：Mock LLM 下问答取数正确；越权（查他租户）拒绝。
|
||
|
||
**批次B 总验收**：三个能力各配 `test_ai_*.py`；全量回归通过；官网素材（30 秒演示脚本）产出。
|
||
|
||
---
|
||
|
||
## 批次 C · P2 商业化基建（#10–13，预计 2 周 + 备案等待）
|
||
|
||
> 内部顺序：**C1 计费 → C2 演示账套 → C3 官网 → C4 上线**（官网价格页依赖套餐定义；演示账套是官网的转化入口）。
|
||
|
||
### C1 套餐/试用/配额系统（#10，新 `apps/billing/`）
|
||
- 模型：`Plan(code, name, price_monthly, limits JSON)` / `Subscription(tenant, plan, status[trial/active/expired], trial_ends_at, period_end)`；预置 plan：free（1 用户/100 SKU/30 天全功能）/ basic ¥998 / pro ¥4800（定价依据清单 #10：卡金蝶 698 与 1500 之间偏上，凭"带总账"打差异）。
|
||
- Enforcement：`billing.quota` 提供 `check_and_count(tenant, kind)`（用户数 / SKU 数 / 月单据量 / AI 次数 / 批次功能开关）；拦截点——注册用户、建商品、过账开单、AI 接口；超限 403 + 前端升级引导弹窗（列差距 + 跳价格页）。
|
||
- 试用到期： Dramatiq cron 每日扫 `trial_ends_at`，到期降级 free 并通知。
|
||
- 验收：`tests/test_billing.py`——超限拦截/试用降级/升级解除限制/租户隔离。
|
||
|
||
### C2 演示账套（#12）
|
||
- `core/management/commands/seed_demo`：固定演示租户（只读角色 + 预置商品/客户/单据/批次效期数据，突出食品行业场景）；重复执行幂等。
|
||
- 登录页加"免注册体验演示账套"按钮（一次性 token 登录）。
|
||
- 验收：一键重建；演示租户禁止写操作（写接口 403）。
|
||
|
||
### C3 营销官网（#11，新 `website/` 静态站或 Django templates）
|
||
- 页面清单（对照清单"内容模块改造对照表"）：
|
||
1. **首页**：H1 带 AI（"AI 开单 + 应收风控的经销商进销存"）；6 角色价值区块（老板/财务/销售/仓管/采购/运营，抄网上管家婆结构）；演示账套扫码入口。
|
||
2. **价格页**：free/¥998/¥4800 三列功能对比表（数据源 = C1 Plan.limits，一处定义两处使用）。
|
||
3. **行业 SEO 落地页 ×3**：食品（批次效期+FEFO+整件散包，A4 批次页截图）、五金（多单位换算+尾差）、汽配（预留 SN，指向 #16 路线）——**每页对应一个已实现特性，不写纸面功能**。
|
||
4. 打印样张/对账单分享链接作为"产品截图"素材。
|
||
- 验收：三页 SEO meta/结构化数据；Lighthouse 移动分 ≥80。
|
||
|
||
### C4 公网上线（#13）
|
||
- 域名购买 + 备案（等待期与 C1–C3 并行）→ HTTPS（Nginx/Caddy 反代 192.168.5.7:18050）→ OCR 客户端迁移。
|
||
- CI 冒烟：ping / 登录 / 开单三接口每日探活。
|
||
- 验收：公网域名 HTTPS 200；备案号挂页脚。
|
||
|
||
---
|
||
|
||
## 批次 D · P3 多端与行业扩展（拿到付费客户后，按 #14→#15→#16→#18）
|
||
|
||
### D1 B2B 订货商城 H5（#14，新 `apps/storefront/`）
|
||
- `CustomerProductAuth(tenant, customer, product)` 授权可见 + `CustomerProductPrice` 等级价复用 quote_price；客户 H5 登录（token，不占用户席）→ 只见授权商品 → 自助下单生成 **SalesOrder 草稿**（内部确认转单，不直接过账）→ 接 C1 配额。
|
||
- 移动端页（Vue3 复用，移动布局）优先，微信小程序（uni-app）后置。
|
||
- 验收：未授权商品不可见、下单草稿流转、额度超限拦截。
|
||
|
||
### D2 业务员移动开单（#15）
|
||
- H5 复用 D1 框架 + A1 取价/单位/抹零组件：外勤开单、查欠款、收款登记；签到后置。
|
||
- 验收：手机浏览器全流程走通。
|
||
|
||
### D3 行业专版开关（#16，按拿下客户顺序做）
|
||
- **序列号 SN**（3C）：`inventory.Serial(tenant, product, serial_no, status)`，入库登记/出库绑定、SN 追溯查询；开关字段 `Product.is_serial_managed`。
|
||
- 辅助属性（服装色码）/套装拆子件（建材）：同模式后置，每项对应一个行业落地页更新。
|
||
- 验收：SN 唯一性、出入库追溯、关闭开关回归零影响。
|
||
|
||
### D4 多币种/税率兑现（#18）★★ 先解决"纸面功能"风险
|
||
- **建议只做税率**（国内刚需、发票强相关）：`SalesBillLine/PurchaseBillLine.tax_rate`，价内/价外口径与凭证拆分（应交税费科目），抹零在税后。
|
||
- 多币种从对外话术中删除（无跨境客户前不做）——兑现或删除，二者必居其一（清单问题 7 要求）。
|
||
- 验收：税率行凭证科目正确、报表含税口径一致；官网话术同步清理。
|
||
|
||
### 打印扩展（#17 收尾，顺带做）
|
||
- 三联送货单/58mm 小票模板、`{{#if}}` 条件块、**对账单分享二维码印上销售单**（客户扫码对账，串起 A3）。
|
||
|
||
---
|
||
|
||
## 五、里程碑与验收
|
||
|
||
| 里程碑 | 内容 | 判定 |
|
||
|---|---|---|
|
||
| M-A（+1 周） | 批次A 完成 | 前端接入全部 P0 能力，Playwright 冒烟绿，157+ 测试不回归 |
|
||
| M-B（+3 周） | 批次B 完成（与 C 并行） | 三个 AI 卖点可演示（含无 KEY 降级路径），30 秒演示视频脚本产出 |
|
||
| M-C（+5 周） | 批次C 完成 | **最小可售闭环达成**：官网可访问、价格页公开、演示账套可进、free 版配额真实拦截 |
|
||
| M-D | 按客户驱动 | 订货商城/移动开单随第一个付费客户上线 |
|
||
|
||
**全局验收标准**（沿用 P0 惯例）：
|
||
- 每项专项测试 `tests/test_<batch>_<item>.py`，全量 `pytest` 通过且不破坏既有 157 例；
|
||
- `manage.py check` 0 issues；`npm run build` 通过；
|
||
- 每批次完成产出 `PROGRESS_<批次>.md` 报告（含变更文件清单与踩坑记录）；
|
||
- **不写纸面功能**：官网/话术只提已实现特性（清单问题 7 教训），未做的从话术删除。
|