# 贡献指南

感谢关注 Prism！本仓库托管于 [git.rc707blog.top](https://git.rc707blog.top/rose_cat707/Prism)。

## 开发环境

### 依赖

- Go 1.25+（见 `go.mod`）
- Node.js 20+（仅前端开发/构建）

国内网络可使用仓库内已配置的镜像：

- Go：`go.env` → `GOPROXY=https://goproxy.cn,direct`
- npm：`web/.npmrc` → `registry.npmmirror.com`

海外用户可将 `GOPROXY` 改为 `https://proxy.golang.org,direct`，npm 使用默认 registry 即可。

### 启动

```bash
# 终端 1：后端
make run

# 终端 2：前端（Vite 代理 /api → :8080）
make dev-web
```

浏览器访问 http://localhost:5173 ，默认密码 `admin`。

### 测试与构建

```bash
make test   # 运行 Go 单元测试
make build  # 构建含前端的单二进制 dist/prism
```

## 提交规范

- 一个 PR 聚焦一个主题，避免混合无关重构
- 涉及 API 变更时同步更新 `internal/api/openapi/spec.yaml`
- 涉及 UI 变更请参考 `UI-DESIGN-SYSTEM.md`
- 确保 `go test ./...` 通过

## CI / 镜像发布

仓库使用 **Gitea Actions**（`.gitea/workflows/ci.yml`）：

| 触发 | 行为 |
|------|------|
| Pull Request | 仅运行 `go test ./...` |
| 推送到 `main` / `master` | 测试 + 构建并推送 `latest` 与 `sha-xxxxxxx` 镜像 |
| 推送 tag `v*` | 测试 + 额外推送版本 tag 镜像 |

镜像发布到 Gitea Container Registry：

```
git.rc707blog.top/{owner}/prism:{tag}
```

### 维护者：配置 CI Secret

在仓库 **Settings → Secrets → Actions** 添加：

| Secret | 说明 |
|--------|------|
| `REGISTRY_TOKEN` | 具有 `write:package` 权限的 Personal Access Token |

> **注意：** Secret 名称不能以 `GITEA_` 或 `GITHUB_` 开头（Gitea 保留前缀），因此使用 `REGISTRY_TOKEN` 而非 `GITEA_TOKEN`。

> Gitea Actions 的 job token 暂不支持直接推送软件包，需使用 PAT。见 [Gitea 文档](https://docs.gitea.com/usage/actions/comparison#package-repository-authorization)。

### Runner 配置

CI 使用 **`runs-on: ubuntu-latest`**（须与 Runners 页「**标签**」列一致）。

1. **Settings → Actions → Runners** 确认 runner **在线**，标签含 `ubuntu-latest`
2. 标签映射的 job 镜像须含 **Node.js**（否则 `actions/checkout` 会报 `node not in PATH`）
3. **构建镜像**：runner 须挂载 `/var/run/docker.sock`（见 [.gitea/act-runner/README.md](.gitea/act-runner/README.md)）
4. CI 使用 shell 安装 Go（阿里云 / golang.google.cn 镜像），避免 `setup-go` 从 GitHub 下载超时

## 目录结构

```
cmd/prism/           进程入口
internal/api/        HTTP 层、OpenAPI、嵌入静态资源
internal/store/      SQLite 与迁移
internal/service/    业务编排
internal/configbuilder/  Mihomo YAML 合成
web/                 Vue 3 管理台
.gitea/workflows/    CI 工作流
```

## 许可

提交代码即表示你同意在 [MIT License](LICENSE) 下授权你的贡献。嵌入的 Mihomo 内核遵循其自身许可，见 [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)。