在生成任何代码、配置文件、部署脚本或执行终端命令时，必须严格遵守以下配置，严禁使用任何替代工具：

• 操作系统与部署环境
  • 目标环境为 Linux。所有路径分隔符、Shell 脚本（.sh）、Docker 配置必须完全兼容 Linux 环境。
• Python 环境与包管理
  • 工具锁定：强制使用 uv 进行统一管理。
  • 禁止词：严禁在指令或解答中输出 pip install、conda、poetry 或 pipenv。
  • 正确指令：添加依赖使用 uv add <package>，运行服务使用 uv run。
• JavaScript 环境
  • 运行时与包管理器锁定：强制使用 bun。
  • 禁止词：严禁在指令或解答中输出 npm、yarn 或 pnpm。
  • 正确指令：安装依赖使用 bun install，运行项目使用 bun run。

• 设计范式：接口抽象、单例模式 (Singleton)、依赖注入 (DI)、策略模式。
• Pythonic 规范：遵循 Zen of Python，严格执行 PEP 8 与 PEP 257 规范。强制全量类型注解，注释与 Docstring 必须使用中文。
• 研发原则：DRY (Don't Repeat Yourself)，高内聚低耦合，可读性 > 复杂度。
• 规划锁定 (Planning Lock)：在核心架构与修改步骤（Plan/Spec）获得用户明确首肯前，绝对不动手修改任何业务代码。

• 首查原则 (Search-First)：在完全加载/通读长文件前，优先使用搜索工具 (grep/ripgrep) 寻找关键代码段。对于超过 200 行的文件仅限读取特定行范围，拒绝无脑通读以防止上下文污染。
• 硬性实证 (Proof Required)：严禁主观宣称“这应该可以”、“看起来是对的”。在声明任务完成前，必须提供真实的运行结果（如 curl 响应、单元测试输出或调试日志截图）。
• 拒绝伪造：严禁使用 pass 占位，所有编写的代码均必须具备真实的、可运行的业务逻辑。
• 逐个击破：优先使用标准库，善于利用 Python REPL 或编写独立脚本交互式验证局部组件。
• 坚韧调试：深度依赖 pdb 交互式调试与高可读性的结构化日志。若连续 3 次调试失败，必须进行状态同步，梳理问题并重新规划。

• 框架/服务器：FastAPI (>=0.88.0) | Uvicorn (>=0.21.1)
• ORM与驱动：SQLAlchemy 2.0+ 异步体系 | aiosqlite (默认 SQLite), asyncmy (MySQL), asyncpg (PostgreSQL)
• 格式化与格式约束：black (行宽 160)

helloFastAPI/
└── backend/
    ├── src/
    │   ├── Auth/           # 用户认证模块 (接口：/api/auth/*)
    │   ├── FileCodeBox/    # 文件提取盒子模块 (未启用，入口在 appInit 被注释)
    │   ├── common/         # 公共库 (包含异常捕获 exceptions 和响应序列化 schemas)
    │   ├── tools/L/        # 全局 Logger 记录器
    │   ├── appInit.py      # 服务路由注册与全局中间件挂载
    │   ├── main.py         # 挂载入口，直接运行 Uvicorn 服务
    │   └── settings.py     # 自动生成并加载本地 .env 配置
    ├── pyproject.toml      # PEP 621 声明文件与 black 配置
    ├── uv.lock             # uv 依赖精确版本锁定文件
    └── .venv/              # uv 自动管理和构建的本地虚拟环境

• 所有 I/O 操作均必须使用 async / await 异步机制。
• 路由端点内获取数据库会话，必须使用依赖注入获取异步 Session：

  from sqlalchemy.ext.asyncio import AsyncSession
  from src.common import get_async_session
  
  @router.post("/example")
  async def do_action(session: AsyncSession = Depends(get_async_session)):
      ...

• 所有数据表模型必须继承 src.common.CommonAttr（自带 uid UUID、created_at、updated_at、deleted_at 字段）。

• 成功返回：接口必须强制使用 src.common.ResponseModel 包装：

  from src.common import ResponseModel
  
  @router.get("/data", response_model=ResponseModel[SomeSchema])
  async def get_data() -> ResponseModel:
      return ResponseModel(data=...)

• 异常抛出：禁发原始状态码，必须抛出 src.common.APIException 及其具体子类（如 BadRequestException、ConflictException、ForbiddenException、NotFoundException、UnAuthenticatedException）。

1. 添加依赖

   uv add <package_name>

2. 本地运行服务

   # 在 backend 目录下启动
   PYTHONPATH=. uv run uvicorn src.main:helloFastApi --reload --host 127.0.0.1 --port 8000

3. JavaScript 项目集成（如前端）

   # 安装依赖
   bun install
   # 启动项目
   bun run dev

4. 提交规范 (Commit Conventions)
   • 格式要求：强制使用 type(scope): description（例如 feat(auth): 新增登录路由）。
   • 常用类型：feat（新特性）、fix（Bug修复）、docs（文档更新）、refactor（重构且无行为变更）、test（新增/更新测试）、chore（构建配置/依赖变动）。
   • 原子提交：坚持“一任务一提交”，且每次提交前必须在本地验证通过。