# Admin Service 开发指南 ## 目录 - [1. 开发环境设置](#1-开发环境设置) - [2. 项目初始化](#2-项目初始化) - [3. 开发流程](#3-开发流程) - [4. 代码规范](#4-代码规范) - [5. 调试技巧](#5-调试技巧) - [6. 常见开发任务](#6-常见开发任务) --- ## 1. 开发环境设置 ### 1.1 系统要求 | 工具 | 版本要求 | 说明 | |-----|---------|------| | **Node.js** | >= 20.x | 推荐使用 LTS 版本 | | **npm** | >= 10.x | 或使用 yarn/pnpm | | **PostgreSQL** | >= 16.x | 本地开发或 Docker | | **Docker** | >= 24.x | (可选) 容器化开发 | | **Git** | >= 2.x | 版本控制 | | **VSCode** | 最新版 | 推荐 IDE | ### 1.2 VSCode 推荐插件 ```json { "recommendations": [ "dbaeumer.vscode-eslint", // ESLint "esbenp.prettier-vscode", // Prettier "prisma.prisma", // Prisma "firsttris.vscode-jest-runner", // Jest Runner "orta.vscode-jest", // Jest "ms-vscode.vscode-typescript-next", // TypeScript "usernamehw.errorlens", // Error Lens "eamodio.gitlens" // GitLens ] } ``` 保存到 `.vscode/extensions.json` ### 1.3 VSCode 工作区设置 ```json { "editor.formatOnSave": true, "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.codeActionsOnSave": { "source.fixAll.eslint": true }, "typescript.preferences.importModuleSpecifier": "relative", "jest.autoRun": "off", "[prisma]": { "editor.defaultFormatter": "Prisma.prisma" } } ``` 保存到 `.vscode/settings.json` --- ## 2. 项目初始化 ### 2.1 克隆项目 ```bash git clone https://github.com/your-org/rwa-durian.git cd rwa-durian/backend/services/admin-service ``` ### 2.2 安装依赖 ```bash # 使用 npm npm install # 或使用 yarn yarn install # 或使用 pnpm pnpm install ``` ### 2.3 环境配置 创建 `.env.development` 文件： ```env # 应用配置 NODE_ENV=development APP_PORT=3005 API_PREFIX=api/v1 # 数据库配置 DATABASE_URL=postgresql://postgres:password@localhost:5432/admin_service_dev?schema=public # 日志配置 LOG_LEVEL=debug # CORS 配置 CORS_ORIGIN=http://localhost:3000,http://localhost:3001 ``` **注意**: 不要提交 `.env.*` 文件到 Git！已添加到 `.gitignore`。 ### 2.4 数据库初始化 #### 方案 1: 本地 PostgreSQL ```bash # 1. 创建数据库 psql -U postgres -c "CREATE DATABASE admin_service_dev;" # 2. 运行迁移 npm run prisma:migrate:dev # 3. 生成 Prisma Client npm run prisma:generate ``` #### 方案 2: Docker PostgreSQL ```bash # 1. 启动数据库容器 docker run -d \ --name admin-dev-db \ -e POSTGRES_USER=postgres \ -e POSTGRES_PASSWORD=password \ -e POSTGRES_DB=admin_service_dev \ -p 5432:5432 \ postgres:16-alpine # 2. 运行迁移 npm run prisma:migrate:dev # 3. 生成 Prisma Client npm run prisma:generate ``` ### 2.5 验证环境 ```bash # 检查数据库连接 npm run prisma:studio # 运行测试 npm run test:unit # 启动开发服务器 npm run start:dev ``` 访问 `http://localhost:3005/api/v1/health` 应返回: ```json {"status": "ok"} ``` --- ## 3. 开发流程 ### 3.1 Git 工作流 #### 分支策略 ``` main (生产) ↑ develop (开发) ↑ feature/xxx (功能分支) hotfix/xxx (紧急修复) ``` #### 创建功能分支 ```bash # 从 develop 创建功能分支 git checkout develop git pull origin develop git checkout -b feature/add-version-delete # 开发... # 提交 git add . git commit -m "feat(version): add delete version functionality" # 推送 git push origin feature/add-version-delete # 创建 Pull Request ``` #### Commit Message 规范 遵循 [Conventional Commits](https://www.conventionalcommits.org/): ``` ():