From 8119bb4c8f8fd7dfd43d8c4622ee85d311fe7160 Mon Sep 17 00:00:00 2001
From: NoahLan <6995syu@163.com>
Date: Thu, 6 Nov 2025 11:24:21 +0800
Subject: [PATCH] =?UTF-8?q?chore:=20=E9=A1=B9=E7=9B=AE=E8=A7=84=E5=88=99?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .cursor/rules/business.mdc  | 191 ++++++++++++
 .cursor/rules/framework.mdc | 594 ++++++++++++++++++++++++++++++++++++
 2 files changed, 785 insertions(+)
 create mode 100644 .cursor/rules/business.mdc
 create mode 100644 .cursor/rules/framework.mdc

diff --git a/.cursor/rules/business.mdc b/.cursor/rules/business.mdc
new file mode 100644
index 0000000..3aefe32
--- /dev/null
+++ b/.cursor/rules/business.mdc
@@ -0,0 +1,191 @@
+---
+alwaysApply: true
+---
+
+# 后端业务规则 (冲压排产系统)
+
+## 业务概述
+
+本系统是**冲压排产系统**，用于将工单中的翅片冲压任务合理分配到不同的冲压设备上，同时协调模具使用和调模工的工作安排。
+
+业务参考项目：`PunchSchedule` 目录
+
+参考文档：
+- @file:PunchSchedule/docs/README.md
+- @file:PunchSchedule/docs/01-业务领域概述.md
+- @file:PunchSchedule/docs/02-数据模型设计.md
+- @file:PunchSchedule/docs/03-排产算法详解.md
+- @file:PunchSchedule/docs/04-约束规则说明.md
+
+## 核心业务实体
+
+### 1. 工单 (ManufacturingOrder)
+
+**定义**: 生产任务的顶层容器，来源于ERP系统
+
+**关键属性**: 工单号、组件号、组件名称、计划数量、单件重量、翅片任务列表
+
+**业务规则**:
+- 工单号必须唯一
+- 一个工单可包含多个不同规格的翅片任务
+- 支持按组件进行任务分组
+
+**参考代码**:
+- @file:PunchSchedule/models/manufacturing_order.py
+
+### 2. 翅片 (Fin)
+
+**定义**: 具体的生产任务单位，定义了详细的加工要求
+
+**关键属性**: 名称、冲压类型、数量、翅片类型、尺寸参数（高度、宽度、长度、波距、料厚）、计划开始时间、工时、ERP工序报告号、未排产原因
+
+**业务规则**:
+- 翅片类型和波距决定模具选择
+- 冲压类型决定设备兼容性
+- 尺寸参数影响设备选择和约束验证
+- BAT产品特殊处理：产品名包含"BAT"且冲压类型为"BST14"时，应转换为"BST2B2"
+
+### 3. 设备 (Machine/Equipment)
+
+**定义**: 冲压设备是生产的物理载体，具有特定的能力和约束
+
+**关键属性**: 设备类型、设备编号、初始状态信息、允许的翅片类型/高度、波距范围限制、最大翅片长度限制
+
+**业务规则**:
+- 设备类型必须与翅片冲压类型匹配
+- 支持设备专业化配置
+- 初始状态用于处理排产开始时的在制品
+
+**参考代码**:
+- @file:PunchSchedule/models/machine.py
+
+### 4. 模具 (Module)
+
+**定义**: 模具是生产翅片的专用工装，决定了产品的规格
+
+**关键属性**: 模具编号、模具类型（整体模具/分体模具）、适用的翅片类型、波距规格
+
+**业务规则**:
+- 模具与翅片通过翅片类型和波距精确匹配
+- 整体模具优先级高于分体模具
+- 模具在使用期间不能被其他设备占用
+
+### 5. 调模工 (ModuleChanger)
+
+**定义**: 调模工负责执行换模和调模操作
+
+**关键属性**: 调模工编号、姓名、班次信息、工作时间
+
+**业务规则**:
+- 分为白班和夜班两种班次
+- 每个调模工在排产周期内有多个班次
+- 支持跨天夜班处理（如21:00-次日05:30）
+
+### 6. 生产计划 (Plan)
+
+**定义**: 生产计划将翅片任务分配到具体设备上执行
+
+**关键属性**: 工单、翅片、设备、模具、排产开始/结束时间、休息时间、调模工、调模任务
+
+**业务规则**:
+- 时间计算自动跳过休息时间
+- 支持关联调模任务
+- 计划按时间顺序排列
+- 同一设备上的计划时间不能重叠
+
+### 7. 调模任务 (ModuleChangeMission)
+
+**定义**: 调模任务是调模工执行的具体操作
+
+**关键属性**: 调模类型（fix/change）、调模时间、开始/结束时间、目标设备、目标计划、新旧模具
+
+**业务规则**:
+- fix调模约20分钟，change换模约120分钟
+- 调模时间会根据工时系数调整（默认0.6）
+- 自动处理时间冲突和后续任务调整
+- 调模任务必须在调模工的工作时间内
+
+## 业务约束规则
+
+### 设备约束
+
+**硬约束**:
+1. 冲压类型匹配：设备类型必须与翅片冲压类型完全匹配
+2. 翅片长度限制：翅片长度不能超过设备的最大加工长度
+3. 翅片类型限制：如果设备配置了允许的翅片类型，翅片类型必须在列表中
+4. 翅片高度限制：如果设备配置了允许的翅片高度，翅片高度必须在列表中
+5. 波距范围限制：翅片波距必须在设备的加工范围内（min_fin_pitch <= pitch <= max_fin_pitch）
+
+**软约束**:
+- 设备专业化优先：在多个设备都兼容的情况下，优先选择专业化设备
+
+参考文档：
+- @file:PunchSchedule/docs/04-约束规则说明.md
+
+### 模具约束
+
+**硬约束**:
+1. 翅片类型匹配：模具的翅片类型必须与任务要求完全匹配
+2. 波距精确匹配：模具的波距必须与翅片要求精确匹配
+3. 模具可用性：模具在使用时间段内不被其他任务占用
+
+**软约束**:
+- 整体模具优先：在多个模具都匹配的情况下，优先选择整体模具
+
+### 时间约束
+
+**硬约束**:
+1. 排产时间窗口：所有任务必须在排产时间范围内
+2. 休息时间跳过：任务执行时间自动跳过所有休息时间段
+3. 时间顺序约束：同一设备上前一任务结束时间 <= 后一任务开始时间
+4. 调模时间约束：调模任务必须在调模工的工作时间内
+
+**软约束**:
+- 计划开始时间优先：优先安排计划开始时间较早的任务
+
+### 人员约束
+
+**硬约束**:
+1. 班次时间限制：调模工只能在其班次时间内工作
+2. 同时性约束：一个调模工同一时间只能执行一个任务
+
+**软约束**:
+- 负载均衡：尽可能平均分配调模工的工作量
+
+## 排产算法
+
+系统采用四步递进式算法：
+
+1. **步骤0**: 初始化设备状态（处理排产开始时设备上正在进行的任务，建立初始状态）
+2. **步骤1**: 贪心填充相同规格任务（为每台设备连续填充与最后任务相同规格的翅片任务，最小化换模次数）
+3. **步骤2**: 调模排产（寻找可以通过调模继续生产的任务，在不换模具的情况下扩大排产范围）
+4. **步骤3**: 换模排产（为无法通过调模解决的任务寻找新模具，实现更大范围的排产）
+
+算法特点：
+- 递进式设计：从简单到复杂，逐步扩大排产范围
+- 贪心优化：每个步骤都追求局部最优
+- 资源协调：统筹考虑设备、模具、人员资源
+- 时间优化：最小化换模时间，最大化生产时间
+
+参考文档：
+- @file:PunchSchedule/docs/03-排产算法详解.md
+- @file:PunchSchedule/calc.py
+
+## 业务逻辑实现注意事项
+
+1. **事务管理**: 排产计算应在事务中执行，失败时回滚
+2. **性能优化**: 大量数据时使用批量查询，避免N+1问题
+3. **缓存策略**: 设备兼容性检查结果可以缓存
+4. **并发控制**: 排产计算时使用锁机制，避免并发修改
+5. **错误处理**: 详细的错误信息，便于诊断问题
+6. **日志记录**: 排产过程的关键步骤都要记录日志
+7. **数据验证**: 输入数据必须经过完整验证
+8. **时间处理**: 统一使用 datetime 对象，注意时区
+
+## 开发优先级建议
+
+1. **第一阶段**: 基础数据模型和CRUD接口（设备、模具、调模工、工单、翅片）
+2. **第二阶段**: 约束验证逻辑实现
+3. **第三阶段**: 排产算法核心实现（步骤0-3）
+4. **第四阶段**: 计划调整和优化功能
+5. **第五阶段**: 看板和报表接口
diff --git a/.cursor/rules/framework.mdc b/.cursor/rules/framework.mdc
new file mode 100644
index 0000000..8127bd8
--- /dev/null
+++ b/.cursor/rules/framework.mdc
@@ -0,0 +1,594 @@
+---
+alwaysApply: true
+---
+
+# 后端项目开发规范 (Flask + APIFlask)
+
+## 项目架构
+
+本项目基于 **Flask + APIFlask** 框架，使用以下技术栈：
+- **Web框架**: Flask + APIFlask (API文档自动生成)
+- **ORM**: SQLAlchemy
+- **数据库迁移**: Flask-Migrate (Alembic)
+- **认证**: Flask-JWT-Extended
+- **序列化**: Marshmallow
+- **限流**: Flask-Limiter
+- **缓存**: Flask-Caching
+- **事件系统**: 自定义事件总线
+
+参考文件：
+- @file:iti/app.py
+- @file:iti/applications/__init__.py
+- @file:iti/config.py
+
+## 项目结构
+
+```
+iti/applications/
+├── __init__.py           # 应用工厂函数
+├── common/               # 公共模块
+│   ├── crud.py          # CRUD 基础操作
+│   ├── enums.py         # 枚举定义
+│   ├── exceptions/      # 异常定义
+│   ├── utils/           # 工具函数
+│   └── storage/         # 文件存储
+├── models/              # 数据模型
+│   ├── schema/          # Schema 定义
+│   └── *.py            # 模型文件
+├── routes/              # 路由定义
+│   ├── sys/            # 系统管理路由
+│   └── schemas/        # 请求/响应 Schema
+├── service/            # 业务逻辑层
+├── extensions/         # 扩展初始化
+└── events/            # 事件处理器
+```
+
+## 代码规范
+
+### 1. 应用工厂模式
+
+使用应用工厂函数创建 Flask 应用：
+
+```python
+from iti.applications import create_app
+
+app = create_app(config_name='dev')
+```
+
+参考：
+- @file:iti/applications/__init__.py
+
+### 2. 配置管理规范
+
+#### 配置类继承结构
+```python
+class BaseConfig:
+    """基础配置类 - 所有环境共享的配置"""
+    # 基础配置项
+
+class DevConfig(BaseConfig):
+    """开发环境配置"""
+    DEBUG = True
+
+class ProdConfig(BaseConfig):
+    """生产环境配置"""
+    DEBUG = False
+```
+
+#### 环境变量加载
+- 使用 `python-dotenv` 加载 `.env` 文件
+- 优先级：`.env.local` > `.env.{FLASK_ENV}` > `.env`
+- 敏感配置必须使用环境变量
+
+参考：
+- @file:iti/config.py
+
+### 3. 数据模型规范
+
+#### 模型基类
+所有模型继承 `BaseModelMixin`：
+
+```python
+from iti.applications.common.crud import BaseModelMixin
+from iti.applications.extensions import db
+
+class User(BaseModelMixin):
+    __tablename__ = "sys_user"
+    
+    username = db.Column(db.String(64), nullable=False, comment="用户名")
+    # 其他字段...
+```
+
+**BaseModelMixin 包含**:
+- `id`: UUID 主键（自动生成）
+- `created_at`: 创建时间
+- `updated_at`: 更新时间
+- `created_by`: 创建人
+- `updated_by`: 更新人
+- `remark`: 备注
+
+参考：
+- @file:iti/applications/common/crud.py
+- @file:iti/applications/models/sys_user.py
+
+#### 模型关系定义
+```python
+# 多对多关系
+roles = db.relationship(
+    "Role",
+    secondary="sys_user_role",
+    back_populates="users",
+)
+
+# 一对多关系
+children = db.relationship(
+    "SysDept",
+    backref="parent",
+    lazy="dynamic",
+)
+```
+
+### 4. Schema 序列化规范
+
+#### Schema 定义
+使用 Marshmallow Schema 进行序列化/反序列化：
+
+```python
+from iti.applications.common.utils import BaseSchema
+from apiflask.fields import String, DateTime, Enum, Nested
+
+class UserSchema(BaseSchema):
+    id = String()
+    username = String()
+    created_at = DateTime(data_key="createdAt", format="%Y-%m-%d %H:%M:%S")
+    
+    # 关系字段
+    roles = Nested("RoleSchema", many=True, dump_only=True)
+```
+
+**命名规范**:
+- 响应字段使用 camelCase（通过 `data_key` 转换）
+- 时间字段格式：`%Y-%m-%d %H:%M:%S`
+
+参考：
+- @file:iti/applications/models/sys_user.py
+
+### 5. 路由定义规范
+
+#### Blueprint 创建
+使用 APIFlask 的 APIBlueprint：
+
+```python
+from apiflask import APIBlueprint
+from iti.applications.common.utils import success
+from iti.applications.extensions import db
+
+bp = APIBlueprint("module_name", __name__, url_prefix="/api/xxx", tag="模块.子模块")
+```
+
+#### 路由装饰器
+```python
+@bp.post("/create")
+@bp.input(CreateRequest.Schema, location="json")
+@bp.output(ResponseSchema)
+@jwt_required()
+@sys_log(name="创建", desc="创建xxx", type=LogType.OPERATION)
+def create(json_data: CreateRequest):
+    """创建资源"""
+    # 业务逻辑
+    return success(data, message="创建成功")
+```
+
+**装饰器顺序**:
+1. `@bp.method("/path")` - 路由定义
+2. `@bp.input()` - 请求验证
+3. `@bp.output()` - 响应定义
+4. `@jwt_required()` - 认证
+5. `@sys_log()` - 日志记录
+6. `@limiter.limit()` - 限流（如需要）
+
+参考：
+- @file:iti/applications/routes/sys/auth.py
+- @file:iti/applications/routes/__init__.py
+
+### 6. 请求/响应 Schema 规范
+
+#### 请求 Schema
+```python
+from apiflask.fields import String, Integer
+from marshmallow import validate
+
+class CreateRequest(ma.Schema):
+    username = String(
+        required=True,
+        validate=validate.Length(min=3, max=64),
+        metadata={"description": "用户名"}
+    )
+    email = String(
+        validate=validate.Email(),
+        metadata={"description": "邮箱"}
+    )
+```
+
+#### 响应 Schema
+使用模型 Schema 或自定义 Schema：
+
+```python
+@bp.output(UserSchema)
+# 或
+@bp.output(ma.Schema)
+```
+
+### 7. 业务逻辑层规范
+
+#### Service 层职责
+- 复杂的业务逻辑处理
+- 跨模型的操作
+- 缓存逻辑
+- 外部服务调用
+
+#### Service 文件组织
+```python
+# service/sys_user.py
+from iti.applications.models import User
+from iti.applications.extensions import db
+
+def get_user_by_id(user_id: str) -> User:
+    """根据ID获取用户"""
+    return db.session.scalar(select(User).filter_by(id=user_id))
+
+def create_user(data: dict) -> User:
+    """创建用户"""
+    user = User(**data)
+    db.session.add(user)
+    db.session.commit()
+    return user
+```
+
+参考：
+- @file:iti/applications/service/sys_config.py
+
+### 8. 异常处理规范
+
+#### 业务异常
+使用 `BizException` 抛出业务异常：
+
+```python
+from iti.applications.common.exceptions.biz_exp import BizException
+
+if user is None:
+    raise BizException("用户不存在")
+```
+
+#### 异常响应格式
+异常会自动转换为 JSON 响应：
+```json
+{
+  "code": 400,
+  "message": "用户不存在",
+  "detail": {}
+}
+```
+
+参考：
+- @file:iti/applications/common/exceptions/biz_exp.py
+- @file:iti/applications/extensions/error_handler.py
+
+### 9. 数据库操作规范
+
+#### 查询操作
+使用 SQLAlchemy 2.0 风格：
+
+```python
+from sqlalchemy import select
+
+# 单条查询
+user = db.session.scalar(select(User).filter_by(id=user_id))
+
+# 多条查询
+users = db.session.scalars(select(User).filter_by(status="enabled")).all()
+
+# 关联查询
+user = db.session.scalar(
+    select(User)
+    .filter_by(id=user_id)
+    .options(joinedload(User.roles))
+)
+```
+
+#### 事务处理
+```python
+try:
+    db.session.add(user)
+    db.session.commit()
+except Exception as e:
+    db.session.rollback()
+    raise BizException("创建失败")
+```
+
+### 10. 认证和授权规范
+
+#### JWT 认证
+使用 `@jwt_required()` 装饰器：
+
+```python
+from flask_jwt_extended import jwt_required, current_user
+
+@bp.get("/profile")
+@jwt_required()
+def get_profile():
+    """获取当前用户信息"""
+    return success(current_user)
+```
+
+#### 权限检查
+使用 `@permission_required()` 装饰器：
+
+```python
+from iti.applications.common.permission import permission_required
+
+@bp.delete("/delete")
+@jwt_required()
+@permission_required("sys:user:delete")
+def delete_user(user_id: str):
+    """删除用户"""
+    # 业务逻辑
+```
+
+参考：
+- @file:iti/applications/common/permission.py
+
+### 11. 日志记录规范
+
+#### 系统日志装饰器
+使用 `@sys_log()` 装饰器记录操作日志：
+
+```python
+from iti.applications.extensions import sys_log
+from iti.applications.common.enums import LogType
+
+@sys_log(
+    name="创建用户",
+    desc="创建新用户",
+    type=LogType.OPERATION,
+    save_db=True,
+    execute_time=True,
+)
+def create_user():
+    # 业务逻辑
+```
+
+参考：
+- @file:iti/applications/extensions/sys_log.py
+
+### 12. 限流规范
+
+#### 限流装饰器
+使用 `@limiter.limit()` 装饰器：
+
+```python
+from iti.applications.extensions.limit import limiter
+
+@bp.post("/sendCode")
+@limiter.limit(limit_value="2 per minute")
+def send_code():
+    """发送验证码"""
+    # 业务逻辑
+```
+
+参考：
+- @file:iti/applications/extensions/limit.py
+
+### 13. 缓存使用规范
+
+#### 缓存装饰器
+```python
+from iti.applications.extensions import cache_simple
+
+@cache_simple.cached(timeout=300, key_prefix="user_")
+def get_user_info(user_id: str):
+    """获取用户信息（带缓存）"""
+    return db.session.scalar(select(User).filter_by(id=user_id))
+```
+
+#### 手动缓存操作
+```python
+cache_simple.set(key="cache_key", value=data, timeout=300)
+cached_data = cache_simple.get(key="cache_key")
+cache_simple.delete(key="cache_key")
+```
+
+参考：
+- @file:iti/applications/extensions/cache.py
+
+### 14. 文件存储规范
+
+#### 文件上传
+使用统一的文件存储接口：
+
+```python
+from iti.applications.common.storage.manager import storage_manager
+
+file_url = storage_manager.save(
+    file=request.files['file'],
+    folder="uploads",
+    filename="custom_name.jpg"
+)
+```
+
+参考：
+- @file:iti/applications/common/storage/manager.py
+
+### 15. 事件系统规范
+
+#### 事件定义
+在 `common/events.py` 中定义事件：
+
+```python
+class UserEvents(Enum):
+    USER_REGISTERED = "user.registered"
+    USER_LOGGED_IN = "user.logged_in"
+```
+
+#### 事件触发
+```python
+from iti.applications.extensions import eventbus
+from iti.applications.common.events import UserEvents
+
+eventbus.emit(UserEvents.USER_REGISTERED.value, user)
+```
+
+#### 事件处理
+在 `events/` 目录创建事件处理器：
+
+```python
+from iti.applications.extensions.eventbus import event_handler
+
+@event_handler("user.registered")
+def on_user_registered(user, **kwargs):
+    """用户注册事件处理"""
+    # 处理逻辑
+```
+
+参考：
+- @file:iti/applications/common/events.py
+- @file:iti/applications/events/user_cache_event_handler.py
+
+### 16. 数据库迁移规范
+
+#### 创建迁移
+```bash
+flask db migrate -m "描述信息"
+```
+
+#### 执行迁移
+```bash
+flask db upgrade
+```
+
+#### 回滚迁移
+```bash
+flask db downgrade
+```
+
+参考：
+- @file:migrations/README
+
+### 17. 响应格式规范
+
+#### 成功响应
+使用 `success()` 函数：
+
+```python
+from iti.applications.common.utils import success
+
+return success(data, message="操作成功")
+```
+
+响应格式：
+```json
+{
+  "code": 200,
+  "data": {...},
+  "message": "操作成功"
+}
+```
+
+#### 错误响应
+通过异常自动处理，或手动返回：
+
+```python
+from iti.applications.common.utils import error
+
+return error(message="错误信息", code=400)
+```
+
+### 18. 枚举定义规范
+
+在 `common/enums.py` 中定义枚举：
+
+```python
+from enum import Enum
+
+class StatusEnum(str, Enum):
+    ENABLED = "enabled"
+    DISABLED = "disabled"
+```
+
+在模型中使用：
+```python
+status = db.Column(
+    db.Enum(StatusEnum, values_callable=lambda x: [e.value for e in x]),
+    nullable=False,
+    default=StatusEnum.ENABLED.value,
+)
+```
+
+参考：
+- @file:iti/applications/common/enums.py
+
+### 19. 工具函数规范
+
+#### 通用工具
+放在 `common/utils/` 目录：
+- `http.py`: HTTP 响应工具
+- `validate.py`: 验证工具
+- `cache.py`: 缓存工具
+- `tree.py`: 树形结构工具
+
+参考：
+- @file:iti/applications/common/utils/http.py
+
+### 20. API 文档规范
+
+#### 自动生成文档
+APIFlask 自动生成 API 文档，访问：
+- Swagger UI: `/docs`
+- ReDoc: `/docs`
+- Elements: `/docs` (默认)
+
+#### 文档注解
+使用 docstring 和 metadata：
+
+```python
+@bp.post("/create")
+@bp.input(CreateRequest.Schema, location="json")
+def create(json_data: CreateRequest):
+    """
+    创建资源
+    
+    这是创建资源的接口，用于...
+    """
+    # 业务逻辑
+```
+
+## 开发注意事项
+
+1. **事务管理**: 确保数据库操作在事务中，异常时回滚
+2. **N+1 查询**: 使用 `joinedload` 或 `selectinload` 避免 N+1 问题
+3. **SQL 注入**: 使用参数化查询，不要拼接 SQL
+4. **性能优化**: 合理使用缓存，避免重复查询
+5. **错误处理**: 所有异常都要有适当的处理，不要暴露敏感信息
+6. **日志记录**: 重要操作都要记录日志，便于排查问题
+7. **类型提示**: 使用 Type Hints 提高代码可读性
+8. **代码复用**: 公共逻辑提取到 service 或 utils
+
+## 测试规范
+
+### 单元测试
+- 测试文件放在 `tests/` 目录
+- 测试文件命名：`test_*.py`
+- 使用 pytest 框架
+
+### 测试示例
+```python
+def test_create_user(client):
+    response = client.post('/api/user', json={
+        'username': 'test',
+        'email': 'test@example.com'
+    })
+    assert response.status_code == 200
+```
+
+参考：
+- @file:tests/test_http_utils.py