# augment-用户管理

**Repository Path**: slcnx/augment-user-management

## Basic Information

- **Project Name**: augment-用户管理
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-01
- **Last Updated**: 2025-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 用户管理系统

基于 Django + React + TypeScript + Ant Design 的全栈用户管理应用。

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/your-repo/releases)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](docker-compose.yml)

## 技术栈

### 后端
- Django 5.2+
- Django REST Framework
- djangorestframework-simplejwt (JWT认证)
- drf-spectacular (OpenAPI 3.0文档)
- django-cors-headers (跨域支持)
- PostgreSQL (生产) / SQLite (开发)

### 前端
- React 19 + TypeScript 5.8+
- UmiMax (构建工具)
- Ant Design 5.15+ (UI组件库)
- Zustand (状态管理)
- 自动生成的TypeScript API客户端

## 项目结构

```
project-root/
├── backend/                    # Django后端
│   ├── core/                   # 核心配置
│   ├── apps/                   # 应用模块
│   │   ├── common/             # 通用工具
│   │   ├── authentication/    # 用户认证
│   │   └── users/              # 用户管理
│   ├── requirements.txt        # Python依赖
│   └── manage.py              # Django管理工具
├── frontend/                   # React前端
│   ├── public/                # 静态资源
│   │   └── config.js          # 运行时配置
│   ├── src/                   # 源代码
│   │   ├── components/        # 可复用组件
│   │   ├── pages/            # 页面组件
│   │   ├── services/         # API服务
│   │   └── utils/            # 工具函数
│   └── package.json          # 前端依赖
└── docs/                      # 项目文档
```

## 快速开始

### 后端启动

```bash
cd backend
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate

pip install -r requirements.txt
python manage.py migrate
python manage.py runserver 8001
```

### 前端启动

```bash
cd frontend
npm install
npm run dev
```

## 开发说明

### API文档
- 开发环境: http://localhost:8001/api/docs/
- Schema: http://localhost:8001/api/schema/

### 前端代理
前端开发服务器会自动代理 `/api` 请求到后端 `http://localhost:8001`

### API客户端生成
```bash
cd frontend
npm run gen:dev
```

## 功能特性

- 用户注册/登录
- JWT Token认证
- 用户列表管理
- 用户信息CRUD
- 权限控制
- 响应式设计
- 自动API文档生成
- 统一错误处理

## 部署

### 生产环境配置
1. 修改 `frontend/public/config.js` 中的 API_BASE_PATH
2. 配置后端数据库和环境变量
3. 构建前端: `npm run build`
4. 部署后端和前端静态文件

## 🐳 Docker部署

### 快速部署
```bash
# 一键部署
./deploy.sh

# 或手动部署
docker-compose up -d --build
```

### 环境切换
```bash
# 切换到开发环境
./env.sh dev
docker-compose up -d --build

# 切换到生产环境
./env.sh prod
docker-compose up -d --build
```

### 访问地址
- **前端**: http://localhost
- **后端API**: http://localhost:8000/api/
- **Django Admin**: http://localhost:8000/admin/
- **API文档**: http://localhost:8000/api/docs/

### 默认账号
- **用户名**: admin
- **密码**: admin123

详细部署说明请参考 [DEPLOYMENT.md](DEPLOYMENT.md)

## 📋 项目管理与版本控制

### 🏷️ 版本管理策略

本项目采用 **语义化版本控制 (Semantic Versioning)**：

- **主版本号 (MAJOR)**: 不兼容的API修改
- **次版本号 (MINOR)**: 向下兼容的功能性新增
- **修订号 (PATCH)**: 向下兼容的问题修正

当前版本：**v1.0.0** (稳定版本)

### 🌿 分支管理策略

采用 **Git Flow** 工作流，结合 `version.sh` 脚本实现自动化管理：

```mermaid
gitGraph
    commit id: "Initial"
    branch develop
    checkout develop
    commit id: "Setup"

    branch feature/user-profile
    checkout feature/user-profile
    commit id: "Add profile"
    commit id: "Add avatar"

    checkout develop
    merge feature/user-profile
    commit id: "Merge feature"

    branch release/v1.1.0
    checkout release/v1.1.0
    commit id: "Prepare release"
    commit id: "Fix bugs"

    checkout main
    merge release/v1.1.0
    commit id: "Release v1.1.0"

    checkout develop
    merge release/v1.1.0

    checkout main
    branch hotfix/v1.1.1
    checkout hotfix/v1.1.1
    commit id: "Critical fix"

    checkout main
    merge hotfix/v1.1.1
    commit id: "Hotfix v1.1.1"

    checkout develop
    merge hotfix/v1.1.1
```

#### 分支说明

- **`main`**: 生产环境分支，只包含稳定的发布版本
- **`develop`**: 开发分支，包含最新的开发功能
- **`feature/*`**: 功能分支，用于开发新功能
- **`release/*`**: 发布分支，用于准备新版本发布
- **`hotfix/*`**: 热修复分支，用于紧急修复生产问题

### 🚀 开发工作流

#### 🔄 完整开发流程图

```mermaid
flowchart TD
    A[项目初始化] --> B{选择开发类型}

    B -->|新功能| C[功能开发流程]
    B -->|版本发布| D[发布流程]
    B -->|紧急修复| E[热修复流程]

    C --> C1[./version.sh feature start name]
    C1 --> C2[在 feature/name 分支开发]
    C2 --> C3[提交代码并测试]
    C3 --> C4[./version.sh feature finish name]
    C4 --> C5[合并到 develop 分支]

    D --> D1[./version.sh release start v1.x.0]
    D1 --> D2[在 release/v1.x.0 分支测试]
    D2 --> D3[修复发现的问题]
    D3 --> D4[./version.sh release finish v1.x.0]
    D4 --> D5[合并到 main 并打标签]
    D5 --> D6[部署到生产环境]

    E --> E1[./version.sh hotfix start v1.x.1]
    E1 --> E2[在 hotfix/v1.x.1 分支修复]
    E2 --> E3[紧急测试验证]
    E3 --> E4[./version.sh hotfix finish v1.x.1]
    E4 --> E5[合并到 main 和 develop]
    E5 --> E6[立即部署修复]

    C5 --> F[继续开发或准备发布]
    D6 --> F
    E6 --> F

    style C fill:#e1f5fe
    style D fill:#f3e5f5
    style E fill:#ffebee
```

#### 🛠️ 使用 version.sh 脚本管理

我们的 `version.sh` 脚本自动化了整个Git Flow流程：

```mermaid
sequenceDiagram
    participant Dev as 开发者
    participant Script as version.sh
    participant Git as Git仓库
    participant CI as CI/CD

    Note over Dev,CI: 功能开发流程
    Dev->>Script: ./version.sh feature start user-profile
    Script->>Git: 创建 feature/user-profile 分支
    Dev->>Dev: 开发功能代码
    Dev->>Script: ./version.sh feature finish user-profile
    Script->>Git: 合并到 develop 分支
    Git->>CI: 触发测试环境部署

    Note over Dev,CI: 版本发布流程
    Dev->>Script: ./version.sh release start v1.1.0
    Script->>Git: 创建 release/v1.1.0 分支
    Dev->>Dev: 测试和bug修复
    Dev->>Script: ./version.sh release finish v1.1.0
    Script->>Git: 合并到 main 并创建标签
    Git->>CI: 触发生产环境部署

    Note over Dev,CI: 热修复流程
    Dev->>Script: ./version.sh hotfix start v1.1.1
    Script->>Git: 从 main 创建 hotfix/v1.1.1
    Dev->>Dev: 紧急修复问题
    Dev->>Script: ./version.sh hotfix finish v1.1.1
    Script->>Git: 合并到 main 和 develop
    Git->>CI: 立即部署修复
```

#### 1. 开发新功能 (自动化)
```bash
# 使用脚本自动化创建功能分支
./version.sh feature start user-profile-enhancement

# 开发完成后自动化合并
./version.sh feature finish user-profile-enhancement
```

**脚本自动执行的操作**:
- 切换到 develop 分支
- 拉取最新代码
- 创建功能分支
- 合并完成后删除功能分支

#### 2. 发布新版本 (自动化)
```bash
# 使用脚本自动化创建发布分支
./version.sh release start v1.1.0

# 在发布分支进行测试和调整后，自动化完成发布
./version.sh release finish v1.1.0
```

**脚本自动执行的操作**:
- 从 develop 创建 release 分支
- 合并到 main 分支
- 创建版本标签
- 合并回 develop 分支
- 推送所有更改到远程仓库

#### 3. 紧急修复 (自动化)
```bash
# 使用脚本自动化创建热修复分支
./version.sh hotfix start v1.1.1

# 修复完成后自动化合并
./version.sh hotfix finish v1.1.1
```

**脚本自动执行的操作**:
- 从 main 创建 hotfix 分支
- 合并到 main 分支并打标签
- 合并到 develop 分支
- 删除热修复分支

#### 📊 版本管理状态图

```mermaid
stateDiagram-v2
    [*] --> Development

    Development --> FeatureBranch : ./version.sh feature start
    FeatureBranch --> Development : ./version.sh feature finish

    Development --> ReleaseBranch : ./version.sh release start
    ReleaseBranch --> Production : ./version.sh release finish
    ReleaseBranch --> Development : merge back

    Production --> HotfixBranch : ./version.sh hotfix start
    HotfixBranch --> Production : ./version.sh hotfix finish
    HotfixBranch --> Development : merge back

    Production --> [*] : stable release

    note right of FeatureBranch
        功能开发
        - 新功能实现
        - 单元测试
        - 代码审查
    end note

    note right of ReleaseBranch
        发布准备
        - 集成测试
        - 性能测试
        - 文档更新
    end note

    note right of HotfixBranch
        紧急修复
        - 安全漏洞
        - 严重bug
        - 生产问题
    end note
```

### 🏷️ 标签管理

#### 创建标签
```bash
# 创建带注释的标签
git tag -a v1.0.0 -m "Initial stable release"

# 推送标签到远程
git push origin --tags

# 推送单个标签
git push origin v1.0.0
```

#### 查看标签
```bash
# 列出所有标签
git tag

# 查看特定标签信息
git show v1.0.0

# 检出特定版本
git checkout v1.0.0
```

### 📝 提交规范

采用 **Conventional Commits** 规范：

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

#### 提交类型
- **feat**: 新功能
- **fix**: 修复bug
- **docs**: 文档更新
- **style**: 代码格式调整
- **refactor**: 代码重构
- **test**: 测试相关
- **chore**: 构建过程或辅助工具的变动

#### 示例
```bash
git commit -m "feat(auth): add password reset functionality"
git commit -m "fix(users): resolve pagination issue in user list"
git commit -m "docs: update API documentation"
```

### 🔄 持续集成/部署

#### 🌍 环境管理流程

```mermaid
flowchart LR
    subgraph "代码分支"
        F[feature/*]
        D[develop]
        M[main]
    end

    subgraph "环境部署"
        DEV[开发环境<br/>localhost:3000]
        STAGE[测试环境<br/>staging.domain.com]
        PROD[生产环境<br/>domain.com]
    end

    subgraph "部署脚本"
        ENV1[./env.sh dev]
        ENV2[./env.sh prod]
        DEPLOY[./deploy.sh]
    end

    F -->|开发测试| DEV
    D -->|自动部署| STAGE
    M -->|手动部署| PROD

    DEV -.->|使用| ENV1
    STAGE -.->|使用| ENV2
    PROD -.->|使用| DEPLOY

    style DEV fill:#e8f5e8
    style STAGE fill:#fff3cd
    style PROD fill:#f8d7da
```

#### 🚀 部署自动化流程

```mermaid
sequenceDiagram
    participant Dev as 开发者
    participant Git as Git仓库
    participant CI as CI/CD系统
    participant Docker as Docker环境
    participant Env as 目标环境

    Note over Dev,Env: 开发环境部署
    Dev->>Git: 推送到 feature 分支
    Dev->>Docker: ./env.sh dev
    Docker->>Docker: 切换开发配置
    Dev->>Docker: docker-compose up -d
    Docker->>Env: 部署到开发环境

    Note over Dev,Env: 测试环境部署
    Dev->>Git: 合并到 develop 分支
    Git->>CI: 触发自动构建
    CI->>Docker: ./env.sh prod (测试配置)
    CI->>Docker: docker-compose up -d --build
    Docker->>Env: 自动部署到测试环境

    Note over Dev,Env: 生产环境部署
    Dev->>Git: 合并到 main 分支并打标签
    Git->>CI: 触发生产部署
    CI->>Docker: ./deploy.sh
    Docker->>Docker: 构建生产镜像
    Docker->>Env: 部署到生产环境
    Env->>Dev: 部署完成通知
```

#### 环境对应关系
- **`feature/*`** → 开发环境 (Development) - `./env.sh dev`
- **`develop`** → 测试环境 (Staging) - 自动部署
- **`main`** → 生产环境 (Production) - `./deploy.sh`

#### 自动化流程
1. **功能分支推送** → 开发环境手动部署
2. **合并到develop** → 自动部署到测试环境
3. **合并到main** → 触发生产环境部署流程
4. **创建标签** → 自动创建Release和部署记录

### 📊 版本发布计划

#### v1.1.0 (计划中)
- [ ] 用户头像上传功能
- [ ] 批量用户操作
- [ ] 高级权限管理
- [ ] 审计日志功能

#### v1.2.0 (规划中)
- [ ] 多租户支持
- [ ] SSO集成
- [ ] API限流
- [ ] 数据导入导出

### 📋 项目管理全景图

```mermaid
mindmap
  root((用户管理系统<br/>项目管理))
    版本控制
      Git Flow工作流
        main分支(生产)
        develop分支(开发)
        feature分支(功能)
        release分支(发布)
        hotfix分支(修复)
      自动化脚本
        version.sh
          feature管理
          release管理
          hotfix管理
          状态查看
    环境管理
      开发环境
        ./env.sh dev
        localhost:3000
        热重载开发
      测试环境
        自动部署
        staging环境
        集成测试
      生产环境
        ./deploy.sh
        Docker部署
        监控告警
    质量保证
      代码规范
        Conventional Commits
        代码审查
        自动化测试
      部署流程
        CI/CD流水线
        自动化部署
        回滚机制
    团队协作
      分支保护
      PR审查
      发布计划
      文档维护
```

### 🛠️ 开发环境设置

#### 🚀 快速开始 (推荐)
```bash
# 1. 克隆项目
git clone <repository-url>
cd user-management-system

# 2. 初始化Git Flow (必须先执行)
./version.sh init

# 3. 设置开发环境
./env.sh dev
docker-compose up -d --build

# 4. 开始功能开发
./version.sh feature start my-new-feature
```

#### ⚠️ 重要提示

**首次使用必须初始化Git Flow**：
```bash
./version.sh init
```

**配置主分支名称** (解决main/master分支差异)：
```bash
# 创建配置文件
cat > .version.config << EOF
MAIN_BRANCH=master  # 或 main，根据你的仓库设置
DEVELOP_BRANCH=develop
AUTO_PUSH=true
DELETE_MERGED_BRANCHES=true
EOF
```

如果未初始化就直接使用其他命令，脚本会自动提示并退出：
```bash
$ ./version.sh feature start user-profile
📋 加载配置文件: .version.config
🔧 当前配置:
  主分支: master
  开发分支: develop
  自动推送: true

❌ 错误: Git Flow尚未初始化

请先运行以下命令初始化Git Flow:
  ./version.sh init

Git Flow初始化将会:
  • 确保master分支存在
  • 创建develop分支
  • 设置分支关联关系
```

**自动分支检测**：
脚本会自动检测你的仓库主分支名称并提示更新配置：
```bash
$ ./version.sh init
⚠️  检测到主分支为: master，但配置为: main
是否更新配置文件中的主分支名称？(y/N): y
✅ 已更新主分支配置为: master
```

#### 📋 完整初始化流程

```mermaid
flowchart TD
    A[克隆项目] --> B[初始化Git Flow]
    B --> C[选择环境配置]
    C --> D{开发环境?}
    D -->|是| E[./env.sh dev]
    D -->|否| F[./env.sh prod]
    E --> G[docker-compose up -d]
    F --> G
    G --> H[访问应用]
    H --> I[开始开发]

    I --> J{开发类型?}
    J -->|新功能| K[./version.sh feature start]
    J -->|修复bug| L[./version.sh hotfix start]
    J -->|发布版本| M[./version.sh release start]

    K --> N[编码开发]
    L --> N
    M --> O[测试验证]
    N --> P[提交代码]
    O --> P
    P --> Q[完成开发]

    style A fill:#e1f5fe
    style G fill:#f3e5f5
    style H fill:#e8f5e8
    style Q fill:#fff3cd
```

#### 代码质量检查
```bash
# 后端代码检查
cd backend
flake8 .
black .
isort .

# 前端代码检查
cd frontend
npm run lint
npm run type-check
```

### 📞 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'feat: add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

### 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 开发规范

请参考项目中的开发规范文档，严格按照 Django + React 全栈开发最佳实践进行开发。