# smartmaterials2

**Repository Path**: lizhenning/smartmaterials2

## Basic Information

- **Project Name**: smartmaterials2
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-27
- **Last Updated**: 2025-11-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Smartmaterials2 项目

基于 Laravel 风格架构的 Python 项目。

## 项目结构

```
EeveeEnv/
│
├── app/                    # 应用核心代码
│   ├── api/                # API 接口定义
│   │   └── v1/             # API V1 版本
│   ├── models/             # 数据模型
│   ├── schemas/            # 数据验证和转换模式
│   └── services/           # 业务逻辑服务
│
├── bootstrap/              # 应用引导和初始化逻辑
│   └── app.py              # 应用初始化
│
├── config/                 # 配置文件目录
│   ├── app.py              # 应用配置
│   ├── logging.py          # 日志配置
│   └── path_conf.py        # 路径配置
│
├── deploy/                 # 部署相关文件
│
├── static/                 # 静态资源文件
│
├── storage/                # 存储目录
│   └── logs/               # 日志存储
│       ├── access.log      # 访问日志
│       └── error.log       # 错误日志
│
├── migrations/             # 数据库迁移文件目录
├── aerich.ini              # Aerich 配置文件
├── main.py                 # 应用入口点
├── pyproject.toml          # Python 项目配置
└── uv.lock                 # 依赖锁文件
```

## 目录说明

### `app/`

应用的核心代码目录，包含业务逻辑的主要组件。

- **`api/`**: 定义所有 API 接口，按版本分类管理
- **`models/`**: 定义数据模型，对应数据库结构
- **`schemas/`**: 包含用于数据验证和转换的模式定义
- **`services/`**: 包含业务逻辑和核心功能的服务层

### `bootstrap/`

包含应用的启动和初始化代码。

- **`app.py`**: 应用初始化逻辑，类似于 Laravel 的 Bootstrap 过程

### `config/`

存放所有配置文件。

- **`app.py`**: 应用通用配置
- **`logging.py`**: 日志系统配置
- **`path_conf.py`**: 项目路径配置

### `deploy/`

包含部署相关文件，如 Docker 配置、CI/CD 脚本等。

### `static/`

用于存储静态资源文件，如 CSS、JavaScript、图片等。

### `storage/`

用于存储应用产生的各类文件。

- **`logs/`**: 存储应用日志文件

### `migrations/`

数据库迁移文件目录，存放所有 Aerich 迁移文件。

### 根目录文件

- **`main.py`**: 应用程序入口点
- **`pyproject.toml`**: Python 项目配置和依赖管理
- **`uv.lock`**: 依赖锁定文件，确保环境一致性

## 安装与使用

### 环境配置

1. 确保安装了 Python 3.8+ 和依赖管理工具
2. 安装项目依赖：
   ```bash
   pip install -r requirements.txt
   ```

### 数据库迁移

项目使用 Aerich 进行数据库迁移管理，类似于 Laravel 的迁移系统。

#### 初始化 Aerich

首次设置项目时，需要初始化 Aerich 和数据库：

```bash
# 初始化 Aerich 配置
aerich init -t config.database.TORTOISE_ORM

# 创建初始数据库结构
aerich init-db

```

#### 创建迁移文件

当您修改了模型（如添加字段、修改表结构）后，需要创建迁移文件：

```bash
# 参数 --name 指定迁移的描述性名称
aerich migrate --name "描述此次修改的名称"

# 示例：添加用户电话字段
aerich migrate --name "add_phone_to_user"
```

#### 应用迁移

创建迁移文件后，将变更应用到数据库：

```bash
# 应用所有未应用的迁移
aerich upgrade
```

#### 查看迁移历史

```bash
# 查看已应用的迁移历史
aerich history
```

#### 回滚迁移

如果需要撤销最近的迁移：

```bash
# 回滚一个版本
aerich downgrade

# 回滚到指定版本
aerich downgrade -v 版本号
```

### 启动应用

```bash
# 开发环境启动
uvicorn main:app --reload
```

## 开发指南

### 数据库模型开发

1. 在 `app/models/` 目录下创建或修改模型文件
2. 所有模型应继承自 `tortoise.models.Model`
3. 修改模型后，使用 Aerich 创建并应用迁移

示例模型：

```python
from tortoise import fields
from tortoise.models import Model

class User(Model):
    id = fields.IntField(pk=True)
    username = fields.CharField(max_length=50, unique=True)
    email = fields.CharField(max_length=100, unique=True)
    created_at = fields.DatetimeField(auto_now_add=True)
    
    class Meta:
        table = "users"
```

### 迁移最佳实践

1. **描述性命名**：为迁移文件使用清晰的描述性名称
2. **版本控制**：将迁移文件纳入版本控制系统
3. **测试迁移**：在应用到生产前，先在测试环境验证迁移
4. **数据备份**：执行重要迁移前备份数据库
5. **小步迁移**：复杂变更拆分为多个小的迁移步骤

### 命令行工具

```commandline

python cli.py user create

```

### 经验积累

```text

1. 写入数据的时区应该是shanghai,,数据库会自动转化为utc,, 读取会,会自动转回shanghai

```