leaudit-platform-backend/docs/leaudit/README.md

LeAudit 设计文档目录

本目录包含 leaudit-platform 项目的核心架构设计文档。

文档索引

文档	内容	状态
document_schema_design.md	文档域表结构设计 — 17 张 leaudit_* 表完整说明	✅ 已落地
dsl_rule_schema_design.md	DSL 规则域表结构 — 规则集/版本/绑定管理	✅ 核心表已落地
processing_logic.md	LeAudit 7 阶段处理流水线说明	📖 参考文档
bridge_directory_design.md	Bridge 桥接层目录与职责设计	✅ 已落地
infrastructure_redesign.md	基础设施重设计 — OSS/队列/缓存/区域隔离	📋 设计蓝图

快览

leaudit-platform 核心链路:

用户上传文档
  → leaudit_bridge pipeline (OCR→Extract→Evaluate→Rescue)
  → StorageAdapter 写入 leaudit_* 表
  → Controller→Service 读取结果返回前端

数据存储:
  PostgreSQL: 17 张 leaudit_* 表 (元数据 + 结果索引)
  MinIO OSS:  bdocs/ + artifacts/ (文件真源)
  Redis:      队列 + 缓存 + 并发控制

---

迁移规范

从老项目 docauditai 迁移代码到新项目 leaudit-platform 时，严格遵守以下规范。

一、路由

规则	说明
路由地址不变	前端不做任何修改，POST /auth/login、POST /upload 等全部保持原样
编码按新规范	不用旧项目 @router.post() 裸写逻辑，改为 Controller → Service(接口+实现) → Model 分层
响应格式统一	旧 {success, data} → 新 Result[T] 格式 {code, message, data}
去掉 V1/V2	旧项目 app/routes/v2/ 的多版本路由全部废弃，只保留实际使用的路由

二、Service 层

规则	说明
业务逻辑原封不动	核心判断逻辑、优先级、算法全部保持和旧项目一致
只改数据访问方式	asyncpg.connect() → SQLAlchemy GetAsyncSession() + text()
接口+实现分离	每个模块定义 IXxxService 抽象接口 + XxxServiceImpl 实现
不顺手优化	已验证的业务逻辑不做"顺便改进"，避免引入新 bug

三、数据库

规则	说明
全 leaudit_* 前缀	与旧 docauditai 库的表完全隔离，不混用
新数据库独立	leaudit_platform@nas.7bm.co:54302，不修改旧库结构
所有表必有	create_time + update_time + delete_time 三时间戳
所有列必有中文注释	COMMENT ON COLUMN xxx IS '...'
软删除	业务表不允许物理删除，统一用 delete_time IS NULL 过滤

四、配置

规则	说明
TOML → os.environ → Pydantic Settings → module export	配置加载链：app.toml → 环境变量 → _settings.py → from fastapi_admin.config import XXX
不硬编码	禁止在代码中写死 host/port/key，一律走 config 模块
app.toml 不入 git	含数据库密码、API Key，.gitignore 已排除

五、Bridge 导入

旧引用	新引用
from core.config import XXX	from fastapi_admin.config import XXX
from core.postgrest.client import ...	from fastapi_common...database import GetAsyncSession + text()
from core.logger import log	from fastapi_common.fastapi_common_logger import logger
from core.celery_app_limited import celery_app	P2 阶段集成
from core.utils.instance_context import ...	已废弃（显式参数替代 os.environ 切换）

六、文件路径

旧路径	新路径
app/routes/v2/	fastapi_modules/fastapi_leaudit/controllers/
app/rbac/	fastapi_modules/fastapi_leaudit/services/impl/
services/leaudit_bridge/	fastapi_modules/fastapi_leaudit/leaudit_bridge/
core/config.py	fastapi_admin/config/
core/storage/	fastapi_common/ (通用化)

七、不允许做的事

• ❌ 在老 docauditai 基础上直接改代码
• ❌ 在新项目中引用 docauditai 的任何模块
• ❌ 在新项目中直接 import leaudit 内核（必须走 bridge）
• ❌ 跳过 Controller→Service→Model 分层直接写路由逻辑
• ❌ 数据库表不加中文注释
• ❌ 硬编码配置值