# holospace

**Repository Path**: shownow/holospace

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小拿空间 (SHOWNOW SPACE)

为 3D 编辑器提供项目与资源管理后台的 monorepo 仓库。包含业务核心(认证 / 分类 / 项目 / 封面上传)的管理后台,前端通过 `rteditor-assetlib-sdk` 对接资源库后端。

> 设计文档见 `design/` 目录:`framework.md` / `architecture.md` / `api.md`。

## 仓库结构

```
holospace/
├── backend/                # Go + Gin + GORM 业务核心后端
├── frontend/               # React 18 + TS + Vite + AntD 管理后台
├── packages/
│   └── rteditor-assetlib-sdk/   # 资源库 SDK(框架无关 TS,前端通过 npm workspace 引入)
├── design/                 # 设计文档(framework / architecture / api)
├── scripts/dev.sh          # 启停前后端的本地开发脚本
├── package.json            # npm workspace 根
└── README.md
```

## 技术栈

| 层 | 技术 |
| --- | --- |
| 后端 | Go 1.21+ / Gin / GORM / SQLite 或 MySQL / Redis 或 Memory 缓存 / JWT(golang-jwt v5)/ zap / viper |
| 前端 | React 18 / TypeScript / Vite / Ant Design 5 / Zustand / Axios |
| 资源库 SDK | TypeScript / Axios / 框架无关,通过 `X-Session-Id` 与资源库后端解耦会话 |

## 环境要求

- Go ≥ 1.21
- Node.js ≥ 18
- 可选:Redis(若后端 cache 切到 redis)、MySQL(若 db 切到 mysql)

## 快速开始

### 1. 一键启停(推荐)

仓库根提供 `scripts/dev.sh`,固定端口:**前端 9901、后端 9902**。

```bash
# 启动(自动 go build 后端二进制到 /tmp/holospace-server,然后拉起前后端)
./scripts/dev.sh start

# 查看状态 / 跟踪日志 / 重启 / 停止
./scripts/dev.sh status
./scripts/dev.sh tail
./scripts/dev.sh restart
./scripts/dev.sh stop
```

启动后可访问:
- 前端:http://localhost:9901/
- 后端:http://localhost:9902/

**默认账号**:`admin / admin123`(由 `internal/migrate` 启动期注入;生产环境务必通过 `SEED_ADMIN_PASSWORD` 环境变量覆盖)

### 2. 手动启动

#### 后端

```bash
cd backend
# 复制配置并按需修改
cp config.example.yaml config.yaml

# 构建 + 运行
go build -o /tmp/holospace-server ./cmd/server
JWT_SECRET=dev-secret-please-change /tmp/holospace-server
```

后端启动期会:
1. 加载 `config.yaml`(可用 `APP_CONFIG_FILE` 指定其他路径)
2. 环境变量优先级最高(`JWT_SECRET` / `HTTP_PORT` / `DB_DRIVER` / `CACHE_DRIVER` / `STORAGE_DRIVER` 等)
3. GORM AutoMigrate 建表
4. 种子数据注入:内置 admin 账号 + 4 条示例分类(可通过 `seed:` 配置块关闭或修改)

#### 前端

```bash
# 根目录安装 workspace 依赖(包含 SDK 软链)
npm install

# 启动开发服务器
npm run dev:frontend

# 类型检查
npm run check:frontend

# 生产构建(SDK + 前端)
npm run build
```

## 配置

### 后端

详见 `backend/config.example.yaml`。常用环境变量:

| 变量 | 说明 | 默认 |
| --- | --- | --- |
| `HTTP_PORT` | HTTP 监听端口 | 8080 |
| `JWT_SECRET` | JWT 签名密钥(**生产必填**) | 空 |
| `JWT_TTL_HOURS` | Token 有效期(小时) | 24 |
| `DB_DRIVER` | `sqlite` / `mysql` | sqlite |
| `DB_SQLITE_PATH` | SQLite 文件路径 | ./tmp/holospace.db |
| `CACHE_DRIVER` | `memory` / `redis` | memory |
| `STORAGE_DRIVER` | `local` / `s3` | local |
| `SEED_ENABLED` | 启动期种子数据开关 | true |
| `SEED_ADMIN_PASSWORD` | 种子 admin 密码 | admin123 |

### 前端

`.env` 模板见 `frontend/.env.example`;运行时配置可通过 `frontend/public/runtime-config.json` 覆盖(部署同源)。详见 `design/architecture.md` §2.3。

## 项目结构(概要)

### 后端

```
backend/
├── cmd/server/main.go           # 入口
├── internal/
│   ├── api/                     # Gin 处理器(auth/user/category/project/file/...)
│   ├── service/                 # 业务逻辑
│   ├── domain/                  # 实体与仓储
│   ├── infra/                   # db / cache / storage / log / token
│   ├── middleware/              # 鉴权 / 日志 / 错误 / CORS
│   ├── migrate/                 # GORM 迁移 + 启动期种子数据
│   ├── config/                  # viper 配置加载
│   └── router/                  # 路由总装
└── test/                        # 单元测试
```

### 前端

```
frontend/src/
├── app/                         # Router / Provider / ConfigProvider / 启动期 runtime 注入
├── pages/                       # Login / Projects / AssetLibrary / Profile
├── services/                    # http / api / assetlib(SDK 工厂)
├── stores/                      # Zustand(auth)
├── config/                      # build(env) / runtime(运行时覆盖)
├── antd-styles/                 # Industrial Precision 主题
├── types/                       # 与 design/api.md 对齐的 TS 类型
└── utils/                       # logger 等
```

## 资源库接入

本期**资源库后端由独立子域名/服务提供**,本仓库不实现。资源库 SDK 已内嵌在 `packages/rteditor-assetlib-sdk`,前端通过 `services/assetlib.ts` 工厂创建 `AssetLibClient`,使用 `X-Session-Id` 头部与资源库后端通信,与本项目业务 JWT 完全解耦。

实现细节、未消费端点降级策略见 `design/api.md` §7 与 `design/architecture.md` §1.1。

## 脚本一览

| 脚本 | 用途 |
| --- | --- |
| `./scripts/dev.sh start` | 启动前后端(端口 9901/9902) |
| `./scripts/dev.sh stop` | 停止前后端 |
| `./scripts/dev.sh restart` | 重启 |
| `./scripts/dev.sh status` | 查看运行状态 |
| `./scripts/dev.sh tail` | 跟踪后端日志 |
| `npm run build` | 顺序构建 SDK + 前端 |
| `npm run check:frontend` | 前端 TypeScript 类型检查 |
| `go test ./...` (backend) | 后端单元与集成测试 |

## 测试

```bash
# 后端
cd backend && go test ./...

# 前端类型检查
npm run check:frontend

# 前端构建
npm run build
```

## 部署

- **后端**:单二进制 `holospace-server`,通过 `config.yaml` + 环境变量注入配置;生产期 `JWT_SECRET` 必填。
- **前端**:静态资源,支持任意子路径部署;构建期通过 `VITE_PUBLIC_BASE` 注入 base,运行时可通过 `/runtime-config.json` 覆盖 API 前缀与资源库地址。`frontend/Dockerfile` 提供多阶段构建(Node → Nginx)。

## 编码约束

- 业务代码禁止 mock / 占位 / 模拟实现(测试代码除外)
- 临时文件 `./temp`,测试文件 `./test`
- 配置加载遵循"环境变量优先于 config.yaml"
- 统一响应:`{code, message, data}`,`code=0` 成功

## 许可证

UNLICENSED — 仅供项目内部使用。