使用者痛点快速定位

• 架构杂乱缺少清晰模块划分导致后期维护成本高。
• 配置信息散落环境变量、数据库地址等四处张贴，调试困难。
• 部署繁琐本地与生产差异大，需要跑多条命令才能开启服务。
• 测试难以复现没有统一应用工厂导致单元测试互相污染。说起来，
• 技术栈陌生团队成员对所用库不熟悉，上手慢。

下面逐步拆解这些痛点，从项目结构到运行时配置。再到最小可行 API，让你快速搭建并验证 AIDataReport 工具。

---

本篇目标概述

前两篇已阐明 为什么做 与 MVP 做什么。此文开始进入实现阶段：

1. 建立清晰包结构，让模块位置一目了然。
2. 集中统一运行时配置。
3. 本地一键启动程序 PostgreSQL。
4. FastAPI 启动，并提供 /health 探活接口。怎么说呢，

---

技术选型概览

项目	推荐选型	用途
编程语言	Python	脚本灵活
Web 框架	FastAPI + Uvicorn	高性能 HTTP 服务
数据库存储	PostgreSQL	程序级租户、项目、审计等表
配置管理	pydantic‑settings + .env	环境变量集中读取
包管理	pyproject.toml + requirements.txt	可编辑安装与依赖锁定
CLI 工具	Typer	快速创建 CLI 接口

---

仓库目录规划

text ai-data-report/ ├─ configs/demo/sales/ ├─ docs/ ├─ src/ │  └─ biagent/ │      ├─ domain/ │      ├─ db/ │      ├─ configservice/ │      ├─ compiler/ │      ├─ reviewer/ │      ├─ executor/ │      ├─ formatter/ │      ├─ audit/ │      ├─ agent/ │      ├─ api/routes/ │     │   └─ health.py …┌──── pipeline.py ← 全流程编排 └──── cli.py ← Typer CLI 主程序 │   settings.py ← 环境变量解析中心 │   main.py ← ASGI 应用工厂

为什么采用 src 布局？

1. 强制 “安装后再导入”，防止误引用未完成代码。
2. 与 pytest --pythonpath=src 或 pip install -e . 配合自然。
3. 在 Docker 或 CI 中更易定位源文件。

---

项目声明与依赖文件

pyproject.toml

toml name = "bi-agent" version = ".0" description = "Configurable enterprise BI Agent platform " requires-python = ">=" dependencies = >=0","sqlalchemy>=0","psycopg>=0","pydantic>=0","pydantic-settings>=0","pyyaml>=0","sqlglot>=0","openpyxl>=0","typer>=0","httpx>=0",]

bi-agent = "bi_agent.cli:app"

"" = "src"

where=

pythonpath= testpaths=

requirements.txt

bash pip install -r requirements.txt pip install -e .

如需临时解决可编辑安装失败：

bash

至于$env，PYTHONPATH='src'

---

环境变量集中管理 – settings.py 与 .env.example

settings.py

python from functools import lrucache from pydanticsettings import BaseSettings,SettingsConfigDict

class Settings: modelconfig = SettingsConfigDict( envfile=".env",envfileencoding='utf-',extra='ignore' ) databaseurl : str ="postgresql+psycopg://biagent@localhost:/biagent" appenv : str ="dev" loglevel : str ="INFO" defaultquerylimit : int = maxquerylimit : int = querytimeoutseconds : int = maxsqllength : int = bailianapikey : str ="" bailianbaseurl : str ="https://dashscope.aliyuncs.com/compatible-mode/v1" bailianmodel : str ="qwen-plus"

@lrucache def getsettings -> Settings: return Settings

.env.example

复制为 .env 即可在本地开发：

dotenv DATABASE_URL=postgresql+psycopg://bi_agent@localhost:/bi_agent \ APP_ENV=dev LOG_LEVEL=INFO \ DEFAULT_QUERY_LIMIT=max QUERY_TIMEOUT_SECONDS=max_sql_length \ BAILIAN_API_KEY="" BAILIAN_BASE_URL=https://dashscope.aliyuncs.com \ BAILIAN_MODEL=qwen-plus

---

FastAPI 空壳 – main.py 与健康检查路由

main.py

python from fastapi import FastAPI from biagent import version from biagent.api.routes import config。health,query def createapp -> FastAPI: app = FastAPI( title='BI Agent',description='可配置公司报表 Agent 网站 ',version=version ) app.includerouter app.includerouter app.includerouter return app

app=create_app

/health

python from fastapi import APIRouter from bi_agent import __version__ router=APIRouter @router.get def health -> dict: return {"status":"ok","version":__version__}

包版本聚合

python __version__='.'

第一个单元测试 – 检测健康接口

python from fastapi.testclient import TestClient from bi_agent.main import create_app def test_health -> None: client=testclient.TestClient) resp=client.get assert resp.status_code==200,assert resp.json=="ok"

---

动手验证 – 本章验收步骤

1️⃣ 创建虚拟环境并激活：

bash python -m venv .venv && source .venv/bin/activate python --version

2️⃣ 安装依赖：

bash pip install -r requirements.txt && pip install -e . cp .env.example .env 或 copy .env.example .env

3️⃣ 开启服务：

bash uvicorn biagent.main:createapp --reload --app-dir src & curl http://127.0.0.1:{port}/health

4️⃣ 执行单元测试：

bash pytest tests/test_health.py -q

---

小结与接下来预告

本章完成了 AIDataReport 开发阶段的第一步先：

1️⃣ 按功能拆分模块。2️⃣ 使用 pydantic‑settings 集中读取运行时参数。3️⃣ Docker Compose 拉起程序 PostgreSQL。4️⃣ 用 FastAPI 应用工厂及 /health 探活证明进程正常。

👉 下一章《语义配置模型与程序库落库》将回答：

• 租户 → 项目 → Agent 如何建模？
• DataSource/Dataset/JOIN 等字段如何描述？
• Pydantic 模型与 ORM 表如何解耦？
• 如何通过 bi-agent init-db 建立程序表？

欢迎同行关注并指出问题，共同学习进步！说起来，

---