docs: update README with project overview, directory structure, core capabilities, and frontend integration tips

README.md

@@ -1,3 +1,51 @@
+## 项目简介
+
+这是一个基于 **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. 准备环境