smalltown/PROJECT.md

城中村租房平台 - 项目文档

一、项目背景与目标

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 表

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 表

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 表

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 租客端

• 房源列表浏览（按地区筛选、关键词搜索）
• 房屋详情查看
• 联系房东（显示电话）
• 移动端UI优化

7.2 房东端

• 用户注册/登录（Cookie认证）
• 发布新房源
• 编辑/删除自己的房源
• 图片上传（文件选择/摄像头拍照）

7.3 系统

• MariaDB数据库集成
• 图片本地存储
• SSH端口转发脚本（远程访问）

八、部署说明

8.1 本地开发

npm run dev
# 访问 http://localhost:3000

8.2 生产构建

npm run build
npm start

8.3 远程访问

SSH反向隧道将远程30000端口映射到本地3000：

./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访问