后端设计治理:批次 0-4 全部完成(安全/部署/一致性/结构/架构)

按 ROADMAP §3.1 治理批次推进的后端设计审查整改:

- 批次 0(安全):/api/status/{task_id} 补 JWT 鉴权与任务归属校验;
  pythonocc_available 真实探测;bcrypt 超 72 字节显式拒绝;
  SECRET_KEY/RUSTFS_* 惰性校验,代码侧弱默认移除
- 批次 1(部署正确性):主处理链路改走 RustFS(分派入参 stp_file_id 化,
  worker 按 object_key 下载);AUTO_MIGRATE 开关 + 迁移目录 alembic/→migrations/
  修复包遮蔽(自动迁移此前从未真正生效);OCC 镜像改 conda 原生执行 +
  基础镜像 tag 锁定;compose 关键项改 ${VAR:?} 强制显式配置
- 批次 2(任务一致性):删除 Redis 进程内存回退,PG 为任务状态单一事实源;
  批量元数据入库(processing_tasks.batch_id,迁移 a3f8c2d91e47);
  型腔失败任务标 failed 不再静默 completed;事务边界收口
  (数据本体写 flush-only、失败先回滚再置 failed、进度更新保留即时 commit)
- 批次 3(API 与代码结构):592 行 advanced_router 拆为 design/cost/machining/
  export 四子路由,请求体全量 Pydantic 化;ROUTE_MODULES + route_registry
  (/api/health 呈现 degraded,DEBUG fail fast);纯计算端点统一 to_thread;
  StorageIntegrationService 按职责三拆;MAX_FILE_SIZE 接线生效、
  celery 复用 Settings.redis_url;管理员重置密码改 JSON body(端到端断裂修复);
  openapi.json 重导出(76 paths)+ 前端 gen:api
- 批次 4(架构演进):共享 ORM 按模块拆分(shared/models/base.py + identity.py、
  moldinsight/models/、inventory/models/,删除三条无使用方的跨模块
  relationship,跨模块桥接收敛为裸 FK 硬规则,无兼容 facade);
  OCC executor 重建补 cancel_futures=True(消除旧队列被慢恢复线程
  并行消化的数据竞争);OCC 吞吐方案设计先行
  (docs/topics/performance/OCC_THROUGHPUT.md);顺手清偿 D15
  (vite.config.ts 未用参数致 npm run build 失败)

测试基线:125 passed, 2 skipped(pytest + sqlite+aiosqlite;归属边界、
路由契约、配置治理、鉴权回归等随批新增)
文档同步:STATUS / TECH_DEBT / ROADMAP / ARCHITECTURE / API_CONTRACT /
OPERATIONS / AGENTS

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
2026-09-17 16:15:49 +08:00
parent 4537faf2c4
commit 0e6b3b1811
82 changed files with 6513 additions and 3709 deletions
+4 -4
View File
@@ -17,10 +17,10 @@ from sqlalchemy import select
from fastapi import FastAPI, APIRouter
from inventory.api import inventory_router
from shared.models.database import (
Base, User, Customer, Warehouse, Supplier, Product, ProductMaterial,
Inventory, MaterialSupplier, SalesOrder, SalesOrderItem,
)
from shared.models.base import Base
from shared.models.identity import User
from inventory.models import Customer, Warehouse, Supplier, Product, ProductMaterial, Inventory, MaterialSupplier, SalesOrder, SalesOrderItem
import moldinsight.models # noqa: F401 # 全量注册:create_all 需含 moldinsight 表(stp_files 等)
from shared.database.database import get_db_session
from shared.services.auth_service import get_current_active_user
+109
View File
@@ -0,0 +1,109 @@
"""批次 3(D1)回归:advanced_router 拆分 + Pydantic 请求模型契约测试。
- 拆分后全部原端点路径保持不变(design / cost / machining / export 四个子路由)
- 请求体校验统一 422(原 request.json() 手动解析的 400/静默默认值退役)
- 纯 Python 计算端点(optimize-layout)经 to_thread 仍返回原响应形态
"""
import pytest
from fastapi import FastAPI
from httpx import AsyncClient, ASGITransport
from sqlalchemy.ext.asyncio import async_sessionmaker, AsyncSession
# design/export 路由的导入链含 processing_service / cad_exporter(OCC)
pytest.importorskip("OCC")
from moldinsight.api.design_router import router as design_router
from moldinsight.api.cost_router import router as cost_router
from moldinsight.api.machining_router import router as machining_router
from moldinsight.api.export_router import router as export_router
from shared.database.database import get_db_session
from shared.services.auth_service import get_current_active_user
from shared.models.identity import User
EXPECTED_PATHS = {
"/optimize-layout", "/design-cooling", "/design-gating", "/design-mold-system",
"/detect-undercuts", "/cost-estimate", "/design-cam", "/check-collision",
"/optimize-toolpath", "/design-electrodes", "/simulate-machining",
"/export-mold", "/export-download/{filepath:path}", "/export-recommendations",
}
def _build_app(async_engine):
test_app = FastAPI()
for r in (design_router, cost_router, machining_router, export_router):
test_app.include_router(r)
session_factory = async_sessionmaker(async_engine, class_=AsyncSession, expire_on_commit=False)
async def override_get_db_session():
async with session_factory() as session:
yield session
# 生产 get_db_session 在依赖解析期即建连(is_connected→connect),
# 裸测试应用必须覆写,否则任何带鉴权链的请求都会先连真实 PG
test_app.dependency_overrides[get_db_session] = override_get_db_session
return test_app
@pytest.fixture
async def api_client(async_engine):
test_app = _build_app(async_engine)
test_app.dependency_overrides[get_current_active_user] = lambda: User(id=1, username="tester")
transport = ASGITransport(app=test_app)
async with AsyncClient(transport=transport, base_url="http://test") as ac:
yield ac
test_app.dependency_overrides.clear()
def test_all_original_paths_registered():
"""拆分不丢端点:原 advanced_router 的全部路径必须仍可注册。"""
test_app = FastAPI()
for r in (design_router, cost_router, machining_router, export_router):
test_app.include_router(r)
paths = {route.path for route in test_app.routes}
missing = EXPECTED_PATHS - paths
assert not missing, f"拆分后丢失端点: {missing}"
@pytest.mark.asyncio
async def test_endpoints_require_auth(async_engine):
"""拆分不得丢掉鉴权:未带 token 访问设计/导出端点必须 401。"""
test_app = _build_app(async_engine) # 只覆写 db,不覆写鉴权
transport = ASGITransport(app=test_app)
async with AsyncClient(transport=transport, base_url="http://test") as ac:
for path in ("/optimize-layout", "/cost-estimate", "/export-mold", "/design-cam"):
resp = await ac.post(path, json={})
assert resp.status_code == 401, f"{path} 未鉴权: {resp.status_code}"
@pytest.mark.asyncio
async def test_optimize_layout_rejects_invalid_cavity_count(api_client):
"""原 400「1-64」校验迁移为 Pydantic 422。"""
resp = await api_client.post("/optimize-layout", json={"cavity_count": 0})
assert resp.status_code == 422
resp = await api_client.post("/optimize-layout", json={"cavity_count": 65})
assert resp.status_code == 422
@pytest.mark.asyncio
async def test_task_id_endpoints_reject_missing_task_id(api_client):
"""task_id 类端点缺参统一 422(原 detect-undercuts 400 / export-mold 404 语义收敛)。"""
for path in ("/detect-undercuts", "/cost-estimate", "/export-mold"):
resp = await api_client.post(path, json={})
assert resp.status_code == 422, f"{path} 缺 task_id 未返回 422"
@pytest.mark.asyncio
async def test_optimize_layout_default_body_succeeds(api_client):
"""纯 Python 计算端点经 to_thread 正常返回原响应形态。"""
resp = await api_client.post("/optimize-layout", json={"cavity_count": 4})
assert resp.status_code == 200
body = resp.json()
assert body["status"] == "success"
assert "data" in body
@pytest.mark.asyncio
async def test_simulate_machining_default_body_succeeds(api_client):
resp = await api_client.post("/simulate-machining", json={})
assert resp.status_code == 200
assert resp.json()["status"] == "success"
+101
View File
@@ -0,0 +1,101 @@
"""批次 3 回归:管理员重置密码走 JSON body。
此前后端把 new_password 声明为裸 str 参数(FastAPI 解析为 query param),
前端两个调用点均发送 JSON body,重置密码端到端断裂(必 422)。
现收敛为 Pydantic 请求模型 { new_password },与 api-client.ts 结构一致。
"""
from types import SimpleNamespace
import pytest
from fastapi import FastAPI
from httpx import AsyncClient, ASGITransport
from sqlalchemy.ext.asyncio import async_sessionmaker, AsyncSession
from sqlalchemy import select
from shared.database.database import get_db_session
from shared.models.identity import User
from shared.services.auth_service import (
get_current_active_user,
get_password_hash,
verify_password,
)
from shared.services.auth_routes import router as auth_router
@pytest.fixture
async def reset_env(async_engine, seeded_db):
"""播种被重置目标用户(id=2,已知旧密码);返回 (client, app, session_factory)。"""
session_factory = async_sessionmaker(async_engine, class_=AsyncSession, expire_on_commit=False)
async with session_factory() as session:
target = User(
id=2, username="resetme", email="resetme@example.com",
hashed_password=get_password_hash("oldpass123"), is_active=True,
)
session.add(target)
await session.commit()
test_app = FastAPI()
test_app.include_router(auth_router) # router 自带 /api/auth 前缀
async def override_get_db_session():
async with session_factory() as session:
yield session
test_app.dependency_overrides[get_db_session] = override_get_db_session
transport = ASGITransport(app=test_app)
async with AsyncClient(transport=transport, base_url="http://test") as ac:
yield ac, test_app, session_factory
test_app.dependency_overrides.clear()
def _login_as(app: FastAPI, *, superuser: bool):
# User.is_superuser 为只读 hybrid property,覆写用户用 SimpleNamespace 承载
app.dependency_overrides[get_current_active_user] = lambda: SimpleNamespace(
id=500, username="admin", is_superuser=superuser
)
@pytest.mark.asyncio
async def test_reset_password_with_json_body(reset_env):
"""JSON body { new_password } 生效:密码真实更新且可用新口令验证。"""
ac, app, session_factory = reset_env
_login_as(app, superuser=True)
resp = await ac.put(
"/api/auth/users/2/reset-password",
json={"new_password": "brandnew456"},
)
assert resp.status_code == 200
async with session_factory() as session:
user = (await session.execute(select(User).where(User.id == 2))).scalar_one()
assert verify_password("brandnew456", user.hashed_password)
assert not verify_password("oldpass123", user.hashed_password)
@pytest.mark.asyncio
async def test_reset_password_rejects_short_password(reset_env):
"""最短 6 位对齐前端校验,违约 422。"""
ac, app, _ = reset_env
_login_as(app, superuser=True)
resp = await ac.put(
"/api/auth/users/2/reset-password",
json={"new_password": "abc"},
)
assert resp.status_code == 422
@pytest.mark.asyncio
async def test_reset_password_requires_admin(reset_env):
ac, app, _ = reset_env
_login_as(app, superuser=False)
resp = await ac.put(
"/api/auth/users/2/reset-password",
json={"new_password": "brandnew456"},
)
assert resp.status_code == 403
+2 -1
View File
@@ -11,7 +11,8 @@ from sqlalchemy.ext.asyncio import async_sessionmaker, AsyncSession
from moldinsight.api.batch_router import router as batch_router
from shared.database.database import get_db_session
from shared.models.database import User, STPFile, ProcessingTask
from shared.models.identity import User
from moldinsight.models import STPFile, ProcessingTask
from shared.services.auth_service import get_current_active_user
+76
View File
@@ -0,0 +1,76 @@
"""批次 3(D14)回归:配置治理。
- settings.redis_url 成为 Redis 连接串唯一拼装点(celery_app 不再自拼)
- MAX_FILE_SIZE 不再是死配置:上传处理器接 settings(此前硬编码 50MB)
"""
import pytest
from shared.config.settings import Settings
def _fresh_settings(monkeypatch, **env):
for key, value in env.items():
monkeypatch.setenv(key, value)
return Settings()
def test_redis_url_without_password(monkeypatch):
s = _fresh_settings(
monkeypatch,
REDIS_HOST="redis-svc", REDIS_PORT="6380", REDIS_PASSWORD="", REDIS_DB="2",
)
assert s.redis_url == "redis://redis-svc:6380/2"
def test_redis_url_with_password(monkeypatch):
s = _fresh_settings(
monkeypatch,
REDIS_HOST="redis-svc", REDIS_PORT="6379", REDIS_PASSWORD="sec ret", REDIS_DB="0",
)
assert s.redis_url == "redis://:sec ret@redis-svc:6379/0"
def test_celery_app_reuses_settings_redis_url():
"""celery_app 的 broker/backend 必须等于 settings.redis_url(消除两份拼装实现)。"""
pytest.importorskip("celery")
import celery_app
from shared.config.settings import settings
assert celery_app.app.conf.broker_url == settings.redis_url
assert celery_app.app.conf.result_backend == settings.redis_url
def test_upload_handler_uses_settings_max_file_size(monkeypatch):
"""MAX_FILE_SIZE 从 .env 一路生效到上传校验(不再是死配置)。"""
pytest.importorskip("minio") # upload_router 导入链含 rustfs_storage
from shared.config import settings as settings_module
from shared.utils.file_handler import FileHandler
monkeypatch.setattr(settings_module.settings, "MAX_FILE_SIZE", 10)
handler = FileHandler(
upload_dir=settings_module.settings.UPLOAD_DIR,
max_file_size=settings_module.settings.MAX_FILE_SIZE,
)
assert handler.max_file_size == 10
import asyncio
class _FakeUpload:
filename = "big.step"
@staticmethod
async def read():
return b"x" * 11
with pytest.raises(ValueError):
asyncio.run(handler.save_uploaded_file(_FakeUpload()))
def test_router_handlers_wired_to_settings():
"""路由模块的 file_handler 实例必须接 settings(而非构造默认值)。"""
pytest.importorskip("minio")
from shared.config.settings import settings
from moldinsight.api import upload_router, batch_router
assert upload_router.file_handler.max_file_size == settings.MAX_FILE_SIZE
assert batch_router.file_handler.max_file_size == settings.MAX_FILE_SIZE
+76
View File
@@ -0,0 +1,76 @@
"""D3 模型拆分归属保护(批次 4,2026-09-17)。
锁定三个拆分成果:
1. 三包模型全量注册后 mapper 可配置、31 表齐全;
2. 单模块部署(inventory-only / moldinsight-only + auth)独立配置 mapper 成功——
跨模块 ORM relationship 已清零,任何一侧不注册对方模型也能工作;
3. 旧 shared.models.database 模块已删除且无兼容 facade(诚实原则:不留假象)。
"""
import importlib
import subprocess
import sys
from pathlib import Path
SRC = str(Path(__file__).resolve().parent.parent / "src")
EXPECTED_TABLES = {
# identity(shared.models.identity)
"users", "roles", "permissions", "user_roles", "role_permissions",
"user_activities", "system_logs",
# moldinsight.models
"stp_files", "geometry_data", "mesh_data", "html_files", "processing_tasks",
"mold_cavity_data", "feature_detections", "design_recommendations", "analysis_metrics",
# inventory.models
"products", "product_materials", "material_price_history", "material_suppliers",
"suppliers", "customers", "warehouses", "inventory", "stock_movements",
"purchase_orders", "purchase_order_items", "sales_orders", "sales_order_items",
"finance_transactions", "finance_allocations",
}
def test_full_registration_covers_all_31_tables():
import shared.models.identity # noqa: F401
import moldinsight.models # noqa: F401
import inventory.models # noqa: F401
from sqlalchemy.orm import configure_mappers
from shared.models.base import Base
configure_mappers()
assert set(Base.metadata.tables) == EXPECTED_TABLES
def test_single_module_deployments_configure_mappers_independently():
"""单模块注册子进程验证:inventory-only 与 moldinsight-only(含 auth identity)
均可在不 import 对方业务模型的情况下 configure_mappers 成功。
用子进程隔离,避免污染本进程的 mapper 注册表。"""
code = (
"import sys; sys.path.insert(0, r'%s')\n"
"from sqlalchemy.orm import configure_mappers\n"
"%s\n"
"configure_mappers()\n"
"print('ok')\n"
)
cases = [
# inventory-only:inventory 模型 + auth 必带的 identity
"import inventory.models, shared.models.identity",
# moldinsight-only:moldinsight 模型 + auth 必带的 identity
"import moldinsight.models, shared.models.identity",
]
for imports in cases:
proc = subprocess.run(
[sys.executable, "-c", code % (SRC, imports)],
capture_output=True, text=True, timeout=120,
)
assert proc.returncode == 0, f"{imports} 配置失败:\n{proc.stderr}"
assert proc.stdout.strip().endswith("ok")
def test_legacy_database_module_is_gone():
"""旧 shared.models.database 已物理删除,无兼容 facade。"""
try:
importlib.import_module("shared.models.database")
except ModuleNotFoundError:
pass
else:
raise AssertionError("shared.models.database 仍可导入——拆分后不允许残留兼容 facade")
+2 -2
View File
@@ -40,9 +40,9 @@ async def test_storage_writes_flush_but_never_commit():
"""D9:数据本体写方法仅 flush;commit 由编排层/请求侧负责。"""
pytest.importorskip("minio")
from sqlalchemy.ext.asyncio import AsyncSession
from moldinsight.services.storage_integration_rustfs import StorageIntegrationService
from moldinsight.services.task_storage_service import TaskStorageService
svc = StorageIntegrationService()
svc = TaskStorageService()
session = AsyncMock(spec=AsyncSession)
# update_task_parameters:select 返回 None(任务不存在)→ 直接 return
result_mock = MagicMock()
+77
View File
@@ -0,0 +1,77 @@
"""批次 3 回归:路由装载失败显式化(_safe_include 不再静默跳过)。
- 非 DEBUG:失败记录进 route_registry,/api/health 呈现 degraded
- DEBUG:装载失败直接抛错(fail fast,开发期当场暴露)
- 注册表状态在测试间隔离(真实 app 在导入期已登记 loaded 列表)
"""
import pytest
from fastapi import FastAPI
from httpx import AsyncClient, ASGITransport
from shared.config.settings import settings
from moldinsight.api import _safe_include
from moldinsight.api.route_registry import route_load_status
from moldinsight.api.health_router import router as health_router
@pytest.fixture(autouse=True)
def clean_registry():
"""清空注册表并在测试后还原真实 app 导入期登记的状态。"""
snapshot = {k: list(v) for k, v in route_load_status.items()}
for items in route_load_status.values():
items.clear()
yield
for items in route_load_status.values():
items.clear()
for key, items in snapshot.items():
route_load_status[key].extend(items)
def test_failed_route_recorded_not_silent(monkeypatch):
"""非 DEBUG:装载失败必须留下显式记录(此前仅 WARNING 日志后静默跳过)。"""
monkeypatch.setattr(settings, "DEBUG", False)
_safe_include("不存在", "moldinsight.api.definitely_missing_module")
failed = route_load_status["failed"]
assert len(failed) == 1
assert failed[0]["label"] == "不存在"
assert failed[0]["module"] == "moldinsight.api.definitely_missing_module"
assert "error" in failed[0]
def test_failed_route_raises_in_debug(monkeypatch):
"""DEBUG:装载失败直接抛错,禁止带病启动。"""
monkeypatch.setattr(settings, "DEBUG", True)
with pytest.raises(ModuleNotFoundError):
_safe_include("不存在", "moldinsight.api.definitely_missing_module")
def test_debug_only_route_disabled_when_debug_off(monkeypatch):
monkeypatch.setattr(settings, "DEBUG", False)
_safe_include("调试", "moldinsight.api.debug_router", debug_only=True)
assert route_load_status["disabled"][0]["module"] == "moldinsight.api.debug_router"
assert route_load_status["failed"] == []
@pytest.mark.asyncio
async def test_health_reports_degraded_and_failed_routes(monkeypatch):
"""health 必须暴露失败路由清单并将 status 置为 degraded。"""
monkeypatch.setattr(settings, "DEBUG", False)
_safe_include("不存在", "moldinsight.api.definitely_missing_module")
test_app = FastAPI()
test_app.include_router(health_router, prefix="/api")
transport = ASGITransport(app=test_app)
async with AsyncClient(transport=transport, base_url="http://test") as ac:
resp = await ac.get("/api/health")
assert resp.status_code == 200
body = resp.json()
assert body["status"] == "degraded"
assert body["routes"]["failed"][0]["module"] == "moldinsight.api.definitely_missing_module"
# 真实探测而非硬编码(布尔类型即可,具体值取决于环境是否安装 OCC)
assert isinstance(body["pythonocc"], bool)
+2 -1
View File
@@ -12,7 +12,8 @@ from sqlalchemy.ext.asyncio import async_sessionmaker, AsyncSession
from moldinsight.api.task_router import router as task_router
from shared.database.database import get_db_session
from shared.models.database import User, STPFile, ProcessingTask
from shared.models.identity import User
from moldinsight.models import STPFile, ProcessingTask
from shared.services.auth_service import (
get_current_active_user,
get_password_hash,