# local_share_20261104

**Repository Path**: burns/local_share_20261104

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-05
- **Last Updated**: 2026-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 邻里圈 LocalShare

面向小区居民的本地生活分享应用。公告由居委会 / 网格员发布，分享由居民发布，支持按省市区、多个小区和 3km / 5km 范围查找身边内容，并可打包为 Android App。

- 前端：uni-app（Vue 3 + Vite）
- 后端：JDK 17 + Spring Boot 3.3 + Spring JDBC + JWT
- 数据库：MySQL 8
- 图片存储：后端本地 `uploads/` 目录，通过 `/uploads/**` 访问

## 功能一览

- **公告**：居委会、网格员账号发布，归属到小区；可设置仅本小区、周边 3km、周边 5km 可见。服务端会按浏览者的小区归属和坐标校验可见性。
- **分享**：居民发布二手闲置、寻物启事、邻里闲聊，支持图片、点赞、评论。
- **发布**：底部中间 `+` 按钮进入发布页。可选择省 / 市 / 区，按当前位置回填最近 10 个小区，也支持手动录入小区。
- **全场可见**：分享可以关闭定位，关闭后所有用户可见，并展示醒目的「全场可见」标签；已定位内容展示「小区内」「周边3km」「周边5km」等标签。
- **搜索**：支持关键词、省市区、多选小区、3km / 5km 范围和内容类型组合筛选。
- **消息**：点赞、评论、小区公告通知，支持全部已读、单条已读、删除。
- **我的**：注册、登录、退出、编辑资料与头像、设置我的小区、查看我的发布、服务器地址设置。
- **演示数据**：首次启动自动写入演示账号、公告、分享、评论、点赞和消息。

## 目录结构

```text
local_share_20261104/
├─ backend/                         # Spring Boot 后端
│  ├─ src/main/java/com/localshare/
│  │  ├─ area/                      # 省市区数据
│  │  ├─ community/                 # 小区与附近小区
│  │  ├─ post/                      # 公告 / 分享 / 评论 / 点赞 / 可见性
│  │  ├─ message/                   # 互动消息
│  │  ├─ user/                      # 注册、登录、资料
│  │  ├─ storage/                   # 图片上传
│  │  └─ seed/                      # 演示数据
│  ├─ src/main/resources/
│  │  ├─ db/schema.sql              # 建表
│  │  ├─ db/data.sql                # 全国省市区基础数据
│  │  └─ application.yml            # 数据库、JWT、上传配置
│  └─ pom.xml
├─ frontend/                        # uni-app 前端
│  ├─ src/pages/                    # 公告、分享、发布、消息、我的等
│  ├─ src/components/               # 底部导航、帖子卡片、地区/小区选择器
│  ├─ src/api/index.js              # 接口封装
│  ├─ src/store/auth.js             # 登录态
│  └─ src/manifest.json             # Android 权限与打包配置
├─ db/area-data.json                # 省市区源数据（导入用参考）
└─ README.md
```

## 环境要求

- JDK 17
- Maven 3.8+
- MySQL 8.0+
- Node.js 18+（推荐 20）
- 打包 Android 时需要 HBuilderX 或 DCloud 云打包

## 快速启动

### 1. 启动 MySQL

确保 MySQL 服务已启动。默认后端使用以下连接信息：

```text
地址：localhost:3306
数据库：localshare
用户名：root
密码：root
```

数据库不需要手动创建。后端启动时会通过 JDBC 参数 `createDatabaseIfNotExist=true` 自动建库，并执行：

- `schema.sql`：创建数据表（`CREATE TABLE IF NOT EXISTS`）
- `data.sql`：导入 3279 条省市区数据（`INSERT IGNORE`）
- `CommunitySeeder`：为每个区县生成 15 个演示小区
- `DemoDataSeeder`：在没有任何用户时写入演示账号和内容

如果本机 MySQL 账号密码不同，可通过环境变量覆盖（PowerShell 示例）：

```powershell
$env:DB_USERNAME="root"
$env:DB_PASSWORD="你的密码"
$env:DB_NAME="localshare"
```

### 2. 启动后端

```powershell
cd backend
mvn spring-boot:run
```

或先打包再运行：

```powershell
cd backend
mvn -DskipTests package
java -jar target/localshare-server.jar
```

启动后访问健康检查：

```text
http://localhost:8080/api/health
```

首次启动需要生成 4 万多条小区数据，通常需要十几秒到几十秒，请等待日志出现启动完成。

### 3. 启动前端 H5

```powershell
cd frontend
npm install
npm run dev:h5
```

浏览器访问 `http://localhost:5173`。开发环境下 Vite 会把 `/api`、`/uploads`、`/demo` 代理到 `http://localhost:8080`，无需额外配置接口地址。

生产构建：

```powershell
npm run build:h5
```

构建产物在 `frontend/dist/build/h5`。如果前端与后端不同源，构建前设置接口地址：

```powershell
$env:VITE_API_BASE="https://你的后端域名"
npm run build:h5
```

### 4. 打包 Android App

1. 使用 HBuilderX 导入 `frontend` 目录（uni-app 项目）。
2. 连接 Android 手机或启动模拟器，选择「运行 → 运行到手机或模拟器」。
3. 需要 APK 时选择「发行 → 原生 App-云打包」。

接口地址：

- Android 模拟器默认使用 `http://10.0.2.2:8080`（即电脑本机的 8080 端口）。
- 真机需要把接口地址改为电脑局域网 IP，例如 `http://192.168.1.10:8080`。
- 可在 App 内「我的 → 服务器设置」中随时修改并保存。

`manifest.json` 已配置定位、相机、存储、网络权限，并开启 `usesCleartextTraffic`，便于本地 HTTP 调试。正式上线建议使用 HTTPS 并关闭明文流量。

## 演示账号

统一密码：`123456`

| 用户名 | 昵称 | 角色 | 说明 |
| --- | --- | --- | --- |
| `resident001` | 王阿姨 | 居民 | 可发布分享、评论、点赞 |
| `resident002` | 李叔 | 居民 | 演示另一居民账号 |
| `grid001` | 网格员小周 | 网格员 | 可发布小区公告 |
| `committee001` | 阳光社区居委会 | 居委会 | 可发布小区公告 |

未登录也可以浏览公开内容和公告列表；发布、评论、点赞、消息、我的发布等需要登录。

## 使用说明

### 公告可见性

- 公告只能由 `GRID`、`COMMITTEE`、`ADMIN` 角色发布。
- 公告必须选择归属小区。
- 公告可见范围支持：
  - 仅归属小区：只有同小区居民可见
  - 周边 3km：同小区 + 3 公里内用户可见
  - 周边 5km：同小区 + 5 公里内用户可见
- 可见性由后端根据当前登录用户的小区 ID 和经纬度判断，不依赖前端隐藏。
- 未登录用户按请求传入的坐标判断周边可见性；无坐标时只能看到不限制位置的内容。

### 定位与小区

- 发布页可使用「定位并回填最近 10 个小区」，按距离由近到远选择。
- 定位失败或未授权时，开发环境会使用杭州西湖区的演示坐标，方便完整体验流程。
- 没有合适小区时，可在小区选择面板中手动录入小区名称和地址，保存后直接选用。
- 用户可在「我的 → 编辑资料与我的小区」中设置或清除自己的小区。

### 全场可见标签

- 分享关闭「发布位置」后，内容不关联小区和坐标，所有用户可见，标签显示为「全场可见」。
- 已定位分享显示「小区内」；周边公告显示「周边3km / 周边5km」。
- 列表页和详情页都会展示对应标签，便于区分内容范围。

### 搜索

搜索页支持任意组合：

- 关键词
- 省 / 市 / 区
- 多选小区（可搜索后勾选多个）
- 范围：不限 / 3km / 5km
- 类型：全部 / 公告 / 分享

3km / 5km 范围搜索需要位置；没有位置时会先尝试定位，失败则使用演示位置。

## 后端配置

主要配置在 `backend/src/main/resources/application.yml`，均可用环境变量覆盖：

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `SERVER_PORT` | `8080` | 后端端口 |
| `DB_HOST` | `localhost` | MySQL 地址 |
| `DB_PORT` | `3306` | MySQL 端口 |
| `DB_NAME` | `localshare` | 数据库名 |
| `DB_USERNAME` | `root` | 数据库用户名 |
| `DB_PASSWORD` | `root` | 数据库密码 |
| `JWT_SECRET` | 内置开发密钥 | JWT 签名密钥，生产环境务必修改 |
| `UPLOAD_DIR` | `./uploads` | 图片上传目录 |

## API 概览

统一响应格式：

```json
{ "code": 0, "message": "ok", "data": {} }
```

需要登录的接口使用请求头：

```text
Authorization: Bearer <JWT>
```

主要接口：

```text
POST   /api/auth/register              注册
POST   /api/auth/login                 登录
POST   /api/auth/logout                退出登录（JWT 无状态）
GET    /api/users/me                   当前用户与统计
GET    /api/users/me/stats             当前用户统计
PUT    /api/users/me                   更新资料 / 小区

GET    /api/areas/provinces            省份
GET    /api/areas/children             下级地区
GET    /api/areas/search               地区搜索
GET    /api/areas/locate               坐标反查区县
GET    /api/areas/meta                 地区数据元信息

GET    /api/communities/nearby         附近小区（默认最近 10 个）
GET    /api/communities/search         小区搜索
POST   /api/communities                手动新增小区

GET    /api/posts                      公告 / 分享列表与搜索
GET    /api/posts/mine                 我的发布
GET    /api/posts/{id}                 详情
POST   /api/posts                      发布
DELETE /api/posts/{id}                 删除自己的发布
POST   /api/posts/{id}/like            点赞 / 取消点赞
GET    /api/posts/{id}/comments        评论列表
POST   /api/posts/{id}/comments        发表评论

GET    /api/messages                   消息列表
GET    /api/messages/unread-count      未读数
POST   /api/messages/{id}/read         单条已读
POST   /api/messages/read-all          全部已读
DELETE /api/messages/{id}              删除消息

POST   /api/upload                     上传图片
GET    /api/health                     健康检查
```

## 数据说明

- 省市区数据来自 `backend/src/main/resources/db/data.sql`，共 3279 条（省 34 / 市 370 / 区县 2875），使用 GCJ-02 坐标。
- `CommunitySeeder` 为每个区县生成 15 个演示小区，名称固定，坐标围绕区县中心随机分布。
- `DemoDataSeeder` 只在 `app_user` 表为空时执行，不会覆盖已有业务数据。
- 演示图片位于后端 `src/main/resources/static/demo/`，访问路径为 `/demo/xxx.svg`。
- 用户上传图片保存在后端运行目录下的 `uploads/`，数据库只保存相对路径。

## 常见问题

**启动时连接数据库失败**

检查 MySQL 服务、端口、账号密码，必要时设置 `DB_USERNAME` / `DB_PASSWORD`。

**H5 页面能打开但接口报网络错误**

确认后端在 `8080` 端口运行，且前端使用 `npm run dev:h5` 启动以启用 Vite 代理。

**Android 真机请求失败**

把「我的 → 服务器设置」改为电脑局域网 IP，确保手机和电脑在同一网络，并检查 Windows 防火墙是否放行 8080 端口。

**定位失败**

开发环境会自动回退到杭州西湖区演示坐标；真机请在系统设置中允许 App 定位权限。

**想清空演示数据重新体验**

删除数据库 `localshare` 后重启后端即可自动重建。注意这会清空所有用户和发布数据。