# 第四章 架构设计 - 目录结构设计

## 4.1 项目根目录

```
DjangoAdmin_Django_NaiveVue/
|
+-- application/                 # Django后端应用主目录
+-- middleware/                   # 自定义中间件
+-- utils/                       # 工具函数库
+-- config/                      # 配置文件目录
+-- constant/                    # 常量定义
+-- extends/                     # 扩展功能
+-- public/                      # 公共资源
|   +-- static/                  # 静态文件
|   +-- templates/               # 代码生成模板
|   +-- uploads/                 # 上传文件存储
+-- data/                        # 数据文件
+-- ui/                          # Vue前端项目
+-- manage.py                    # Django管理脚本
+-- generator.py                 # 代码生成器CLI
+-- config.json                  # 代码生成配置
+-- requirements.txt             # Python依赖
+-- .env                         # 环境变量配置
+-- CLAUDE.md                    # Claude Code指导文件
```

## 4.2 后端应用目录 (application/)

```
application/
|
+-- __init__.py                  # 包初始化
+-- settings.py                  # Django项目配置
+-- urls.py                      # 主路由配置
+-- models.py                    # BaseModel抽象基类
+-- constants.py                 # 项目常量定义
+-- asgi.py                      # ASGI入口
+-- wsgi.py                      # WSGI入口
|
+-- login/                       # 登录模块
+-- index/                       # 首页模块
+-- user/                        # 用户管理模块
+-- role/                        # 角色管理模块
+-- menu/                        # 菜单管理模块
+-- dept/                        # 部门管理模块
+-- dict/                        # 字典管理模块
+-- config/                      # 配置管理模块
+-- job/                         # 定时任务模块
+-- article/                     # 文章管理模块
+-- example/                     # 案例模块（参考示例）
+-- generator/                   # 代码生成器模块
+-- operation_log/               # 操作日志模块
+-- login_log/                   # 登录日志模块
+-- upload/                      # 文件上传模块
+-- ...                          # 其他业务模块
```

## 4.3 标准模块目录结构

每个业务模块遵循统一的文件结构：

```
application/<module>/
|
+-- __init__.py                  # 包初始化文件
+-- apps.py                      # Django应用配置
+-- models.py                    # 数据模型定义
+-- forms.py                     # 表单验证类
+-- services.py                  # 业务逻辑函数
+-- views.py                     # 视图处理类
+-- urls.py                      # URL路由配置
+-- admin.py                     # Admin后台注册
+-- constants.py                 # 模块常量（可选）
+-- migrations/                  # 数据库迁移文件
    +-- __init__.py
    +-- 0001_initial.py
```

### 文件职责说明

| 文件 | 职责 | 典型内容 |
|------|------|----------|
| `models.py` | 数据模型定义 | 继承 BaseModel，定义业务字段 |
| `forms.py` | 表单验证 | ModelForm 子类，字段验证规则 |
| `services.py` | 业务逻辑 | CRUD 操作，分页查询，数据处理 |
| `views.py` | 视图处理 | 类视图，装饰器，权限检查 |
| `urls.py` | 路由配置 | path() 映射，URL 到视图的绑定 |
| `apps.py` | 应用配置 | AppConfig 子类，应用名称 |
| `admin.py` | Admin注册 | 模型在 Django Admin 的注册 |

## 4.4 中间件目录 (middleware/)

```
middleware/
|
+-- __init__.py                  # 包初始化
+-- login_middleware.py          # JWT登录认证装饰器
+-- permission_middleware.py     # 权限控制混入类
```

### 中间件文件说明

| 文件 | 功能 | 核心类/函数 |
|------|------|-------------|
| `login_middleware.py` | JWT认证 | `check_login` 装饰器 |
| `permission_middleware.py` | RBAC权限 | `PermissionRequired` 混入类 |

## 4.5 工具函数目录 (utils/)

```
utils/
|
+-- __init__.py                  # 包初始化
+-- R.py                         # 统一响应格式
+-- jwt.py                       # JWT令牌处理
+-- security.py                  # 用户安全工具
+-- common.py                    # 通用工具函数
+-- regular.py                   # 正则验证工具
+-- password.py                  # 密码处理工具
+-- file.py                      # 文件处理工具
+-- ip_location.py               # IP地理位置查询
+-- ip2region.py                 # IP数据库查询
+-- ip2region.xdb                # IP数据库文件
```

### 工具文件说明

| 文件 | 功能 | 核心函数 |
|------|------|----------|
| `R.py` | 统一响应 | `R.ok()`, `R.failed()`, `R.response()` |
| `jwt.py` | JWT处理 | `create_token()`, `parse_payload()`, `refresh_token()` |
| `security.py` | 用户信息 | `get_user_id()`, `get_username()` |
| `common.py` | 通用工具 | `parse_request_body()`, `format_datetime()`, `get_file_url()` |
| `regular.py` | 表单验证 | `get_err()` |
| `password.py` | 密码处理 | `hash_password()`, `verify_password()` |

## 4.6 配置目录 (config/)

```
config/
|
+-- __init__.py                  # 包初始化
+-- env.py                       # 环境变量配置
```

### 配置项说明

`config/env.py` 定义了所有可配置的环境变量：

```python
# 应用配置
DJANGO_NAME = os.getenv('DJANGO_NAME', 'Django+NaiveUI旗舰版')
DJANGO_VERSION = os.getenv('DJANGO_VERSION', 'v3.0.0')
DJANGO_DEBUG = (os.getenv('DJANGO_DEBUG', 'True') == 'True')
DJANGO_DEMO = (os.getenv('DJANGO_DEMO', 'True') == 'True')

# 数据库配置
DATABASE_ENGINE = os.getenv('DATABASE_ENGINE', "django.db.backends.mysql")
DATABASE_NAME = os.getenv('DATABASE_NAME', 'djangoadmin.django.naivevue')
DATABASE_HOST = os.getenv('DATABASE_HOST', "127.0.0.1")
DATABASE_PORT = os.getenv('DATABASE_PORT', 3306)
DATABASE_PREFIX = os.getenv('DATABASE_PREFIX', "django_")

# Redis配置
REDIS_HOST = os.getenv('REDIS_HOST', '127.0.0.1')
REDIS_PORT = int(os.getenv('REDIS_PORT', 6379))
REDIS_PASSWORD = os.getenv('REDIS_PASSWORD', '123456')
REDIS_DB = int(os.getenv('REDIS_DB', 0))

# IP地理位置配置
IP_LOCATION_SOURCE = os.environ.get('IP_LOCATION_SOURCE', 'api')
IP_CACHE_ENABLED = os.environ.get('IP_CACHE_ENABLED', 'True') == 'True'
IP_CACHE_TIMEOUT = int(os.environ.get('IP_CACHE_TIMEOUT', 86400))
```

## 4.7 前端目录 (ui/)

```
ui/
|
+-- public/                      # 静态资源
+-- src/
|   +-- api/                     # API接口定义
|   |   +-- tool/                # 业务API模块
|   |       +-- example.ts       # 案例API
|   |       +-- user.ts          # 用户API
|   |
|   +-- views/                   # 页面组件
|   |   +-- tool/                # 业务页面
|   |       +-- example/         # 案例页面
|   |       |   +-- index.vue    # 列表页
|   |       |   +-- edit.vue     # 编辑页
|   |       |   +-- detail.vue   # 详情页
|   |
|   +-- components/              # 公共组件
|   |   +-- BasicTable/          # 表格组件
|   |   +-- BasicForm/           # 表单组件
|   |   +-- PageWrapper/         # 页面容器
|   |
|   +-- router/                  # 路由配置
|   +-- store/                   # Pinia状态管理
|   +-- utils/                   # 工具函数
|   +-- layouts/                 # 布局组件
|
+-- .env.development             # 开发环境配置
+-- .env.production              # 生产环境配置
+-- package.json                 # 依赖配置
+-- vite.config.ts               # Vite配置
+-- tsconfig.json                # TypeScript配置
```

## 4.8 公共资源目录 (public/)

```
public/
|
+-- static/                      # 静态文件
+-- templates/                   # 代码生成模板
|   +-- models.py.tpl            # 模型模板
|   +-- forms.py.tpl             # 表单模板
|   +-- services.py.tpl          # 服务模板
|   +-- views.py.tpl             # 视图模板
|   +-- urls.py.tpl              # 路由模板
|   +-- ui/
|       +-- index.vue.tpl        # 列表页模板
|       +-- edit.vue.tpl         # 编辑页模板
|       +-- detail.vue.tpl       # 详情页模板
|       +-- api.ts.tpl           # API模块模板
|
+-- uploads/                     # 上传文件存储
    +-- example/                 # 按模块分类存储
    +-- avatar/                  # 头像文件
    +-- temp/                    # 临时文件
```