docs: 添加项目文档
This commit is contained in:
Cuishibing
160
PROJECT.md
Normal file
160
PROJECT.md
Normal file
@@ -0,0 +1,160 @@
|
|||||||
|
# 城中村租房平台 - 项目文档
|
||||||
|
|
||||||
|
## 一、项目背景与目标
|
||||||
|
|
||||||
|
### 1.1 项目背景
|
||||||
|
城中村租房信息平台，为房东和租客提供简洁的租房信息服务。
|
||||||
|
|
||||||
|
### 1.2 项目目标
|
||||||
|
- 租客端：无需登录即可浏览、搜索房源，查看详情并联系房东
|
||||||
|
- 房东端：注册/登录后发布、管理房源，支持图片上传
|
||||||
|
- 移动端优先：适配手机访问
|
||||||
|
|
||||||
|
## 二、技术栈
|
||||||
|
|
||||||
|
| 类型 | 技术 |
|
||||||
|
|------|------|
|
||||||
|
| 框架 | Next.js 16 + TypeScript |
|
||||||
|
| 样式 | TailwindCSS |
|
||||||
|
| 数据库 | MariaDB 10 (192.168.0.196:3306) |
|
||||||
|
| 图片存储 | 本地文件系统 (public/uploads/) |
|
||||||
|
|
||||||
|
## 三、工程结构
|
||||||
|
|
||||||
|
```
|
||||||
|
smalltown2/
|
||||||
|
├── app/ # Next.js App Router
|
||||||
|
│ ├── api/ # API接口
|
||||||
|
│ │ ├── auth/ # 认证相关
|
||||||
|
│ │ │ ├── login/route.ts # 登录
|
||||||
|
│ │ │ ├── register/route.ts# 注册
|
||||||
|
│ │ │ └── me/route.ts # 当前用户
|
||||||
|
│ │ ├── houses/ # 房屋CRUD
|
||||||
|
│ │ │ ├── route.ts # 列表/创建
|
||||||
|
│ │ │ └── [id]/route.ts # 详情/更新/删除
|
||||||
|
│ │ ├── owner/houses/route.ts# 房东房源管理
|
||||||
|
│ │ ├── districts/route.ts # 地区列表
|
||||||
|
│ │ └── upload/route.ts # 图片上传
|
||||||
|
│ ├── house/[id]/page.tsx # 房屋详情页（租客）
|
||||||
|
│ ├── owner/ # 房东登录页
|
||||||
|
│ ├── owner/dashboard/ # 房东管理后台
|
||||||
|
│ └── page.tsx # 首页（租客浏览）
|
||||||
|
├── lib/
|
||||||
|
│ └── db.ts # 数据库连接池
|
||||||
|
├── public/uploads/ # 上传的图片
|
||||||
|
├── port_forwarding.sh # SSH隧道脚本
|
||||||
|
└── data/ # 本地数据（已弃用，data/已加入.gitignore）
|
||||||
|
```
|
||||||
|
|
||||||
|
## 四、数据库表结构
|
||||||
|
|
||||||
|
### 4.1 users 表
|
||||||
|
```sql
|
||||||
|
CREATE TABLE users (
|
||||||
|
id VARCHAR(36) PRIMARY KEY,
|
||||||
|
username VARCHAR(50) NOT NULL UNIQUE,
|
||||||
|
password_hash VARCHAR(64) NOT NULL,
|
||||||
|
token VARCHAR(64),
|
||||||
|
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 houses 表
|
||||||
|
```sql
|
||||||
|
CREATE TABLE houses (
|
||||||
|
id VARCHAR(36) PRIMARY KEY,
|
||||||
|
owner VARCHAR(50) NOT NULL,
|
||||||
|
title VARCHAR(200) NOT NULL,
|
||||||
|
description TEXT,
|
||||||
|
price INT NOT NULL,
|
||||||
|
district VARCHAR(50) NOT NULL,
|
||||||
|
address VARCHAR(500) NOT NULL,
|
||||||
|
phone VARCHAR(20) NOT NULL,
|
||||||
|
images JSON,
|
||||||
|
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.3 districts 表
|
||||||
|
```sql
|
||||||
|
CREATE TABLE districts (
|
||||||
|
id INT AUTO_INCREMENT PRIMARY KEY,
|
||||||
|
name VARCHAR(50) NOT NULL UNIQUE,
|
||||||
|
sort_order INT DEFAULT 0
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
## 五、页面路由
|
||||||
|
|
||||||
|
| 路径 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| `/` | 租客首页 - 浏览房源列表 |
|
||||||
|
| `/house/[id]` | 房屋详情页（租客） |
|
||||||
|
| `/owner` | 房东登录/注册页 |
|
||||||
|
| `/owner/dashboard` | 房东管理后台 |
|
||||||
|
|
||||||
|
## 六、API接口
|
||||||
|
|
||||||
|
| 方法 | 路径 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| POST | `/api/auth/register` | 房东注册 |
|
||||||
|
| POST | `/api/auth/login` | 房东登录 |
|
||||||
|
| GET | `/api/auth/me` | 获取当前用户 |
|
||||||
|
| DELETE | `/api/auth/me` | 登出 |
|
||||||
|
| GET | `/api/houses` | 获取房源列表（支持district/keyword筛选） |
|
||||||
|
| POST | `/api/houses` | 创建房源（需登录） |
|
||||||
|
| GET | `/api/houses/[id]` | 获取房源详情 |
|
||||||
|
| PUT | `/api/houses/[id]` | 更新房源（需登录，房东只能修改自己的） |
|
||||||
|
| DELETE | `/api/houses/[id]` | 删除房源（需登录，房东只能删除自己的） |
|
||||||
|
| GET | `/api/owner/houses` | 获取房东自己的房源（需登录） |
|
||||||
|
| GET | `/api/districts` | 获取地区列表 |
|
||||||
|
| POST | `/api/upload` | 上传图片 |
|
||||||
|
|
||||||
|
## 七、已完成功能
|
||||||
|
|
||||||
|
### 7.1 租客端
|
||||||
|
- [x] 房源列表浏览（按地区筛选、关键词搜索）
|
||||||
|
- [x] 房屋详情查看
|
||||||
|
- [x] 联系房东（显示电话）
|
||||||
|
- [x] 移动端UI优化
|
||||||
|
|
||||||
|
### 7.2 房东端
|
||||||
|
- [x] 用户注册/登录（Cookie认证）
|
||||||
|
- [x] 发布新房源
|
||||||
|
- [x] 编辑/删除自己的房源
|
||||||
|
- [x] 图片上传（文件选择/摄像头拍照）
|
||||||
|
|
||||||
|
### 7.3 系统
|
||||||
|
- [x] MariaDB数据库集成
|
||||||
|
- [x] 图片本地存储
|
||||||
|
- [x] SSH端口转发脚本（远程访问）
|
||||||
|
|
||||||
|
## 八、部署说明
|
||||||
|
|
||||||
|
### 8.1 本地开发
|
||||||
|
```bash
|
||||||
|
npm run dev
|
||||||
|
# 访问 http://localhost:3000
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8.2 生产构建
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
npm start
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8.3 远程访问
|
||||||
|
SSH反向隧道将远程30000端口映射到本地3000：
|
||||||
|
```bash
|
||||||
|
./port_forwarding.sh start # 启动
|
||||||
|
./port_forwarding.sh stop # 停止
|
||||||
|
./port_forwarding.sh status # 状态
|
||||||
|
# 访问 http://47.120.74.73:30000
|
||||||
|
```
|
||||||
|
|
||||||
|
## 九、注意事项
|
||||||
|
|
||||||
|
1. 数据库连接配置在 `lib/db.ts`，生产环境注意安全
|
||||||
|
2. 上传的图片存储在 `public/uploads/` 目录，已加入 .gitignore
|
||||||
|
3. data/ 目录已加入 .gitignore（旧的JSON存储方式）
|
||||||
|
4. Cookie设置 `secure: false` 以支持HTTP访问
|
||||||
Reference in New Issue
Block a user