wren
134 lines
5.4 KiB
Markdown
134 lines
5.4 KiB
Markdown
# LeAudit 设计文档目录
|
||
|
||
本目录包含 `leaudit-platform` 项目的核心架构设计文档。
|
||
|
||
## 阅读顺序
|
||
|
||
1. `docs/HANDOFF.md`
|
||
2. `document_schema_design.md`
|
||
3. `dsl_rule_schema_design.md`
|
||
4. `bridge_directory_design.md`
|
||
5. `processing_logic.md`
|
||
6. `docs/规则编辑/README.md`
|
||
|
||
## 文档索引
|
||
|
||
| 文档 | 内容 | 状态 |
|
||
|------|------|------|
|
||
| [document_schema_design.md](document_schema_design.md) | 文档域表结构设计 — 17 张 `leaudit_*` 表完整说明 | ✅ 已落地 |
|
||
| [dsl_rule_schema_design.md](dsl_rule_schema_design.md) | DSL 规则域表结构 — 规则集/版本/绑定管理 | ✅ 核心表已落地 |
|
||
| [processing_logic.md](processing_logic.md) | LeAudit 7 阶段处理流水线说明 | 📖 参考文档 |
|
||
| [bridge_directory_design.md](bridge_directory_design.md) | Bridge 桥接层目录与职责设计 | ✅ 已落地 |
|
||
| [infrastructure_redesign.md](infrastructure_redesign.md) | 基础设施重设计 — OSS/队列/缓存/区域隔离 | 📋 设计蓝图 |
|
||
|
||
## 当前运行参数口径
|
||
|
||
- 并发与重试参数不再单独保留为独立说明文档
|
||
- 当前约定统一如下：
|
||
- 重试参数使用 `*_RETRY_MAX_ATTEMPTS`
|
||
- 退避参数使用 `*_RETRY_BACKOFF_BASE_SECONDS`
|
||
- 统一按指数退避计算等待时间
|
||
- 当前主要链路包括：
|
||
- LLM
|
||
- VLM
|
||
- OCR
|
||
- signature probe
|
||
- 相关代码位置：
|
||
- `fastapi_admin/config/_settings.py`
|
||
- `fastapi_modules/fastapi_leaudit/leaudit_bridge/client_factory.py`
|
||
- `fastapi_modules/fastapi_leaudit/leaudit_bridge/resilient_clients.py`
|
||
- `fastapi_modules/fastapi_leaudit/leaudit_bridge/ocr_bridge.py`
|
||
|
||
## 当前边界
|
||
|
||
- 当前“系统现状、已完成事项、剩余阻塞”统一看 `docs/HANDOFF.md`
|
||
- 本目录只保留相对稳定的后端架构、表结构、处理链路设计
|
||
- 原 `SYSTEM_OVERVIEW.md` 的阶段性现状内容已收口到 `docs/HANDOFF.md` 与本文件
|
||
|
||
## 快览
|
||
|
||
```
|
||
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 分层直接写路由逻辑
|
||
- ❌ 数据库表不加中文注释
|
||
- ❌ 硬编码配置值
|