Merge pull request #20 from benjamin-747/main

refactor: migrate atomgit/portal integrations and system-level error …

Author: benjamin-747

.env.example

@@ -7,3 +7,13 @@ LOG_LEVEL=debug
 
 # Go to https://smee.io/new set this to the URL that you are redirected to.
 WEBHOOK_PROXY_URL=
+
+# Backend API base (existing task API).
+API_ENDPOINT=
+
+# Portal server base URL for mentor limits API.
+# Example: https://portal.example.com
+PORTAL_ENDPOINT=
+
+# Bearer token for openatom integration APIs on portal.
+OPENATOM_INTEGRATION_TOKEN=

.github/workflows/bot-deploy.yml

@@ -81,6 +81,6 @@ jobs:
       #       -p 3000:3000 --restart=always \
       #       public.ecr.aws/m8q5m4u3/r2cn/bot:latest
       #       # Atomgit (when enabled): add GitHub repo secrets and uncomment, e.g.
-      #       # -e ATOMGIT_WEBHOOK_SECRET=${{ secrets.ATOMGIT_WEBHOOK_SECRET }} \
+      #       # -e PORTAL_ENDPOINT=${{ secrets.PORTAL_ENDPOINT }} \
       #       # -e ATOMGIT_API_BASE=${{ secrets.ATOMGIT_API_BASE }} \
       #       # -e ATOMGIT_TOKEN=${{ secrets.ATOMGIT_TOKEN }} \

README.md

@@ -38,17 +38,14 @@ Configure the repository webhook URL to **`POST https://<host>:<port>/webhooks/a
 
 | Variable | Description |
 |----------|-------------|
-| `ATOMGIT_WEBHOOK_SECRET` | Webhook secret: compared to `X-Gitlab-Token` / `X-AtomGit-Token` (default), or used for HMAC (see `ATOMGIT_WEBHOOK_VERIFY_MODE`). If unset, the route responds `200` with `{ ok: false }` and does not process payloads (avoids retry storms). |
-| `ATOMGIT_WEBHOOK_VERIFY_MODE` | `token` (default) or `hmac-sha256` (compare `X-AtomGit-Signature` / `X-Gitlab-Signature` as `sha256=<hex>` of raw body). |
+| `PORTAL_ENDPOINT` | Portal base URL. Atomgit webhook verification token is fetched by owner from `/api/integration/open-source-orgs/webhook-tokens` and cached for 5 minutes. |
+| `OPENATOM_INTEGRATION_TOKEN` | Bearer token used in `Authorization` header when calling portal openatom integration APIs. |
 | `ATOMGIT_API_BASE` | REST root for OpenAPI calls, e.g. `https://api.atomgit.com/api/v5`. Writes: comments `POST .../repos/:owner/:repo/issues/:number/comments`; labels `POST .../labels` (JSON **array of strings**); close/reopen issue uses `GET .../repos/:owner/:repo/issues/:number` then `PATCH .../repos/:owner/issues/:number` with **`application/x-www-form-urlencoded`** (`repo`, `title`, `body`, `state=close|reopen`) per [AtomGit](https://docs.atomgit.com/docs/apis/patch-api-v-5-repos-owner-issues-number). Required when handling Atomgit webhooks that need `AtomgitScmClient`. |
 | `ATOMGIT_TOKEN` | `Authorization: Bearer` token for OpenAPI. |
 | `ATOMGIT_API_VERSION` | Optional; default `2023-02-21` (`X-Api-Version` header). |
-| `ATOMGIT_DEFAULT_BRANCH` | Optional; default `main` — used for `getRepositoryContent` raw file reads. |
 
 **Payload mapping** (see `src/webhooks/map-atomgit-to-canonical.ts`): `Note Hook` / `object_kind: note` on an **Issue** → `IssueCommentCreated`; **Issue Hook** → `IssueLabeled` when (1) `action: update` and `changes.labels` has **at least one** new label, or (2) **`action: open`** and labels (on `object_attributes` or top-level `issue`) already include an **`r2cn-*`** score label (create-issue-with-labels). Other events are acknowledged with **200** and a debug log (no handler).
 
-**Config YAML**: `loadBotConfig` still reads `r2cn-dev/...` via `ScmClient.getRepositoryContent`. On Atomgit-only installs, that path must exist on the same instance or you need a separate config strategy (docs §7).
-
 ## Docker
 
 ```sh

comment.en.yaml

@@ -1,9 +1,15 @@
 project:
   noneProjectComment: >
-    Welcome to the R2CN project! Before getting started, you need to submit a PR first. For details, please refer to the documentation at https://r2cn.dev/docs/project/signup
+    Welcome to the R2CN project! Before getting started, you need to apply on the portal for project registration and mentor qualification onboarding.
   noneMaintainerComment: >
     You currently do not have permission to create R2CN tasks. Please contact your repository or organization administrator to submit a PR to add your GitHub ID to the r2cn.yaml file. For reference, see https://r2cn.dev/docs/project/mentor-and-tasks/mentor.
 
+system:
+  apiUnavailable: >
+    The backend API service is unavailable. Please try again later.
+  webhookTokenMismatch: >
+    Project registration failed. Please contact the administrator.
+
 task:
   success: >
     Task created successfully.
@@ -13,8 +19,6 @@ task:
     Task score and other information cannot be modified after the task is completed.
   taskNotFound: >
     The task has not been created yet. Please use the "R2CN-score" label to create a task first.
-  apiUnavailable: >
-    The backend API service is unavailable. Please try again later.
   scoreUndefinedComment: >
     Please use the "R2CN-score" label to create a task. The score in the current label is incorrect.
   scoreInvalidComment: >
@@ -38,7 +42,7 @@ requestAssign:
   success: >
     Claim successful: Waiting for mentor review. Please contact your mentor for review in a timely manner.
   waitingInfoReview: >
-    Claim failed: Please register as a student at https://summer-ospp.ac.cn/r2cnLogin and pass the review before claiming tasks.
+    Claim failed: Please register as a student at https://internship.xuanwu.openatom.cn/en/signin and pass the review before claiming tasks.
   waitingContract: >
     Claim failed: Contract not signed. If you have confirmed signing, please contact the administrator in the R2CN Discord (https://discord.gg/WRp4TKv6rh) #signup-student channel to update the contract signing status.
   existTask: >

comment.zh.yaml

@@ -1,8 +1,14 @@
 project:
   noneProjectComment: >
-    欢迎参与R2CN项目,在开始之前您需要先提交一个PR, 详情可参考文档 https://r2cn.dev/docs/project/signup
+    欢迎参与R2CN项目,在开始之前您需要先去 portal 申请项目注册和导师资格录入，详情可参考文档 https://r2cn.dev/docs/project/signup
   noneMaintainerComment: >
-    您当前没有权限来创建R2CN任务,请联系您仓库或者组织管理员提交PR将您的GitHub ID加入r2cn.yaml文件,参考 https://r2cn.dev/docs/project/mentor-and-tasks/mentor
+    您当前没有权限来创建R2CN任务,请联系开源实习方将您的信息维护到系统中.
+
+system:
+  apiUnavailable: >
+    当前后端 API 服务不可用，请稍后重试。
+  webhookTokenMismatch: >
+    项目注册失败，请联系管理员处理。
 
 task:
   success: >
@@ -12,13 +18,11 @@ task:
   notAllowedModify: >
     任务完成后无法修改分值等信息.
   taskNotFound: >
-    任务还未创建,需要使用“R2CN-分值”标签先创建任务.
-  apiUnavailable: >
-    当前后端 API 服务不可用，请稍后重试。
+    任务还未创建,需要使用“系统管理员配置的标签前缀-分值”标签先创建任务.
   scoreUndefinedComment: >
-    请使用“R2CN-分值”标签来创建任务,当前标签的分值不正确.
+    请使用“系统管理员配置的标签前缀-分值”标签来创建任务,当前标签的分值不正确.
   scoreInvalidComment: >
-    R2CN-分值超出组织管理员配置的上限,或者分值小于2.
+    系统管理员配置的标签前缀-分值超出组织管理员配置的上限,或者分值小于2.
   multiScoreLabel: >
     只能拥有一个分值标签,请先移除所有r2cn-分数标签,然后再选择1个r2cn-分数标签来新建任务.
   userToomanyTask: >
@@ -38,7 +42,7 @@ requestAssign:
   success: >
     认领成功: 等待导师审核,请及时联系导师进行审核.
   waitingInfoReview: >
-    认领失败: 请先在 https://summer-ospp.ac.cn/r2cnLogin 进行学生注册并通过审核后才能认领任务.
+    认领失败: 请先在 https://internship.xuanwu.openatom.cn/zh-CN/signin 进行学生注册并通过审核后才能认领任务.
   waitingContract: >
     认领失败: 合同未签署,如果已经确认签署请在 R2CN Discord(https://discord.gg/WRp4TKv6rh) 的 #signup-student 频道联系管理员更新合同签署状态.
   existTask: >

docs/dual-webhook-scm-architecture.md

@@ -229,13 +229,13 @@ src/
 
 | 变量 | 用途 |
 |------|------|
-| **`ATOMGIT_WEBHOOK_SECRET`** | Atomgit Webhook 验签密钥（具体算法与 Header 以官方文档为准） |
+| **`PORTAL_ENDPOINT`** | Portal 服务根地址；按 owner 从 `/api/integration/open-source-orgs/webhook-tokens` 拉取 Atomgit webhook token 并缓存 |
 | **`ATOMGIT_API_BASE`** | Atomgit OpenAPI 根 URL（例如 `https://api.atomgit.com/api/v5`，无尾斜杠）。发评论走 `POST /repos/:owner/:repo/issues/:number/comments`。 |
 | **`ATOMGIT_TOKEN`** | 调用 Atomgit API 的 token（或按组织拆为多 token，再增加 `ATOMGIT_TOKEN_*`） |
 
 #### 6.3.4 运维与对齐说明
 
-- **密钥轮换**：`WEBHOOK_SECRET` / `ATOMGIT_WEBHOOK_SECRET` 与平台控制台配置需同步更新。
+- **密钥轮换**：`WEBHOOK_SECRET` 与平台控制台配置需同步更新；Atomgit webhook token 由 portal 维护。
 - **文档维护**：实现落地后，将**最终**变量名与是否必填同步到 README 或运维 runbook；本文档第 6.3 节作为设计期清单，可与代码 `process.env` 使用处交叉引用。
 
 ---

src/config/index.ts

@@ -22,6 +22,7 @@ export interface Config {
 
 export interface BotComment {
     project: ProjectComment,
+    system: SystemComment,
     task: TaskComment,
     command: CommandComment,
     requestAssign: RequestAssign,
@@ -40,12 +41,16 @@ interface ProjectComment {
     noneMaintainerComment: string,
 }
 
+interface SystemComment {
+    apiUnavailable: string,
+    webhookTokenMismatch: string,
+}
+
 interface TaskComment {
     success: string,
     successUpdate: string,
     notAllowedModify: string,
     taskNotFound: string,
-    apiUnavailable: string,
     scoreUndefinedComment: string,
     multiScoreLabel: string,
     scoreInvalidComment: string,
@@ -110,6 +115,7 @@ export interface CommandRequest {
 export interface ApiResponse<T> {
     message: string;
     data: T;
+    status?: number;
 }
 
 const http = axios.create({
@@ -122,10 +128,47 @@ const NON_ERROR_MESSAGES = new Set([
 ]);
 
 export function isBackendApiError<T>(res: Pick<ApiResponse<T>, "message" | "data">): boolean {
+    const withStatus = res as Pick<ApiResponse<T>, "message" | "data" | "status">;
+    const message = String(res.message ?? "").trim();
     if (res.data != null) {
         return false;
     }
-    return !NON_ERROR_MESSAGES.has(res.message);
+    // Treat 4xx as business/domain failures, not service unavailability.
+    if (withStatus.status != null && withStatus.status >= 400 && withStatus.status < 500) {
+        return false;
+    }
+    // Explicit 5xx means backend/service failure.
+    if (withStatus.status != null && withStatus.status >= 500) {
+        return true;
+    }
+    if (message === "" || NON_ERROR_MESSAGES.has(message)) {
+        return false;
+    }
+    // Network-level failures from Axios/fetch-like stacks.
+    if (/(ECONNREFUSED|ECONNRESET|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|fetch failed|network error|socket hang up)/i.test(message)) {
+        return true;
+    }
+    // Keep this conservative: unknown textual messages without status are treated as business errors.
+    return false;
+}
+
+/**
+ * Some task/command POST endpoints return `{ data: true }` on success; others return
+ * `{ data: <Task | record> }` with HTTP 200. This treats both as success; `data === false` or
+ * `data == null` counts as failure.
+ */
+export function isCommandApiDataSuccess<T>(res: Pick<ApiResponse<T>, "data">): boolean {
+    const d = res.data as unknown;
+    if (d === true) {
+        return true;
+    }
+    if (d === false || d == null) {
+        return false;
+    }
+    if (typeof d === "object") {
+        return true;
+    }
+    return true;
 }
 
 function toFailedApiResponse<T>(error: unknown): ApiResponse<T> {
@@ -137,23 +180,54 @@ function toFailedApiResponse<T>(error: unknown): ApiResponse<T> {
             backendMessage ??
             (status != null ? `HTTP ${status}: ${e.message}` : e.message) ??
             "Unknown error occurred";
-        return { message: msg, data: null as unknown as T };
+        return { message: msg, data: null as unknown as T, status };
     }
     if (error instanceof Error) {
         return { message: error.message, data: null as unknown as T };
     }
     return { message: "Unknown error occurred", data: null as unknown as T };
 }
 
+function logApiAxiosError(
+    method: "GET" | "POST",
+    url: string,
+    payload: unknown,
+    error: unknown,
+    failedMessage: string,
+): void {
+    if (axios.isAxiosError(error)) {
+        const e = error as AxiosError<unknown>;
+        const base: Record<string, unknown> = {
+            method,
+            url,
+            status: e.response?.status,
+            body: e.response?.data,
+            message: e.message,
+            error: failedMessage,
+        };
+        if (method === "POST") {
+            base.payload = payload;
+        }
+        console.error("[api] error", base);
+        return;
+    }
+    console.error("[api] error", { method, url, error: failedMessage, cause: error });
+}
+
 export const fetchData = async <T>(url: string): Promise<ApiResponse<T>> => {
     try {
         console.info("[api] request", { method: "GET", url });
         const response: AxiosResponse<ApiResponse<T>> = await http.get(url);
-        console.info("[api] response", { method: "GET", url, message: response.data.message });
+        console.info("[api] response", {
+            method: "GET",
+            url,
+            status: response.status,
+            body: response.data,
+        });
         return response.data;
     } catch (error: unknown) {
         const failed = toFailedApiResponse<T>(error);
-        console.error("[api] error", { method: "GET", url, error: failed.message });
+        logApiAxiosError("GET", url, undefined, error, failed.message);
         return failed;
     }
 };
@@ -162,16 +236,16 @@ export const postData = async <T, U>(url: string, payload: U): Promise<ApiRespon
     try {
         console.info("[api] request", { method: "POST", url, payload });
         const response: AxiosResponse<ApiResponse<T>> = await http.post(url, payload);
-        console.info("[api] response", { method: "POST", url, message: response.data.message });
-        return response.data;
-    } catch (error: unknown) {
-        const failed = toFailedApiResponse<T>(error);
-        console.error("[api] error", {
+        console.info("[api] response", {
             method: "POST",
             url,
-            error: failed.message,
-            payload,
+            status: response.status,
+            body: response.data,
         });
+        return response.data;
+    } catch (error: unknown) {
+        const failed = toFailedApiResponse<T>(error);
+        logApiAxiosError("POST", url, payload, error, failed.message);
         return failed;
     }
 };