docs: add cell storage protocol modules design for 2.2.6–2.2.10

Co-authored-by: Cursor <cursoragent@cursor.com>

backend/app/crud/express_company.py

@@ -0,0 +1,156 @@
+"""快递公司 CRUD（biz_express_company）"""
+from __future__ import annotations
+
+import math
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+from sqlalchemy import and_, func, or_
+from sqlalchemy.orm import Session
+
+from app.core.utils import generate_uuid
+from app.models.models import BizExpressCompany
+
+
+def _row_to_dict(e: BizExpressCompany) -> Dict[str, Any]:
+    return {
+        "id": e.id,
+        "expressCode": e.express_code,
+        "expressName": e.express_name,
+        "tenantNo": e.tenant_no,
+        "orderNum": e.order_num if e.order_num is not None else 0,
+        "remark": e.remark or "",
+        "createTime": e.create_time.strftime("%Y-%m-%d %H:%M:%S") if e.create_time else "",
+        "updateTime": e.update_time.strftime("%Y-%m-%d %H:%M:%S") if e.update_time else "",
+    }
+
+
+def list_express_companies(
+    db: Session,
+    *,
+    page: int = 1,
+    page_size: int = 10,
+    keyword: Optional[str] = None,
+    tenant_no: Optional[str] = None,
+) -> Tuple[List[Dict[str, Any]], int]:
+    def _filtered():
+        q0 = db.query(BizExpressCompany).filter(BizExpressCompany.del_flag == 0)
+        if tenant_no:
+            q0 = q0.filter(BizExpressCompany.tenant_no == tenant_no)
+        kw = (keyword or "").strip()
+        if kw:
+            like = f"%{kw}%"
+            q0 = q0.filter(or_(BizExpressCompany.express_code.like(like), BizExpressCompany.express_name.like(like)))
+        return q0
+
+    total = _filtered().order_by(None).with_entities(func.count(BizExpressCompany.id)).scalar() or 0
+    page = max(1, page)
+    page_size = min(max(1, page_size), 100)
+    rows = (
+        _filtered()
+        .order_by(BizExpressCompany.order_num.asc(), BizExpressCompany.create_time.desc())
+        .offset((page - 1) * page_size)
+        .limit(page_size)
+        .all()
+    )
+    return [_row_to_dict(x) for x in rows], int(total)
+
+
+def get_express_company(db: Session, company_id: str) -> Optional[BizExpressCompany]:
+    return (
+        db.query(BizExpressCompany)
+        .filter(and_(BizExpressCompany.id == company_id, BizExpressCompany.del_flag == 0))
+        .first()
+    )
+
+
+def express_code_exists(db: Session, code: str, tenant_no: str, exclude_id: Optional[str] = None) -> bool:
+    q = db.query(BizExpressCompany).filter(and_(BizExpressCompany.express_code == code.strip(), BizExpressCompany.tenant_no == tenant_no, BizExpressCompany.del_flag == 0))
+    if exclude_id:
+        q = q.filter(BizExpressCompany.id != exclude_id)
+    return q.first() is not None
+
+
+def create_express_company(
+    db: Session,
+    *,
+    express_code: str,
+    express_name: str,
+    tenant_no: str = "zkxw",
+    order_num: Optional[int] = None,
+    remark: Optional[str] = None,
+    user_id: Optional[str] = None,
+) -> BizExpressCompany:
+    ec = (express_code or "").strip()
+    if not ec:
+        raise ValueError("快递公司编码不能为空")
+    if express_code_exists(db, ec, tenant_no):
+        raise ValueError("快递公司编码已存在")
+    obj = BizExpressCompany(
+        id=generate_uuid(),
+        express_code=ec,
+        express_name=(express_name or "").strip() or ec,
+        tenant_no=tenant_no,
+        order_num=order_num if order_num is not None else 0,
+        remark=(remark or "").strip() or None,
+        create_by=user_id,
+        create_dept_id="",
+        create_time=datetime.now(),
+        update_by=user_id,
+        update_time=datetime.now(),
+        del_flag=0,
+    )
+    db.add(obj)
+    db.commit()
+    db.refresh(obj)
+    return obj
+
+
+def update_express_company(
+    db: Session,
+    company_id: str,
+    *,
+    express_code: Optional[str] = None,
+    express_name: Optional[str] = None,
+    order_num: Optional[int] = None,
+    remark: Optional[str] = None,
+    user_id: Optional[str] = None,
+) -> BizExpressCompany:
+    obj = get_express_company(db, company_id)
+    if not obj:
+        raise ValueError("快递公司不存在")
+    if express_code is not None:
+        new_code = express_code.strip()
+        if not new_code:
+            raise ValueError("快递公司编码不能为空")
+        if new_code != obj.express_code and express_code_exists(db, new_code, obj.tenant_no, exclude_id=company_id):
+            raise ValueError("快递公司编码已存在")
+        obj.express_code = new_code
+    if express_name is not None:
+        obj.express_name = (express_name or "").strip() or obj.express_name
+    if order_num is not None:
+        obj.order_num = order_num
+    if remark is not None:
+        obj.remark = (remark or "").strip() or None
+    obj.update_by = user_id
+    obj.update_time = datetime.now()
+    db.add(obj)
+    db.commit()
+    db.refresh(obj)
+    return obj
+
+
+def soft_delete_express_company(db: Session, company_id: str) -> None:
+    obj = get_express_company(db, company_id)
+    if not obj:
+        raise ValueError("快递公司不存在")
+    obj.del_flag = 1
+    obj.update_time = datetime.now()
+    db.add(obj)
+    db.commit()
+
+
+def total_pages(total: int, page_size: int) -> int:
+    if total <= 0:
+        return 0
+    return int(math.ceil(total / float(page_size)))