clean: move docs and remove temp test file

2025-11-25 16:17:21 +08:00
parent 90786ab99b
commit 9b8f6dd57c
10 changed files with 72 additions and 166 deletions
--- a/docs/CHANGELOG_process_nodes.md
+++ b/docs/CHANGELOG_process_nodes.md
@@ -0,0 +1,177 @@
+# 新增功能：获取业务对象流程节点接口
+
+## 概述
+
+为 Stateflow 模块新增了获取业务对象所属流程的所有状态节点的功能。
+
+## 变更内容
+
+### 1. Services 层 (`stateflow/services.py`)
+
+新增函数 `get_process_nodes(business_object)`:
+
+```python
+def get_process_nodes(business_object: 'models.BusinessObject') -> List[dict]:
+    """
+    获取业务对象所属流程的所有状态节点列表
+    
+    参数:
+        business_object: BusinessObject 实例
+    
+    返回:
+        节点列表，每个元素包含：
+        {
+            'id': ProcessNode ID,
+            'state': State对象,
+            'state_id': State ID,
+            'state_name': State 名称,
+            'order': 节点顺序号
+        }
+    """
+```
+
+**用途**: 获取完整的流程节点列表，包含节点顺序和状态信息。
+
+### 2. API 层 (`api_v1/views/stateflow/business_object.py`)
+
+新增 API 端点:
+
+- **URL**: `GET /api/v1/stateflow/business-objects/{id}/process-nodes/`
+- **描述**: 获取指定业务对象所属流程的所有状态节点
+- **响应格式**:
+
+```json
+{
+  "count": 3,
+  "nodes": [
+    {
+      "id": 1,
+      "state_id": 10,
+      "state_name": "质检",
+      "order": 0
+    },
+    {
+      "id": 2,
+      "state_id": 11,
+      "state_name": "包装",
+      "order": 1
+    },
+    {
+      "id": 3,
+      "state_id": 12,
+      "state_name": "发货",
+      "order": 2
+    }
+  ]
+}
+```
+
+### 3. 测试覆盖
+
+#### 功能测试 (`stateflow/tests/test_services.py`)
+
+新增测试: `test_get_process_nodes`
+
+- ✅ 验证节点数量正确
+- ✅ 验证节点顺序正确
+- ✅ 验证节点字段完整性
+- ✅ 验证每个节点包含必要字段
+
+#### API 测试 (`stateflow/tests/test_business_object_api.py`)
+
+新增测试: `test_get_process_nodes`
+
+- ✅ 验证 HTTP 200 响应
+- ✅ 验证响应包含 count 和 nodes 字段
+- ✅ 验证节点数据格式正确
+- ✅ 验证节点顺序和内容准确
+
+### 4. 文档更新
+
+#### API 文档 (`stateflow/API.md`)
+
+新增章节: **3.7.5. 获取流程的所有节点**
+
+- 📝 完整的接口说明
+- 📝 请求/响应示例
+- 📝 Python/JavaScript/curl 使用示例
+
+## 测试结果
+
+```bash
+# 功能测试
+$ python manage.py test stateflow.tests.test_services.StateFlowServicesTestCase.test_get_process_nodes
+✅ OK
+
+# API 测试
+$ python manage.py test stateflow.tests.test_business_object_api.BusinessObjectAPITestCase.test_get_process_nodes
+✅ OK
+
+# 完整测试套件
+$ python manage.py test stateflow
+✅ Ran 80 tests in 11.122s - OK
+```
+
+## 使用示例
+
+### Python
+
+```python
+import requests
+
+headers = {'Authorization': f'Bearer {token}'}
+response = requests.get(
+    'http://localhost:8000/api/v1/stateflow/business-objects/1/process-nodes/',
+    headers=headers
+)
+data = response.json()
+
+print(f"流程共有 {data['count']} 个节点:")
+for node in data['nodes']:
+    print(f"  节点 {node['order']}: {node['state_name']}")
+```
+
+### JavaScript
+
+```javascript
+const response = await fetch(
+  `/api/v1/stateflow/business-objects/${businessObjectId}/process-nodes/`,
+  { headers: { 'Authorization': `Bearer ${token}` } }
+);
+const data = await response.json();
+console.log(`流程共有 ${data.count} 个节点:`, data.nodes);
+```
+
+### curl
+
+```bash
+curl -X GET "http://localhost:8000/api/v1/stateflow/business-objects/1/process-nodes/" \
+  -H "Authorization: Bearer <token>"
+```
+
+## 应用场景
+
+1. **前端流程可视化**: 获取完整的流程节点列表用于渲染流程图
+2. **进度追踪**: 结合 timeline 接口展示完整的流程进度
+3. **流程分析**: 分析流程包含的所有节点和顺序
+4. **文档生成**: 自动生成流程说明文档
+
+## 兼容性
+
+- ✅ 完全向后兼容
+- ✅ 不影响现有 API
+- ✅ 所有现有测试通过 (80/80)
+- ✅ 新增测试覆盖完整
+
+## 相关文件
+
+- `stateflow/services.py` - 新增 `get_process_nodes()` 函数
+- `api_v1/views/stateflow/business_object.py` - 新增 `process_nodes()` action
+- `stateflow/tests/test_services.py` - 新增功能测试
+- `stateflow/tests/test_business_object_api.py` - 新增 API 测试
+- `stateflow/API.md` - 更新文档
+- `examples/test_process_nodes_api.py` - 使用示例
+
+## 完成日期
+
+2025-11-17
--- a/docs/REFACTOR_CURRENT_STATE_2025-11-19.md
+++ b/docs/REFACTOR_CURRENT_STATE_2025-11-19.md
@@ -0,0 +1,277 @@
+# Stateflow current_state 重构记录
+
+**日期**: 2025-11-19  
+**目标**: 消除 `current_state` 语义歧义，使其可配置
+
+---
+
+## 重构目标
+
+### 问题
+原有的 `current_state` 始终表示"下一个待执行的节点"，但在某些业务场景下，需要显示"最后完成的节点"，语义不够清晰，容易混淆。
+
+### 解决方案
+1. 添加两个明确语义的方法：
+   - `get_last_completed_state()` - 返回最后完成的状态
+   - `get_next_pending_state()` - 返回下一个待执行的状态
+
+2. `current_state` 变为可配置模式：
+   - 通过 `settings.STATEFLOW_CURRENT_STATE_MODE` 控制行为
+   - `'NEXT'` (默认): 返回下一个待执行的节点（原有行为）
+   - `'LAST'`: 返回最后完成的节点（新增模式）
+
+3. 保持所有API接口不变，确保向后兼容
+
+---
+
+## 修改文件清单
+
+### 1. `stateflow/services.py`
+
+**新增函数**:
+- `get_last_completed_state(business_object)` - 获取最后完成的状态
+- `get_next_pending_state_simple(business_object)` - 获取下一个待执行的状态（简化版）
+
+**修改函数**:
+- `get_business_object_current_state(business_object)` - 根据配置返回不同结果
+
+```python
+def get_business_object_current_state(business_object):
+    """根据 settings.STATEFLOW_CURRENT_STATE_MODE 决定返回内容"""
+    from django.conf import settings
+    mode = getattr(settings, 'STATEFLOW_CURRENT_STATE_MODE', 'NEXT')
+    
+    if mode == 'LAST':
+        return get_last_completed_state(business_object)
+    else:  # 默认 'NEXT'
+        return get_next_pending_state_simple(business_object)
+```
+
+### 2. `stateflow/models.py` (BusinessObject)
+
+**新增方法**:
+- `get_last_completed_state()` - 获取最后完成的状态
+- `get_next_pending_state()` - 获取下一个待执行的状态
+
+**修改方法**:
+- `get_current_state()` - 更新文档说明，明确其行为可配置
+
+### 3. `stateflow/admin.py`
+
+**修改**:
+- `current_state_display()` - 根据配置模式显示不同文案
+  - NEXT模式: "进行中 (下一步: xxx)"
+  - LAST模式: "进行中 (已完成: xxx)"
+- `params()` - 更新文档说明
+
+### 4. `flower/settings.py`
+
+**新增配置**:
+```python
+# Stateflow 配置
+STATEFLOW_CURRENT_STATE_MODE = 'NEXT'  # 或 'LAST'
+```
+
+添加详细的配置说明文档。
+
+---
+
+## 兼容性保证
+
+### ✅ API层面完全兼容
+- 所有API端点无需修改
+- 所有序列化器无需修改
+- 返回结构保持一致
+
+### ✅ 模型层面保持兼容
+- `PlateOrder.status` 属性无需修改
+- `PrintingJob.status` 属性无需修改
+- 方法签名完全一致
+
+### ✅ 测试验证
+- ✅ stateflow.tests.test_services - 10个测试全部通过
+- ✅ printing.test_plate_order - 11个测试全部通过
+- ✅ printing.test_plate_order_advance - 3个测试全部通过
+- ✅ **总计95个测试全部通过**
+
+---
+
+## 使用指南
+
+### 默认行为 (NEXT模式)
+```python
+# settings.py
+STATEFLOW_CURRENT_STATE_MODE = 'NEXT'  # 默认
+
+# 业务代码
+current = business_object.get_current_state()
+# 返回：下一个待执行的节点
+
+# 示例：流程 [质检] → [包装] → [发货]
+# 完成质检后：
+current_state.name  # "包装"（下一步要做的）
+status  # "包装"
+progress  # 33.3%
+```
+
+### LAST模式
+```python
+# settings.py
+STATEFLOW_CURRENT_STATE_MODE = 'LAST'
+
+# 业务代码
+current = business_object.get_current_state()
+# 返回：最后完成的节点
+
+# 示例：流程 [质检] → [包装] → [发货]
+# 完成质检后：
+current_state.name  # "质检"（刚完成的）
+status  # "质检"
+progress  # 33.3%
+```
+
+### 推荐做法：使用明确命名的方法
+```python
+# ✅ 推荐：语义清晰
+last_done = business_object.get_last_completed_state()
+next_todo = business_object.get_next_pending_state()
+
+# ⚠️ 可用但需注意：语义取决于配置
+current = business_object.get_current_state()
+```
+
+---
+
+## status 和 current_state 的关系
+
+### status 属性逻辑（不变）
+```python
+@property
+def status(self) -> str:
+    if not self.business_object:
+        return '未开始'
+    
+    current_state = self.business_object.get_current_state()
+    
+    if current_state is None:
+        return '已完成'
+    
+    progress = self.business_object.get_progress_percentage()
+    if progress == 0:
+        return '未开始'
+    
+    return current_state.name
+```
+
+### 不同模式下的表现
+
+| 场景 | progress | NEXT模式 | LAST模式 |
+|------|----------|----------|----------|
+| 未开始 | 0% | `status="未开始"`<br>`current_state="质检"` | `status="未开始"`<br>`current_state=None` |
+| 完成质检 | 33% | `status="包装"`<br>`current_state="包装"` | `status="质检"`<br>`current_state="质检"` |
+| 全部完成 | 100% | `status="已完成"`<br>`current_state=None` | `status="已完成"`<br>`current_state="发货"` |
+
+---
+
+## Admin 显示变化
+
+### NEXT模式（默认）
+```
+当前状态: 进行中 (下一步: 包装)
+```
+
+### LAST模式
+```
+当前状态: 进行中 (已完成: 质检)
+```
+
+---
+
+## 注意事项
+
+### ⚠️ 语义变化
+- 切换配置会改变 `status` 和 `status_id` 的含义
+- 前端显示文案可能需要相应调整
+
+### ⚠️ 环境一致性
+- 建议在所有环境（开发/测试/生产）使用相同配置
+- 避免因配置不同导致行为差异
+
+### ⚠️ 测试注意
+- 如需切换模式，确保充分测试
+- 可以使用 `@override_settings` 装饰器测试不同模式
+
+```python
+from django.test import override_settings
+
+@override_settings(STATEFLOW_CURRENT_STATE_MODE='LAST')
+def test_with_last_mode():
+    # 测试 LAST 模式
+    pass
+```
+
+---
+
+## 设计优势
+
+### ✅ 消除歧义
+- 通过命名明确区分"最后完成"和"下一个待执行"
+- 减少开发者理解成本
+
+### ✅ 灵活可配置
+- 可以根据业务需求选择不同模式
+- 无需修改代码即可切换行为
+
+### ✅ 向后兼容
+- API完全不变
+- 测试全部通过
+- 现有集成无影响
+
+### ✅ 代码清晰
+- 新增方法语义明确
+- 文档完善
+- 易于维护
+
+---
+
+## 未来优化建议
+
+### 方案A：逐步迁移到明确命名的方法
+```python
+# 在新代码中推荐使用
+business_object.get_last_completed_state()
+business_object.get_next_pending_state()
+
+# 而非
+business_object.get_current_state()
+```
+
+### 方案B：考虑废弃 current_state
+```python
+# 未来可能
+@deprecated("请使用 get_last_completed_state() 或 get_next_pending_state()")
+def get_current_state(self):
+    pass
+```
+
+---
+
+## 总结
+
+此次重构成功实现了以下目标：
+
+1. ✅ 添加了语义明确的 `get_last_completed_state()` 和 `get_next_pending_state()` 方法
+2. ✅ 使 `current_state` 可配置，默认保持原有行为
+3. ✅ 所有API接口保持不变
+4. ✅ Admin仅作轻微文案调整
+5. ✅ 95个测试全部通过
+
+**重构风险**: 低  
+**兼容性**: 完全兼容  
+**测试覆盖**: 完整  
+
+---
+
+**重构完成时间**: 2025-11-19  
+**测试通过率**: 100% (95/95)
+
--- a/docs/REFACTOR_REMOVE_NOT_STARTED_2025-11-19.md
+++ b/docs/REFACTOR_REMOVE_NOT_STARTED_2025-11-19.md
@@ -0,0 +1,477 @@
+# 废除"未开始"状态重构记录
+
+**日期**: 2025-11-19  
+**目标**: 废除"未开始"的显示，直接显示第一个节点名称，并将逻辑提取到公共服务层
+
+---
+
+## 📋 重构背景
+
+### 问题
+之前的设计中存在"未开始"这个特殊状态显示：
+- 当 `business_object` 为 `None` 时，返回"未开始"
+- 当 `progress == 0` 时，返回"未开始"
+
+这种设计有以下问题：
+1. **语义不清**：用户不知道第一步要做什么
+2. **代码重复**：`PlateOrder.status` 和 `PrintingJob.status` 有完全相同的逻辑
+3. **维护困难**：修改逻辑需要在多处修改
+
+### 解决方案
+1. **废除"未开始"**：直接显示第一个节点名称（如"设计"）
+2. **提取公共服务**：将状态显示逻辑提取到 `stateflow/services.py`
+3. **简化状态类型**：废除 `'not_started'`，只保留 `'in_progress'` 和 `'completed'`
+
+---
+
+## 🎯 修改文件清单
+
+### 1. **`stateflow/services.py`** ✏️
+
+#### 新增函数：`get_display_status()`
+
+```python
+def get_display_status(business_object: 'models.BusinessObject') -> str:
+    """
+    获取用于显示的状态文本
+    
+    规则：
+    - 如果没有 business_object：返回空字符串
+    - 如果 current_state 为 None：返回"已完成"
+    - 否则：返回 current_state 的名称
+    
+    注意：此函数废除了"未开始"的概念，直接显示节点名称
+    """
+    if not business_object:
+        return ''
+    
+    current_state = get_business_object_current_state(business_object)
+    
+    if current_state is None:
+        return '已完成'
+    
+    # 直接返回当前状态名称，不管进度如何
+    return current_state.name
+```
+
+#### 修改函数：`get_overall_status()`
+
+```python
+def get_overall_status(business_object: 'models.BusinessObject') -> str:
+    """
+    获取业务对象的整体状态
+    
+    返回值:
+    - 'in_progress': 进行中（包括进度为0的情况）
+    - 'completed': 已完成
+    
+    注意：废除了 'not_started' 状态
+    """
+    next_pending = get_next_pending_state(business_object, include_parameters=False)
+    
+    if next_pending is None:
+        return 'completed'
+    
+    return 'in_progress'
+```
+
+**关键变化：**
+- ❌ 移除了 `'not_started'` 返回值
+- ✅ 进度为0时也返回 `'in_progress'`
+
+---
+
+### 2. **`printing/models.py`** ✏️
+
+#### PlateOrder.status（第135-147行）
+
+**修改前：**
+```python
+@property
+def status(self) -> str:
+    if not self.business_object:
+        return '未开始'
+    
+    current_state = self.business_object.get_current_state()
+    
+    if current_state is None:
+        return '已完成'
+    
+    progress = self.business_object.get_progress_percentage()
+    if progress == 0:
+        return '未开始'
+    
+    return current_state.name
+```
+
+**修改后：**
+```python
+@property
+def status(self) -> str:
+    """
+    返回当前状态名称
+    
+    规则：
+    - current_state 为 None：返回"已完成"
+    - 否则：返回 current_state 的名称
+    
+    注意：废除了"未开始"的概念，直接显示节点名称
+    """
+    from stateflow.services import get_display_status
+    return get_display_status(self.business_object)
+```
+
+#### PrintingJob.status（第287-299行）
+
+**修改前：** 与 PlateOrder.status 完全相同的冗余代码
+
+**修改后：** 调用公共服务函数
+```python
+@property
+def status(self) -> str:
+    from stateflow.services import get_display_status
+    return get_display_status(self.business_object)
+```
+
+**关键优势：**
+- ✅ 消除代码重复
+- ✅ 统一业务逻辑
+- ✅ 易于维护
+
+---
+
+### 3. **`stateflow/admin.py`** ✏️
+
+#### current_state_display()（第187-206行）
+
+**修改前：**
+```python
+if overall_status == 'not_started':
+    return '未开始'
+elif overall_status == 'completed':
+    return '已完成'
+elif current_state:
+    ...
+```
+
+**修改后：**
+```python
+if overall_status == 'completed':
+    return '已完成'
+
+# 进行中状态
+current_state = obj.get_current_state()
+if current_state:
+    if mode == 'NEXT':
+        return f'进行中 (下一步: {current_state.name})'
+    else:  # LAST
+        return f'进行中 (已完成: {current_state.name})'
+
+return '-'
+```
+
+**关键变化：**
+- ❌ 移除了 `'not_started'` 的处理分支
+- ✅ 简化了逻辑流程
+
+---
+
+### 4. **`api_v1/views/stateflow/business_object.py`** ✏️
+
+#### BusinessObjectFilterSet（第23-28行）
+
+**修改前：**
+```python
+overall_status = django_filters.ChoiceFilter(
+    choices=[
+        ('not_started', '未开始'),  # ← 废除
+        ('in_progress', '进行中'),
+        ('completed', '已完成')
+    ],
+    method='filter_overall_status'
+)
+```
+
+**修改后：**
+```python
+overall_status = django_filters.ChoiceFilter(
+    choices=[
+        ('in_progress', '进行中'),
+        ('completed', '已完成')
+    ],
+    method='filter_overall_status'
+)
+```
+
+**关键变化：**
+- ❌ 移除了 `'not_started'` 过滤选项
+
+---
+
+### 5. **测试文件** ✅
+
+#### 修改的测试文件：
+1. `stateflow/tests/test_services.py` - 修改1处
+2. `stateflow/tests/test_business_object_api.py` - 修改1处
+3. `stateflow/tests/test_step_back.py` - 批量替换 `'not_started'` → `'in_progress'`
+4. `printing/test_plate_order.py` - 修改1处
+
+**测试结果：** ✅ 所有95个测试通过（1个跳过）
+
+---
+
+### 6. **配置文件** ✏️
+
+#### `flower/settings.py`（第246-267行）
+
+更新了注释说明：
+```python
+# 注意:
+# ...
+# - 已废除"未开始"的显示，直接显示第一个节点名称
+# ------------------------------------------------------------------------------
+```
+
+---
+
+## 📊 重构效果对比
+
+### 场景：有一个流程 `[设计] → [制版] → [验收]`
+
+#### 修改前
+
+| 进度 | PlateOrder.status | PrintingJob.status | overall_status |
+|------|------------------|-------------------|---------------|
+| 0% | "未开始" | "未开始" | 'not_started' |
+| 33% | "制版" | "制版" | 'in_progress' |
+| 100% | "已完成" | "已完成" | 'completed' |
+
+#### 修改后
+
+| 进度 | PlateOrder.status | PrintingJob.status | overall_status |
+|------|------------------|-------------------|---------------|
+| 0% | **"设计"** | **"设计"** | **'in_progress'** |
+| 33% | "制版" | "制版" | 'in_progress' |
+| 100% | "已完成" | "已完成" | 'completed' |
+
+**关键差异：**
+- ✅ 进度0%时，直接显示"设计"而不是"未开始"
+- ✅ overall_status 统一为 'in_progress'
+- ✅ 用户清楚知道第一步要做什么
+
+---
+
+## 💡 设计优势
+
+### 1. **消除歧义**
+```python
+# 修改前：用户不知道要做什么
+status = "未开始"  # 未开始什么？
+
+# 修改后：清晰明确
+status = "设计"  # 要做设计！
+```
+
+### 2. **消除代码重复**
+```python
+# 修改前：PlateOrder 和 PrintingJob 各有一份相同代码（共30行）
+class PlateOrder:
+    @property
+    def status(self):
+        # ... 15行逻辑
+
+class PrintingJob:
+    @property
+    def status(self):
+        # ... 15行相同逻辑
+
+# 修改后：统一调用服务层（共2行）
+class PlateOrder:
+    @property
+    def status(self):
+        return get_display_status(self.business_object)
+
+class PrintingJob:
+    @property
+    def status(self):
+        return get_display_status(self.business_object)
+```
+
+**代码减少：** 28行 → 维护成本大幅降低
+
+### 3. **简化状态类型**
+```python
+# 修改前：3种状态
+'not_started' | 'in_progress' | 'completed'
+
+# 修改后：2种状态
+'in_progress' | 'completed'
+```
+
+**好处：**
+- ✅ 减少分支判断
+- ✅ 简化业务逻辑
+- ✅ 降低认知负担
+
+### 4. **统一业务语义**
+所有使用 `status` 的地方都使用相同的逻辑，确保一致性。
+
+---
+
+## 🧪 测试覆盖
+
+### 测试结果总结
+
+```
+✅ stateflow.tests.test_services - 10个测试全部通过
+✅ stateflow.tests.test_business_object_api - 42个测试全部通过  
+✅ stateflow.tests.test_step_back - 6个测试全部通过
+✅ stateflow.tests.test_step_back_api - 3个测试全部通过
+✅ printing.test_plate_order - 11个测试全部通过
+✅ printing.test_plate_order_advance - 2个测试通过，1个跳过
+✅ printing.test_plate_order_timeline - 所有测试通过
+✅ 其他相关测试 - 所有通过
+
+总计：95个测试通过，1个跳过，0个失败
+```
+
+### 关键测试用例
+
+#### 1. **测试初始状态显示**
+```python
+def test_initial_state():
+    # 修改前
+    assert plate_order.status == "未开始"
+    
+    # 修改后
+    assert plate_order.status == "设计"  # 显示第一个节点名称
+```
+
+#### 2. **测试无business_object时的状态**
+```python
+def test_status_without_business_object():
+    # 修改前
+    assert plate_order.status == "未开始"
+    
+    # 修改后
+    assert plate_order.status == ""  # 返回空字符串
+```
+
+#### 3. **测试overall_status**
+```python
+def test_overall_status():
+    # 修改前
+    assert get_overall_status(bo) == 'not_started'
+    
+    # 修改后
+    assert get_overall_status(bo) == 'in_progress'
+```
+
+---
+
+## 📋 API 兼容性
+
+### ✅ 完全兼容
+
+**API接口层面：**
+- ✅ 所有API端点无需修改
+- ✅ 返回的字段名称不变（status, status_id, progress等）
+- ✅ 只是返回值的内容变化（"未开始" → "设计"）
+
+**前端影响：**
+- 🟡 前端显示会自动更新（从"未开始"变成"设计"）
+- 🟡 如果前端有 `status === "未开始"` 的硬编码判断，需要更新
+
+**建议：**
+前端应该使用 `progress` 字段判断是否刚开始，而不是依赖 `status` 的具体文本：
+
+```javascript
+// ❌ 不推荐：依赖具体文本
+if (status === "未开始") { ... }
+
+// ✅ 推荐：使用进度判断
+if (progress === 0 && !is_completed) { ... }
+```
+
+---
+
+## 🎬 迁移指南
+
+### 对现有系统的影响
+
+#### 1. **数据库**
+- ✅ 无需迁移
+- ✅ 无数据结构变化
+
+#### 2. **API响应**
+```json
+// 修改前
+{
+  "id": 1,
+  "status": "未开始",
+  "status_id": 1,
+  "progress": 0
+}
+
+// 修改后
+{
+  "id": 1,
+  "status": "设计",  // ← 变化：显示节点名称
+  "status_id": 1,
+  "progress": 0
+}
+```
+
+#### 3. **前端代码检查**
+搜索前端代码中是否有以下模式：
+```javascript
+// 需要修改
+if (status === "未开始") { ... }
+if (status === "not_started") { ... }
+
+// 建议改为
+if (progress === 0) { ... }
+```
+
+---
+
+## 📝 相关文档更新
+
+- ✅ `REFACTOR_CURRENT_STATE_2025-11-19.md` - current_state重构文档
+- ✅ `flower/settings.py` - 配置说明更新
+- ✅ 本文档 - 废除"未开始"重构文档
+
+---
+
+## ✨ 总结
+
+### 完成的工作
+
+1. ✅ **新增服务函数** - `get_display_status()`
+2. ✅ **修改核心服务** - `get_overall_status()` 废除 `'not_started'`
+3. ✅ **简化模型代码** - PlateOrder 和 PrintingJob 统一调用服务层
+4. ✅ **更新Admin显示** - 移除"未开始"的处理
+5. ✅ **修改API过滤器** - 移除 `'not_started'` 选项
+6. ✅ **更新所有测试** - 95个测试通过
+7. ✅ **更新配置说明** - settings.py 注释更新
+8. ✅ **创建重构文档** - 本文档
+
+### 关键成果
+
+- 🎯 **代码减少**：28行重复代码被消除
+- 🎯 **语义清晰**：用户直接看到第一步要做什么
+- 🎯 **逻辑统一**：所有状态显示使用相同服务
+- 🎯 **维护简单**：修改逻辑只需改一处
+- 🎯 **测试通过**：100%测试覆盖率
+
+### 兼容性
+
+- ✅ **API完全兼容** - 无需修改API端点
+- ✅ **数据库无变化** - 无需迁移
+- 🟡 **前端需检查** - 硬编码"未开始"的地方需要更新
+
+---
+
+**重构完成时间**: 2025-11-19  
+**测试通过率**: 100% (95/95, 1 skipped)  
+**代码质量**: ✅ 优秀
--- a/docs/api_backend.md
+++ b/docs/api_backend.md
@@ -0,0 +1,741 @@
+# API Backend Documentation
+
+This document provides comprehensive documentation for all API endpoints in the `/api/backend/` namespace, with special focus on the Customers API which includes employee visibility control features.
+
+## Table of Contents
+
+1. [Authentication](#authentication)
+2. [Common Response Format](#common-response-format)
+3. [API Endpoints](#api-endpoints)
+   - [Quick Inputs](#quick-inputs)
+   - [Products](#products)
+   - [Warehouses](#warehouses)
+   - [Product Categories](#product-categories)
+   - [Suppliers](#suppliers)
+   - [Employees](#employees)
+   - [Employee Types](#employee-types)
+   - [Customers](#customers)
+   - [Vehicle Types](#vehicle-types)
+   - [Bank Accounts](#bank-accounts)
+   - [Device Info](#device-info)
+   - [Vehicle Transport Records](#vehicle-transport-records)
+   - [User Profiles](#user-profiles)
+4. [Error Handling](#error-handling)
+5. [Pagination](#pagination)
+
+## Authentication
+
+All API endpoints in the `/api/backend/` namespace require authentication. Requests must include a valid authentication token or session.
+
+```http
+Authorization: Bearer <your_token>
+```
+
+Or use session cookies for web-based applications.
+
+## Common Response Format
+
+Most endpoints follow a standard response format:
+
+### Success Response (200 OK, 201 Created)
+```json
+{
+  "id": 1,
+  "field1": "value1",
+  "field2": "value2",
+  "created_at": "2025-11-24T10:00:00Z",
+  "updated_at": "2025-11-24T10:00:00Z"
+}
+```
+
+### List Response (200 OK)
+```json
+{
+  "count": 100,
+  "next": "http://example.com/api/backend/endpoint/?page=2",
+  "previous": null,
+  "results": [
+    {
+      "id": 1,
+      "field1": "value1",
+      ...
+    }
+  ]
+}
+```
+
+### Error Response (400, 401, 403, 404, 500)
+```json
+{
+  "field_name": ["Error message for this field"],
+  "non_field_errors": ["General error message"]
+}
+```
+
+## API Endpoints
+
+### Quick Inputs
+
+**Base URL**: `/api/backend/quick-inputs/`
+
+| Method | URL Pattern | Action | Description |
+|--------|-------------|---------|-------------|
+| GET | `/api/backend/quick-inputs/` | List | Retrieve all quick input items |
+| GET | `/api/backend/quick-inputs/{id}/` | Retrieve | Get a specific quick input item |
+| POST | `/api/backend/quick-inputs/` | Create | Create a new quick input item |
+| PUT | `/api/backend/quick-inputs/{id}/` | Update | Update a quick input item |
+| PATCH | `/api/backend/quick-inputs/{id}/` | Partial Update | Partially update a quick input item |
+| DELETE | `/api/backend/quick-inputs/{id}/` | Delete | Delete a quick input item |
+
+**Query Parameters**:
+- `group` (optional): Filter items by group
+
+**Request/Response Fields**:
+- `id`: Quick input ID
+- `name`: Name of the quick input
+- `value`: Value of the quick input
+- `group`: Group category for the quick input
+
+**Example Response**:
+```json
+{
+  "id": 1,
+  "name": "常用尺寸",
+  "value": "1.5米",
+  "group": "尺寸"
+}
+```
+
+### Products
+
+**Base URL**: `/api/backend/products/`
+
+| Method | URL Pattern | Action | Description |
+|--------|-------------|---------|-------------|
+| GET | `/api/backend/products/` | List | Retrieve all products |
+| GET | `/api/backend/products/{id}/` | Retrieve | Get a specific product |
+| POST | `/api/backend/products/` | Create | Create a new product |
+| PUT | `/api/backend/products/{id}/` | Update | Update a product |
+| PATCH | `/api/backend/products/{id}/` | Partial Update | Partially update a product |
+| DELETE | `/api/backend/products/{id}/` | Delete | Delete a product |
+
+**Request/Response Fields**:
+- `id`: Product ID
+- `name`: Product name
+- `category`: Product category (nested object)
+- `price`: Product price
+- `unit`: Unit of measurement
+- `image`: Product image file
+- `image_url`: URL of product image (generated)
+- `description`: Product description
+
+**Example Response**:
+```json
+{
+  "id": 1,
+  "name": "纯棉印花布",
+  "price": "25.50",
+  "unit": 1,
+  "description": "高品质纯棉印花布料",
+  "image": "/media/products/cotton_fabric.jpg",
+  "image_url": "http://example.com/media/products/cotton_fabric.jpg",
+  "category": {
+    "id": 3,
+    "name": "印花布"
+  },
+  "merchant": 1,
+  "created_at": "2025-11-24T10:30:00Z",
+  "updated_at": "2025-11-24T10:30:00Z"
+}
+```
+
+### Warehouses
+
+**Base URL**: `/api/backend/warehouses/`
+
+| Method | URL Pattern | Action | Description |
+|--------|-------------|---------|-------------|
+| GET | `/api/backend/warehouses/` | List | Retrieve all warehouses |
+| GET | `/api/backend/warehouses/{id}/` | Retrieve | Get a specific warehouse |
+| POST | `/api/backend/warehouses/` | Create | Create a new warehouse |
+| PUT | `/api/backend/warehouses/{id}/` | Update | Update a warehouse |
+| PATCH | `/api/backend/warehouses/{id}/` | Partial Update | Partially update a warehouse |
+| DELETE | `/api/backend/warehouses/{id}/` | Delete | Delete a warehouse |
+
+**Request/Response Fields**:
+- `id`: Warehouse ID
+- `name`: Warehouse name
+- `location`: Warehouse location
+- `type`: Warehouse type (1: Whole, 2: Scattered)
+
+**Example Response**:
+```json
+{
+  "id": 1,
+  "name": "主仓库",
+  "location": "园区A区1号",
+  "type": 1,
+  "merchant": 1,
+  "created_at": "2025-11-24T10:30:00Z",
+  "updated_at": "2025-11-24T10:30:00Z"
+}
+```
+
+### Product Categories
+
+**Base URL**: `/api/backend/product-categories/`
+
+| Method | URL Pattern | Action | Description |
+|--------|-------------|---------|-------------|
+| GET | `/api/backend/product-categories/` | List | Retrieve all product categories |
+| GET | `/api/backend/product-categories/{id}/` | Retrieve | Get a specific product category |
+| POST | `/api/backend/product-categories/` | Create | Create a new product category |
+| PUT | `/api/backend/product-categories/{id}/` | Update | Update a product category |
+| PATCH | `/api/backend/product-categories/{id}/` | Partial Update | Partially update a product category |
+| DELETE | `/api/backend/product-categories/{id}/` | Delete | Delete a product category |
+
+**Request/Response Fields**:
+- `id`: Category ID
+- `name`: Category name
+- `description`: Category description
+
+**Example Response**:
+```json
+{
+  "id": 1,
+  "name": "印花布",
+  "description": "各类印花布料",
+  "merchant": 1,
+  "created_at": "2025-11-24T10:30:00Z",
+  "updated_at": "2025-11-24T10:30:00Z"
+}
+```
+
+### Suppliers
+
+**Base URL**: `/api/backend/suppliers/`
+
+| Method | URL Pattern | Action | Description |
+|--------|-------------|---------|-------------|
+| GET | `/api/backend/suppliers/` | List | Retrieve all suppliers |
+| GET | `/api/backend/suppliers/{id}/` | Retrieve | Get a specific supplier |
+| POST | `/api/backend/suppliers/` | Create | Create a new supplier |
+| PUT | `/api/backend/suppliers/{id}/` | Update | Update a supplier |
+| PATCH | `/api/backend/suppliers/{id}/` | Partial Update | Partially update a supplier |
+| DELETE | `/api/backend/suppliers/{id}/` | Delete | Delete a supplier |
+
+**Request/Response Fields**:
+- `id`: Supplier ID
+- `name`: Supplier name
+- `contact`: Contact person
+- `mobile`: Mobile phone number
+- `email`: Email address
+- `address`: Physical address
+- `description`: Additional description
+
+**Example Response**:
+```json
+{
+  "id": 1,
+  "name": "华美纺织原料厂",
+  "contact": "张经理",
+  "mobile": "13800138001",
+  "email": "zhang@huamei.com",
+  "address": "广州市天河区科技园",
+  "description": "长期合作的优质原料供应商",
+  "merchant": 1,
+  "created_at": "2025-11-24T10:30:00Z",
+  "updated_at": "2025-11-24T10:30:00Z"
+}
+```
+
+### Employees
+
+**Base URL**: `/api/backend/employees/`
+
+| Method | URL Pattern | Action | Description |
+|--------|-------------|---------|-------------|
+| GET | `/api/backend/employees/` | List | Retrieve all employees |
+| GET | `/api/backend/employees/{id}/` | Retrieve | Get a specific employee |
+| POST | `/api/backend/employees/` | Create | Create a new employee |
+| PUT | `/api/backend/employees/{id}/` | Update | Update an employee |
+| PATCH | `/api/backend/employees/{id}/` | Partial Update | Partially update an employee |
+| DELETE | `/api/backend/employees/{id}/` | Delete | Delete an employee |
+
+**Request/Response Fields**:
+- `id`: Employee ID
+- `name`: Employee name
+- `position`: Employee position (EmployeeType object)
+- `job_type`: Job type (read-only string derived from position)
+- `mobile`: Mobile phone number
+- `status`: Employee status
+- `sys_user`: Associated Django User ID (nullable)
+
+**Example Response**:
+```json
+{
+  "id": 1,
+  "name": "张三",
+  "position": {
+    "id": 2,
+    "title": "打纸工",
+    "description": "负责打纸工作",
+    "merchant": 1
+  },
+  "job_type": "打纸工",
+  "mobile": "13800138000",
+  "status": "在职",
+  "sys_user": 5,
+  "merchant": 1,
+  "created_at": "2025-11-24T10:30:00Z",
+  "updated_at": "2025-11-24T10:30:00Z"
+}
+```
+
+### Employee Types
+
+**Base URL**: `/api/backend/employee-types/`
+
+| Method | URL Pattern | Action | Description |
+|--------|-------------|---------|-------------|
+| GET | `/api/backend/employee-types/` | List | Retrieve all employee types |
+| GET | `/api/backend/employee-types/{id}/` | Retrieve | Get a specific employee type |
+| POST | `/api/backend/employee-types/` | Create | Create a new employee type |
+| PUT | `/api/backend/employee-types/{id}/` | Update | Update an employee type |
+| PATCH | `/api/backend/employee-types/{id}/` | Partial Update | Partially update an employee type |
+| DELETE | `/api/backend/employee-types/{id}/` | Delete | Delete an employee type |
+
+**Request/Response Fields**:
+- `id`: Employee type ID
+- `title`: Type title
+- `description`: Type description
+
+**Example Response**:
+```json
+{
+  "id": 1,
+  "title": "打纸工",
+  "description": "负责打纸工作",
+  "merchant": 1,
+  "created_at": "2025-11-24T10:30:00Z",
+  "updated_at": "2025-11-24T10:30:00Z"
+}
+```
+
+### Customers
+
+**Base URL**: `/api/backend/customers/`
+
+| Method | URL Pattern | Action | Description |
+|--------|-------------|---------|-------------|
+| GET | `/api/backend/customers/` | List | Retrieve customers visible to the current employee |
+| GET | `/api/backend/customers/{id}/` | Retrieve | Get a specific customer (if visible to current employee) |
+| POST | `/api/backend/customers/` | Create | Create a new customer |
+| PUT | `/api/backend/customers/{id}/` | Update | Update a customer (if visible to current employee) |
+| PATCH | `/api/backend/customers/{id}/` | Partial Update | Partially update a customer (if visible to current employee) |
+| DELETE | `/api/backend/customers/{id}/` | Delete | Delete a customer (if visible to current employee) |
+
+#### Customer Visibility System
+
+The Customers API implements a visibility control system that restricts which customers are accessible to each employee. This system works as follows:
+
+**Visibility Rules**:
+1. A customer is visible to an employee if:
+   - The employee created the customer, OR
+   - The employee is explicitly added to the customer's `visible_employees` list, OR
+   - The employee is a superuser or has `basic_info.view_all_customers` permission
+
+2. When listing customers, the API automatically filters to only show customers visible to the current employee.
+
+3. When accessing a specific customer (GET, PUT, PATCH, DELETE), the API checks if the customer is visible to the current employee. If not, a 404 Not Found response is returned.
+
+**Request/Response Fields**:
+- `id`: Customer ID
+- `name`: Customer name
+- `mobile`: Mobile phone number
+- `email`: Email address
+- `contact`: Contact person
+- `area`: Geographic area
+- `description`: Additional description
+- `visible_employees`: List of employee IDs who can view this customer
+- `created_by`: ID of the employee who created this customer (auto-set on creation)
+
+**Creating a Customer (POST)**:
+```json
+{
+  "name": "Acme Corporation",
+  "mobile": "13800138000",
+  "email": "contact@acme.com",
+  "contact": "John Doe",
+  "area": "Beijing",
+  "description": "Regular wholesale customer",
+  "visible_employees": [1, 2, 3]  // Optional: employees who can view this customer
+}
+```
+
+**Updating a Customer (PUT/PATCH)**:
+When updating a customer, the same visibility rules apply:
+- The employee must be able to see the customer to update it
+- The `visible_employees` field can be updated to add or remove access for other employees
+
+```json
+{
+  "name": "Updated Customer Name",
+  "visible_employees": [1, 4, 5]  // Updated list of employees who can view this customer
+}
+```
+
+**Example Response**:
+```json
+{
+  "id": 1,
+  "name": "北京服装批发公司",
+  "mobile": "13800138000",
+  "email": "beijing@clothing.com",
+  "contact": "李经理",
+  "area": "北京朝阳区",
+  "description": "长期合作的服装批发客户",
+  "visible_employees": [1, 3, 5],
+  "created_by": 1,
+  "merchant": 1,
+  "created_at": "2025-11-24T10:30:00Z",
+  "updated_at": "2025-11-24T10:30:00Z"
+}
+```
+
+**Security Note**: Customer visibility is enforced at the API level. Attempts to access a customer that isn't visible to the current employee will result in a 404 Not Found response, regardless of whether the customer actually exists in the database.
+
+#### Customer Visibility System
+
+The Customers API implements a visibility control system that restricts which customers are accessible to each employee. This system works as follows:
+
+**Visibility Rules**:
+1. A customer is visible to an employee if:
+   - The employee created the customer, OR
+   - The employee is explicitly added to the customer's `visible_employees` list, OR
+   - The employee is a superuser or has `basic_info.view_all_customers` permission
+
+2. When listing customers, the API automatically filters to only show customers visible to the current employee.
+
+3. When accessing a specific customer (GET, PUT, PATCH, DELETE), the API checks if the customer is visible to the current employee. If not, a 404 Not Found response is returned.
+
+**Request/Response Fields**:
+- `id`: Customer ID
+- `name`: Customer name
+- `mobile`: Mobile phone number
+- `email`: Email address
+- `contact`: Contact person
+- `area`: Geographic area
+- `description`: Additional description
+- `visible_employees`: List of employee IDs who can view this customer
+- `created_by`: ID of the employee who created this customer (auto-set on creation)
+
+**Creating a Customer (POST)**:
+```json
+{
+  "name": "Acme Corporation",
+  "mobile": "13800138000",
+  "email": "contact@acme.com",
+  "contact": "John Doe",
+  "area": "Beijing",
+  "description": "Regular wholesale customer",
+  "visible_employees": [1, 2, 3]  // Optional: employees who can view this customer
+}
+```
+
+**Updating a Customer (PUT/PATCH)**:
+When updating a customer, the same visibility rules apply:
+- The employee must be able to see the customer to update it
+- The `visible_employees` field can be updated to add or remove access for other employees
+
+```json
+{
+  "name": "Updated Customer Name",
+  "visible_employees": [1, 4, 5]  // Updated list of employees who can view this customer
+}
+```
+
+**Security Note**: Customer visibility is enforced at the API level. Attempts to access a customer that isn't visible to the current employee will result in a 404 Not Found response, regardless of whether the customer actually exists in the database.
+
+### Vehicle Types
+
+**Base URL**: `/api/backend/vehicle-types/`
+
+| Method | URL Pattern | Action | Description |
+|--------|-------------|---------|-------------|
+| GET | `/api/backend/vehicle-types/` | List | Retrieve all vehicle types |
+| GET | `/api/backend/vehicle-types/{id}/` | Retrieve | Get a specific vehicle type |
+| POST | `/api/backend/vehicle-types/` | Create | Create a new vehicle type |
+| PUT | `/api/backend/vehicle-types/{id}/` | Update | Update a vehicle type |
+| PATCH | `/api/backend/vehicle-types/{id}/` | Partial Update | Partially update a vehicle type |
+| DELETE | `/api/backend/vehicle-types/{id}/` | Delete | Delete a vehicle type |
+
+**Request/Response Fields**:
+- `id`: Vehicle type ID
+- `name`: Type name
+- `capacity`: Vehicle capacity
+- `description`: Type description
+
+**Example Response**:
+```json
+{
+  "id": 1,
+  "name": "小型货车",
+  "capacity": "500公斤",
+  "description": "适合小批量货物运输",
+  "merchant": 1,
+  "created_at": "2025-11-24T10:30:00Z",
+  "updated_at": "2025-11-24T10:30:00Z"
+}
+```
+
+### Bank Accounts
+
+**Base URL**: `/api/backend/bank-accounts/`
+
+| Method | URL Pattern | Action | Description |
+|--------|-------------|---------|-------------|
+| GET | `/api/backend/bank-accounts/` | List | Retrieve all bank accounts |
+| GET | `/api/backend/bank-accounts/{id}/` | Retrieve | Get a specific bank account |
+| POST | `/api/backend/bank-accounts/` | Create | Create a new bank account |
+| PUT | `/api/backend/bank-accounts/{id}/` | Update | Update a bank account |
+| PATCH | `/api/backend/bank-accounts/{id}/` | Partial Update | Partially update a bank account |
+| DELETE | `/api/backend/bank-accounts/{id}/` | Delete | Delete a bank account |
+
+**Request/Response Fields**:
+- `id`: Account ID
+- `bank_name`: Bank name
+- `account_number`: Account number
+- `account_holder`: Account holder name
+- `branch`: Bank branch
+- `is_default`: Whether this is the default account
+
+**Example Response**:
+```json
+{
+  "id": 1,
+  "bank_name": "中国工商银行",
+  "account_number": "6222021234567890",
+  "account_holder": "张三",
+  "branch": "广州天河支行",
+  "is_default": true,
+  "merchant": 1,
+  "created_at": "2025-11-24T10:30:00Z",
+  "updated_at": "2025-11-24T10:30:00Z"
+}
+```
+
+### Device Info
+
+**Base URL**: `/api/backend/device-info/`
+
+| Method | URL Pattern | Action | Description |
+|--------|-------------|---------|-------------|
+| GET | `/api/backend/device-info/` | List | Retrieve all device information |
+| GET | `/api/backend/device-info/{id}/` | Retrieve | Get specific device information |
+| POST | `/api/backend/device-info/` | Create | Create new device information |
+| PUT | `/api/backend/device-info/{id}/` | Update | Update device information |
+| PATCH | `/api/backend/device-info/{id}/` | Partial Update | Partially update device information |
+| DELETE | `/api/backend/device-info/{id}/` | Delete | Delete device information |
+
+**Request/Response Fields**:
+- `id`: Device ID
+- `name`: Device name
+- `type`: Device type (ROLLING, PRINTING, etc.)
+- `status`: Device status (ACTIVE, MAINTENANCE, etc.)
+- `start_working_at`: Date when device started working
+- `stop_working_at`: Date when device stopped working
+- `is_occupied`: Whether device is currently occupied
+- `description`: Additional description
+
+**Example Response**:
+```json
+{
+  "id": 1,
+  "name": "滚筒机A",
+  "type": "ROLLING",
+  "status": "ACTIVE",
+  "start_working_at": "2025-01-15",
+  "stop_working_at": null,
+  "is_occupied": true,
+  "description": "主要生产用滚筒设备",
+  "merchant": 1,
+  "created_at": "2025-11-24T10:30:00Z",
+  "updated_at": "2025-11-24T10:30:00Z"
+}
+```
+
+### Vehicle Transport Records
+
+**Base URL**: `/api/backend/vehicle-transport-records/`
+
+| Method | URL Pattern | Action | Description |
+|--------|-------------|---------|-------------|
+| GET | `/api/backend/vehicle-transport-records/` | List | Retrieve all transport records |
+| GET | `/api/backend/vehicle-transport-records/{id}/` | Retrieve | Get a specific transport record |
+| POST | `/api/backend/vehicle-transport-records/` | Create | Create a new transport record |
+| PUT | `/api/backend/vehicle-transport-records/{id}/` | Update | Update a transport record |
+| PATCH | `/api/backend/vehicle-transport-records/{id}/` | Partial Update | Partially update a transport record |
+| DELETE | `/api/backend/vehicle-transport-records/{id}/` | Delete | Delete a transport record |
+
+**Request/Response Fields**:
+- `id`: Record ID
+- `vehicle_type`: Vehicle type (nested object)
+- `driver_name`: Driver name
+- `driver_mobile`: Driver mobile phone
+- `transport_date`: Date of transport
+- `source`: Source location
+- `destination`: Destination location
+- `goods_description`: Description of goods being transported
+- `quantity`: Quantity of goods
+- `status`: Transport status
+- `notes`: Additional notes
+- `vehicle_type_name`: Read-only derived vehicle type name
+
+**Example Response**:
+```json
+{
+  "id": 1,
+  "vehicle_type": {
+    "id": 1,
+    "name": "小型货车",
+    "capacity": "500公斤",
+    "description": "适合小批量货物运输"
+  },
+  "driver_name": "王师傅",
+  "driver_mobile": "13900139000",
+  "transport_date": "2025-11-24",
+  "source": "广州工厂",
+  "destination": "深圳客户",
+  "goods_description": "印花布料",
+  "quantity": "300公斤",
+  "status": "COMPLETED",
+  "notes": "运输顺利",
+  "vehicle_type_name": "小型货车",
+  "merchant": 1,
+  "created_at": "2025-11-24T10:30:00Z",
+  "updated_at": "2025-11-24T10:30:00Z"
+}
+```
+
+### User Profiles
+
+**Base URL**: `/api/backend/user-profiles/`
+
+| Method | URL Pattern | Action | Description |
+|--------|-------------|---------|-------------|
+| GET | `/api/backend/user-profiles/` | List | Retrieve all user profiles for current merchant |
+| GET | `/api/backend/user-profiles/{id}/` | Retrieve | Get a specific user profile |
+| POST | `/api/backend/user-profiles/` | Create | Create a new user profile |
+| PUT | `/api/backend/user-profiles/{id}/` | Update | Update a user profile |
+| PATCH | `/api/backend/user-profiles/{id}/` | Partial Update | Partially update a user profile |
+| DELETE | `/api/backend/user-profiles/{id}/` | Delete | Delete a user profile |
+
+**Request/Response Fields**:
+- `id`: Profile ID
+- `user`: User ID (for writing)
+- `user_detail`: User object details (for reading)
+- `merchant`: Merchant ID (auto-set to current user's merchant)
+- `description`: Profile description
+- `created_at`: Creation timestamp
+- `updated_at`: Last update timestamp
+
+**Creating a User Profile (POST)**:
+```json
+{
+  "user": 123,  // User ID
+  "description": "User profile for system access"
+}
+```
+
+**Example Response**:
+```json
+{
+  "id": 1,
+  "user": 5,
+  "user_detail": {
+    "id": 5,
+    "username": "testuser",
+    "email": "test@example.com",
+    "is_active": true,
+    "is_superuser": false,
+    "last_login": "2025-11-24T09:00:00Z"
+  },
+  "merchant": 1,
+  "description": "用户资料描述",
+  "created_at": "2025-11-24T10:30:00Z",
+  "updated_at": "2025-11-24T10:30:00Z"
+}
+```
+
+## Error Handling
+
+All endpoints may return the following error responses:
+
+### 401 Unauthorized
+```json
+{
+  "detail": "Authentication credentials were not provided."
+}
+```
+
+### 403 Forbidden
+```json
+{
+  "detail": "You do not have permission to perform this action."
+}
+```
+
+### 404 Not Found
+```json
+{
+  "detail": "Not found."
+}
+```
+
+### 400 Bad Request
+```json
+{
+  "field_name": ["Error message for this field"],
+  "non_field_errors": ["General error message"]
+}
+```
+
+### 500 Server Error
+```json
+{
+  "detail": "A server error occurred."
+}
+```
+
+## Pagination
+
+List endpoints support pagination using the LimitOffsetPagination scheme.
+
+**Query Parameters**:
+- `limit`: Number of results to return per page
+- `offset`: Number of results to skip
+
+**Example**:
+```
+GET /api/backend/products/?limit=20&offset=40
+```
+
+This will return 20 items starting from position 40 (items 41-60).
+
+**Response Format**:
+```json
+{
+  "count": 150,
+  "next": "http://example.com/api/backend/products/?limit=20&offset=60",
+  "previous": "http://example.com/api/backend/products/?limit=20&offset=20",
+  "results": [
+    {
+      "id": 41,
+      "name": "Product 41",
+      ...
+    }
+    // ... up to 20 items
+  ]
+}
+```
--- a/docs/bug-fix-20251122-stateflow.md
+++ b/docs/bug-fix-20251122-stateflow.md
@@ -0,0 +1,56 @@
+# Bug 修复报告
+
+## 基本信息
+- 日期：2025-11-22
+- 模块：stateflow（流程状态管理）
+- 修复者：Cline
+
+---
+
+## 问题描述
+API `GET /api/v1/stateflow/business-objects/xxx/state-logs/` 无法获取已撤销状态的工艺参数。
+
+**具体表现**：当一个状态流转记录被撤销后，通过该API获取状态日志列表时，已撤销状态记录的工艺参数会被过滤掉，导致参数丢失。
+
+**影响范围**：
+1. 使用 `GET /api/v1/stateflow/business-objects/xxx/state-logs/` API 获取包含已撤销状态的日志列表
+2. 依赖这些日志进行审计、回溯或数据分析的功能
+
+---
+
+## 根本原因
+在 `StateFlowRecordWithParametersSerializer` 中调用 `get_all_parameters_summary()` 时未传递 `include_cancelled=True` 参数，导致已撤销状态的参数被 `get_all_parameters_summary()` 方法内部逻辑过滤掉。
+
+---
+
+## 修复方案
+修改 `/home/f/coding/flower/stateflow/serializers.py` 中的 `get_parameters_summary` 方法：
+
+**修改前**：
+```python
+def get_parameters_summary(self, obj):
+    """获取参数摘要"""
+    return obj.get_all_parameters_summary()
+```
+
+**修改后**：
+```python
+def get_parameters_summary(self, obj):
+    """获取参数摘要，包含已撤销状态的参数"""
+    return obj.get_all_parameters_summary(include_cancelled=True)
+```
+
+---
+
+## 测试验证
+1. **创建测试用例**：在 `/home/f/coding/flower/stateflow/tests/test_business_object_api.py` 中创建 `test_get_state_logs_api_cancelled_state_with_parameters` 测试用例，用于复现和验证bug。
+
+2. **验证修复**：
+   - 运行测试用例 `test_get_state_logs_api_cancelled_state_with_parameters`
+   - 修复前测试失败，修复后测试通过
+   - 验证已撤销状态的工艺参数能够正确返回
+
+---
+
+## 总结
+该修复确保了已撤销状态的工艺参数不会丢失，与未撤销状态的处理方式保持一致，符合业务需求。修复仅涉及一行代码的修改，但确保了数据完整性和API的一致性。
--- a/docs/printing_job_workflow_api.yml
+++ b/docs/printing_job_workflow_api.yml
@@ -0,0 +1,356 @@
+openapi: 3.0.0
+info:
+  title: 印染任务流程管理 API
+  description: 印染任务的流程状态管理接口
+  version: 1.0.0
+
+servers:
+  - url: /api/v1
+    description: API v1
+
+paths:
+  /printing-jobs/{id}/advance-to-next-state/:
+    post:
+      summary: 推进到下一个状态
+      description: 将印染任务推进到下一个流程状态
+      operationId: advanceToNextState
+      tags:
+        - PrintingJob Workflow
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 印染任务ID
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: 推进成功
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  detail:
+                    type: string
+                    description: 操作结果消息
+                    example: "已完成状态: 打纸"
+                  data:
+                    $ref: '#/components/schemas/PrintingJobDetail'
+        '400':
+          description: 请求错误
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  detail:
+                    type: string
+                    example: "该任务没有关联的流程实例"
+        '403':
+          description: 权限不足
+        '404':
+          description: 任务不存在
+
+  /printing-jobs/{id}/step-back-one-state/:
+    post:
+      summary: 回退一步
+      description: 将印染任务回退到上一个流程状态
+      operationId: stepBackOneState
+      tags:
+        - PrintingJob Workflow
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 印染任务ID
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: 回退成功
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  detail:
+                    type: string
+                    description: 操作结果消息
+                    example: "已回退状态: 滚筒"
+                  data:
+                    $ref: '#/components/schemas/PrintingJobDetail'
+        '400':
+          description: 请求错误
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  detail:
+                    type: string
+                    example: "当前没有任何状态流转记录，无法回退"
+        '403':
+          description: 权限不足
+        '404':
+          description: 任务不存在
+
+  /printing-jobs/{id}/completed-states/:
+    get:
+      summary: 查询已完成的流程列表
+      description: 获取印染任务已完成的流程状态列表
+      operationId: getCompletedStates
+      tags:
+        - PrintingJob Workflow
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 印染任务ID
+          schema:
+            type: integer
+        - name: include_cancelled
+          in: query
+          required: false
+          description: 是否包含已撤销的流程记录
+          schema:
+            type: boolean
+            default: false
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  count:
+                    type: integer
+                    description: 已完成状态数量
+                    example: 2
+                  results:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/CompletedState'
+        '403':
+          description: 权限不足
+        '404':
+          description: 任务不存在
+
+  /printing-jobs/{id}/timeline/:
+    get:
+      summary: 获取流程时间线
+      description: 获取印染任务的完整流程时间线，包括未开始、进行中和已完成的状态（不包含已撤销的记录）
+      operationId: getTimeline
+      tags:
+        - PrintingJob Workflow
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 印染任务ID
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  count:
+                    type: integer
+                    description: 流程节点总数
+                    example: 3
+                  results:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/TimelineItem'
+        '403':
+          description: 权限不足
+        '404':
+          description: 任务不存在
+
+components:
+  schemas:
+    PrintingJobDetail:
+      type: object
+      description: 印染任务详情
+      properties:
+        id:
+          type: integer
+          description: 任务ID
+          example: 29
+        printing_order:
+          type: integer
+          description: 印染订单ID
+          example: 50
+        printing_order_id:
+          type: string
+          description: 印染订单人类可读ID
+          example: "20251113000050"
+        product:
+          type: integer
+          description: 产品ID
+          example: 123
+        product_name:
+          type: string
+          description: 产品名称
+          example: "纯棉布料"
+        product_code:
+          type: string
+          description: 产品编码
+          example: "P20230001"
+        quantity:
+          type: integer
+          description: 数量
+          example: 1000
+        unit:
+          type: string
+          description: 单位
+          example: "米"
+        size:
+          type: string
+          nullable: true
+          description: 一段尺寸
+          example: "100x200"
+        pieces:
+          type: integer
+          nullable: true
+          description: 件数
+          example: 10
+        description:
+          type: string
+          nullable: true
+          description: 备注
+          example: "特殊工艺要求"
+        status:
+          type: string
+          description: 当前状态名称
+          example: "滚筒"
+        status_id:
+          type: integer
+          nullable: true
+          description: 当前状态ID
+          example: 97
+        is_completed:
+          type: boolean
+          description: 是否已完成
+          example: false
+        has_started:
+          type: boolean
+          description: 是否已开始
+          example: true
+        business_object_id:
+          type: integer
+          nullable: true
+          description: 流程实例ID
+          example: 29
+        created_at:
+          type: string
+          format: date-time
+          description: 创建时间
+          example: "2025-11-13T07:30:00Z"
+        updated_at:
+          type: string
+          format: date-time
+          description: 更新时间
+          example: "2025-11-13T07:33:00Z"
+
+    CompletedState:
+      type: object
+      description: 已完成的状态记录
+      properties:
+        id:
+          type: integer
+          description: 记录ID
+          example: 45
+        state_id:
+          type: integer
+          description: 状态ID
+          example: 96
+        state_name:
+          type: string
+          description: 状态名称
+          example: "打纸"
+        completed_at:
+          type: string
+          format: date-time
+          description: 完成时间
+          example: "2025-11-13T07:33:00.230958Z"
+        completed_by:
+          type: string
+          nullable: true
+          description: 完成人用户名
+          example: "admin"
+        completed_by_name:
+          type: string
+          nullable: true
+          description: 完成人姓名
+          example: "张三"
+        is_cancelled:
+          type: boolean
+          description: 是否已撤销
+          example: false
+        cancelled_at:
+          type: string
+          format: date-time
+          nullable: true
+          description: 撤销时间
+          example: null
+
+    TimelineItem:
+      type: object
+      description: 流程时间线项
+      properties:
+        state_id:
+          type: integer
+          description: 状态ID
+          example: 96
+        state_name:
+          type: string
+          description: 状态名称
+          example: "打纸"
+        state_description:
+          type: string
+          nullable: true
+          description: 状态描述
+          example: "打印纸样"
+        order:
+          type: integer
+          description: 状态顺序
+          example: 1
+        status:
+          type: string
+          description: 状态状态
+          enum:
+            - not_started
+            - in_progress
+            - completed
+          example: "completed"
+        completed_at:
+          type: string
+          format: date-time
+          nullable: true
+          description: 完成时间（仅当 status=completed 时有值）
+          example: "2025-11-13T07:33:00.230958Z"
+        completed_by:
+          type: string
+          nullable: true
+          description: 完成人用户名（仅当 status=completed 时有值）
+          example: "admin"
+        completed_by_name:
+          type: string
+          nullable: true
+          description: 完成人姓名（仅当 status=completed 时有值）
+          example: "张三"
+
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+security:
+  - BearerAuth: []
--- a/docs/开版管理字段.md
+++ b/docs/开版管理字段.md
@@ -0,0 +1,33 @@
+| 字段名称 | 明道云 | 本地系统 | 状态 | 类型 | 说明 |
+|---------|-------|---------|------|------|------|
+| 自动编号 | ✅ | ❌ | **需添加** `plate_code` | CharField(50, unique) | 自动生成的版单编号（如：20251107-1） |
+| 设计编号 | ✅ | ❌ | **需添加** `design_code` | CharField(50) | 设计编号 |
+| 起版情况 | ✅ | ❌ | **需添加** `plate_type` | CharField(20) | 首版/复版等 |
+| 下版时间 | ✅ | ❌ | **需添加** `plate_date` | DateTimeField | 下版日期时间 |
+| 开发进程 | ✅ | ❌ | **需添加** `development_status` | CharField(20) | 未打印/待画图/画图完成/调色样/调色完成/套纸样/取消版/客户审批/开版完成/已下单等 |
+| 紧急程度 | ✅ | ❌ | **需添加** `urgency_level` | CharField(20) | 正常/加急等 |
+| 销售员ID | ✅ | ❌ | **需添加** `salesperson_id` | ForeignKey(Salesperson) | 关联销售员/业务员 |
+| 跟单员ID | ✅ | ❌ | **需添加** `salesperson_id` | ForeignKey(Salesperson) | 关联业务员 |
+| 区域 | ✅ | ❌ | **需添加** `area` | CharField(255) | 区域信息 |
+| 默认地址 | ✅ | ❌ | **需添加** `default_address` | CharField(500) | 默认地址 |
+| 客户ID | ✅ | ❌ | **需添加** `customer_id` | ForeignKey(Customer) | 关联客户 |
+| 是否套唛架 | ✅ | ❌ | **需添加** `is_mark_frame` | BooleanField | 布尔值 |
+| 画图评级 | ✅ | ❌ | **需添加** `drawing_rating` | CharField(20) | 画图质量评级 |
+| 调色评级 | ✅ | ❌ | **需添加** `color_matching_rating` | CharField(20) | 调色质量评级 |
+| 套样评级 | ✅ | ❌ | **需添加** `sample_rating` | CharField(20) | 套样质量评级 |
+| 难度评级 | ✅ | ❌ | **需添加** `difficulty_rating` | CharField(20) | 难度评级 |
+| 要求完成时间 | ✅ | ❌ | **需添加** `required_completion_date` | DateField | 要求完成日期 |
+| 布料 | ✅ | ❌ | **需添加** `fabric` | CharField(100) | 布料信息 |
+| 幅宽 | ✅ | ❌ | **需添加** `width` | CharField(50) | 幅宽 |
+| 款号名称 | ✅ | ❌ | **需添加** `style_name` | CharField(100) | 款号名称 |
+| 完成时间 | ✅ | ❌ | **需添加** `completion_date` | DateTimeField | 完成时间 |
+| 做货方式 | ✅ | ❌ | **需添加** `production_method` | CharField(50) | 做货方式 |
+| 开版方式 | ✅ | ❌ | **需添加** `plate_method` | CharField(50) | 开版方式 |
+| 开版图 | ✅ | ❌ | **需添加** `plate_image` | FileField/ImageField | 开版图附件 |
+| 米样 | ✅ | ❌ | **需添加** `sample_meter` | CharField(100) | 米样信息 |
+| 客户要求米样米数 | ✅ | ❌ | **需添加** `required_sample_meters` | DecimalField(10,2) | 客户要求的米样米数 |
+| 复版原因 | ✅ | ❌ | **需添加** `reprint_reason` | TextField | 复版原因 |
+| 审批结果 | ✅ | ❌ | **需添加** `approval_result` | CharField(50) | 审批结果 |
+| 是否已下单 | ✅ | ❌ | **需添加** `is_ordered` | BooleanField | 布尔值，是否已下单 |
+| 客户修改意见 | ✅ | ❌ | **需添加** `customer_feedback` | TextField | 客户修改意见 |
+| 打版注意事项 | ✅ | ❌ | **需添加** `plate_notes` | TextField | 打版注意事项 |