hyf-backend/README.md

## 项目简介
#
这是一个基于 **FastAPI** 的后端服务，提供「智能工作流」「知识库问答」「数据库智能查询」等能力，前端可以通过 REST API 调用这些能力。

### 主要目录结构（前端常用关注点）
- **`th_agenter/api/endpoints/`**：对外 HTTP 接口（路由）  
  - `auth.py`：登录、鉴权相关接口  
  - `users.py` / `roles.py`：用户与角色管理  
  - `chat.py` / `smart_chat.py` / `smart_query.py`：普通聊天、智能问答、智能查询  
  - `knowledge_base.py`：知识库管理（上传文档、构建向量库、检索）  
  - `workflow.py`：工作流定义、获取、执行等接口  
- **`th_agenter/services/`**：业务逻辑层，API 绝大部分会调用这里  
  - `workflow_engine.py` / `smart_workflow.py`：工作流执行引擎与智能工作流封装  
  - `knowledge_chat.py` / `document_processor.py` / `embedding_factory.py`：知识库问答、向量检索、文档处理  
  - `auth.py` / `user.py` 等：账号、权限等业务  
- **`th_agenter/schemas/`**：Pydantic 模型，定义接口请求/响应的数据结构  
- **`th_agenter/models/`**：SQLAlchemy 模型，对应数据库表结构  
- **`th_agenter/core/`**：应用配置、上下文、中间件、异常处理、权限控制等  
- **`th_agenter/db/`**：数据库连接、基础模型、Alembic 迁移脚本封装  
- **`utils/`**：日志（`util_log.py`）、文件、环境、异常等通用工具  
- **`scripts/`**：本地开发相关脚本（如 `start_local.sh`、`install_mysql.sh` 等）  
- **`data/`**：本地数据与向量库文件（如 Chroma 存储）  

### 核心能力与典型接口
- **鉴权与用户体系**
  - 登录、Token 相关接口在 `auth.py` 中定义，一般使用 Bearer Token 放在 `Authorization` 头里。
  - 用户、角色、权限相关接口在 `users.py`、`roles.py`、`core/simple_permissions.py` 等文件中。

- **聊天与智能问答**
  - 普通聊天接口：`chat.py`  
  - 智能聊天 / 智能问答：`smart_chat.py`、`smart_query.py`、`langchain_chat.py`  
  - 有些接口可能支持流式返回或长连接（如 SSE），可直接查看对应 endpoint 的返回类型。

- **知识库管理**
  - 相关接口在 `knowledge_base.py` 中，业务逻辑在 `services/knowledge_base.py`、`services/document_processor.py`、`services/knowledge_chat.py` 中。  
  - 支持上传文档（通常是 multipart）、构建向量库、基于文档进行问答。

- **工作流引擎**
  - 路由在 `workflow.py`，核心执行逻辑在 `services/workflow_engine.py`、`services/smart_workflow.py`、`services/workflow_engine.py` 中。  
  - 支持定义工作流、查询工作流详情、执行工作流，并在执行过程中写入日志/上下文（如 `session.desc`）。

### 前端对接小提示
- **接口文档**：服务启动后可以访问 `http://localhost:8000/docs` 查看 Swagger 文档（或 `/redoc`）。  
- **认证方式**：大多需要携带 `Authorization: Bearer <token>`，具体登录接口与返回字段可在 `auth.py` 与对应 `schemas` 中查看。  
- **上传文件**：知识库相关接口通常使用 `multipart/form-data`，前端可以用 `FormData` 构造请求。  
- **错误格式**：统一使用 FastAPI 的 JSON 错误响应格式，并在 `core/exceptions.py` 中做了封装，前端可以根据 `code`/`detail` 等字段做统一处理。  
- **调试追踪**：很多服务里会给 `session.desc` 等字段写入本次请求的行为描述（例如「获取工作流引擎」），方便在日志中排查问题。  

## 启动项目（本地）

1. 准备环境  
   - 推荐 Python 3.11+  
   - 创建并激活虚拟环境：`python3 -m venv .venv && source .venv/bin/activate`  
   - 依赖安装：`pip install -r requirements.txt`（若 requirements.txt 为 UTF-16，需要先转 UTF-8）

2. 配置数据库  
   - 确保本地 MySQL 运行，并创建数据库/账号（例）：  
     ```sql
     CREATE DATABASE allm DEFAULT CHARACTER SET utf8mb4;
     ALTER USER 'root'@'localhost' IDENTIFIED BY '*******';
     GRANT ALL PRIVILEGES ON allm.* TO 'root'@'localhost';
     FLUSH PRIVILEGES;
     ```  
   - 启动前设置环境变量：  
     ```bash
     export DATABASE_URL="******"
     ```

3. 迁移（首次必跑）  
   ```bash
   python -m alembic upgrade head
   ```

4. 启动服务  
   ```bash
   # 启动项目命令
   python3 -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload
   ```
5. 查看日志
   ```bash
   tail -f /tmp/uvicorn.log
   ```