docs: add fix-double-finalize-and-bindings-api implementation plan
This commit is contained in:
wren
@@ -0,0 +1,100 @@
|
||||
# LeAudit 设计文档目录
|
||||
|
||||
本目录包含 `leaudit-platform` 项目的核心架构设计文档。
|
||||
|
||||
## 文档索引
|
||||
|
||||
| 文档 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| [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/队列/缓存/区域隔离 | 📋 设计蓝图 |
|
||||
|
||||
## 快览
|
||||
|
||||
```
|
||||
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 分层直接写路由逻辑
|
||||
- ❌ 数据库表不加中文注释
|
||||
- ❌ 硬编码配置值
|
||||
Reference in New Issue
Block a user