# eshop

**Repository Path**: artlongs/eshop

## Basic Information

- **Project Name**: eshop
- **Description**: 跨境独立站
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# fs-admin

## 介绍

fs-admin 是一个现代化的后台管理系统，采用 **htmx 多页应用（MPA）** 架构，具备良好的 SEO 友好性和简洁的交互体验。

### 核心特性

- **SEO 友好**：每个页面独立 URL，搜索引擎可直接抓取完整内容
- **权限控制**：基于 RBAC 的权限校验，精确到按钮级别
- **轻量交互**：htmx 提供优雅的 AJAX 局部更新，无需复杂前端架构
- **快速开发**：提供代码生成工具，自动生成前后端代码
- **易于部署**：单体架构，前端资源打包进后端 jar

### 技术栈

| 层级 | 技术 |
|------|------|
| 前端框架 | htmx 2.0 + Alpine.js |
| 构建工具 | Vite 5 |
| 后端框架 | Solon + Java 17 |
| 数据库 | PostgreSQL |
| ORM | fastmybatis |

## 目录说明

```
fs-admin/
├── fs-admin-backend/        # 后端代码（Solon + Java17）
│   ├── admin-boot/        # 启动入口
│   ├── admin-common/      # 公共模块
│   ├── admin-dao/         # 数据访问层
│   ├── admin-service/     # 服务层
│   └── admin-web/         # Web 层（Controller）
├── fs-admin-htmx/          # 前端代码（htmx 多页应用）
│   ├── src/
│   │   ├── pages/         # 页面 HTML
│   │   ├── shared/        # 共享模块（API、工具）
│   │   ├── css/           # 样式文件
│   │   └── lib/           # 第三方库（htmx）
│   └── vite.config.js     # Vite 配置
└── fs-code-gen/           # 代码生成工具
```

## 快速开始

### 环境要求

- JDK 17+
- Node.js 18+
- PostgreSQL 12+

### 1. 初始化数据库

```bash
# 创建数据库
psql -U postgres -c "CREATE DATABASE fsadmin;"

# 导入数据
psql -U postgres -d fsadmin -f postgresql.sql
```

### 2. 启动后端服务

```bash
cd fs-admin-backend

# 构建项目
mvn clean package -Dmaven.test.skip=true

# 启动服务（默认端口 8090）
java -jar admin-boot/target/fs-admin-1.0.0-SNAPSHOT.jar
```

### 3. 启动前端开发服务器

```bash
cd fs-admin-htmx

# 安装依赖
npm install

# 启动开发服务器（端口 9125）
npm run dev
```

访问 http://localhost:9125/

### 登录账号

- 超级管理员：账号 `admin`，密码 `123456`

## 项目结构详解

### 前端页面结构

```
fs-admin-htmx/src/pages/
├── index.html        # 首页 /
├── login.html       # 登录页 /login.html
├── dashboard.html   # 仪表盘 /dashboard.html
└── users.html       # 用户管理 /users.html
```

### 页面功能说明

| 页面 | 路由 | 功能 |
|------|------|------|
| 首页 | `/index.html` | 系统概览、快速入口 |
| 登录 | `/login.html` | 用户认证 |
| 仪表盘 | `/dashboard.html` | 数据统计、最近活动 |
| 用户管理 | `/users.html` | 用户增删改查 |

### 共享模块

```javascript
// API 客户端 - 统一处理认证和数据请求
src/shared/api.js

// 工具函数 - 格式化、分页、提示等
src/shared/utils.js
```

## 配置说明

### 后端端口配置

文件：`fs-admin-backend/admin-boot/src/main/resources/app.yml`

```yaml
server:
  port: 8090

postgresql:
  host: localhost:5432
  db: fsadmin
  username: postgres
  password: 111
```

### 前端代理配置

文件：`fs-admin-htmx/vite.config.js`

```javascript
proxy: {
  '/sys': {
    target: 'http://localhost:8090',
    changeOrigin: true
  }
}
```

修改后端端口时，需同步修改两处配置。

## 构建部署

### 开发构建

```bash
cd fs-admin-htmx
npm run build
```

构建产物输出到 `fs-admin-backend/admin-boot/src/main/resources/static/`

### 生产构建

```bash
# 在项目根目录执行
./build.sh
```

构建完成后，只需启动后端服务：

```bash
java -jar fs-admin-backend/admin-boot/target/fs-admin-1.0.0-SNAPSHOT.jar
```

访问 http://localhost:8090/

## API 接口

后端提供 RESTful API，前端通过 AJAX 调用。

### 认证接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/sys/login` | POST | 用户登录 |

### 数据接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/sys/user/list` | GET | 用户列表 |
| `/sys/user/{id}` | GET | 用户详情 |
| `/sys/user/{id}` | DELETE | 删除用户 |
| `/sys/dashboard` | GET | 仪表盘数据 |

## htmx 交互示例

### 局部更新

```html
<!-- 点击按钮时，加载并显示用户列表片段 -->
<button hx-get="/api/users"
        hx-target="#userList"
        hx-swap="innerHTML">
  刷新列表
</button>

<!-- 用户列表容器 -->
<div id="userList"></div>
```

### 表单提交

```html
<form hx-post="/sys/user"
      hx-target="#result"
      hx-swap="innerHTML">
  <input name="username" type="text">
  <button type="submit">提交</button>
</form>
<div id="result"></div>
```

### 请求指示器

```html
<button hx-get="/api/data"
        hx-indicator="#loading">
  加载数据
</button>
<div id="loading" class="htmx-indicator">加载中...</div>
```

## 与 Vue3 版本的区别

| 特性 | htmx MPA 版本 | Vue3 版本 |
|------|---------------|-----------|
| SEO | ✅ 完美支持 | ❌ 需 SSR |
| 首屏速度 | ✅ 快（直出 HTML） | 较慢 |
| 学习成本 | 低 | 中 |
| 状态管理 | 简单（localStorage） | 复杂（Pinia） |
| 页面切换 | 整页刷新或局部更新 | 无刷新 |
| 适用场景 | 需 SEO 的后台 | 纯管理后台 |

## 预览图

- 用户管理

![用户管理](./asset/1.png)

- 角色管理

![角色管理](./asset/2.png)

- 菜单管理

![菜单管理](./asset/3.png)