# 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 分层直接写路由逻辑
- ❌ 数据库表不加中文注释
- ❌ 硬编码配置值