# asset_helper_backend 微服务基础架构（V1） 请一次性完整生成 asset_helper_backend Monorepo 微服务后端项目，严格遵循以下所有要求，确保所有文件可直接编译运行、Docker Compose 本地一键启动，无任何报错，代码风格统一、类型完整，完全适配单人+AI（Trae）的开发模式；同时需支持本机无额外环境（仅需安装Docker和Docker Compose）即可启动，且包含清晰的启动验证步骤，方便我确认项目启动效果；**本项目为第一版基础架构开发，仅搭建架构骨架，不包含任何业务逻辑**。 ## 一、严格锁定技术栈版本（一字不差，不可修改） 1. Gateway: FastAPI + WebSocket（唯一对外入口，负责HTTP请求转发和WebSocket实时通信，基于Starlette框架实现异步高并发通信，支持文本与二进制消息传输） 2. 微服务内部通信: FastAPI + gRPC（高性能跨服务通信，基于HTTP/2协议，支持双向流、头部压缩和多路复用，吞吐量优于传统REST API） 3. 数据库: PostgreSQL 18.3-alpine3.23（每个微服务独立DB实例，支持数据持久化和初始化脚本执行，配置健康检查确保服务可用性） 4. 缓存/消息: Redis 8.6.2-alpine（轻量级缓存，支持高并发访问，配置健康检查） 5. 容器化: Docker + Docker Compose（实现服务隔离与快速部署，区分本地开发和生产环境配置） 6. Python: 3.13.7-alpine3.22（轻量级基础镜像，体积小巧，适合容器化部署，支持异步I/O操作） 7. 依赖管理: pyproject.toml + uv（全局统一依赖管理，启用uv workspaces，整合所有子服务依赖） 8. 开发模式: 单人+AI（Trae），Monorepo架构，微服务独立部署、可扩展 ## 二、严格遵循目录结构（一字不差，所有文件必须生成，无遗漏） asset_helper_backend/ ├── docker-compose.yml # 本地开发配置（不变，包含所有服务及健康检查） ├── docker-compose.prod.yml # 生产环境配置（不变，无挂载、配置重启策略） ├── .env.example # 环境变量模板（包含所有必要环境变量，可直接复制为.env使用） ├── Makefile # 单人+AI通用命令入口（实现所有核心命令，可直接执行） ├── .gitignore # 避免AI提交冲突（忽略.env、虚拟环境、编译文件等） ├── pyproject.toml # 全局Python依赖规范（启用uv workspaces，统一依赖版本） ├── scripts/ # 可直接执行脚本（权限配置为可执行，无需手动修改） │ ├── init-db.sh # 初始化数据库，为每个微服务创建独立库、用户和权限 │ └── proto-gen.sh # 编译gRPC协议文件，输出到各服务指定目录 ├── shared/ # 共享核心包（纯工具、无业务逻辑，可被所有服务依赖，贴合第一版基础架构定位） │ ├── src/shared/ │ │ ├── models/ # Pydantic基模型和SQLAlchemy基类 │ │ ├── exceptions/ # 统一异常类和异常处理器 │ │ ├── middleware/ # 通用中间件（关联ID、日志、异常处理） │ │ ├── utils/ # 工具类（配置加载、日志、安全、gRPC/Redis客户端） │ │ └── proto/ # gRPC协议定义文件（先创建user.proto） │ ├── pyproject.toml # 共享包依赖配置 │ └── Dockerfile # 共享包构建配置 ├── services/ # 微服务目录（单人+AI开发，可无限新增） │ ├── gateway/ # 对外入口：HTTP + WebSocket，仅搭建基础框架，无业务逻辑处理 │ │ ├── app/ │ │ │ ├── api/ # HTTP路由（转发到gRPC服务） │ │ │ ├── ws/ # WebSocket处理（连接管理、消息处理） │ │ │ ├── core/ # 配置、启动、依赖注入 │ │ │ └── main.py # FastAPI实例启动（包含HTTP和WebSocket） │ │ ├── Dockerfile # 基于python:3.13.7-alpine3.22构建，启动uvicorn │ │ └── requirements.txt # 网关服务依赖 │ └── user-service/ # 用户微服务：纯gRPC接口，无HTTP，仅搭建基础框架，无业务逻辑 │ ├── app/ │ │ ├── api/ # gRPC服务实现（对应proto定义的所有方法） │ │ ├── core/ # 配置（继承shared.config） │ │ ├── db/ # 异步SQLAlchemy会话和User模型 │ │ └── main.py # gRPC服务器启动 │ ├── Dockerfile # 基于python:3.13.7-alpine3.22构建，启动gRPC服务 │ └── requirements.txt # 用户服务依赖 └── infra/ # 基础设施（不变，包含数据库、缓存、反向代理配置） ├── postgres/ # PostgreSQL相关配置（数据持久化、初始化） ├── redis/ # Redis相关配置（数据持久化） └── nginx/ # Nginx反向代理配置 ## 三、核心文件具体要求（必须完全实现，不可省略） ### 1. 根目录文件 （1）pyproject.toml：指定Python 3.13.7，全局依赖包含fastapi、uvicorn、grpcio、grpcio-tools、pydantic、sqlalchemy、asyncpg、redis、python-dotenv、loguru；开发依赖包含ruff、pytest、pytest-asyncio、pre-commit；启用uv workspaces，包含shared/、services/gateway/、services/user-service/。 （2）Makefile：必须实现all、build、up、down、logs、proto-gen、init-db、test、lint命令，命令可直接执行，无需手动修改。 （3）.gitignore：忽略.env、__pycache__、.venv、*.pyc、dist/、build/、*.log、docker-compose.override.yml。 （4）scripts/proto-gen.sh：自动编译shared/src/shared/proto/**/*.proto文件，输出到各服务的app/grpc_generated/目录，添加可执行权限，可直接运行。 （5）scripts/init-db.sh：为每个微服务创建独立PostgreSQL库、用户、权限，添加可执行权限，可直接运行，支持数据库初始化脚本执行。 （6）.env.example：包含ENV、DEBUG、POSTGRES_USER、POSTGRES_PASSWORD、REDIS_URL、GRPC_PORT、HTTP_PORT等必要环境变量，标注默认值。 ### 2. shared共享包 （1）shared/pyproject.toml：名称为asset_helper_shared，依赖包含fastapi、pydantic、grpcio、sqlalchemy、asyncpg、redis、loguru。 （2）shared.models：实现BaseModel（Pydantic基类）、BaseDBModel（SQLAlchemy基类，含id、created_at、updated_at字段）。 （3）shared.exceptions：实现AppException（基类），以及NotFoundError、UnauthorizedError、ForbiddenError、BadRequestError、InternalError等具体异常，同时实现全局异常处理器（可被gateway直接使用）。 （4）shared.middleware：实现CorrelationIdMiddleware、LoggingMiddleware、ExceptionMiddleware，适配FastAPI异步请求流程。 （5）shared.utils：实现config.py（Pydantic Settings加载环境变量）、logger.py（loguru全局日志配置）、security.py（JWT生成与验证、密码哈希）、grpc_client.py（gRPC客户端基类，支持服务调用）、redis_client.py（Redis连接池配置，支持异步操作）。 （6）shared/proto/user.proto：定义UserService服务，包含GetUser、CreateUser、UpdateUser、DeleteUser、ListUsers五个接口，指定proto3版本，定义请求和响应消息结构，字段编号合理分配；仅定义基础接口模板，不包含任何业务规则和业务字段设计，贴合基础架构定位。 ### 3. user-service（纯gRPC微服务） （1）技术与端口：Python 3.13.7-alpine3.22，gRPC服务监听0.0.0.0:50051，独立PostgreSQL库为user_db。 （2）目录实现：app/main.py启动gRPC服务器；app/core/config.py继承shared.config；app/db/session.py实现异步SQLAlchemy会话；app/db/models.py实现User模型（继承shared.models.BaseDBModel），仅包含基础字段，无业务相关字段；app/api/user_service.py实现UserService所有gRPC方法（仅模拟基础数据库CRUD操作，无任何业务逻辑和业务规则）；app/grpc_generated/目录用于存放自动生成的gRPC代码。 （3）Dockerfile：基于python:3.13.7-alpine3.22，安装依赖、复制代码、启动gRPC服务，配置健康检查。 ### 4. gateway（对外入口） （1）技术与端口：FastAPI + WebSocket，HTTP服务监听0.0.0.0:8000，WebSocket端点为/ws，内部调用user-service:50051的gRPC服务。 （2）目录实现：app/main.py创建FastAPI实例，集成HTTP和WebSocket；app/core/config.py配置服务参数；app/api/v1/users.py实现用户HTTP CRUD路由（仅负责转发到gRPC服务，无任何业务逻辑处理）；app/ws/manager.py实现WebSocket连接管理器（支持多连接管理）；app/ws/handlers.py实现用户消息处理（支持文本和二进制消息，无业务相关消息处理逻辑）；app/dependencies.py实现gRPC客户端注入。 （3）Dockerfile：基于python:3.13.7-alpine3.22，安装依赖、复制代码、启动uvicorn（支持WebSocket），配置健康检查。 ### 5. Docker Compose配置 （1）docker-compose.yml（本地）：包含postgres（18.3-alpine3.23）、redis（8.6.2-alpine）、user-service、gateway四个服务；所有服务加入asset_helper_net网络；配置服务依赖健康检查（postgres使用pg_isready检查，redis使用redis-cli ping检查）；环境变量从.env读取；配置数据持久化卷；无需本机安装Python、PostgreSQL、Redis等依赖，仅需Docker和Docker Compose即可启动；新增启动前置说明（告知需先安装Docker和Docker Compose，以及复制.env.example为.env的步骤）。 （2）docker-compose.prod.yml（生产）：无本地文件挂载；配置服务重启策略为always；仅暴露gateway:8000端口，其他服务不对外暴露端口；强化安全配置，移除开发环境冗余参数。 ## 四、最终交付要求（必须满足，否则需重新调整） 1. 所有技术栈版本严格匹配，无任何版本偏差； 2. 目录结构与要求完全一致，无遗漏、无多余文件； 3. 执行make proto-gen可正常生成gRPC代码，无编译错误； 4. 执行make init-db可正常初始化所有微服务的独立数据库； 5. 执行make up可一键启动所有容器，所有服务健康运行，无报错； 6. 访问gateway:8000/docs可正常打开Swagger文档，查看HTTP接口； 7. gateway的WebSocket端点/ws可正常连接，支持消息收发； 8. user-service的gRPC端口50051可正常连通，gateway能正常调用其gRPC接口； 9. shared共享包可被所有服务正常导入，无导入错误； 10. 代码类型标注完整，符合Python规范，无语法错误、无冗余代码； 11. 所有脚本可直接执行，无需手动修改权限或配置； 12. 项目支持后续新增微服务，扩展灵活，不影响现有服务运行； 13. 本机无Python、PostgreSQL、Redis等环境也可正常启动，仅需安装Docker和Docker Compose，Trae需在项目根目录生成清晰的「本地启动&验证步骤文档」（命名为STARTUP_VERIFY.md）； 14. STARTUP_VERIFY.md需包含：Docker和Docker Compose安装指引（极简版）、复制.env.example为.env的操作步骤、执行make up启动服务的命令、服务启动后验证步骤（含Swagger访问、WebSocket连接、gRPC连通性的具体操作和预期结果）、常见启动报错排查方法； 15. 启动验证步骤需简单易懂，无需专业技术背景，可直接按步骤操作确认项目启动效果，确保每一步验证都有明确的操作命令和预期反馈； 16. 全程严格遵循“第一版基础架构”定位，所有代码仅包含架构层、工具层实现，不涉及任何业务逻辑、业务规则、业务字段，不添加任何与具体业务相关的代码或配置； 17. user-service的User模型仅包含基础通用字段（如id、created_at、updated_at、username、password_hash），不添加任何业务相关字段（如角色、权限、业务关联信息等），gRPC方法仅实现基础CRUD，无业务逻辑判断。 > （注：文档部分内容可能由 AI 生成）