forked from erp-dev/erp
feat: shipment_delivery
This commit is contained in:
161
docs/2026-04-02-rds-pgbouncer-server-side-cursor-issue.md
Normal file
161
docs/2026-04-02-rds-pgbouncer-server-side-cursor-issue.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# 2026-04-02 RDS PgBouncer 命名游标问题记录
|
||||
|
||||
## 背景
|
||||
|
||||
生产环境在 Django Admin 页面访问 `SalesItem` 编辑页时出现如下错误：
|
||||
|
||||
```text
|
||||
ProgrammingError at /admin/shipment/salesitem/1/change/
|
||||
cursor "_django_curs_128437320623808_sync_1" already exists
|
||||
```
|
||||
|
||||
本地开发/测试环境未复现该问题。
|
||||
|
||||
## 现象
|
||||
|
||||
- 出错页面：`/admin/shipment/salesitem/<id>/change/`
|
||||
- 错误类型：PostgreSQL `ProgrammingError`
|
||||
- 关键错误信息：`cursor "... already exists"`
|
||||
- 特征：属于数据库连接/游标状态错误，而不是表结构错误
|
||||
|
||||
## 排查结论
|
||||
|
||||
### 1. 不是 migrate 未执行导致
|
||||
|
||||
本次错误不符合迁移缺失的典型表现。
|
||||
|
||||
如果是 migration 未执行，通常会看到：
|
||||
|
||||
- 某字段不存在
|
||||
- 某表不存在
|
||||
- 约束不存在
|
||||
- 类型不匹配
|
||||
|
||||
而本次是“命名游标已经存在”，属于运行时数据库连接状态问题。
|
||||
|
||||
### 2. 当前 `SalesItem` Admin 实现本身没有明显异常
|
||||
|
||||
`shipment` 模块中的 admin 配置较为简单，没有明显会主动触发复杂命名游标行为的自定义逻辑：
|
||||
|
||||
- 参考：[shipment/admin.py](/home/f/coding/flower/shipment/admin.py)
|
||||
|
||||
因此本问题更像是生产环境数据库接入方式引发，而不是该页面逻辑本身写坏。
|
||||
|
||||
### 3. 根因判断：阿里云 RDS 自带 PgBouncer/连接池 与 Django server-side cursors 兼容性问题
|
||||
|
||||
生产环境已确认使用“阿里云 RDS 自带代理/连接池”。
|
||||
|
||||
Django 在 PostgreSQL 下会在部分场景使用 server-side cursors（尤其与 `QuerySet.iterator()` 相关）。
|
||||
当应用经过连接池/代理访问数据库时，连接池不能稳定保证命名游标依赖的“同一物理连接上下文”，从而可能触发：
|
||||
|
||||
- 命名游标残留
|
||||
- 游标状态错乱
|
||||
- `cursor "... already exists"`
|
||||
|
||||
这类问题在连接池场景下比直连 PostgreSQL 更容易出现。
|
||||
|
||||
## 代码与配置侧观察
|
||||
|
||||
### 数据库配置
|
||||
|
||||
项目数据库配置位于：
|
||||
|
||||
- [flower/settings.py](/home/f/coding/flower/flower/settings.py)
|
||||
|
||||
原有配置特征：
|
||||
|
||||
- 使用 PostgreSQL
|
||||
- 支持 `CONN_MAX_AGE`
|
||||
- 未显式设置 `DISABLE_SERVER_SIDE_CURSORS`
|
||||
|
||||
### 项目内的连接池配置
|
||||
|
||||
仓库自带的 PgBouncer 配置位于：
|
||||
|
||||
- [deploy/pgbouncer/pgbouncer.ini](/home/f/coding/flower/deploy/pgbouncer/pgbouncer.ini)
|
||||
|
||||
仓库内自建 PgBouncer 使用的是 `session` 模式。
|
||||
但生产环境此次问题来自阿里云 RDS 自带代理/连接池，实际行为应以云侧代理为准，不能简单等同于本仓库自带 PgBouncer 配置。
|
||||
|
||||
## 修复决策
|
||||
|
||||
考虑到：
|
||||
|
||||
- 生产环境不能放弃连接池
|
||||
- 该系统存在较多大查询
|
||||
- 生产已经出现与命名游标相关的实际错误
|
||||
|
||||
最终决定采用 Django 官方支持的兼容方案：
|
||||
|
||||
在数据库配置中加入：
|
||||
|
||||
```python
|
||||
'DISABLE_SERVER_SIDE_CURSORS': True,
|
||||
```
|
||||
|
||||
并保留：
|
||||
|
||||
```python
|
||||
'CONN_MAX_AGE': env.int('CONN_MAX_AGE', default=0),
|
||||
```
|
||||
|
||||
## 修复位置
|
||||
|
||||
已在以下位置加入配置：
|
||||
|
||||
- [flower/settings.py](/home/f/coding/flower/flower/settings.py)
|
||||
|
||||
配置位置为 `DATABASES['default']` 顶层，与 `ENGINE`、`HOST`、`PORT`、`CONN_MAX_AGE` 同级，不放在 `OPTIONS` 中。
|
||||
|
||||
## 采用该修复的原因
|
||||
|
||||
### 为什么不优先怀疑 migration
|
||||
|
||||
因为错误类型明显属于连接/游标状态，不属于 schema 不一致。
|
||||
|
||||
### 为什么不取消连接池
|
||||
|
||||
生产环境仍需要连接池承载系统中的大查询与整体数据库连接管理。
|
||||
|
||||
### 为什么选择禁用 server-side cursors
|
||||
|
||||
这是 Django 官方针对连接池/代理场景给出的标准兼容方向之一。
|
||||
|
||||
对当前项目而言，这一决策的风险低于继续保留命名游标并承受生产不稳定性。
|
||||
|
||||
## 可能的副作用
|
||||
|
||||
启用 `DISABLE_SERVER_SIDE_CURSORS=True` 后：
|
||||
|
||||
- 普通页面和常规 ORM 查询通常不会受功能性影响
|
||||
- 依赖 `QuerySet.iterator()` 的超大结果集遍历，可能失去 server-side cursor 带来的部分性能/内存优势
|
||||
|
||||
项目中需要后续重点观察的批量遍历代码包括：
|
||||
|
||||
- [printing/tasks.py](/home/f/coding/flower/printing/tasks.py)
|
||||
- [api_v1/external_product_image_backfill.py](/home/f/coding/flower/api_v1/external_product_image_backfill.py)
|
||||
|
||||
也就是说，该修复更可能带来“部分后台任务性能特征变化”，而不是“开发环境或生产环境无法正确运行”。
|
||||
|
||||
## 对开发环境的影响判断
|
||||
|
||||
开发环境同样可以启用 `DISABLE_SERVER_SIDE_CURSORS=True`，不会导致系统无法运行。
|
||||
|
||||
主要影响仍然是：
|
||||
|
||||
- 大结果集遍历时的性能和内存行为可能更保守
|
||||
|
||||
但这不属于严重副作用。
|
||||
|
||||
## 结论
|
||||
|
||||
本次问题定性为：
|
||||
|
||||
- **生产环境数据库连接池代理与 Django server-side cursors 的兼容性问题**
|
||||
|
||||
本次修复决策为：
|
||||
|
||||
- **保留连接池**
|
||||
- **在 Django 数据库配置中启用 `DISABLE_SERVER_SIDE_CURSORS=True`**
|
||||
|
||||
该决策用于降低生产环境中命名游标相关错误的出现概率，并保持系统整体连接池架构不变。
|
||||
@@ -70,6 +70,12 @@
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `sales_items` 现在返回的是带图片字段的销售品详情结构
|
||||
- 若销售品关联的 `PrintingJob.product` 存在主图，则会返回 `product_image_url`
|
||||
- 若无关联图片，则 `product_image_url` 为 `null`
|
||||
|
||||
### 出货单详情
|
||||
|
||||
- **URL**: `/api/v1/shipment/shipments/<id>/`
|
||||
@@ -82,6 +88,10 @@
|
||||
|------|------|------|
|
||||
| status | int | 可选状态过滤；取值为 1=草稿(未发布), 2=已发布, 3=已取消, 4=已驳回, 5=已审核。传入后仅当该出货单状态匹配时才返回详情 |
|
||||
|
||||
说明：
|
||||
|
||||
- 详情中的 `sales_items` 同样返回带 `product_image_url` 的销售品详情结构
|
||||
|
||||
---
|
||||
|
||||
### 更新出货单
|
||||
@@ -92,7 +102,7 @@
|
||||
|
||||
说明：
|
||||
|
||||
- 仅允许修改业务数据字段：`customer`、`shipment_date`、`area`、`remark`、`external_id`
|
||||
- 仅允许修改业务数据字段：`customer`、`shipment_date`、`address`、`contact_name`、`contact_phone`、`area`、`remark`、`external_id`
|
||||
- 该接口不允许修改 `status`
|
||||
- 仅 `草稿(未发布)` 状态的出货单允许修改
|
||||
- 非草稿状态会返回 `400 Bad Request`
|
||||
@@ -101,6 +111,9 @@
|
||||
|
||||
```json
|
||||
{
|
||||
"address": "宁波市滨海路 9 号",
|
||||
"contact_name": "王五",
|
||||
"contact_phone": "13700137000",
|
||||
"area": "更新地区",
|
||||
"remark": "更新备注"
|
||||
}
|
||||
@@ -139,6 +152,9 @@
|
||||
|------|------|------|------|
|
||||
| customer | int | 是 | 客户ID |
|
||||
| shipment_date | string | 是 | 出货日期（YYYY-MM-DD） |
|
||||
| address | string | 否 | 地址（可空字符串，长度<=255） |
|
||||
| contact_name | string | 否 | 联系人（可空字符串，长度<=100） |
|
||||
| contact_phone | string | 否 | 联系电话（可空字符串，长度<=50） |
|
||||
| area | string | 否 | 出货地区（可空字符串，长度<=30） |
|
||||
| remark | string | 否 | 备注 |
|
||||
| sales_items | array[int] | 否 | 要关联的销售品ID列表 |
|
||||
@@ -149,6 +165,9 @@
|
||||
{
|
||||
"customer": 1,
|
||||
"shipment_date": "2026-01-14",
|
||||
"address": "杭州市测试路 1 号",
|
||||
"contact_name": "张三",
|
||||
"contact_phone": "13800138000",
|
||||
"area": "华东",
|
||||
"remark": "备注信息",
|
||||
"sales_items": [1, 2, 3]
|
||||
@@ -165,6 +184,9 @@
|
||||
"customer": 1,
|
||||
"customer_name": "客户A",
|
||||
"shipment_date": "2026-01-14",
|
||||
"address": "杭州市测试路 1 号",
|
||||
"contact_name": "张三",
|
||||
"contact_phone": "13800138000",
|
||||
"area": "华东",
|
||||
"remark": "备注信息",
|
||||
"status": 1,
|
||||
@@ -194,6 +216,9 @@
|
||||
| customer | int | 客户ID |
|
||||
| customer_name | string | 客户名称 |
|
||||
| shipment_date | string | 出货日期 |
|
||||
| address | string | 地址 |
|
||||
| contact_name | string | 联系人 |
|
||||
| contact_phone | string | 联系电话 |
|
||||
| area | string | 出货地区 |
|
||||
| remark | string | 备注 |
|
||||
| status | int | 状态枚举（1=草稿(未发布), 2=已发布, 3=已取消, 4=已驳回, 5=已审核） |
|
||||
@@ -287,6 +312,9 @@
|
||||
|------|------|------|------|
|
||||
| customer | int | 是 | 客户ID |
|
||||
| shipment_date | string | 是 | 出货日期（YYYY-MM-DD） |
|
||||
| address | string | 否 | 地址（可空字符串，长度<=255） |
|
||||
| contact_name | string | 否 | 联系人（可空字符串，长度<=100） |
|
||||
| contact_phone | string | 否 | 联系电话（可空字符串，长度<=50） |
|
||||
| area | string | 否 | 出货地区（可空字符串，长度<=30） |
|
||||
| remark | string | 否 | 备注 |
|
||||
| external_id | string | 是 | 外部订单号（长度<=120） |
|
||||
@@ -306,6 +334,9 @@
|
||||
{
|
||||
"customer": 1,
|
||||
"shipment_date": "2026-01-14",
|
||||
"address": "绍兴市仓库 2 号",
|
||||
"contact_name": "李四",
|
||||
"contact_phone": "13900139000",
|
||||
"area": "华南",
|
||||
"remark": "external 备注（可选）",
|
||||
"external_id": "EXT-ORDER-001",
|
||||
@@ -326,6 +357,9 @@
|
||||
"customer": 1,
|
||||
"customer_name": "客户A",
|
||||
"shipment_date": "2026-01-14",
|
||||
"address": "绍兴市仓库 2 号",
|
||||
"contact_name": "李四",
|
||||
"contact_phone": "13900139000",
|
||||
"area": "华南",
|
||||
"remark": "external 备注（可选）",
|
||||
"status": 1,
|
||||
|
||||
319
docs/shipment_delivery.md
Normal file
319
docs/shipment_delivery.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# Shipment Delivery API
|
||||
|
||||
本文档说明 `shipment` 模块中的“送货单”模型及相关 API。
|
||||
|
||||
## 业务说明
|
||||
|
||||
送货单用于表示一次具体的送货行为。
|
||||
|
||||
特点：
|
||||
|
||||
- 一个送货单可关联多个出货单
|
||||
- 一个出货单最多属于一个送货单
|
||||
- 送货单与出货单关系为一对多
|
||||
- 送货单使用独立状态流转，不复用出货单状态
|
||||
|
||||
## 状态枚举
|
||||
|
||||
送货单状态定义如下：
|
||||
|
||||
- `1 = 待送货`
|
||||
- `2 = 送货中`
|
||||
- `3 = 已送达`
|
||||
- `4 = 已取消`
|
||||
|
||||
状态机规则：
|
||||
|
||||
- `待送货 -> 送货中`
|
||||
- `送货中 -> 已送达`
|
||||
- 不允许回退
|
||||
- 重复设置同一状态时保持幂等，直接返回当前对象
|
||||
- `已取消` 为终态
|
||||
|
||||
时间字段规则：
|
||||
|
||||
- 进入 `送货中` 时写入 `started_at`
|
||||
- 进入 `已送达` 时写入 `delivered_at`
|
||||
|
||||
## 模型字段
|
||||
|
||||
送货单模型包含以下核心字段：
|
||||
|
||||
- `id`
|
||||
- `merchant`
|
||||
- `driver_name`
|
||||
- `vehicle_trip`
|
||||
- `contact_phone`
|
||||
- `vehicle_capacity`
|
||||
- `remark`
|
||||
- `internal_remark`
|
||||
- `status`
|
||||
- `started_at`
|
||||
- `delivered_at`
|
||||
- `created_by`
|
||||
- `operator`
|
||||
- `cancelled_at`
|
||||
- `cancelled_by`
|
||||
- `created_at`
|
||||
- `updated_at`
|
||||
|
||||
说明：
|
||||
|
||||
- `driver_name` 已加索引
|
||||
- `vehicle_trip` 已加索引
|
||||
- `status` 已加索引
|
||||
- `created_by` 为系统用户 `User`
|
||||
- `operator` 为业务员工 `Employee`
|
||||
- `merchant` 用于多商户隔离
|
||||
- 创建、修改、状态流转时，会根据 `request.user.employee` 自动写入 `operator`
|
||||
- 取消送货单时会写入 `cancelled_at` 与 `cancelled_by`
|
||||
|
||||
## API 列表
|
||||
|
||||
### 1. 查询送货单列表
|
||||
|
||||
- `GET /api/v1/shipment/deliveries/`
|
||||
|
||||
支持查询参数：
|
||||
|
||||
- `status`
|
||||
- `driver_name`
|
||||
- `vehicle_trip`
|
||||
- `limit`
|
||||
- `offset`
|
||||
|
||||
查询说明：
|
||||
|
||||
- `status` 为精确匹配
|
||||
- `driver_name` 为包含匹配
|
||||
- `vehicle_trip` 为包含匹配
|
||||
|
||||
示例：
|
||||
|
||||
```http
|
||||
GET /api/v1/shipment/deliveries/?status=2&driver_name=张&vehicle_trip=001&limit=20&offset=0
|
||||
```
|
||||
|
||||
返回示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"count": 1,
|
||||
"next": null,
|
||||
"previous": null,
|
||||
"results": [
|
||||
{
|
||||
"id": 1,
|
||||
"merchant_id": 1,
|
||||
"merchant_name": "测试印花厂",
|
||||
"driver_name": "张司机",
|
||||
"vehicle_trip": "KD-001",
|
||||
"contact_phone": "13800138000",
|
||||
"vehicle_capacity": "9.6米厢车",
|
||||
"remark": "先装车",
|
||||
"internal_remark": "注意对账",
|
||||
"status": 1,
|
||||
"status_display": "待送货",
|
||||
"started_at": null,
|
||||
"delivered_at": null,
|
||||
"cancelled_at": null,
|
||||
"shipments_count": 2,
|
||||
"shipments": [
|
||||
{
|
||||
"id": 10,
|
||||
"customer": 5,
|
||||
"customer_name": "客户A",
|
||||
"shipment_date": "2026-04-03",
|
||||
"status": 2,
|
||||
"status_display": "已发布",
|
||||
"external_id": null
|
||||
}
|
||||
],
|
||||
"created_by_id": 8,
|
||||
"created_by_name": "测试员工",
|
||||
"operator_id": 3,
|
||||
"operator_name": "测试员工",
|
||||
"cancelled_by_id": null,
|
||||
"cancelled_by_name": null,
|
||||
"created_at": "2026-04-03T10:00:00+08:00",
|
||||
"updated_at": "2026-04-03T10:00:00+08:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 创建送货单
|
||||
|
||||
- `POST /api/v1/shipment/deliveries/`
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"driver_name": "张司机",
|
||||
"vehicle_trip": "KD-001",
|
||||
"contact_phone": "13800138000",
|
||||
"vehicle_capacity": "9.6米厢车",
|
||||
"remark": "先装车",
|
||||
"internal_remark": "注意对账",
|
||||
"shipments": [10, 11]
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
- `driver_name`: 必填，司机名
|
||||
- `vehicle_trip`: 必填，车次
|
||||
- `contact_phone`: 可选，联系电话
|
||||
- `vehicle_capacity`: 可选，车辆容量
|
||||
- `remark`: 可选，备注
|
||||
- `internal_remark`: 可选，内部备注
|
||||
- `shipments`: 可选，出货单 ID 列表
|
||||
|
||||
创建规则：
|
||||
|
||||
- 只能绑定当前用户所属商户的出货单
|
||||
- 只能绑定状态为 `已审核` 的出货单
|
||||
- 已绑定到其他送货单的出货单不能重复绑定
|
||||
- 创建接口不支持直接传入 `status`
|
||||
|
||||
### 3. 查询送货单详情
|
||||
|
||||
- `GET /api/v1/shipment/deliveries/{id}/`
|
||||
|
||||
返回字段与列表单项一致，但会返回完整 `shipments` 摘要数组。
|
||||
|
||||
### 4. 修改送货单
|
||||
|
||||
- `PATCH /api/v1/shipment/deliveries/{id}/`
|
||||
- `PUT /api/v1/shipment/deliveries/{id}/`
|
||||
|
||||
请求体示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"driver_name": "李司机",
|
||||
"vehicle_trip": "KD-001-B",
|
||||
"contact_phone": "13700137000",
|
||||
"vehicle_capacity": "13米高栏",
|
||||
"remark": "改派车辆",
|
||||
"internal_remark": "已电话确认",
|
||||
"shipments": [11, 12]
|
||||
}
|
||||
```
|
||||
|
||||
修改规则：
|
||||
|
||||
- `driver_name`、`vehicle_trip`、`contact_phone`、`vehicle_capacity`、`remark`、`internal_remark` 可单独修改
|
||||
- `shipments` 如果传入，则视为“整体替换当前绑定的出货单集合”
|
||||
- 替换绑定时，出货单仍然必须满足“当前商户、已审核、未绑定到其他送货单”
|
||||
- 更新接口不支持直接修改 `status`
|
||||
|
||||
### 5. 删除送货单
|
||||
|
||||
- `DELETE /api/v1/shipment/deliveries/{id}/`
|
||||
|
||||
行为说明：
|
||||
|
||||
- 删除送货单时，会先解除与其关联的出货单绑定
|
||||
- 删除成功返回 `204 No Content`
|
||||
|
||||
### 6. 修改送货单状态
|
||||
|
||||
- `POST /api/v1/shipment/deliveries/{id}/status/`
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"status": 2
|
||||
}
|
||||
```
|
||||
|
||||
状态取值：
|
||||
|
||||
- `1 = 待送货`
|
||||
- `2 = 送货中`
|
||||
- `3 = 已送达`
|
||||
|
||||
规则说明：
|
||||
|
||||
- 只允许按状态机顺序流转
|
||||
- 不允许回退
|
||||
- 相同状态重复提交保持幂等
|
||||
- 成功改到 `送货中` 时写入 `started_at`
|
||||
- 成功改到 `已送达` 时写入 `delivered_at`
|
||||
- 该接口不用于取消送货单
|
||||
|
||||
### 7. 取消送货单
|
||||
|
||||
- `POST /api/v1/shipment/deliveries/{id}/cancel/`
|
||||
|
||||
权限要求：
|
||||
|
||||
- 需要 Django 权限：`shipment.cancel_shipmentdelivery`
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
行为说明：
|
||||
|
||||
- 将送货单状态改为 `已取消`
|
||||
- 写入 `cancelled_at`
|
||||
- 写入 `cancelled_by`
|
||||
- 同时会根据 `request.user.employee` 更新 `operator`
|
||||
- 已取消的送货单再次取消保持幂等
|
||||
|
||||
### 8. 追加绑定出货单到已有送货单
|
||||
|
||||
- `POST /api/v1/shipment/deliveries/{id}/bind-shipments/`
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"shipments": [12, 13]
|
||||
}
|
||||
```
|
||||
|
||||
规则说明：
|
||||
|
||||
- 该接口是“追加绑定”，不会替换当前已有绑定
|
||||
- 只允许绑定当前用户所属商户的出货单
|
||||
- 出货单必须处于 `已审核` 状态
|
||||
- 已绑定到其他送货单的出货单不能再次绑定
|
||||
- 成功后会根据 `request.user.employee` 更新 `operator`
|
||||
|
||||
## Service 设计
|
||||
|
||||
送货单的业务写入逻辑统一放在 `shipment/services.py` 中：
|
||||
|
||||
- `create_shipment_delivery(...)`
|
||||
- `update_shipment_delivery(...)`
|
||||
- `modify_shipment_delivery_status(...)`
|
||||
- `cancel_shipment_delivery(...)`
|
||||
- `delete_shipment_delivery(...)`
|
||||
|
||||
说明：
|
||||
|
||||
- list / detail 属于简单只读查询，直接由 API 查询集处理
|
||||
- create / update / delete / status modify 均通过 service 完成
|
||||
|
||||
## 测试覆盖
|
||||
|
||||
已补充以下测试方向：
|
||||
|
||||
- 创建送货单并绑定多个出货单
|
||||
- 绑定已属于其他送货单的出货单时报错
|
||||
- 绑定非当前商户出货单时报错
|
||||
- 列表支持 `status / driver_name / vehicle_trip` 查询
|
||||
- 详情返回关联出货单摘要
|
||||
- 更新送货单并替换绑定出货单
|
||||
- 创建、修改、状态流转会写入 `operator`
|
||||
- 取消送货单需要权限校验，并写入 `cancelled_at / cancelled_by`
|
||||
- 状态流转写入 `started_at / delivered_at`
|
||||
- 非法状态流转报错
|
||||
- 删除送货单后解除出货单绑定
|
||||
Reference in New Issue
Block a user