Skip to main content

acosmi/support/
bug_report.rs

1//! 支持 / 反馈域:CrabCode CLI bug 报告。端口自 `support/bug-report.ts`
2//! (注入 `submit_bug_report` / `get_bug_report` 到 [`Client`],declaration-merging 模式)。
3//!
4//! V30 CrabCode CLI bug 报告端点封装:
5//!   - POST /api/v4/crabcode_cli_feedback  —— Bearer JWT (account scope),限流 20/h/user
6//!   - GET  /api/v4/crabcode/bug/:bug_id   —— 公开(无 auth),限流 60/min/IP
7//!
8//! 设计要点:
9//!   - report_data 用 `serde_json::Value`(调用方任意 JSON),后端只解析为 map 做脱敏 + 字段
10//!     抽取,不做严格 schema 校验。
11//!   - 服务端兜底脱敏 6 类正则;调用方无须自行做密钥过滤。
12//!   - 公开 GET 端点走 `do_public_json_full`,无 token 也能调。
13
14use crate::core::client::Client;
15use crate::shared::{Error, Result};
16use serde::{Deserialize, Serialize};
17use serde_json::{json, Value};
18use std::collections::HashMap;
19use tokio_util::sync::CancellationToken;
20
21/// 响应解包 —— 这两个端点返回**裸字段**,不是平台通用的 `{code, data, msg}` 信封。
22///
23/// 真源:nexus-v4 `internal/handler/crabcode_bug.go`
24///   `Submit`   → `c.JSON(200, gin.H{"feedback_id": …, "detail_url": …})`
25///   `AdminGet` → `c.JSON(200, view)`
26/// Go SDK(`bug_report.go`,整条移植链的源头)也是直接 decode 进 `BugReportResult`。
27/// 是 TS 移植先套了一层 `APIResponse`,本文件又照着 TS 抄了过来 —— 本文件自己的
28/// `bug_report_result_wire_snake_case` 单测注释里写着「端点裸字段,非 ApiResponse
29/// 信封」,测的却只有结构体的 serde 形态,从来没测过这条 wire 路径,于是这句正确的
30/// 描述和错误的实现在同一个文件里共存了很久。
31///
32/// 后果不轻:套了信封的版本恒失败,而网关此时**已经落库并发出通知邮件**。
33///
34/// 这里裸形态优先、信封形态兜底:网关将来若统一成信封,无需再动 SDK。
35fn unwrap_bare_or_enveloped<T: serde::de::DeserializeOwned>(raw: Value, op: &str) -> Result<T> {
36    let observed_keys = || -> String {
37        match raw.as_object() {
38            Some(map) if !map.is_empty() => map.keys().cloned().collect::<Vec<_>>().join(","),
39            _ => "<none>".to_string(),
40        }
41    };
42    let inner = raw.as_object().and_then(|m| m.get("data")).cloned();
43    if let Ok(value) = serde_json::from_value::<T>(raw.clone()) {
44        return Ok(value);
45    }
46    if let Some(inner) = inner {
47        if let Ok(value) = serde_json::from_value::<T>(inner) {
48            return Ok(value);
49        }
50    }
51    Err(Error::other(format!(
52        "acosmi: {op}: gateway accepted the request but the response is missing required fields (observed keys: {})",
53        observed_keys()
54    )))
55}
56
57/// POST /api/v4/crabcode_cli_feedback 返回体。对应 TS `BugReportResult`。
58#[derive(Debug, Clone, Serialize, Deserialize)]
59pub struct BugReportResult {
60    /// 服务端生成的 UUID(写入 GitHub Issue body 用)。
61    pub feedback_id: String,
62    /// 公开页链接,形如 `https://<base>/chat/crabcode/bug/<uuid>`。
63    pub detail_url: String,
64}
65
66/// GET /api/v4/crabcode/bug/:id 返回体(公开 ViewModel)。对应 TS `BugView`。
67///
68/// errors / transcript / extras 用 `Vec<Value>` / `HashMap<String, Value>`:客户端 reportData
69/// schema 会随版本变,SDK 不强 typed。
70#[derive(Debug, Clone, Serialize, Deserialize)]
71pub struct BugView {
72    pub id: String,
73    pub description: String,
74    #[serde(default, skip_serializing_if = "Option::is_none")]
75    pub platform: Option<String>,
76    #[serde(default, skip_serializing_if = "Option::is_none")]
77    pub terminal: Option<String>,
78    #[serde(default, skip_serializing_if = "Option::is_none")]
79    pub version: Option<String>,
80    #[serde(rename = "messageCount")]
81    pub message_count: i64,
82    #[serde(rename = "hasErrors")]
83    pub has_errors: bool,
84    pub status: String,
85    #[serde(
86        rename = "clientDatetime",
87        default,
88        skip_serializing_if = "Option::is_none"
89    )]
90    pub client_datetime: Option<String>,
91    #[serde(rename = "createdAt")]
92    pub created_at: String,
93    #[serde(default, skip_serializing_if = "Option::is_none")]
94    pub errors: Option<Vec<Value>>,
95    #[serde(default, skip_serializing_if = "Option::is_none")]
96    pub transcript: Option<Vec<Value>>,
97    #[serde(default, skip_serializing_if = "Option::is_none")]
98    pub extras: Option<HashMap<String, Value>>,
99}
100
101impl Client {
102    /// 上报一份 CrabCode bug 报告。对应 TS `submitBugReport`。
103    ///
104    /// `report_data` 是任意 JSON 可编码值,后端只解析为 map 做脱敏 + 字段抽取。
105    ///
106    /// 错误:
107    ///   - [`Error::Http`] 401 —— token 过期(内部已做一次 refresh + retry,仍 401 抛出)。
108    ///   - [`Error::Http`] 403 type="permission_error"(含 "Custom data retention settings")
109    ///     —— 用户所在组织 ZDR,拒绝收集。
110    ///   - [`Error::Http`] 400 type="invalid_request_error" —— content 不是合法 JSON。
111    ///   - [`Error::Http`] 429 —— 限流 20/h/user。
112    ///   - [`Error::Network`] —— 传输层错误。
113    pub async fn submit_bug_report(
114        &self,
115        report_data: &Value,
116        signal: Option<CancellationToken>,
117    ) -> Result<BugReportResult> {
118        if report_data.is_null() {
119            return Err(Error::other("acosmi: reportData required"));
120        }
121        let content_str = serde_json::to_string(report_data)
122            .map_err(|e| Error::other(format!("acosmi: marshal reportData: {e}")))?;
123        let body = json!({ "content": content_str }).to_string();
124        let (raw, _) = self
125            .do_json_full::<Value>(
126                http::Method::POST,
127                "/crabcode_cli_feedback",
128                Some(&body),
129                signal,
130            )
131            .await?;
132        let raw = raw.ok_or_else(|| Error::other("/crabcode_cli_feedback: empty response body"))?;
133        unwrap_bare_or_enveloped(raw, "submit_bug_report")
134    }
135
136    /// 取公开 ViewModel(无需 auth,任意人凭 ID 可读)。对应 TS `getBugReport`。
137    ///
138    /// 错误:
139    ///   - [`Error::Http`] 404 —— bug 不存在或被软删。
140    ///   - [`Error::Http`] 429 —— 限流 60/min/IP。
141    ///   - [`Error::Network`] —— 传输层错误。
142    pub async fn get_bug_report(
143        &self,
144        bug_id: &str,
145        signal: Option<CancellationToken>,
146    ) -> Result<BugView> {
147        let trimmed = bug_id.trim();
148        if trimmed.is_empty() {
149            return Err(Error::other("acosmi: bugID required"));
150        }
151        // 公开端点 —— 不强制 token(未登录 / token 过期场景下也能查)。
152        let raw: Value = self
153            .do_public_json_full(&format!("/crabcode/bug/{trimmed}"), signal)
154            .await?;
155        unwrap_bare_or_enveloped(raw, "get_bug_report")
156    }
157}
158
159#[cfg(test)]
160mod tests {
161    use super::*;
162
163    // —— wire 路径闸门 ——
164    //
165    // 下面这些钉的是 `submit_bug_report` / `get_bug_report` 实际会走的解包分支。
166    // 此前本 mod 只测结构体的 serde 形态,恒绿,照不到「多套了一层 ApiResponse
167    // 信封」这个真实缺陷 —— 断言数不为零但对该缺陷零覆盖。
168
169    #[test]
170    fn unwraps_bare_response_which_is_what_the_gateway_returns() {
171        let raw = serde_json::json!({
172            "feedback_id": "uuid-1",
173            "detail_url": "https://x/chat/crabcode/bug/uuid-1"
174        });
175        let r: BugReportResult = unwrap_bare_or_enveloped(raw, "submit_bug_report").unwrap();
176        assert_eq!(r.feedback_id, "uuid-1");
177        assert_eq!(r.detail_url, "https://x/chat/crabcode/bug/uuid-1");
178    }
179
180    #[test]
181    fn still_unwraps_envelope_response_so_a_gateway_change_does_not_regress() {
182        let raw = serde_json::json!({
183            "code": 0,
184            "msg": "",
185            "data": { "feedback_id": "uuid-2", "detail_url": "https://x/d" }
186        });
187        let r: BugReportResult = unwrap_bare_or_enveloped(raw, "submit_bug_report").unwrap();
188        assert_eq!(r.feedback_id, "uuid-2");
189    }
190
191    #[test]
192    fn missing_required_fields_errors_with_observed_keys() {
193        let raw = serde_json::json!({ "code": 0, "msg": "ok" });
194        let err = unwrap_bare_or_enveloped::<BugReportResult>(raw, "submit_bug_report")
195            .expect_err("must not silently succeed: the report is likely already stored");
196        let msg = err.to_string();
197        assert!(msg.contains("submit_bug_report"), "op missing from: {msg}");
198        assert!(msg.contains("code"), "observed keys missing from: {msg}");
199        assert!(msg.contains("msg"), "observed keys missing from: {msg}");
200    }
201
202    #[test]
203    fn bug_view_unwraps_bare_admin_response() {
204        let raw = serde_json::json!({
205            "id": "uuid-3",
206            "description": "boom",
207            "messageCount": 2,
208            "hasErrors": true,
209            "status": "new",
210            "createdAt": "2026-08-04T00:00:00Z"
211        });
212        let v: BugView = unwrap_bare_or_enveloped(raw, "get_bug_report").unwrap();
213        assert_eq!(v.id, "uuid-3");
214        assert_eq!(v.description, "boom");
215    }
216
217    #[test]
218    fn bug_report_result_wire_snake_case() {
219        // feedback_id / detail_url 是 snake_case(端点裸字段,非 ApiResponse 信封)。
220        let r: BugReportResult = serde_json::from_str(
221            r#"{"feedback_id":"uuid-1","detail_url":"https://x/chat/crabcode/bug/uuid-1"}"#,
222        )
223        .unwrap();
224        assert_eq!(r.feedback_id, "uuid-1");
225        assert_eq!(r.detail_url, "https://x/chat/crabcode/bug/uuid-1");
226        let back = serde_json::to_value(&r).unwrap();
227        assert_eq!(back["feedback_id"], "uuid-1");
228        assert_eq!(back["detail_url"], "https://x/chat/crabcode/bug/uuid-1");
229    }
230
231    #[test]
232    fn bug_view_camel_case_wire() {
233        let v: BugView = serde_json::from_str(
234            r#"{"id":"b1","description":"d","messageCount":3,"hasErrors":true,"status":"open","createdAt":"2026-05-01T00:00:00","extras":{"k":"v"}}"#,
235        )
236        .unwrap();
237        assert_eq!(v.id, "b1");
238        assert_eq!(v.message_count, 3);
239        assert!(v.has_errors);
240        assert_eq!(v.created_at, "2026-05-01T00:00:00");
241        assert!(v.extras.is_some());
242    }
243}