# keweims

**Repository Path**: zky-git/keweims

## Basic Information

- **Project Name**: keweims
- **Description**: dddddddddd
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-30
- **Last Updated**: 2025-12-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 Poetry 项目管理指南

本项目已迁移到 Poetry 进行依赖管理，以下是使用说明：

## 环境要求
- Python >= 3.9, < 4.0
- Poetry (Python 依赖管理工具)

## 快速开始

### 1. 安装 Poetry
```bash
curl -sSL https://install.python-poetry.org | python3 -
```

### 2. 配置国内镜像源（可选，加速下载）
```bash
poetry source add tsinghua https://pypi.tuna.tsinghua.edu.cn/simple
```

### 3. 安装项目依赖
```bash
poetry install
```

### 4. 激活虚拟环境
```bash
poetry shell
```

### 5. 运行开发服务器
```bash
poetry run python manage.py runserver 0.0.0.0:8000
```

## 🔧 常用 Poetry 命令

### 依赖管理
```bash
# 添加生产依赖
poetry add package_name

# 添加开发依赖
poetry add --dev package_name

# 更新依赖
poetry update

# 查看依赖树
poetry show --tree
```

### 项目运行
```bash
# 运行 Django 管理命令（推荐方式）
poetry run python manage.py [command]

# 数据库迁移
poetry run python manage.py migrate

# 创建超级用户
poetry run python manage.py createsuperuser

# 代码质量检查
poetry run black .          # 代码格式化
poetry run flake8           # 代码检查
poetry run pytest           # 运行测试
```

---

## 开发环境启动（传统方式）

```bash
python manage.py runserver 0.0.0.0:8000
```

> ⚠️ **注意**：推荐使用 `poetry run python manage.py runserver 0.0.0.0:8000`

## 数据库迁移

当修改模型后，需要执行数据库迁移：

```bash
# 创建迁移文件
python manage.py makemigrations

# 应用迁移到数据库
python manage.py migrate
```

## 器材分类管理

新添加的器材分类功能包括：

1. **分类模型**：EquipmentCategory，用于管理器材分类
2. **后台管理**：可在 Django Admin 中管理分类
3. **API 接口**：
    - `GET /api/categories/` - 获取所有器材分类
    - `GET /api/equipments/` - 获取器材列表（包含分类信息）
    - `GET /api/equipments/{id}/` - 获取器材详情（包含分类信息）

## 数据库变更说明

器材模型中的 `category` 字段已从简单的字符字段改为外键关联，这意味着：

-   每个器材必须属于一个分类
-   可以通过分类来筛选器材
-   分类信息现在作为独立的实体存在，便于管理和扩展

### 迁移故障排除

如果遇到外键完整性错误（如器材分类转换问题），系统已自动处理现有数据：

-   自动创建常用分类（健身器材、办公用品、电子设备等）
-   将现有器材的字符串分类转换为新的外键关联
-   确保数据完整性

## 器材分类与轮播图功能

### 数据库模型更新

1. **新增器材分类模型** (`EquipmentCategory`)

    - 分类名称、描述、创建时间
    - 支持分类的唯一标识和管理

2. **新增轮播图模型** (`Banner`)
    - 轮播图标题、图片、链接地址
    - 显示顺序、启用状态、点击统计
    - 按顺序排序，支持启用/禁用控制

### 后台管理功能

#### 器材分类管理 (/admin/)

-   新增器材分类管理模块
-   支持分类名称搜索和排序
-   器材列表显示分类信息

#### 轮播图管理 (/admin/)

-   新增轮播图管理模块
-   支持图片上传、标题描述、链接设置
-   可设置显示顺序和启用状态
-   点击次数统计（只读显示）

### API 接口扩展

#### 新增器材分类接口

-   `GET /api/categories/` - 获取器材分类列表

#### 新增轮播图接口

-   `GET /api/banners/` - 获取启用的轮播图列表（按顺序）
-   `POST /api/banners/{id}/click/` - 轮播图点击统计

#### 更新现有器材接口

-   所有器材接口现在包含完整的分类信息
-   支持通过分类筛选器材

## 小程序跨域问题解决

### 问题描述

小程序在本地开发调试时，调用 Django 接口会出现跨域（CORS）错误，导致请求失败。

### 解决方案

#### 1. 安装 CORS 依赖

```bash
pip install django-cors-headers
```

#### 2. Django 配置

已在 `settings.py` 中完成以下配置：

-   在 `INSTALLED_APPS` 中添加 `'corsheaders'`
-   在 `MIDDLEWARE` 中添加 `'corsheaders.middleware.CorsMiddleware'`
-   配置 CORS 相关设置，支持小程序跨域请求

#### 3. 配置说明

**开发环境配置**：

-   `CORS_ALLOW_ALL_ORIGINS = True` - 允许所有域名访问
-   `CORS_ALLOW_CREDENTIALS = True` - 允许携带凭证
-   支持所有常用 HTTP 方法和请求头

**生产环境配置**：

-   建议修改为指定域名访问
-   设置 `CORS_ALLOW_ALL_ORIGINS = False`
-   启用 `CORS_ALLOWED_ORIGINS` 列表

#### 4. 常用接口

小程序可以调用的接口地址：

-   器材列表：`http://127.0.0.1:8000/api/equipments/`
-   器材详情：`http://127.0.0.1:8000/api/equipments/{id}/`
-   分类列表：`http://127.0.0.1:8000/api/categories/`
-   轮播图列表：`http://127.0.0.1:8000/api/banners/`
-   轮播图点击：`http://127.0.0.1:8000/api/banners/{id}/click/`

#### 5. 小程序请求示例

```javascript
wx.request({
	url: "http://127.0.0.1:8000/api/equipments/",
	method: "GET",
	success(res) {
		console.log("器材列表:", res.data);
	},
	fail(err) {
		console.error("请求失败:", err);
	},
});
```

### 小程序开发工具域名校验问题解决

#### 问题现象

在微信小程序开发工具中调试时，出现以下错误：

```
http://127.0.0.1:8000 不在以下 request 合法域名列表中
```

这是因为微信小程序对网络请求有严格的域名白名单限制。

#### 解决方案

##### 方案 1：开发阶段配置（推荐）

1. **打开微信开发者工具**
2. **进入项目详情设置**：
    - 点击工具栏的"详情"按钮
    - 或者点击右上角的"设置"图标
3. **取消域名校验**：
    - 在"本地设置"中勾选 ✅ **"不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书"**
    - 这个选项允许在开发阶段绕过域名校验限制

##### 方案 2：使用 HTTPS（生产环境推荐）

如果你需要使用 HTTPS，可以配置 Django 开发服务器的 SSL 支持：

```bash
# 安装SSL支持
pip install django-extensions Werkzeug

# 启动HTTPS服务器（使用自签名证书）
python manage.py runserver_plus --cert server.crt 0.0.0.0:8000
```

**注意**：生产环境建议使用专业的 HTTPS 配置。

##### 方案 3：使用 localhost 替代 127.0.0.1

```javascript
wx.request({
	url: "http://localhost:8000/api/equipments/",
	method: "GET",
	success(res) {
		console.log("器材列表:", res.data);
	},
});
```

#### 常见问题排查

1. **确认 Django 服务器正在运行**：

    ```bash
    python manage.py runserver 0.0.0.0:8000
    ```

2. **确认 CORS 配置正确**：

    - 已在 settings.py 中配置 django-cors-headers
    - 可以通过 curl 测试 API 是否返回正确的 CORS 头

3. **测试 API 接口**：

    ```bash
    curl -H "Origin: http://servicewechat.com" http://127.0.0.1:8000/api/equipments/
    ```

4. **检查微信开发者工具控制台**：
    - 查看 Network 面板，确认请求状态
    - 查看 Console 面板，确认错误信息

## 安装和部署

### 环境要求

-   Python 3.8+
-   Django 4.2+
-   所有依赖包（见 requirements.txt）

### 安装依赖

```bash
pip install -r requirements.txt
```