# OpenPlatform

**Repository Path**: my919/open-platform

## Basic Information

- **Project Name**: OpenPlatform
- **Description**: No description available
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenPlatform（同意开放平台）

面向第三方应用与终端用户的**授权 / 同意**管理能力：租户、应用（OAuth 风格 client）、Scope、平台用户映射，以及用户同意记录与撤销（PostgreSQL）。

英文说明见 [README.en.md](README.en.md)。

## 技术栈

- **语言**：Go 1.22+
- **HTTP**：Echo；进程生命周期：Kratos v2 `transport/http`
- **数据库**：PostgreSQL，访问层 `pgx/v5`
- **API 文档**：Swagger 2.0（`swag` 生成 + `echo-swagger` 提供 UI）

## 环境要求

- Go 1.22 或更高版本
- PostgreSQL（已创建空库，且具备建表权限）

## 数据库准备

在目标库中执行建表脚本（可任选 `psql` 或图形客户端）：

```bash
psql "$DATABASE_URL" -f sql/schema.sql
```

可选：导入示例数据（演示租户 / 应用 / 用户等）：

```bash
psql "$DATABASE_URL" -f sql/seed_example.sql
```

> `seed_example.sql` 中的 `client_secret_hash` 为占位符，正式环境请通过接口创建应用以写入真实 bcrypt 哈希。

## 环境变量

| 变量 | 必填 | 说明 |
|------|------|------|
| `APP_ENV` | 否 | 运行环境标识，未设置时视为 `local`；用于选择加载 `.env.<APP_ENV>` |
| `DATABASE_URL` | 是 | PostgreSQL 连接串，例如 `postgres://user:pass@127.0.0.1:5432/dbname?sslmode=disable` |
| `LISTEN_ADDR` | 否 | HTTP 监听地址，默认 `:8080` |

### 使用 .env 区分环境

在**仓库根目录**（与 `go.mod` 同级）放置 env 文件，启动时会自动加载（见 `src/internal/config/env.go`）：

1. 先加载 `.env`（若存在）：写入环境变量，**不会**覆盖已在 shell 中导出的同名变量。  
2. 再加载 `.env.<APP_ENV>`（若存在）：**会覆盖**上一步从 `.env` 写入的同名项，也会覆盖 **shell 中已导出** 的同名变量（仅针对该文件中列出的键）。`APP_ENV` 未设置时为 `local`。

典型用法：

```bash
cp .env.example .env.local
# 编辑 .env.local 填入本地数据库等
export APP_ENV=local   # 可省略，默认即 local
go run ./src/cmd/server
```

测试 / 生产可分别维护 `.env.test`、`.env.production`，启动前设置 `APP_ENV=test` 或 `APP_ENV=production`（若只存在 `.env.production` 而无 `.env`，必须在 shell 中导出 `APP_ENV`，否则会先按默认 `local` 去找 `.env.local`）。生产环境更推荐在 K8s、systemd 等侧注入变量，避免在磁盘保存密钥。

已忽略提交：`.env`、`.env.*`（保留仓库中的 `.env.example`）。

## 启动方式

在**仓库根目录**执行（可直接依赖 `.env`，也可继续用 export 覆盖）：

```bash
# 任选其一：使用 .env* 文件，或临时导出
# export DATABASE_URL='postgres://user:pass@127.0.0.1:5432/yourdb?sslmode=disable'

go run ./src/cmd/server
```

编译为可执行文件后运行：

```bash
go build -o bin/server ./src/cmd/server
./bin/server
```

服务就绪后：

- **健康检查**：`GET http://127.0.0.1:8080/healthz`
- **业务 API**：前缀 `http://127.0.0.1:8080/api/v1/`
- **Swagger UI**：浏览器打开 [http://127.0.0.1:8080/swagger/index.html](http://127.0.0.1:8080/swagger/index.html)

## 重新生成 Swagger 文档

修改接口注解后，在 `src/cmd/server` 目录执行：

```bash
cd src/cmd/server && go generate
```

或在仓库根目录：

```bash
swag init -g main.go -d src/cmd/server,src/internal/handler,src/internal/server --parseInternal -o src/docs
```

需已安装 `swag`：`go install github.com/swaggo/swag/cmd/swag@latest`。

## 参与贡献

1. Fork 本仓库  
2. 新建功能分支（如 `Feat_xxx`）  
3. 提交代码并发起 Pull Request