# orbit

**Repository Path**: nbea/orbit

## Basic Information

- **Project Name**: orbit
- **Description**: 工时登记系统
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Orbit

Orbit 是一个 PC 端项目管理平台原型，当前包含两个一期模块：

- 系统管理：用户、角色、菜单权限管理，以及用户创建。
- 工时管理：项目工时登记与查询。

## 项目结构

```text
.
├── orbit-admin       # React + TypeScript + Ant Design 前端原型
├── orbit-services    # Java + Spring Boot 业务主后端
├── docs              # 表结构与设计说明
└── infra             # PostgreSQL / Redis 本地基础设施
```

## 本地启动

环境建议：

- Node.js 18+
- JDK 17+
- Maven 3.8+

## Docker 一键部署

项目已提供完整 Docker Compose 编排，包含：

- PostgreSQL 16
- Redis 7
- `orbit-services` 后端服务
- `orbit-admin` 前端 Nginx 静态站点与 `/api` 反向代理

从项目根目录执行：

```bash
docker compose -f infra/docker-compose.yml up -d --build
```

部署完成后访问：

```text
前端：http://localhost:8182
后端：http://localhost:8180
PostgreSQL：localhost:15432
Redis：localhost:16379
```

停止：

```bash
docker compose -f infra/docker-compose.yml down
```

如需同时删除数据库数据卷：

```bash
docker compose -f infra/docker-compose.yml down -v
```

可通过环境变量覆盖默认端口和密码：

```bash
POSTGRES_PORT=15432 \
REDIS_PORT=16379 \
ORBIT_SERVICES_PORT=18180 \
ORBIT_ADMIN_PORT=18182 \
POSTGRES_PASSWORD=orbit \
REDIS_PASSWORD='antelope@123' \
docker compose -f infra/docker-compose.yml up -d --build
```

### 启停脚本

```bash
# 启动前后端
scripts/orbit.sh start

# 查看运行状态
scripts/orbit.sh status

# 停止前后端
scripts/orbit.sh stop
```

也可以单独操作某个服务：

```bash
scripts/orbit.sh start backend
scripts/orbit.sh start frontend
scripts/orbit.sh status backend
scripts/orbit.sh stop frontend
```

脚本会把 PID 和日志写入 `.orbit-runtime/`：

- 后端日志：`.orbit-runtime/orbit-services.log`
- 前端日志：`.orbit-runtime/orbit-admin.log`

### 本地基础设施

当前默认连接本机服务：

- PostgreSQL：`localhost:5432/orbit`
- Redis：`localhost:6379`，密码见后端配置

如果需要重新初始化 PostgreSQL 用户和数据库，可参考本文末尾 SQL。

### 后端

```bash
cd orbit-services
export JAVA_HOME=/opt/homebrew/opt/openjdk@17
export PATH="$JAVA_HOME/bin:$PATH"
mvn spring-boot:run
```

默认服务地址：`http://localhost:8180`

### 前端

```bash
cd orbit-admin
npm install
npm run dev
```

默认前端地址：`http://localhost:8182`

## 默认账号

```text
账号：admin
密码：orbit123
```

## 智能助理 API KEY 登记工时

Orbit 支持给当前登录用户生成个人 API KEY，用于智能助理通过 RESTful 接口登记工时。

### 生成 API KEY

登录系统后进入：

```text
系统管理 -> API KEY 管理
```

填写 KEY 名称后点击“生成 API KEY”。生成后的 KEY 只展示一次，请妥善保存。

API KEY 默认只具备以下权限范围：

```text
worktime:write
```

它只能调用集成类工时登记接口，不能访问用户管理、角色管理等后台管理接口。若不再使用，可在页面中吊销。

### 接口地址

```http
POST /api/integration/worktime/entries
```

如果通过前端 Nginx 访问，推荐使用：

```text
http://localhost:8182/api/integration/worktime/entries
```

服务器部署时可替换为实际 IP 或域名：

```text
http://10.192.125.5:8182/api/integration/worktime/entries
```

### 认证方式

推荐使用请求头：

```http
X-API-Key: orbit_sk_xxxxxxxxxxxxxxxxx
```

也兼容：

```http
Authorization: Bearer orbit_sk_xxxxxxxxxxxxxxxxx
```

### 请求体

```json
{
  "projectType": "研发项目",
  "customerName": "内部",
  "projectName": "Orbit 平台",
  "workDate": "2026-05-20",
  "hours": 2.5,
  "content": "通过智能助理登记 Orbit API KEY 工时接口"
}
```

字段说明：

- `projectType`：项目类型，枚举值为 `交付项目`、`咨询项目`、`研发项目`、`其他`
- `customerName`：客户名称
- `projectName`：项目名称
- `workDate`：工作日期，格式 `YYYY-MM-DD`
- `hours`：工时，范围大于 0 且不超过 24
- `content`：工作内容

### curl 示例

```bash
curl -X POST 'http://localhost:8182/api/integration/worktime/entries' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: orbit_sk_xxxxxxxxxxxxxxxxx' \
  -d '{
    "projectType": "研发项目",
    "customerName": "内部",
    "projectName": "Orbit 平台",
    "workDate": "2026-05-20",
    "hours": 2.5,
    "content": "通过智能助理登记 Orbit API KEY 工时接口"
  }'
```

接口会根据 API KEY 自动识别登记用户，调用方不能指定或覆盖 `userId`。

### 脚本调用示例

项目内提供了一个直接调用 RESTful 接口的脚本：

```bash
ORBIT_API_KEY=orbit_sk_xxxxxxxxxxxxxxxxx \
PROJECT_TYPE=研发项目 \
CUSTOMER_NAME=内部 \
PROJECT_NAME='Orbit 平台' \
WORK_DATE=2026-05-20 \
HOURS=2.5 \
CONTENT='通过智能助理登记工时' \
scripts/orbit-worktime-api.sh
```

如果部署在服务器上，可指定服务地址：

```bash
ORBIT_API_BASE='http://10.192.125.5:8182' \
ORBIT_API_KEY=orbit_sk_xxxxxxxxxxxxxxxxx \
PROJECT_TYPE=研发项目 \
CUSTOMER_NAME=内部 \
PROJECT_NAME='Orbit 平台' \
WORK_DATE=2026-05-20 \
HOURS=2.5 \
CONTENT='通过智能助理登记工时' \
scripts/orbit-worktime-api.sh
```

## PostgreSQL 初始化 SQL

使用有管理员权限的 PostgreSQL 账号执行：

```sql
create user orbit with password 'orbit';
create database orbit owner orbit;
grant all privileges on database orbit to orbit;

\c orbit

grant usage, create on schema public to orbit;
alter schema public owner to orbit;
alter default privileges in schema public grant all on tables to orbit;
alter default privileges in schema public grant all on sequences to orbit;
alter default privileges in schema public grant all on functions to orbit;
```