AIRegulation-DocAnalysis/backend/README.md

# AI+合规智能中枢后端

`backend` 是当前正式使用的 FastAPI 后端目录，入口为 `app.main:app`。

## 架构约束入口

- Backend authoritative architecture 文档：`docs/architecture/backend-project-architecture.md`
- Backend migration RFC：`docs/rfc/backend-api-parsing-embedding-migration-requirements.md`
- 后续 backend 新增功能和重构默认遵守：`api -> application -> domain ports -> infrastructure`
- `backend/app/services/*` 与 `backend/app/workflows/*` 为迁移期 legacy 目录，除迁移或兼容修复外，不应新增业务编排逻辑。

## 启动

```bash
pip install -r backend/requirements.txt
PYTHONPATH=backend uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

也可以直接使用根目录统一脚本：

```bash
./dev.sh start api --foreground
```

## 主要接口

- `GET /health`
- `GET /`
- `POST /api/v1/documents/upload`
- `GET /api/v1/documents/list`
- `GET /api/v1/documents/management-list`
- `GET /api/v1/documents/download/{doc_id}`
- `POST /api/v1/knowledge/search`
- `POST /api/v1/knowledge/retrieval`
- `POST /api/v1/agent/ask`
- `POST /api/v1/agent/chat`
- `GET /api/v1/agent/chat/stream`

## 目录说明

```text
backend/
├── app/
│   ├── api/              # FastAPI 路由与 transport models
│   ├── application/      # 用例编排层
│   ├── domain/           # 核心业务模型与稳定端口
│   ├── infrastructure/   # 外部系统适配器
│   ├── shared/           # composition root 与横切支撑
│   ├── config/           # 配置与日志
│   ├── services/         # legacy façade / 兼容入口
│   ├── workflows/        # legacy workflow 入口
│   └── workers/          # 任务相关代码
├── .env.example
├── requirements.txt
└── main.py
```

## 说明

- 路由前缀保持为 `/api/v1`，以兼容当前前端。
- 当前主业务链路入口是 `documents`、`knowledge`、`agent`。
- `compliance.py` 当前仍被挂载，但尚未满足目标架构约束；在迁移前不应继续扩展业务编排。
- `docs.py` 与 `rag.py` 为遗留/非主入口，不应继续扩展。

## 开发约束

- backend 开发前先阅读 `docs/architecture/backend-project-architecture.md`。
- 新增业务能力默认落在 `application` 层，由 `api` 调用，不要直接写进 route。
- route 不应直接访问 MinIO、Milvus、Parser SDK、LLM SDK 或 `ConversationStore`。
- `backend/app/shared/bootstrap.py` 是当前 composition root；依赖装配优先收口到这里。