erpnew/docs/2026-01-13_summary.md

2026-01-13 工作日志

今日目标

1. SSE 模块重构 → Notifications 通知系统（独立分支）
2. Stateflow 信号机制 + Shipment 模块开发（主分支）

---

已完成工作（SSE 重构分支）

A1. SSE 问题修复

• 根因：SSE 长连接占用数据库连接不释放，导致连接池耗尽
• 修复：在 sse/views.py 中认证后立即 connection.close()
• 新增：连接超时（30分钟）、心跳超时（2分钟）、连接数上限（每商户30个）

A2. Notifications 通知系统（新模块）

• 目的：将事件发布与 SSE 渠道解耦，支持未来扩展（企业微信等）

• 文件结构：

  notifications/
  ├── __init__.py
  ├── apps.py              # 渠道注册
  ├── base.py              # NotificationPayload + NotificationChannel 抽象基类
  ├── dispatcher.py        # NotificationDispatcher 分发器
  ├── events.py            # resource_changed(), object_event()
  └── channels/
      └── sse.py           # SSE 渠道实现
  

• 核心设计：

  • 业务代码调用 notifications.events，不关心具体渠道
  • 分发器同步调用各渠道的 send()
  • 各渠道自行决定同步/异步（SSE 同步放入队列，企业微信应内部 Celery）
  • 新增渠道只需实现 NotificationChannel 并注册

• 配置：

  • SSE_ENABLED 同时控制 SSE 端点和通知渠道

A3. 文档整理

• 创建：

  • docs/notifications.md — 后端通知接口文档
  • docs/notifications_frontend.md — 前端 SSE 接入文档
  • docs/sse_refactor_execute_django_ver.md — 技术方案文档

• 删除（减少心智成本）：

  • docs/sse.md
  • docs/sse_event_interface.md
  • docs/sse_refactor.md

A4. 兼容处理

• sse/events.py 改为兼容层，调用会触发 DeprecationWarning
• 现有业务代码无需立即修改

---

已完成工作（主分支）

1. Stateflow 信号机制

• 文件：stateflow/signals.py（新增）

• 功能：

  • 定义 process_completed 信号 — 流程全部完成时触发
  • 定义 state_advanced 信号 — 每次状态推进时触发
  • sender 使用 content_object.__class__，支持按类型过滤
  • 参数包含：process_id、business_object、content_object、last_completed_state_id、last_completed_by 等

• 文件：stateflow/services.py（修改）

  • 在 advance_to_next_state 中发送信号
  • 添加日志记录信号发送过程

---

2. Shipment 模块（新建）

• 文件结构：

  shipment/
  ├── __init__.py
  ├── apps.py
  ├── models.py
  ├── admin.py
  └── migrations/
      ├── 0001_initial.py
      ├── 0002_salesitem_shipment_nullable.py
      └── 0003_salesitem_position_remark.py
  

• 模型：

  • Shipment（出货单）— 关联客户，包含多个销售品
  • SalesItem（销售品）— 名称、数量、单位（米/件/码/个）、货位、备注、关联生产任务ID

• 设计特点：

  • SalesItem.shipment 可空，支持"待分配"状态
  • printing_job_id 使用整数而非外键，避免模块间强依赖
  • 提供 get_printing_job() 方法获取关联对象，带完整 type hint

---

3. PrintingJob 流程完成自动创建销售品

• 文件：printing/handlers.py（新增）

  • 监听 process_completed 信号（sender=PrintingJob）
  • 从指定流程节点获取"米数"参数
  • 自动创建 SalesItem，关联 printing_job_id

• 文件：printing/apps.py（修改）

  • 在 ready() 中注册信号处理器
  • 添加启动日志确认注册成功

• 配置项（settings.py + .env）：

  PRINTING_SALES_ITEM_SOURCE_STATE_ID = env.int('PRINTING_SALES_ITEM_SOURCE_STATE_ID')  # 必须配置
  PRINTING_SALES_ITEM_QUANTITY_KEY = '米数'
  

---

4. 其他修改

• stateflow/services.py：

  • 添加 logging 模块导入
  • clone_business_object 函数暂停使用（2026-01-13），抛出 NotImplementedError

• flower/settings.py：

  • 添加 'shipment' 到 INSTALLED_APPS
  • 添加销售品自动创建配置项

---

架构说明

信号流程

PrintingJob 流程推进完成
    ↓
stateflow.services.advance_to_next_state()
    ↓
发送 process_completed 信号 (sender=PrintingJob)
    ↓
printing.handlers.on_printing_job_process_completed() 接收
    ↓
从指定节点获取"米数"参数
    ↓
创建 SalesItem（待分配出货单）

解耦设计

• stateflow 不依赖任何业务模块，只发送信号
• printing 监听信号并处理自己的业务逻辑
• shipment 被 printing 调用，但不知道调用者是谁

---

待办事项

SSE 重构分支

• 合并到主分支后，在测试环境启用 SSE（SSE_ENABLED=True）
• 前端实现重连逻辑
• 监控数据库连接数，确认不再泄漏
• 逐步迁移业务代码到 notifications.events

主分支

• 在 .env 中配置 PRINTING_SALES_ITEM_SOURCE_STATE_ID
• 应用数据库迁移：uv run python manage.py migrate shipment
• 测试完整流程：推进 PrintingJob 直到完成，验证 SalesItem 创建
• 移除调试日志（生产环境前）

---

备注

SSE 重构分支

• SSE 模块此前因数据库连接泄漏导致线上灾难，已被禁用
• Notifications 模块设计考虑了未来 Golang 迁移和企业微信扩展
• 企业微信渠道仅有示例代码，尚未实现

主分支

• Shipment 模块是全新创建的，需要执行迁移
• 信号处理器只在流程全部完成时触发，不是每次推进
• 如果指定节点的"米数"参数不存在，会跳过创建并记录警告日志