v0.2.0: CRM/ERP 系统升级 - 清理 .gitignore 并移除误提交的 venv/env/db 文件

- 更新 .gitignore：全面覆盖环境变量、数据库、日志、缓存、上传文件
- 移除误跟踪的 server/venv/、crm_data.db、.env 文件
- 新增 server/.env.example 模板
- 新增合同管理、利润核算、AI教练等功能模块
- 新增 Playwright e2e 测试套件
- 前后端多项功能升级和 bug 修复

server/tests/__init__.py

@@ -0,0 +1 @@
+# tests package

server/tests/api/__init__.py

@@ -0,0 +1 @@
+# tests/api package

server/tests/api/test_auth.py

@@ -0,0 +1,89 @@
+"""
+鉴权模块测试 —— /api/auth
+覆盖: 登录 / me / 改密 / Token 校验 / 错误场景
+"""
+import pytest
+from httpx import AsyncClient
+from tests.conftest import make_auth_headers, ADMIN_USER_ID, SALES_USER_ID
+
+
+class TestLogin:
+    """POST /api/auth/login"""
+
+    async def test_login_success(self, client: AsyncClient, seed_data):
+        """正确账密 → 200 + access_token"""
+        resp = await client.post("/api/auth/login", json={
+            "username": "admin", "password": "admin123"
+        })
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["code"] == 200
+        assert "access_token" in body["data"]
+        assert body["message"] == "登录成功"
+
+    async def test_login_wrong_password(self, client: AsyncClient, seed_data):
+        """错误密码 → 401"""
+        resp = await client.post("/api/auth/login", json={
+            "username": "admin", "password": "wrongpass"
+        })
+        assert resp.status_code == 401
+        assert "密码错误" in resp.json()["message"]
+
+    async def test_login_nonexistent_user(self, client: AsyncClient, seed_data):
+        """不存在的用户 → 401"""
+        resp = await client.post("/api/auth/login", json={
+            "username": "nobody", "password": "123456"
+        })
+        assert resp.status_code == 401
+
+    async def test_login_empty_fields(self, client: AsyncClient, seed_data):
+        """空字段 → 422 参数校验失败"""
+        resp = await client.post("/api/auth/login", json={
+            "username": "", "password": ""
+        })
+        assert resp.status_code == 422
+
+
+class TestGetMe:
+    """GET /api/auth/me"""
+
+    async def test_me_success(self, client: AsyncClient, admin_headers):
+        """合法 Token → 200 + 用户信息"""
+        resp = await client.get("/api/auth/me", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert data["username"] == "admin"
+        assert data["data_scope"] == "all"
+
+    async def test_me_no_token(self, client: AsyncClient, seed_data):
+        """无 Token → 422 (Header 缺失)"""
+        resp = await client.get("/api/auth/me")
+        assert resp.status_code == 422
+
+    async def test_me_invalid_token(self, client: AsyncClient, seed_data):
+        """伪造 Token → 401"""
+        resp = await client.get("/api/auth/me", headers={
+            "Authorization": "Bearer fake-token-xxx"
+        })
+        assert resp.status_code == 401
+
+
+class TestChangePassword:
+    """PUT /api/auth/password"""
+
+    async def test_change_password_success(self, client: AsyncClient, admin_headers):
+        """正确旧密码 + 合法新密码 → 200"""
+        resp = await client.put("/api/auth/password", headers=admin_headers, json={
+            "old_password": "admin123",
+            "new_password": "newpass999"
+        })
+        assert resp.status_code == 200
+        assert "密码修改成功" in resp.json()["message"]
+
+    async def test_change_password_wrong_old(self, client: AsyncClient, admin_headers):
+        """旧密码错误 → 400"""
+        resp = await client.put("/api/auth/password", headers=admin_headers, json={
+            "old_password": "wrongold",
+            "new_password": "newpass999"
+        })
+        assert resp.status_code == 400

server/tests/api/test_companies.py

@@ -0,0 +1,49 @@
+"""
+公司管理测试 —— /api/companies
+覆盖: 公司列表 / 当前公司详情 / 更新公司信息 / 权限
+"""
+import pytest
+from httpx import AsyncClient
+from tests.conftest import COMPANY_ID
+
+
+class TestCompanyList:
+    """GET /api/companies"""
+
+    async def test_list_companies(self, client: AsyncClient, admin_headers):
+        """管理员获取公司列表 → 200"""
+        resp = await client.get("/api/companies", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert "companies" in data
+        assert len(data["companies"]) >= 1
+        assert data["companies"][0]["code"] == "TEST-CO"
+
+
+class TestCurrentCompany:
+    """GET /api/companies/current"""
+
+    async def test_get_current_company(self, client: AsyncClient, admin_headers):
+        """获取当前公司详情 → 200"""
+        resp = await client.get("/api/companies/current", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert data["name"] == "测试润滑油有限公司"
+
+
+class TestUpdateCompany:
+    """PUT /api/companies/current"""
+
+    async def test_admin_update_company(self, client: AsyncClient, admin_headers):
+        """管理员更新公司信息 → 200"""
+        resp = await client.put("/api/companies/current", headers=admin_headers, json={
+            "full_info": {"full_name": "天津测试润滑油有限公司-改", "tax_id": "91120000XXXX"}
+        })
+        assert resp.status_code == 200
+
+    async def test_sales_update_company_forbidden(self, client: AsyncClient, sales_headers):
+        """普通销售更新公司 → 403"""
+        resp = await client.put("/api/companies/current", headers=sales_headers, json={
+            "full_info": {"full_name": "hack"}
+        })
+        assert resp.status_code == 403

server/tests/api/test_contacts.py

@@ -0,0 +1,76 @@
+"""
+联系人模块测试 —— /api/customers/{cid}/contacts & /api/contacts/{id}
+覆盖: CRUD 完整链路
+"""
+import uuid
+import pytest
+from httpx import AsyncClient
+from tests.conftest import CUSTOMER_ID
+
+
+class TestContactsCRUD:
+    """联系人 CRUD 全链路"""
+
+    async def test_list_contacts_empty(self, client: AsyncClient, admin_headers):
+        """初始无联系人 → 200 + 空数组"""
+        resp = await client.get(
+            f"/api/customers/{CUSTOMER_ID}/contacts",
+            headers=admin_headers
+        )
+        assert resp.status_code == 200
+        assert isinstance(resp.json()["data"], list)
+
+    async def test_create_contact(self, client: AsyncClient, admin_headers):
+        """新增联系人 → 200"""
+        resp = await client.post(
+            f"/api/customers/{CUSTOMER_ID}/contacts",
+            headers=admin_headers,
+            json={"name": "王采购", "phone": "13700137000", "title": "采购总监"}
+        )
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert data["name"] == "王采购"
+        return data.get("id")
+
+    async def test_create_and_update_contact(self, client: AsyncClient, admin_headers):
+        """新增后编辑联系人 → 200"""
+        # 新增
+        create_resp = await client.post(
+            f"/api/customers/{CUSTOMER_ID}/contacts",
+            headers=admin_headers,
+            json={"name": "临时联系人", "phone": "10000"}
+        )
+        assert create_resp.status_code == 200
+        contact_id = create_resp.json()["data"]["id"]
+
+        # 编辑
+        update_resp = await client.put(
+            f"/api/contacts/{contact_id}",
+            headers=admin_headers,
+            json={"name": "正式联系人", "title": "技术经理"}
+        )
+        assert update_resp.status_code == 200
+
+    async def test_create_and_delete_contact(self, client: AsyncClient, admin_headers):
+        """新增后删除联系人 → 200"""
+        create_resp = await client.post(
+            f"/api/customers/{CUSTOMER_ID}/contacts",
+            headers=admin_headers,
+            json={"name": "待删联系人"}
+        )
+        contact_id = create_resp.json()["data"]["id"]
+
+        del_resp = await client.delete(
+            f"/api/contacts/{contact_id}",
+            headers=admin_headers
+        )
+        assert del_resp.status_code == 200
+
+    async def test_create_contact_no_name(self, client: AsyncClient, admin_headers):
+        """缺少 name → 422"""
+        resp = await client.post(
+            f"/api/customers/{CUSTOMER_ID}/contacts",
+            headers=admin_headers,
+            json={"phone": "123"}
+        )
+        assert resp.status_code == 422

server/tests/api/test_contracts.py

@@ -0,0 +1,86 @@
+"""
+合同管理模块测试 —— /api/contracts
+覆盖: CRUD / 一键推单 / Word 生成 / 上传盖章版
+"""
+import uuid
+import pytest
+from httpx import AsyncClient
+from tests.conftest import (
+    make_auth_headers, ADMIN_USER_ID,
+    COMPANY_ID, CUSTOMER_ID, SKU_ID,
+)
+
+
+class TestCreateContract:
+    """POST /api/contracts"""
+
+    @pytest.mark.xfail(reason="SQLite 嵌套事务 + selectin lazy load 导致 MissingGreenlet，需 PG 环境")
+    async def test_create_contract_success(self, client: AsyncClient, admin_headers):
+        """创建合同（含明细行） → 200"""
+        resp = await client.post("/api/contracts", headers=admin_headers, json={
+            "buyer_customer_id": str(CUSTOMER_ID),
+            "payment_terms": "货到付全款",
+            "shipping_terms": "买方自提",
+            "items": [
+                {"sku_id": str(SKU_ID), "qty": 20, "unit_price": 260.00, "sub_total": 5200.00}
+            ],
+            "remark": "测试合同"
+        })
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert "contract_no" in data
+        assert float(data["total_amount_excl_tax"]) > 0
+
+    async def test_create_contract_no_items(self, client: AsyncClient, admin_headers):
+        """空明细 → 应失败"""
+        resp = await client.post("/api/contracts", headers=admin_headers, json={
+            "buyer_customer_id": str(CUSTOMER_ID),
+            "payment_terms": "货到付全款",
+            "shipping_terms": "买方自提",
+            "items": []
+        })
+        assert resp.status_code in (400, 422)
+
+
+class TestListContracts:
+    """GET /api/contracts"""
+
+    async def test_list_contracts(self, client: AsyncClient, admin_headers):
+        """合同列表 → 200"""
+        resp = await client.get("/api/contracts", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert "total" in data
+
+
+class TestContractDetail:
+    """GET /api/contracts/{id}"""
+
+    async def test_get_nonexistent_contract(self, client: AsyncClient, admin_headers):
+        """不存在的合同 → 404"""
+        fake_id = uuid.uuid4()
+        resp = await client.get(f"/api/contracts/{fake_id}", headers=admin_headers)
+        assert resp.status_code == 404
+
+
+class TestDeleteContract:
+    """DELETE /api/contracts/{id}"""
+
+    async def test_delete_nonexistent(self, client: AsyncClient, admin_headers):
+        """删除不存在的合同 → 应失败"""
+        fake_id = uuid.uuid4()
+        resp = await client.delete(f"/api/contracts/{fake_id}", headers=admin_headers)
+        assert resp.status_code in (404, 500)
+
+
+class TestGenerateOrderFromContract:
+    """POST /api/contracts/{id}/generate-order"""
+
+    async def test_generate_order_nonexistent(self, client: AsyncClient, admin_headers):
+        """不存在的合同推单 → 404"""
+        fake_id = uuid.uuid4()
+        resp = await client.post(
+            f"/api/contracts/{fake_id}/generate-order",
+            headers=admin_headers
+        )
+        assert resp.status_code in (404, 500)

server/tests/api/test_customers.py

@@ -0,0 +1,144 @@
+"""
+客户管理模块测试 —— /api/customers
+覆盖: CRUD / 搜索 / 归档恢复 / 转移 / 数据权限隔离
+"""
+import uuid
+import pytest
+from httpx import AsyncClient
+from tests.conftest import (
+    make_auth_headers, ADMIN_USER_ID, SALES_USER_ID,
+    COMPANY_ID, CUSTOMER_ID,
+)
+
+
+class TestCreateCustomer:
+    """POST /api/customers"""
+
+    async def test_create_customer_success(self, client: AsyncClient, admin_headers):
+        """正常创建客户 → 200"""
+        resp = await client.post("/api/customers", headers=admin_headers, json={
+            "name": "新客户测试公司",
+            "level": "B",
+            "industry": "制造业",
+            "contact": "李经理",
+            "phone": "13900139000",
+        })
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert data["name"] == "新客户测试公司"
+        assert data["level"] == "B"
+
+    async def test_create_customer_minimal(self, client: AsyncClient, admin_headers):
+        """仅必填字段（name） → 200"""
+        resp = await client.post("/api/customers", headers=admin_headers, json={
+            "name": "最简客户",
+        })
+        assert resp.status_code == 200
+
+    async def test_create_customer_no_auth(self, client: AsyncClient, seed_data):
+        """无认证 → 422"""
+        resp = await client.post("/api/customers", json={"name": "test"})
+        assert resp.status_code == 422
+
+
+class TestListCustomers:
+    """GET /api/customers"""
+
+    async def test_list_customers_success(self, client: AsyncClient, admin_headers):
+        """管理员列表 → 200 + 包含种子客户"""
+        resp = await client.get("/api/customers", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert data["total"] >= 1
+        assert len(data["items"]) >= 1
+
+    async def test_list_customers_with_level_filter(self, client: AsyncClient, admin_headers):
+        """等级筛选 level=A → 只返回A级"""
+        resp = await client.get("/api/customers?level=A", headers=admin_headers)
+        assert resp.status_code == 200
+        for item in resp.json()["data"]["items"]:
+            assert item["level"] == "A"
+
+    async def test_list_customers_keyword_search(self, client: AsyncClient, admin_headers):
+        """关键词搜索 → 模糊匹配"""
+        resp = await client.get("/api/customers?keyword=中石化", headers=admin_headers)
+        assert resp.status_code == 200
+
+    async def test_list_customers_pagination(self, client: AsyncClient, admin_headers):
+        """分页参数 page=1&size=5 → 正常分页"""
+        resp = await client.get("/api/customers?page=1&size=5", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert "total" in data
+        assert "items" in data
+
+
+class TestGetCustomer:
+    """GET /api/customers/{id}"""
+
+    async def test_get_customer_success(self, client: AsyncClient, admin_headers):
+        """获取种子客户 → 200"""
+        resp = await client.get(f"/api/customers/{CUSTOMER_ID}", headers=admin_headers)
+        assert resp.status_code == 200
+        assert resp.json()["data"]["name"] == "中石化天津分公司"
+
+    async def test_get_customer_not_found(self, client: AsyncClient, admin_headers):
+        """不存在的 UUID → 404"""
+        fake_id = uuid.uuid4()
+        resp = await client.get(f"/api/customers/{fake_id}", headers=admin_headers)
+        assert resp.status_code == 404
+
+
+class TestUpdateCustomer:
+    """PUT /api/customers/{id}"""
+
+    async def test_update_customer_success(self, client: AsyncClient, admin_headers):
+        """更新客户等级 → 200"""
+        resp = await client.put(f"/api/customers/{CUSTOMER_ID}", headers=admin_headers, json={
+            "level": "B",
+            "industry": "化学工业",
+        })
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert data["level"] == "B"
+
+
+class TestDeleteAndRestore:
+    """DELETE + PUT /restore"""
+
+    async def test_delete_customer(self, client: AsyncClient, admin_headers):
+        """软删除 → 200"""
+        resp = await client.delete(f"/api/customers/{CUSTOMER_ID}", headers=admin_headers)
+        assert resp.status_code == 200
+        assert "归档" in resp.json()["message"]
+
+    async def test_restore_customer(self, client: AsyncClient, admin_headers):
+        """恢复归档 → 200"""
+        # 先归档
+        await client.delete(f"/api/customers/{CUSTOMER_ID}", headers=admin_headers)
+        # 再恢复
+        resp = await client.put(f"/api/customers/{CUSTOMER_ID}/restore", headers=admin_headers)
+        assert resp.status_code == 200
+
+
+class TestSearchCustomer:
+    """GET /api/customers/search"""
+
+    async def test_search_success(self, client: AsyncClient, admin_headers):
+        """搜索 q=中石化 → 返回匹配结果"""
+        resp = await client.get("/api/customers/search?q=中石化", headers=admin_headers)
+        assert resp.status_code == 200
+
+
+class TestTransferCustomer:
+    """PUT /api/customers/{id}/transfer"""
+
+    async def test_transfer_success(self, client: AsyncClient, admin_headers):
+        """管理员转移客户 → 200"""
+        resp = await client.put(
+            f"/api/customers/{CUSTOMER_ID}/transfer",
+            headers=admin_headers,
+            json={"new_owner_id": str(ADMIN_USER_ID)}
+        )
+        assert resp.status_code == 200
+        assert "转移成功" in resp.json()["message"]

server/tests/api/test_dashboard.py

@@ -0,0 +1,24 @@
+"""
+Dashboard 统计测试 —— /api/dashboard
+"""
+import pytest
+from httpx import AsyncClient
+
+
+class TestDashboardStats:
+    """GET /api/dashboard/stats"""
+
+    async def test_get_stats(self, client: AsyncClient, admin_headers):
+        """工作台统计 → 200 + 有 4 个统计项"""
+        resp = await client.get("/api/dashboard/stats", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert "orders_count" in data
+        assert "pending_shipping" in data
+        assert "warning_skus" in data
+        assert "monthly_revenue" in data
+
+    async def test_stats_no_auth(self, client: AsyncClient, seed_data):
+        """无认证 → 422"""
+        resp = await client.get("/api/dashboard/stats")
+        assert resp.status_code == 422

server/tests/api/test_finance.py

@@ -0,0 +1,51 @@
+"""
+财务票据模块测试 —— /api/finance
+覆盖: 票据入池 / 列表 / 作废 / 报销单 CRUD / 审批
+"""
+import uuid
+import pytest
+from httpx import AsyncClient
+from tests.conftest import ADMIN_USER_ID, COMPANY_ID
+
+
+class TestInvoicePool:
+    """票据池 CRUD"""
+
+    async def test_create_invoice(self, client: AsyncClient, admin_headers):
+        """票据入池 → 200"""
+        resp = await client.post("/api/finance/invoices", headers=admin_headers, json={
+            "merchant_name": "加油站发票",
+            "amount": 500.00,
+            "invoice_date": "2026-03-15",
+            "type": "expense",
+            "ai_extracted_data": {"invoice_code": "12345678"},
+        })
+        assert resp.status_code == 200
+
+    async def test_list_invoices(self, client: AsyncClient, admin_headers):
+        """票据列表 → 200"""
+        resp = await client.get("/api/finance/invoices", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert "total" in data
+
+    async def test_void_nonexistent_invoice(self, client: AsyncClient, admin_headers):
+        """作废不存在的票据 → 404"""
+        fake_id = uuid.uuid4()
+        resp = await client.delete(f"/api/finance/invoices/{fake_id}", headers=admin_headers)
+        assert resp.status_code in (404, 500)
+
+
+class TestExpenses:
+    """报销单"""
+
+    async def test_list_expenses(self, client: AsyncClient, admin_headers):
+        """报销单列表 → 200"""
+        resp = await client.get("/api/finance/expenses", headers=admin_headers)
+        assert resp.status_code == 200
+
+    async def test_get_nonexistent_expense(self, client: AsyncClient, admin_headers):
+        """不存在的报销单 → 404"""
+        fake_id = uuid.uuid4()
+        resp = await client.get(f"/api/finance/expenses/{fake_id}", headers=admin_headers)
+        assert resp.status_code in (404, 500)

server/tests/api/test_health.py

@@ -0,0 +1,16 @@
+"""
+健康检查 + 模板下载测试
+"""
+import pytest
+from httpx import AsyncClient
+
+
+class TestHealthCheck:
+    """GET /health"""
+
+    async def test_health_check(self, client: AsyncClient):
+        """健康检查 → 200"""
+        resp = await client.get("/health")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["status"] == "ok"

server/tests/api/test_orders.py

@@ -0,0 +1,104 @@
+"""
+订单管理模块测试 —— /api/orders
+覆盖: 创建订单 / 列表 / 详情 / 动态定价 / 收款 / 订单发票关联
+"""
+import uuid
+import pytest
+from httpx import AsyncClient
+from tests.conftest import (
+    make_auth_headers, ADMIN_USER_ID, SALES_USER_ID,
+    COMPANY_ID, CUSTOMER_ID, SKU_ID,
+)
+
+
+class TestCreateOrder:
+    """POST /api/orders"""
+
+    async def test_create_order_success(self, client: AsyncClient, admin_headers):
+        """创建含 1 个明细行的订单 → 200"""
+        resp = await client.post("/api/orders", headers=admin_headers, json={
+            "customer_id": str(CUSTOMER_ID),
+            "items": [
+                {"sku_id": str(SKU_ID), "qty": 10, "unit_price": 280.00}
+            ],
+            "remark": "测试订单",
+            "order_date": "2026-03-30"
+        })
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert "order_no" in data
+        assert float(data["total_amount"]) == 2800.00
+
+    async def test_create_order_no_items(self, client: AsyncClient, admin_headers):
+        """空明细 → 应失败（422 或 400）"""
+        resp = await client.post("/api/orders", headers=admin_headers, json={
+            "customer_id": str(CUSTOMER_ID),
+            "items": []
+        })
+        assert resp.status_code in (400, 422)
+
+    async def test_create_order_no_company_header(self, client: AsyncClient, seed_data):
+        """缺少 X-Company-Id → 422"""
+        headers = {"Authorization": f"Bearer {make_auth_headers(ADMIN_USER_ID)['Authorization'].split(' ')[1]}"}
+        resp = await client.post("/api/orders", headers=headers, json={
+            "customer_id": str(CUSTOMER_ID),
+            "items": [{"sku_id": str(SKU_ID), "qty": 1, "unit_price": 280}]
+        })
+        assert resp.status_code == 422
+
+
+class TestListOrders:
+    """GET /api/orders"""
+
+    async def test_list_orders_empty(self, client: AsyncClient, admin_headers):
+        """无订单时 → 200 + total=0"""
+        resp = await client.get("/api/orders", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert data["total"] >= 0
+
+    async def test_list_orders_with_filters(self, client: AsyncClient, admin_headers):
+        """带筛选条件 → 200"""
+        resp = await client.get(
+            "/api/orders?shipping_state=pending&payment_state=unpaid",
+            headers=admin_headers
+        )
+        assert resp.status_code == 200
+
+
+class TestOrderDetail:
+    """GET /api/orders/{id}"""
+
+    async def test_get_nonexistent_order(self, client: AsyncClient, admin_headers):
+        """不存在的订单 → 404"""
+        fake_id = uuid.uuid4()
+        resp = await client.get(f"/api/orders/{fake_id}", headers=admin_headers)
+        assert resp.status_code == 404
+
+
+class TestCalculatePrice:
+    """GET /api/orders/price/calculate"""
+
+    async def test_calculate_price(self, client: AsyncClient, admin_headers):
+        """动态定价查询 → 200"""
+        resp = await client.get(
+            f"/api/orders/price/calculate?customer_id={CUSTOMER_ID}&sku_id={SKU_ID}",
+            headers=admin_headers
+        )
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert "price" in data or "standard_price" in data or "unit_price" in data
+
+
+class TestOrderPayment:
+    """PUT /api/orders/{id}/payment"""
+
+    async def test_update_payment_nonexistent(self, client: AsyncClient, admin_headers):
+        """不存在的订单更新收款 → 404"""
+        fake_id = uuid.uuid4()
+        resp = await client.put(
+            f"/api/orders/{fake_id}/payment",
+            headers=admin_headers,
+            json={"paid_amount": 1000}
+        )
+        assert resp.status_code == 404

server/tests/api/test_products.py

@@ -0,0 +1,105 @@
+"""
+产品与库存模块测试 —— /api/products
+覆盖: 分类CRUD / SKU CRUD / 库存变更 / 库存流水
+"""
+import uuid
+import pytest
+from httpx import AsyncClient
+from tests.conftest import ADMIN_USER_ID, COMPANY_ID, SKU_ID
+
+
+class TestCategoryTree:
+    """GET /api/products/categories/tree"""
+
+    async def test_get_category_tree(self, client: AsyncClient, admin_headers):
+        """获取分类树 → 200"""
+        resp = await client.get("/api/products/categories/tree", headers=admin_headers)
+        assert resp.status_code == 200
+        # 初始可能为空数组
+        assert isinstance(resp.json()["data"], list)
+
+
+class TestCreateCategory:
+    """POST /api/products/categories"""
+
+    async def test_create_category(self, client: AsyncClient, admin_headers):
+        """新增根分类 → 200"""
+        resp = await client.post("/api/products/categories", headers=admin_headers, json={
+            "name": "润滑油系列",
+        })
+        assert resp.status_code == 200
+
+
+class TestListSkus:
+    """GET /api/products/skus"""
+
+    async def test_list_skus(self, client: AsyncClient, admin_headers):
+        """SKU 列表 → 200 + 包含种子 SKU"""
+        resp = await client.get("/api/products/skus", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert data["total"] >= 1
+
+    async def test_list_skus_search(self, client: AsyncClient, admin_headers):
+        """搜索 keyword=壳牌 → 返回匹配"""
+        resp = await client.get("/api/products/skus?keyword=壳牌", headers=admin_headers)
+        assert resp.status_code == 200
+
+
+class TestCreateSku:
+    """POST /api/products/skus"""
+
+    async def test_create_sku(self, client: AsyncClient, admin_headers):
+        """新增 SKU → 200"""
+        resp = await client.post("/api/products/skus", headers=admin_headers, json={
+            "sku_code": "LUB-002",
+            "name": "美孚1号 5W-30",
+            "spec": "4L/瓶",
+            "standard_price": 350.00,
+            "unit": "瓶",
+        })
+        assert resp.status_code == 200
+        assert resp.json()["data"]["sku_code"] == "LUB-002"
+
+    async def test_create_sku_duplicate_code(self, client: AsyncClient, admin_headers):
+        """重复 sku_code → 应失败（唯一约束）"""
+        resp = await client.post("/api/products/skus", headers=admin_headers, json={
+            "sku_code": "LUB-001",  # 与种子数据重复
+            "name": "重复产品",
+            "standard_price": 100,
+        })
+        assert resp.status_code in (400, 500)
+
+
+class TestUpdateSku:
+    """PUT /api/products/skus/{id}"""
+
+    async def test_update_sku(self, client: AsyncClient, admin_headers):
+        """修改 SKU 价格 → 200"""
+        resp = await client.put(f"/api/products/skus/{SKU_ID}", headers=admin_headers, json={
+            "standard_price": 300.00,
+        })
+        assert resp.status_code == 200
+
+
+class TestInventoryFlow:
+    """POST /api/products/inventory/flow"""
+
+    async def test_create_inventory_flow_in(self, client: AsyncClient, admin_headers):
+        """入库 → 200"""
+        resp = await client.post("/api/products/inventory/flow", headers=admin_headers, json={
+            "sku_id": str(SKU_ID),
+            "change_qty": 100,
+            "reason": "purchase_in",
+            "remark": "首次入库",
+            "purchase_unit_price": 150.00,
+        })
+        assert resp.status_code == 200
+
+    async def test_get_inventory_flows(self, client: AsyncClient, admin_headers):
+        """查询 SKU 库存流水 → 200"""
+        resp = await client.get(
+            f"/api/products/inventory/flows/{SKU_ID}",
+            headers=admin_headers
+        )
+        assert resp.status_code == 200

server/tests/api/test_profit.py

@@ -0,0 +1,37 @@
+"""
+利润核算模块测试 —— /api/profit
+"""
+import uuid
+import pytest
+from httpx import AsyncClient
+
+
+class TestProfitReport:
+    """GET /api/profit/report"""
+
+    async def test_profit_report(self, client: AsyncClient, admin_headers):
+        """利润报表（可能为空） → 200"""
+        resp = await client.get("/api/profit/report", headers=admin_headers)
+        assert resp.status_code == 200
+
+    async def test_profit_report_with_dates(self, client: AsyncClient, admin_headers):
+        """带日期范围 → 200"""
+        resp = await client.get(
+            "/api/profit/report?start_date=2026-01-01&end_date=2026-03-31",
+            headers=admin_headers
+        )
+        assert resp.status_code == 200
+
+
+class TestCostSnapshot:
+    """POST /api/profit/snapshot/{order_id}"""
+
+    async def test_snapshot_nonexistent_order(self, client: AsyncClient, admin_headers):
+        """不存在的订单快照 → 404 或空"""
+        fake_id = uuid.uuid4()
+        resp = await client.post(
+            f"/api/profit/snapshot/{fake_id}",
+            headers=admin_headers
+        )
+        # 可能返回 200 + 空结果，也可能 404
+        assert resp.status_code in (200, 404, 500)

server/tests/api/test_reports.py

@@ -0,0 +1,70 @@
+"""
+复盘报告模块测试 —— /api/reports
+覆盖: 确认存档 / 历史列表 / 修改 / 删除
+注: SSE 流式 /generate 需要 Dify，在此 mock/跳过
+"""
+import uuid
+import pytest
+from httpx import AsyncClient
+from tests.conftest import ADMIN_USER_ID
+
+
+class TestReportConfirm:
+    """POST /api/reports/confirm"""
+
+    async def test_confirm_report(self, client: AsyncClient, admin_headers):
+        """确认存档复盘报告 → 200"""
+        resp = await client.post("/api/reports/confirm", headers=admin_headers, json={
+            "start_date": "2026-03-01",
+            "end_date": "2026-03-31",
+            "content_md": "# 3月复盘报告\n\n本月完成10笔订单...",
+            "report_type": "monthly",
+        })
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert data["status"] == "confirmed"
+
+
+class TestReportHistory:
+    """GET /api/reports/history"""
+
+    async def test_list_report_history(self, client: AsyncClient, admin_headers):
+        """报告历史 → 200"""
+        resp = await client.get("/api/reports/history", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert "total" in data
+        assert "items" in data
+
+
+class TestReportCRUD:
+    """PUT / DELETE /api/reports/{id}"""
+
+    async def test_update_nonexistent_report(self, client: AsyncClient, admin_headers):
+        """修改不存在的报告 → 404"""
+        fake_id = uuid.uuid4()
+        resp = await client.put(f"/api/reports/{fake_id}", headers=admin_headers, json={
+            "content_md": "updated content",
+        })
+        assert resp.status_code == 404
+
+    async def test_delete_nonexistent_report(self, client: AsyncClient, admin_headers):
+        """删除不存在的报告 → 404"""
+        fake_id = uuid.uuid4()
+        resp = await client.delete(f"/api/reports/{fake_id}", headers=admin_headers)
+        assert resp.status_code == 404
+
+    async def test_create_and_delete_report(self, client: AsyncClient, admin_headers):
+        """创建→删除 完整链路"""
+        # 创建
+        create_resp = await client.post("/api/reports/confirm", headers=admin_headers, json={
+            "start_date": "2026-02-01",
+            "end_date": "2026-02-28",
+            "content_md": "# 2月复盘\n\n测试内容",
+        })
+        assert create_resp.status_code == 200
+        report_id = create_resp.json()["data"]["id"]
+
+        # 删除
+        del_resp = await client.delete(f"/api/reports/{report_id}", headers=admin_headers)
+        assert del_resp.status_code == 200

server/tests/api/test_sales_invoice.py

@@ -0,0 +1,39 @@
+"""
+销项发票模块测试 —— /api/finance/sales-invoices
+"""
+import uuid
+import pytest
+from httpx import AsyncClient
+from tests.conftest import CUSTOMER_ID
+
+
+class TestSalesInvoice:
+
+    async def test_list_sales_invoices(self, client: AsyncClient, admin_headers):
+        """销项发票列表 → 200"""
+        resp = await client.get("/api/finance/sales-invoices", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert "total" in data
+
+    async def test_create_sales_invoice(self, client: AsyncClient, admin_headers):
+        """创建销项发票 → 200"""
+        resp = await client.post("/api/finance/sales-invoices", headers=admin_headers, json={
+            "issuer": "测试润滑油有限公司",
+            "receiver_customer_id": str(CUSTOMER_ID),
+            "invoice_number": "INV-2026-001",
+            "amount": 5000.00,
+            "billing_date": "2026-03-20",
+        })
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert data["invoice_number"] == "INV-2026-001"
+
+    async def test_get_nonexistent_invoice(self, client: AsyncClient, admin_headers):
+        """不存在的发票详情 → 404"""
+        fake_id = uuid.uuid4()
+        resp = await client.get(
+            f"/api/finance/sales-invoices/{fake_id}",
+            headers=admin_headers
+        )
+        assert resp.status_code in (404, 500)

server/tests/api/test_sales_logs.py

@@ -0,0 +1,43 @@
+"""
+销售日志模块测试 —— /api/sales-logs
+覆盖: CRUD
+注: list_logs 在 SQLite 下跳过（用了 PG 的 ANY() 函数）
+"""
+import uuid
+import pytest
+from httpx import AsyncClient
+from tests.conftest import CUSTOMER_ID
+
+
+class TestSalesLogsCRUD:
+
+    async def test_create_log(self, client: AsyncClient, admin_headers):
+        """创建销售日志 → 200"""
+        resp = await client.post("/api/sales-logs", headers=admin_headers, json={
+            "content": "今天拜访了中石化天津分公司，讨论了润滑油采购事宜",
+            "customer_id": str(CUSTOMER_ID),
+            "log_date": "2026-03-30",
+        })
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert "id" in data
+
+    @pytest.mark.skip(reason="SQLite 不支持 PG 的 ANY() 函数，该测试需在 PG 环境运行")
+    async def test_list_logs(self, client: AsyncClient, admin_headers):
+        """日志列表 → 200"""
+        resp = await client.get("/api/sales-logs", headers=admin_headers)
+        assert resp.status_code == 200
+
+    async def test_create_log_empty_content(self, client: AsyncClient, admin_headers):
+        """空内容 → 422"""
+        resp = await client.post("/api/sales-logs", headers=admin_headers, json={
+            "content": "",
+        })
+        assert resp.status_code in (200, 422)
+
+    @pytest.mark.xfail(reason="service 层抛裸 Exception 在 SQLite 嵌套事务下传播异常，需 PG 环境")
+    async def test_delete_nonexistent_log(self, client: AsyncClient, admin_headers):
+        """删除不存在的日志 → 非 200（404 或 500 均可）"""
+        fake_id = uuid.uuid4()
+        resp = await client.delete(f"/api/sales-logs/{fake_id}", headers=admin_headers)
+        assert resp.status_code != 200

server/tests/api/test_security.py

@@ -0,0 +1,83 @@
+"""
+安全与权限测试 —— 跨模块
+覆盖: IDOR 防护 / 多租户隔离 / Token 过期 / ACL
+"""
+import uuid
+import pytest
+from datetime import timedelta
+from httpx import AsyncClient
+from tests.conftest import (
+    make_auth_headers, ADMIN_USER_ID, SALES_USER_ID,
+    COMPANY_ID,
+)
+from app.core.security import create_access_token
+
+
+class TestIDOR:
+    """IDOR 防护: 用伪造的 company_id 访问其他租户数据"""
+
+    async def test_fake_company_id_forbidden(self, client: AsyncClient, seed_data):
+        """伪造 X-Company-Id → 403"""
+        fake_company = uuid.uuid4()
+        headers = make_auth_headers(ADMIN_USER_ID, company_id=fake_company)
+        resp = await client.get("/api/orders", headers=headers)
+        assert resp.status_code == 403
+
+    async def test_invalid_company_id_format(self, client: AsyncClient, seed_data):
+        """非法 UUID 格式 → 401/422"""
+        token = create_access_token(data={"sub": str(ADMIN_USER_ID)})
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "X-Company-Id": "not-a-uuid",
+        }
+        resp = await client.get("/api/orders", headers=headers)
+        assert resp.status_code in (401, 422)
+
+
+class TestTokenSecurity:
+    """Token 安全"""
+
+    async def test_expired_token(self, client: AsyncClient, seed_data):
+        """过期 Token → 401"""
+        expired_token = create_access_token(
+            data={"sub": str(ADMIN_USER_ID)},
+            expires_delta=timedelta(seconds=-10)  # 已过期
+        )
+        resp = await client.get("/api/auth/me", headers={
+            "Authorization": f"Bearer {expired_token}"
+        })
+        assert resp.status_code == 401
+
+    async def test_malformed_bearer(self, client: AsyncClient, seed_data):
+        """格式错误的 Authorization → 401"""
+        resp = await client.get("/api/auth/me", headers={
+            "Authorization": "Basic some-basic-auth"
+        })
+        assert resp.status_code == 401
+
+    async def test_empty_bearer(self, client: AsyncClient, seed_data):
+        """空 Bearer → 401"""
+        resp = await client.get("/api/auth/me", headers={
+            "Authorization": "Bearer "
+        })
+        assert resp.status_code == 401
+
+
+class TestACL:
+    """角色访问控制"""
+
+    async def test_sales_cannot_access_settings(self, client: AsyncClient, sales_headers):
+        """普通销售无法访问系统设置 → 403"""
+        endpoints = [
+            "/api/settings/departments/tree",
+            "/api/settings/roles",
+            "/api/settings/users",
+        ]
+        for ep in endpoints:
+            resp = await client.get(ep, headers=sales_headers)
+            assert resp.status_code == 403, f"Expected 403 for {ep}, got {resp.status_code}"
+
+    async def test_sales_cannot_export_customers(self, client: AsyncClient, sales_headers):
+        """普通销售无法导出客户 → 403"""
+        resp = await client.get("/api/crm/export", headers=sales_headers)
+        assert resp.status_code == 403

server/tests/api/test_settings.py

@@ -0,0 +1,125 @@
+"""
+系统设置模块测试 —— /api/settings
+覆盖: 部门树 / 角色CRUD / 员工CRUD / 重置密码 / 权限守卫
+"""
+import uuid
+import pytest
+from httpx import AsyncClient
+from tests.conftest import (
+    ADMIN_USER_ID, SALES_USER_ID, DEPT_ID,
+    ADMIN_ROLE_ID, SALES_ROLE_ID,
+)
+
+
+class TestDeptTree:
+    """GET /api/settings/departments/tree"""
+
+    async def test_admin_get_dept_tree(self, client: AsyncClient, admin_headers):
+        """管理员 → 200 + 部门树"""
+        resp = await client.get("/api/settings/departments/tree", headers=admin_headers)
+        assert resp.status_code == 200
+        assert isinstance(resp.json()["data"], list)
+
+    async def test_sales_get_dept_tree_forbidden(self, client: AsyncClient, sales_headers):
+        """普通销售 → 403"""
+        resp = await client.get("/api/settings/departments/tree", headers=sales_headers)
+        assert resp.status_code == 403
+
+
+class TestRoles:
+    """/api/settings/roles"""
+
+    async def test_list_roles(self, client: AsyncClient, admin_headers):
+        """角色列表 → 200"""
+        resp = await client.get("/api/settings/roles", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert len(data) >= 2  # admin + sales
+
+    async def test_create_role(self, client: AsyncClient, admin_headers):
+        """新增角色 → 200"""
+        resp = await client.post("/api/settings/roles", headers=admin_headers, json={
+            "role_name": "财务主管",
+            "data_scope": "dept_and_sub",
+            "menu_keys": ["finance", "dashboard"],
+            "description": "财务部门主管角色",
+        })
+        assert resp.status_code == 200
+        assert resp.json()["data"]["role_name"] == "财务主管"
+
+    async def test_create_duplicate_role(self, client: AsyncClient, admin_headers):
+        """重复角色名 → 400"""
+        resp = await client.post("/api/settings/roles", headers=admin_headers, json={
+            "role_name": "管理员",  # 已存在
+            "data_scope": "all",
+        })
+        assert resp.status_code == 400
+
+    async def test_update_role(self, client: AsyncClient, admin_headers):
+        """修改角色 → 200"""
+        resp = await client.put(
+            f"/api/settings/roles/{SALES_ROLE_ID}",
+            headers=admin_headers,
+            json={"description": "基础销售角色-已更新"}
+        )
+        assert resp.status_code == 200
+
+    async def test_sales_cannot_manage_roles(self, client: AsyncClient, sales_headers):
+        """普通销售管理角色 → 403"""
+        resp = await client.get("/api/settings/roles", headers=sales_headers)
+        assert resp.status_code == 403
+
+
+class TestUsers:
+    """/api/settings/users"""
+
+    async def test_list_users(self, client: AsyncClient, admin_headers):
+        """员工列表 → 200"""
+        resp = await client.get("/api/settings/users", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert data["total"] >= 2
+
+    async def test_create_user(self, client: AsyncClient, admin_headers):
+        """开通新账号 → 200"""
+        resp = await client.post("/api/settings/users", headers=admin_headers, json={
+            "username": "newuser01",
+            "password": "test123456",
+            "real_name": "新员工",
+            "dept_id": str(DEPT_ID),
+            "role_id": str(SALES_ROLE_ID),
+        })
+        assert resp.status_code == 200
+        assert resp.json()["data"]["username"] == "newuser01"
+
+    async def test_create_duplicate_username(self, client: AsyncClient, admin_headers):
+        """重复用户名 → 400"""
+        resp = await client.post("/api/settings/users", headers=admin_headers, json={
+            "username": "admin",  # 已存在
+            "password": "123456",
+            "real_name": "重复用户",
+        })
+        assert resp.status_code == 400
+
+    async def test_update_user(self, client: AsyncClient, admin_headers):
+        """编辑员工 → 200"""
+        resp = await client.put(
+            f"/api/settings/users/{SALES_USER_ID}",
+            headers=admin_headers,
+            json={"real_name": "销售01-改名", "phone": "13800000001"}
+        )
+        assert resp.status_code == 200
+
+    async def test_reset_password(self, client: AsyncClient, admin_headers):
+        """重置密码 → 200"""
+        resp = await client.put(
+            f"/api/settings/users/{SALES_USER_ID}/reset-password",
+            headers=admin_headers,
+            json={"new_password": "reset999"}
+        )
+        assert resp.status_code == 200
+
+    async def test_sales_cannot_manage_users(self, client: AsyncClient, sales_headers):
+        """普通销售无法管理员工 → 403"""
+        resp = await client.get("/api/settings/users", headers=sales_headers)
+        assert resp.status_code == 403

server/tests/api/test_shipping.py

@@ -0,0 +1,22 @@
+"""
+发货模块测试 —— /api/shipping
+"""
+import uuid
+import pytest
+from httpx import AsyncClient
+
+
+class TestShipping:
+
+    async def test_list_shipping(self, client: AsyncClient, admin_headers):
+        """发货单列表 → 200"""
+        resp = await client.get("/api/shipping", headers=admin_headers)
+        assert resp.status_code == 200
+        data = resp.json()["data"]
+        assert "total" in data
+
+    async def test_get_shipping_by_nonexistent_order(self, client: AsyncClient, admin_headers):
+        """不存在的订单发货轨迹 → 200(空列表) 或 404"""
+        fake_id = uuid.uuid4()
+        resp = await client.get(f"/api/shipping/order/{fake_id}", headers=admin_headers)
+        assert resp.status_code in (200, 404)

server/tests/conftest.py

@@ -0,0 +1,350 @@
+"""
+SHBL-ERP CRM 测试基础设施
+=========================
+策略: 在 import app 之前, 先修改 settings 实例的 DATABASE_URL,
+     然后 monkey-patch app.db.database 模块, 再安全 import app。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import uuid
+from datetime import date, datetime
+from typing import AsyncGenerator
+
+import pytest
+import pytest_asyncio
+
+# ═══════════════════════════════════════════════════════════
+#  Step 1: 设置环境变量 (在任何 app 代码被 import 之前)
+# ═══════════════════════════════════════════════════════════
+import os
+os.environ["DATABASE_URL"] = "sqlite+aiosqlite://"
+os.environ["JWT_SECRET_KEY"] = "test-secret-key-for-unit-tests"
+os.environ["DEBUG"] = "false"
+os.environ["DIFY_API_BASE_URL"] = ""
+os.environ["DIFY_API_KEY"] = ""
+os.environ["DIFY_WORKFLOW_PERSONA_KEY"] = ""
+os.environ["DIFY_WORKFLOW_REPORT_KEY"] = ""
+
+# ═══════════════════════════════════════════════════════════
+#  Step 2: 先 import config (轻量级, 不会触发 DB 连接)
+#          然后 patch settings.DATABASE_URL
+# ═══════════════════════════════════════════════════════════
+from app.core.config import settings  # noqa: E402
+# 确保 settings 指向 sqlite
+settings.DATABASE_URL = "sqlite+aiosqlite://"
+
+# ═══════════════════════════════════════════════════════════
+#  Step 3: 预先构造 database 模块并注入 sys.modules,
+#          绕开 database.py 模块级代码中的 PG 参数
+# ═══════════════════════════════════════════════════════════
+from sqlalchemy import event as sa_event
+from sqlalchemy.ext.asyncio import (
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from types import ModuleType
+from collections.abc import AsyncGenerator as AsyncGenType
+
+# ── PG → SQLite 类型编译适配 + bind/result processor ─────
+from sqlalchemy.ext.compiler import compiles
+from sqlalchemy.dialects.postgresql import JSONB, UUID as PG_UUID, ARRAY as PG_ARRAY
+import json as _json
+
+@compiles(JSONB, "sqlite")
+def _compile_jsonb_sqlite(element, compiler, **kw):
+    return "TEXT"
+
+@compiles(PG_UUID, "sqlite")
+def _compile_uuid_sqlite(element, compiler, **kw):
+    return "CHAR(36)"
+
+@compiles(PG_ARRAY, "sqlite")
+def _compile_array_sqlite(element, compiler, **kw):
+    return "TEXT"
+
+# 让 UUID(as_uuid=True) 在 SQLite 下正确序列化/反序列化
+_orig_uuid_bind = PG_UUID.bind_processor
+_orig_uuid_result = PG_UUID.result_processor
+
+def _uuid_bind_processor(self, dialect):
+    if dialect.name == "sqlite":
+        def process(value):
+            if value is not None:
+                return str(value) if not isinstance(value, str) else value
+            return value
+        return process
+    return _orig_uuid_bind(self, dialect)
+
+def _uuid_result_processor(self, dialect, coltype):
+    if dialect.name == "sqlite":
+        def process(value):
+            if value is not None and not isinstance(value, uuid.UUID):
+                return uuid.UUID(str(value))
+            return value
+        return process
+    return _orig_uuid_result(self, dialect, coltype)
+
+PG_UUID.bind_processor = _uuid_bind_processor
+PG_UUID.result_processor = _uuid_result_processor
+
+# JSONB 在 SQLite 下序列化为 JSON 字符串
+_orig_jsonb_bind = JSONB.bind_processor
+_orig_jsonb_result = JSONB.result_processor
+
+def _jsonb_bind_processor(self, dialect):
+    if dialect.name == "sqlite":
+        def process(value):
+            if value is not None:
+                return _json.dumps(value, ensure_ascii=False) if not isinstance(value, str) else value
+            return value
+        return process
+    return _orig_jsonb_bind(self, dialect)
+
+def _jsonb_result_processor(self, dialect, coltype):
+    if dialect.name == "sqlite":
+        def process(value):
+            if value is not None and isinstance(value, str):
+                try:
+                    return _json.loads(value)
+                except _json.JSONDecodeError:
+                    return value
+            return value
+        return process
+    return _orig_jsonb_result(self, dialect, coltype)
+
+JSONB.bind_processor = _jsonb_bind_processor
+JSONB.result_processor = _jsonb_result_processor
+
+# ARRAY 在 SQLite 下序列化为 JSON 字符串
+_orig_array_bind = PG_ARRAY.bind_processor
+_orig_array_result = PG_ARRAY.result_processor
+
+def _array_bind_processor(self, dialect):
+    if dialect.name == "sqlite":
+        def process(value):
+            if value is not None:
+                return _json.dumps([str(v) for v in value], ensure_ascii=False) if not isinstance(value, str) else value
+            return value
+        return process
+    if hasattr(_orig_array_bind, '__func__'):
+        return _orig_array_bind(self, dialect)
+    return None
+
+def _array_result_processor(self, dialect, coltype):
+    if dialect.name == "sqlite":
+        def process(value):
+            if value is not None and isinstance(value, str):
+                try:
+                    return _json.loads(value)
+                except _json.JSONDecodeError:
+                    return value
+            return value
+        return process
+    if hasattr(_orig_array_result, '__func__'):
+        return _orig_array_result(self, dialect, coltype)
+    return None
+
+PG_ARRAY.bind_processor = _array_bind_processor
+PG_ARRAY.result_processor = _array_result_processor
+
+
+# 创建测试 SQLite 引擎
+_test_engine = create_async_engine("sqlite+aiosqlite://", echo=False)
+
+@sa_event.listens_for(_test_engine.sync_engine, "connect")
+def _set_sqlite_pragma(dbapi_conn, connection_record):
+    cursor = dbapi_conn.cursor()
+    cursor.execute("PRAGMA foreign_keys=OFF")
+    cursor.close()
+
+_test_session_factory = async_sessionmaker(
+    _test_engine, class_=AsyncSession, expire_on_commit=False
+)
+
+async def _test_get_db() -> AsyncGenType:
+    async with _test_session_factory() as session:
+        try:
+            yield session
+        finally:
+            await session.close()
+
+# 创建 fake database 模块
+_fake_db_mod = ModuleType("app.db.database")
+_fake_db_mod.engine = _test_engine
+_fake_db_mod.async_session_factory = _test_session_factory
+_fake_db_mod.get_db = _test_get_db
+
+# 注入到 sys.modules，后续所有 `from app.db.database import ...` 都会用这个
+sys.modules["app.db.database"] = _fake_db_mod
+# 确保 parent 包也存在
+if "app.db" not in sys.modules:
+    _fake_db_pkg = ModuleType("app.db")
+    _fake_db_pkg.database = _fake_db_mod
+    sys.modules["app.db"] = _fake_db_pkg
+
+# ═══════════════════════════════════════════════════════════
+#  Step 4: 现在安全地 import app 及所有模型
+# ═══════════════════════════════════════════════════════════
+from app.core.security import create_access_token, hash_password  # noqa: E402
+from app.models.base import Base  # noqa: E402
+from app.main import app  # noqa: E402
+
+from app.models.sys import SysDepartment, SysRole, SysUser, SysCompany, SysUserCompany  # noqa: F401
+from app.models.crm import CrmCustomer, CrmContact  # noqa: F401
+from app.models.erp import ProductCategory, ProductSku, InventoryFlow, ErpSkuInventory  # noqa: F401
+from app.models.order import ErpOrder, ErpOrderItem  # noqa: F401
+from app.models.contract import ErpContract, ErpContractItem, ErpContractAttachment  # noqa: F401
+from app.models.finance import FinInvoicePool, FinExpenseRecord, FinExpenseDetail, FinSalesInvoice  # noqa: F401
+from app.models.shipping import ErpShippingRecord, ErpShippingItem  # noqa: F401
+from app.models.ai import AiChatSession, SalesLog, AiReportDraft  # noqa: F401
+from app.models.cost import ErpOrderItemCost  # noqa: F401
+
+from httpx import ASGITransport, AsyncClient
+
+# ═══════════════════════════════════════════════════════════
+#  固定 UUID
+# ═══════════════════════════════════════════════════════════
+ADMIN_USER_ID = uuid.UUID("00000000-0000-0000-0000-000000000001")
+SALES_USER_ID = uuid.UUID("00000000-0000-0000-0000-000000000002")
+COMPANY_ID    = uuid.UUID("00000000-0000-0000-0000-000000000010")
+DEPT_ID       = uuid.UUID("00000000-0000-0000-0000-000000000020")
+ADMIN_ROLE_ID = uuid.UUID("00000000-0000-0000-0000-000000000030")
+SALES_ROLE_ID = uuid.UUID("00000000-0000-0000-0000-000000000031")
+CUSTOMER_ID   = uuid.UUID("00000000-0000-0000-0000-000000000040")
+SKU_ID        = uuid.UUID("00000000-0000-0000-0000-000000000050")
+
+
+# ═══════════════════════════════════════════════════════════
+#  Fixtures
+# ═══════════════════════════════════════════════════════════
+
+@pytest.fixture(scope="session")
+def event_loop():
+    loop = asyncio.new_event_loop()
+    yield loop
+    loop.close()
+
+
+@pytest_asyncio.fixture(scope="session", loop_scope="session")
+async def _create_tables():
+    """session 级: 只建表一次"""
+    async with _test_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+    async with _test_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+    await _test_engine.dispose()
+
+
+@pytest_asyncio.fixture()
+async def db_session(_create_tables) -> AsyncGenerator[AsyncSession, None]:
+    """
+    每个测试用例用独立的事务包裹:
+    - 开启一个连接级事务 (begin)
+    - 在该事务上创建 session
+    - 测试结束后 rollback 连接级事务，所有改动都会被撤销
+    """
+    async with _test_engine.connect() as conn:
+        trans = await conn.begin()
+        session = AsyncSession(bind=conn, expire_on_commit=False)
+        try:
+            yield session
+        finally:
+            await session.close()
+            await trans.rollback()
+
+
+@pytest_asyncio.fixture()
+async def client(_create_tables, db_session) -> AsyncGenerator[AsyncClient, None]:
+    async def override_get_db():
+        yield db_session
+
+    app.dependency_overrides[_test_get_db] = override_get_db
+
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://testserver") as ac:
+        yield ac
+
+    app.dependency_overrides.clear()
+
+
+@pytest_asyncio.fixture()
+async def seed_data(db_session: AsyncSession):
+    """种子数据: 部门/角色/公司/用户/客户/SKU"""
+    dept = SysDepartment(id=DEPT_ID, name="销售部", sort_order=1)
+    db_session.add(dept)
+
+    admin_role = SysRole(
+        id=ADMIN_ROLE_ID, role_name="管理员", data_scope="all",
+        menu_keys=["dashboard", "customers", "orders", "contracts", "products",
+                    "shipping", "finance", "settings", "logs", "reports"]
+    )
+    sales_role = SysRole(
+        id=SALES_ROLE_ID, role_name="销售", data_scope="self",
+        menu_keys=["dashboard", "customers", "orders", "logs"]
+    )
+    db_session.add_all([admin_role, sales_role])
+
+    company = SysCompany(
+        id=COMPANY_ID, name="测试润滑油有限公司", code="TEST-CO",
+        full_info={"full_name": "天津测试润滑油有限公司", "tax_id": "91120000XXXX"}
+    )
+    db_session.add(company)
+
+    admin_user = SysUser(
+        id=ADMIN_USER_ID, username="admin", password_hash=hash_password("admin123"),
+        real_name="管理员", dept_id=DEPT_ID, role_id=ADMIN_ROLE_ID, status=1
+    )
+    sales_user = SysUser(
+        id=SALES_USER_ID, username="sales01", password_hash=hash_password("sales123"),
+        real_name="销售01", dept_id=DEPT_ID, role_id=SALES_ROLE_ID, status=1
+    )
+    db_session.add_all([admin_user, sales_user])
+    await db_session.flush()
+
+    db_session.add(SysUserCompany(user_id=ADMIN_USER_ID, company_id=COMPANY_ID, is_default=True))
+    db_session.add(SysUserCompany(user_id=SALES_USER_ID, company_id=COMPANY_ID, is_default=True))
+
+    customer = CrmCustomer(
+        id=CUSTOMER_ID, name="中石化天津分公司", level="A",
+        industry="石油化工", contact="张经理", phone="13800138000",
+        owner_id=SALES_USER_ID
+    )
+    db_session.add(customer)
+
+    sku = ProductSku(
+        id=SKU_ID, sku_code="LUB-001", name="壳牌劲霸R4 15W-40",
+        spec="18L/桶", standard_price=280.00, unit="桶"
+    )
+    db_session.add(sku)
+
+    await db_session.commit()
+    return {
+        "admin_user_id": ADMIN_USER_ID,
+        "sales_user_id": SALES_USER_ID,
+        "company_id": COMPANY_ID,
+        "customer_id": CUSTOMER_ID,
+        "sku_id": SKU_ID,
+    }
+
+
+def make_auth_headers(user_id: uuid.UUID, company_id: uuid.UUID = COMPANY_ID) -> dict:
+    token = create_access_token(data={"sub": str(user_id)})
+    return {
+        "Authorization": f"Bearer {token}",
+        "X-Company-Id": str(company_id),
+    }
+
+
+@pytest_asyncio.fixture()
+def admin_headers(seed_data) -> dict:
+    return make_auth_headers(ADMIN_USER_ID)
+
+
+@pytest_asyncio.fixture()
+def sales_headers(seed_data) -> dict:
+    return make_auth_headers(SALES_USER_ID)