tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-10-03 15:06:36 +08:00
Code Issues Packages Projects Releases Wiki Activity

upload+accessKey

Browse Source
This commit is contained in:
ryan
2026-06-07 21:21:06 +08:00
parent 360a26f109
commit 70a13dc107
35 changed files with 4763 additions and 1321 deletions
Download Patch File Download Diff File Expand all files Collapse all files
frontend/components/common/docs/api.tsx
+205 -526
View File
@@ -1,15 +1,15 @@
import { type PolicySection } from "./types"
import { CodeBlock } from "@/components/ui/code-block"
import {type PolicySection} from "./types"
import {CodeBlock} from "@/components/ui/code-block"
import {
DocsTable,
DocsTableHeader,
DocsTableBody,
DocsTableHead,
DocsTableRow,
DocsTableCell,
DocsTableHead,
DocsTableHeader,
DocsTableRow,
} from "@/components/ui/docs-table"
export const DOCS_LAST_UPDATED = "2026-04-20"
export const DOCS_LAST_UPDATED = "2026-06-07"
/**
* ------------------------------------------------------------------
@@ -18,572 +18,251 @@ export const DOCS_LAST_UPDATED = "2026-04-20"
*/
export const apiSections: PolicySection[] = [
{
value: "official-service",
title: "1. 官方 LDC 接口",
value: "api-specs",
title: "1. 接口规范与鉴权说明",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<div className="bg-muted/50 border border-border/50 rounded-lg px-3 py-2 mb-6">
<p className="text-muted-foreground m-0">官方原生接口，使用 Ed25519 签名算法，安全性更高</p>
<p className="text-muted-foreground m-0">平台统一接口调用格式规范以及开发者访问令牌鉴权方式说明</p>
</div>
<h3 id="1-1-overview" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">1.1 概览</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-2">
<li><strong>协议：</strong>官方 LDC 支付协议</li>
<li><strong>服务类型：</strong>支持 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">type=ldcpay</code></li>
<li><strong>网关基址：</strong><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">https://credit.linux.do/epay</code></li>
<li><strong>签名方式：</strong>Ed25519 非对称加密</li>
</ul>
<h3 id="1-2-flow" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">1.2 对接流程</h3>
<ol className="list-decimal pl-4 md:pl-5 space-y-2">
<li>控制台创建应用，配置 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">client_id</code> 并在应用设置中上传商户 Ed25519 公钥</li>
<li>根据“签名算法”及商户私钥生成 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">sign</code></li>
<li>调用 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">/pay/submit</code> 发起积分流转请求</li>
<li>认证完成后，通过异步回调或轮询接口同步状态</li>
</ol>
<h3 id="1-3-auth-sign" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">1.3 鉴权与签名</h3>
<h4 className="font-medium text-foreground mt-3 md:mt-4 mb-2">1.3.1 签名算法</h4>
<div className="space-y-4">
<ol className="list-decimal pl-4 md:pl-5 space-y-2">
<li>取除 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">sign</code> 以外的所有非空请求参数</li>
<li>将参数按参数名 ASCII 码从到大排序（字典序）</li>
<li>使用 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">k1=v1&k2=v2...</code> 格式拼接成字符串</li>
<li>将 <strong>应用密钥 (Client Secret)</strong> 直接追加到字符串末尾</li>
<li>使用商户私钥对最终字符串进行 <strong>Ed25519</strong> 签名</li>
<li>将签名结果转换成 Base64 编码作为 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">sign</code> 参数</li>
</ol>
<CodeBlock
code={`// 示例：client_id=1&money=10.00&order_name=Test&out_trade_no=M1&type=ldcpay{SECRET}
data = "client_id=1&money=10.00&order_name=Test&out_trade_no=M1&type=ldcpay" + client_secret
signature = ed25519.Sign(privateKey, []byte(data))
signBase64 = base64.StdEncoding.EncodeToString(signature)`}
language="javascript"
/>
</div>
<h3 id="1-4-submit" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">1.4 积分流转服务</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-2 mb-6">
<li><strong>方法：</strong>POST <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">/epay/pay/submit.php</code></li>
<li><strong>编码：</strong><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">application/json</code> 或 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">application/x-www-form-urlencoded</code></li>
</ul>
<h3 id="1-1-response-format" className="text-base md:text-lg font-semibold text-foreground mt-6 mb-3">1.1 统一响应格式</h3>
<p>系统所有 API 接口均遵循标准 JSON 响应结构：</p>
<DocsTable>
<DocsTableHeader>
<DocsTableRow>
<DocsTableHead className="w-[100px] whitespace-nowrap">参数</DocsTableHead>
<DocsTableHead className="w-[80px] whitespace-nowrap">必填</DocsTableHead>
<DocsTableHead className="w-[120px]">字段</DocsTableHead>
<DocsTableHead className="w-[100px]">类型</DocsTableHead>
<DocsTableHead>说明</DocsTableHead>
</DocsTableRow>
</DocsTableHeader>
<DocsTableBody>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">client_id</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>应用客户端 ID</DocsTableCell>
<DocsTableCell className="font-mono text-xs">error_msg</DocsTableCell>
<DocsTableCell>string</DocsTableCell>
<DocsTableCell>错误信息。请求成功时为空字符串 `""`，失败时包含错误详情描述。</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">type</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>固定 <code className="bg-muted px-1 rounded text-xs before:content-none after:content-none">ldcpay</code></DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">out_trade_no</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>业务单号</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">money</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>积分数量，必须保留两位小数（比如，10.00）</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">order_name</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>商品名称</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">notify_url</DocsTableCell>
<DocsTableCell>否</DocsTableCell>
<DocsTableCell>会参与签名；可选订单级异步通知地址。长度不超过 100，需为合法 URL。传入后支付成功优先回调该地址，未传则使用应用 notify_url</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">return_url</DocsTableCell>
<DocsTableCell>否</DocsTableCell>
<DocsTableCell>会参与签名；可选订单级回跳地址。长度不超过 100，需为合法 URL。传入后支付成功页面优先跳转该地址，未传则使用应用 redirect_uri</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">sign</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>按“签名算法”生成的 Base64 签名串</DocsTableCell>
<DocsTableCell className="font-mono text-xs">data</DocsTableCell>
<DocsTableCell>any</DocsTableCell>
<DocsTableCell>接口返回的具体数据内容。请求失败或无数据返回时为 `null`。</DocsTableCell>
</DocsTableRow>
</DocsTableBody>
</DocsTable>
<h3 id="1-5-others" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">1.5 其他接口</h3>
<p className="text-muted-foreground mb-4">其他接口定义请参考 <a href="#3-common-services" className="text-primary underline underline-offset-4">3. 其他接口</a>。</p>
<ul className="list-disc pl-4 md:pl-5 space-y-2">
<li><strong>订单查询：</strong>详见 <a href="#3-1-order" className="text-primary underline underline-offset-4">3.1 订单查询</a></li>
<li><strong>订单退款：</strong>详见 <a href="#3-2-refund" className="text-primary underline underline-offset-4">3.2 订单退款</a></li>
<li><strong>异步通知：</strong>详见 <a href="#3-3-notify" className="text-primary underline underline-offset-4">3.3 异步通知</a></li>
</ul>
</div>
),
children: [
{ value: "1-1-overview", title: "1.1 概览" },
{ value: "1-2-flow", title: "1.2 对接流程" },
{ value: "1-3-auth-sign", title: "1.3 鉴权与签名" },
{ value: "1-4-submit", title: "1.4 积分流转服务" },
{ value: "1-5-others", title: "1.5 其他接口" },
]
},
{
value: "epay-compatibility",
title: "2. 易支付兼容接口",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<div className="bg-muted/50 border border-border/50 rounded-lg px-3 py-2 mb-6">
<p className="text-muted-foreground m-0">兼容易支付、CodePay、VPay 等支付协议</p>
</div>
<h3 id="2-1-overview" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">2.1 概览</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-2">
<li><strong>协议：</strong>EasyPay / CodePay / VPay 兼容协议</li>
<li><strong>服务类型：</strong>仅支持 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">type=epay</code></li>
<li><strong>网关基址：</strong><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">https://credit.linux.do/epay</code></li>
<li><strong>订单有效期：</strong>取系统配置 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">order_expire_minutes</code>（平台端设置）</li>
</ul>
<h3 id="2-2-common-errors" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">2.2 常见错误</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-2">
<li><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">不支持的请求类型</code>：<code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">type</code> 仅允许 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">epay</code></li>
<li><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">签名验证失败</code>：参与签名字段与请求体需一致，密钥直接拼接</li>
<li><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">金额必须大于0</code> / <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">积分小数位数不能超过2位</code></li>
<li><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">订单已过期</code>：超出系统配置有效期</li>
<li><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">订单不存在或已完成</code>：订单号错误、已退回或已完成</li>
<li><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">余额不足</code>：余额退回时用户积分不足</li>
</ul>
<h3 id="2-3-flow" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">2.3 对接流程</h3>
<ol className="list-decimal pl-4 md:pl-5 space-y-2">
<li>控制台创建 API Key，记录 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">pid</code>、<code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">key</code>，配置回调地址</li>
<li>按“签名算法”生成 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">sign</code>，调用 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">/epay/pay/submit.php</code> 创建积分流转服务并跳转认证界面</li>
<li>可通过 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">/epay/api.php</code> 轮询结果，或等待异步回调</li>
<li>退回服务时，携带同一 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">trade_no</code> 和原积分数量，调用积分退回接口</li>
<li>回调验签通过后返回 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">success</code> 完成闭环</li>
</ol>
<h3 id="2-4-auth-sign" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">2.4 鉴权与签名</h3>
<h4 className="font-medium text-foreground mt-3 md:mt-4 mb-2">2.4.1 API Key</h4>
<ul className="list-disc pl-4 md:pl-5 space-y-2 mb-4">
<li><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">pid</code>：Client ID</li>
<li><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">key</code>：Client Secret（妥善保管）</li>
<li><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">notify_url</code> / <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">return_url</code>：应用级默认回调地址（兜底）；创建订单时可在请求中传同名字段作为订单级覆盖，未传时回退应用配置。</li>
</ul>
<h4 className="font-medium text-foreground mt-3 md:mt-4 mb-2">2.4.2 签名算法</h4>
<div className="space-y-4">
<ol className="list-decimal pl-4 md:pl-5 space-y-2">
<li>取所有非空字段（排除 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">sign</code>、<code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">sign_type</code> 字段）</li>
<li>将上述字段按 ASCII 升序，依次拼成 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">k1=v1&k2=v2</code></li>
<li>在末尾追加应用密钥：<code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">k1=v1&k2=v2{"{secret}"}</code></li>
<li>整体进行 MD5，取小写十六进制作为 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">sign</code></li>
</ol>
<CodeBlock
code={`payload="money=10&name=Test&out_trade_no=M20250101&pid=001&type=epay"
sign=$(echo -n "\${payload}\${SECRET}" | md5) # 输出小写`}
language="bash"
/>
</div>
<h3 id="2-5-submit" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">2.5 积分流转服务</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-2 mb-6">
<li><strong>方法：</strong>POST <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">/epay/pay/submit.php</code></li>
<li><strong>编码：</strong><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">application/json</code> 或 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">application/x-www-form-urlencoded</code></li>
<li><strong>成功：</strong>验签通过后，平台自动创建积分流转服务，并跳转到认证界面（Location=<code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">https://credit.linux.do/paying?order_no=...</code>）</li>
<li><strong>失败：</strong>返回 JSON <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">{`{"error_msg":"...", "data":null}`}</code></li>
</ul>
<DocsTable>
<DocsTableHeader>
<DocsTableRow>
<DocsTableHead className="w-[100px] whitespace-nowrap">参数</DocsTableHead>
<DocsTableHead className="w-[80px] whitespace-nowrap">必填</DocsTableHead>
<DocsTableHead>说明</DocsTableHead>
</DocsTableRow>
</DocsTableHeader>
<DocsTableBody>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">pid</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>Client ID</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">type</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>固定 <code className="bg-muted px-1 rounded text-xs before:content-none after:content-none">epay</code></DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">out_trade_no</DocsTableCell>
<DocsTableCell>否</DocsTableCell>
<DocsTableCell>业务单号，建议全局唯一</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">name</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>标题，最多 64 字符</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">money</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>积分数量，最多 2 位小数</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">notify_url</DocsTableCell>
<DocsTableCell>否</DocsTableCell>
<DocsTableCell>会参与签名；可选订单级异步通知地址。长度不超过 100，需为合法 URL。传入后支付成功优先回调该地址，未传则使用应用 notify_url</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">return_url</DocsTableCell>
<DocsTableCell>否</DocsTableCell>
<DocsTableCell>会参与签名；可选订单级回跳地址。长度不超过 100，需为合法 URL。传入后支付成功页面优先跳转该地址，未传则使用应用 redirect_uri</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">device</DocsTableCell>
<DocsTableCell>否</DocsTableCell>
<DocsTableCell>终端标识，可选</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">sign</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>按“签名算法”生成</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">sign_type</DocsTableCell>
<DocsTableCell>否</DocsTableCell>
<DocsTableCell>固定 <code className="bg-muted px-1 rounded text-xs before:content-none after:content-none">MD5</code></DocsTableCell>
</DocsTableRow>
</DocsTableBody>
</DocsTable>
<p className="text-muted-foreground mb-2">请求示例：</p>
<CodeBlock
code={`curl -X POST https://credit.linux.do/epay/pay/submit.php \\
-H "Content-Type: application/x-www-form-urlencoded" \\
-d "pid=001" \\
-d "type=epay" \\
-d "out_trade_no=M20250101" \\
-d "name=Test" \\
-d "money=10" \\
-d "sign=\${SIGN}" \\
-d "sign_type=MD5"`}
language="bash"
/>
<h3 id="2-6-others" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">2.6 其他接口</h3>
<p className="text-muted-foreground mb-4">其他接口定义请参考 <a href="#3-common-services" className="text-primary underline underline-offset-4">3. 其他接口</a>。</p>
<ul className="list-disc pl-4 md:pl-5 space-y-2">
<li><strong>订单查询：</strong>详见 <a href="#3-1-order" className="text-primary underline underline-offset-4">3.1 订单查询</a></li>
<li><strong>订单退款：</strong>详见 <a href="#3-2-refund" className="text-primary underline underline-offset-4">3.2 订单退款</a></li>
<li><strong>异步通知：</strong>详见 <a href="#3-3-notify" className="text-primary underline underline-offset-4">3.3 异步通知</a></li>
</ul>
</div>
),
children: [
{ value: "2-1-overview", title: "2.1 概览" },
{ value: "2-2-common-errors", title: "2.2 常见错误" },
{ value: "2-3-flow", title: "2.3 对接流程" },
{ value: "2-4-auth-sign", title: "2.4 鉴权与签名" },
{ value: "2-5-submit", title: "2.5 积分流转服务" },
{ value: "2-6-others", title: "2.6 其他接口" },
]
},
{
value: "common-services",
title: "3. 其他接口",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<div className="bg-muted/50 border border-border/50 rounded-lg px-3 py-2 mb-6">
<p className="text-muted-foreground m-0">官方接口与易支付兼容接口公用接口。</p>
</div>
<h3 id="3-1-order" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">3.1 订单查询</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-2 mb-6">
<li><strong>方法：</strong>GET <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">/epay/api.php</code></li>
<li><strong>认证：</strong><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">pid</code> + <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">key</code></li>
<li><strong>说明：</strong><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">out_trade_no</code> 必填；<code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">act</code> 可传 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">order</code>，后端不强校验。</li>
</ul>
<DocsTable>
<DocsTableHeader>
<DocsTableRow>
<DocsTableHead className="w-[100px] whitespace-nowrap">参数</DocsTableHead>
<DocsTableHead className="w-[80px] whitespace-nowrap">必填</DocsTableHead>
<DocsTableHead>说明</DocsTableHead>
</DocsTableRow>
</DocsTableHeader>
<DocsTableBody>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">act</DocsTableCell>
<DocsTableCell>否</DocsTableCell>
<DocsTableCell>可选字段，建议 <code className="bg-muted px-1 rounded text-xs before:content-none after:content-none">order</code></DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">pid</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>Client ID</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">key</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>Client Secret</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">out_trade_no</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>业务单号</DocsTableCell>
</DocsTableRow>
</DocsTableBody>
</DocsTable>
<p className="text-muted-foreground mb-2">成功响应：</p>
<CodeBlock
code={`{
"code": 1,
"msg": "查询订单号成功！",
"trade_no": "M20250101",
"out_trade_no": "M20250101",
"type": "epay",
"pid": "001",
"addtime": "2025-01-01 12:00:00",
"endtime": "2025-01-01 12:01:30",
"name": "Test",
"money": "10",
"status": 1
}`}
language="json"
/>
<p className="text-muted-foreground text-xs"><strong className="text-foreground">补充：</strong><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">status</code> 1=成功，0=失败/处理中；不存在会返回 HTTP 404 且 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">{`{"code":-1,"msg":"服务不存在或已完成"}`}</code>。</p>
<h3 id="3-2-refund" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">3.2 订单退款</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-2 mb-6">
<li><strong>方法：</strong>POST <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">/epay/api.php</code></li>
<li><strong>编码：</strong><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">application/json</code> 或 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">application/x-www-form-urlencoded</code></li>
<li><strong>限制：</strong>仅支持对已成功的积分流转服务进行积分的全额退回</li>
</ul>
<div>
<DocsTable>
<DocsTableHeader>
<DocsTableRow>
<DocsTableHead className="w-[100px] whitespace-nowrap">参数</DocsTableHead>
<DocsTableHead className="w-[80px] whitespace-nowrap">必填</DocsTableHead>
<DocsTableHead>说明</DocsTableHead>
</DocsTableRow>
</DocsTableHeader>
<DocsTableBody>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">pid</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>Client ID</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">key</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>Client Secret</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">trade_no</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>编号</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">money</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>必须等于原积分流转服务的积分数量</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">out_trade_no</DocsTableCell>
<DocsTableCell>否</DocsTableCell>
<DocsTableCell>业务单号（兼容）</DocsTableCell>
</DocsTableRow>
</DocsTableBody>
</DocsTable>
</div>
<p className="text-muted-foreground mb-2">响应：</p>
<CodeBlock code={`{ "code": 1, "msg": "退款成功" }`} language="json" />
<p className="text-muted-foreground text-xs"><strong className="text-foreground">常见失败：</strong>服务不存在/未认证、金额不合法（&lt;=0 或小数超过 2 位）。</p>
<h3 id="3-3-notify" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">3.3 异步通知</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-2 mb-6">
<li><strong>触发：</strong>认证成功后；失败自动重试，最多 5 次（单次 30s 超时）</li>
<li><strong>目标：</strong>订单级 notify_url（如有）优先，否则回退到创建应用时设置的 notify_url</li>
<li><strong>方式：</strong>HTTP GET</li>
</ul>
<div>
<DocsTable>
<DocsTableHeader>
<DocsTableRow>
<DocsTableHead className="w-[100px] whitespace-nowrap">参数</DocsTableHead>
<DocsTableHead>说明</DocsTableHead>
</DocsTableRow>
</DocsTableHeader>
<DocsTableBody>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">pid</DocsTableCell>
<DocsTableCell>Client ID</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">trade_no</DocsTableCell>
<DocsTableCell>编号</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">out_trade_no</DocsTableCell>
<DocsTableCell>业务单号</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">type</DocsTableCell>
<DocsTableCell>固定 <code className="bg-muted px-1 rounded text-xs before:content-none after:content-none">epay</code></DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">name</DocsTableCell>
<DocsTableCell>标题</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">money</DocsTableCell>
<DocsTableCell>积分数量，最多 2 位小数</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">trade_status</DocsTableCell>
<DocsTableCell>固定 <code className="bg-muted px-1 rounded text-xs before:content-none after:content-none">TRADE_SUCCESS</code></DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">sign</DocsTableCell>
<DocsTableCell>按“签名算法”生成</DocsTableCell>
</DocsTableRow>
</DocsTableBody>
</DocsTable>
</div>
<p className="text-muted-foreground text-xs">应用需返回 HTTP 200 且响应体为 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">success</code>（大小写不敏感），否则视为失败并继续重试。</p>
<h3 id="3-4-distribute" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">3.4 商户分发接口</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-2 mb-6">
<li><strong>方法：</strong>POST <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">/lpay/distribute</code></li>
<li><strong>编码：</strong><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">application/json</code></li>
<li><strong>认证：</strong>Basic Auth (使用 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">client_id:client_secret</code> 进行 Base64 编码)</li>
</ul>
<DocsTable>
<DocsTableHeader>
<DocsTableRow>
<DocsTableHead className="w-[100px] whitespace-nowrap">参数</DocsTableHead>
<DocsTableHead className="w-[80px] whitespace-nowrap">必填</DocsTableHead>
<DocsTableHead>说明</DocsTableHead>
</DocsTableRow>
</DocsTableHeader>
<DocsTableBody>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">user_id</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>收款人用户 ID (数字)</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">username</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>收款人用户名 (用于二次校验)</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">amount</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>分发积分数量，最多 2 位小数</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">out_trade_no</DocsTableCell>
<DocsTableCell>否</DocsTableCell>
<DocsTableCell>商户自定义单号</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">remark</DocsTableCell>
<DocsTableCell>否</DocsTableCell>
<DocsTableCell>分发备注</DocsTableCell>
</DocsTableRow>
</DocsTableBody>
</DocsTable>
<p className="text-muted-foreground text-xs"><strong className="text-foreground">成功响应：</strong><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">{`{"code":1, "data":{"trade_no":"...", "out_trade_no":"..."}}`}</code></p>
<h3 id="3-5-user-balance" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">3.5 用户余额统计</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-2 mb-6">
<li><strong>方法：</strong>GET <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">/api/v1/dashboard/stats/user-balance</code></li>
<li><strong>认证：</strong>无需鉴权（公开接口）</li>
<li><strong>说明：</strong>获取平台所有用户可用余额的统计数据，结果有缓存，TTL 由系统配置决定</li>
</ul>
<p className="text-muted-foreground mb-2">成功响应：</p>
<p className="mt-2">成功响应示例：</p>
<CodeBlock
code={`{
"error_msg": "",
"data": {
"total_count": 1234,
"total_amount": "98765.00",
"avg_amount": "80.03",
"median_amount": "50.00",
"min_amount": "0.00",
"max_amount": "9999.00",
"std_dev": "123.45"
"id": 1,
"username": "ryan",
"nickname": "Ryan"
}
}`}
language="json"
/>
<p className="mt-2">失败响应示例：</p>
<CodeBlock
code={`{
"error_msg": "用户密码错误",
"data": null
}`}
language="json"
/>
<h3 id="1-2-authentication" className="text-base md:text-lg font-semibold text-foreground mt-6 mb-3">1.2 鉴权方式</h3>
<p>除了公共公开接口（如登录、注册、配置）外，受保护的接口需要携带凭证才能正常访问：</p>
<ul className="list-disc pl-5 space-y-2">
<li><strong>Session 凭证：</strong>浏览器环境下支持利用常规 Session Cookie 会话保持登录。</li>
<li><strong>AccessToken 令牌：</strong>供后台调用或第三方应用集成使用。客户端生成 API 访问令牌后，需要在请求头（Request Header）中携带以进行身份校验。</li>
</ul>
<div className="bg-muted border rounded-xl p-4 mt-2 space-y-2">
<p className="font-bold text-xs">支持携带令牌的请求头格式（二选一）：</p>
<ul className="list-disc pl-5 text-xs text-muted-foreground space-y-1">
<li><code className="bg-muted-foreground/10 px-1 rounded text-[11px] font-mono">Authorization: Bearer at_xxx</code></li>
<li><code className="bg-muted-foreground/10 px-1 rounded text-[11px] font-mono">X-Access-Token: at_xxx</code></li>
</ul>
</div>
</div>
),
children: [
{ value: "1-1-response-format", title: "1.1 统一响应格式" },
{ value: "1-2-authentication", title: "1.2 鉴权方式" },
]
},
{
value: "auth-apis",
title: "2. 用户与认证接口",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<h3 id="2-1-register" className="text-base md:text-lg font-semibold text-foreground mt-4 mb-2">2.1 用户注册</h3>
<p><strong>接口：</strong>POST <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono">/api/v1/user/register</code></p>
<p><strong>说明：</strong>注册本地账户（在后台注册开关开启状态下）。</p>
<DocsTable>
<DocsTableHeader>
<DocsTableRow>
<DocsTableHead className="w-[120px] whitespace-nowrap">字段</DocsTableHead>
<DocsTableHead className="w-[120px]">参数</DocsTableHead>
<DocsTableHead className="w-[80px]">必填</DocsTableHead>
<DocsTableHead>类型</DocsTableHead>
<DocsTableHead>说明</DocsTableHead>
</DocsTableRow>
</DocsTableHeader>
<DocsTableBody>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">total_count</DocsTableCell>
<DocsTableCell>统计用户总数</DocsTableCell>
<DocsTableCell className="font-mono text-xs">username</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>string</DocsTableCell>
<DocsTableCell>用户名，必须唯一且无空格。</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">total_amount</DocsTableCell>
<DocsTableCell>所有用户可用余额之和</DocsTableCell>
<DocsTableCell className="font-mono text-xs">password</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>string</DocsTableCell>
<DocsTableCell>密码，长度必须大于等于 8 位。</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">avg_amount</DocsTableCell>
<DocsTableCell>平均余额</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">median_amount</DocsTableCell>
<DocsTableCell>余额中位数</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">min_amount</DocsTableCell>
<DocsTableCell>最小余额</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">max_amount</DocsTableCell>
<DocsTableCell>最大余额</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">std_dev</DocsTableCell>
<DocsTableCell>余额标准差</DocsTableCell>
<DocsTableCell className="font-mono text-xs">nickname</DocsTableCell>
<DocsTableCell>否</DocsTableCell>
<DocsTableCell>string</DocsTableCell>
<DocsTableCell>昵称。未传时默认与用户名一致。</DocsTableCell>
</DocsTableRow>
</DocsTableBody>
</DocsTable>
<h3 id="2-2-login" className="text-base md:text-lg font-semibold text-foreground mt-6 mb-2">2.2 密码登录</h3>
<p><strong>接口：</strong>POST <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono">/api/v1/user/login</code></p>
<p><strong>说明：</strong>通过常规用户名密码进行登录校验，成功后建立 Session Cookie 会话。</p>
<DocsTable>
<DocsTableHeader>
<DocsTableRow>
<DocsTableHead className="w-[120px]">参数</DocsTableHead>
<DocsTableHead className="w-[80px]">必填</DocsTableHead>
<DocsTableHead>类型</DocsTableHead>
<DocsTableHead>说明</DocsTableHead>
</DocsTableRow>
</DocsTableHeader>
<DocsTableBody>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">username</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>string</DocsTableCell>
<DocsTableCell>用户名</DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell className="font-mono text-xs">password</DocsTableCell>
<DocsTableCell>是</DocsTableCell>
<DocsTableCell>string</DocsTableCell>
<DocsTableCell>密码</DocsTableCell>
</DocsTableRow>
</DocsTableBody>
</DocsTable>
<h3 id="2-3-logout" className="text-base md:text-lg font-semibold text-foreground mt-6 mb-2">2.3 退出登录</h3>
<p><strong>接口：</strong>GET <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono">/api/v1/user/logout</code></p>
<p><strong>说明：</strong>销毁当前会话 Cookie 并退出登录状态。</p>
<h3 id="2-4-profile" className="text-base md:text-lg font-semibold text-foreground mt-6 mb-2">2.4 获取个人资料</h3>
<p><strong>接口：</strong>GET <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono">/api/v1/user/self</code></p>
<p><strong>说明：</strong>获取当前登录账户的基本数据模型（包含 ID、角色、昵称等）。</p>
</div>
),
children: [
{ value: "3-1-order", title: "3.1 订单查询" },
{ value: "3-2-refund", title: "3.2 订单退款" },
{ value: "3-3-notify", title: "3.3 异步通知" },
{ value: "3-4-distribute", title: "3.4 商户分发接口" },
{ value: "3-5-user-balance", title: "3.5 用户余额统计" },
{ value: "2-1-register", title: "2.1 用户注册" },
{ value: "2-2-login", title: "2.2 密码登录" },
{ value: "2-3-logout", title: "2.3 退出登录" },
{ value: "2-4-profile", title: "2.4 获取个人资料" },
]
},
{
value: "token-apis",
title: "3. 个人访问令牌 (AccessToken) 接口",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<div className="bg-muted/50 border border-border/50 rounded-lg px-3 py-2 mb-4">
<p className="text-muted-foreground m-0">AccessToken 管理相关接口均要求通过 Session 登录后调用，支持普通用户权限。</p>
</div>
<h3 id="3-1-list-token" className="text-base md:text-lg font-semibold text-foreground mt-4 mb-2">3.1 获取令牌列表</h3>
<p><strong>接口：</strong>GET <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono">/api/v1/user/access-tokens</code></p>
<p><strong>说明：</strong>查询当前用户已创建的所有令牌详情（令牌明文已被脱敏）。</p>
<h3 id="3-2-create-token" className="text-base md:text-lg font-semibold text-foreground mt-6 mb-2">3.2 新建访问令牌</h3>
<p><strong>接口：</strong>POST <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono">/api/v1/user/access-tokens</code></p>
<p><strong>参数：</strong>JSON Body <code className="bg-muted px-1.5 rounded text-xs font-mono">{`{"name": "token名称"}`}</code></p>
<p><strong>说明：</strong>生成一个全新访问令牌。返回体中包含一次性明文 Token，切勿遗失。</p>
<p className="mt-2">成功返回样例：</p>
<CodeBlock
code={`{
"error_msg": "",
"data": {
"token": "at_628d022b7a95e26bcd8b29c9...",
"record": {
"id": 5,
"user_id": 1,
"name": "my-dev-key",
"masked_token": "at_628d...29c9",
"last_used_at": null,
"created_at": "2026-06-07T21:30:00+08:00"
}
}
}`}
language="json"
/>
<h3 id="3-3-delete-token" className="text-base md:text-lg font-semibold text-foreground mt-6 mb-2">3.3 撤销/删除令牌</h3>
<p><strong>接口：</strong>DELETE <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono">/api/v1/user/access-tokens/:id</code></p>
<p><strong>说明：</strong>通过 ID 物理删除对应访问令牌，该令牌将立即失效。</p>
<h3 id="3-4-rotate-token" className="text-base md:text-lg font-semibold text-foreground mt-6 mb-2">3.4 轮换令牌密钥</h3>
<p><strong>接口：</strong>POST <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono">/api/v1/user/access-tokens/:id/rotate</code></p>
<p><strong>说明：</strong>轮换指定令牌的物理密钥值。系统将废弃原有密钥，返回新生成的明文 Token，并将 `last_used_at` 置空，令牌名称与 ID 保持一致。</p>
</div>
),
children: [
{ value: "3-1-list-token", title: "3.1 获取令牌列表" },
{ value: "3-2-create-token", title: "3.2 新建访问令牌" },
{ value: "3-3-delete-token", title: "3.3 撤销/删除令牌" },
{ value: "3-4-rotate-token", title: "3.4 轮换令牌密钥" },
]
},
{
value: "config-apis",
title: "4. 公共配置与管理接口",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<h3 id="4-1-public-config" className="text-base md:text-lg font-semibold text-foreground mt-4 mb-2">4.1 公共系统配置</h3>
<p><strong>接口：</strong>GET <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono">/api/v1/config/public</code></p>
<p><strong>说明：</strong>无感获取当前系统的公开业务设置（如注册是否开启、密码登录是否开启）。供前端页面动态渲染使用。</p>
<p className="mt-2">返回数据结构样例：</p>
<CodeBlock
code={`{
"error_msg": "",
"data": {
"site_name": "Antigravity Project",
"registration_enabled": true,
"password_login_enabled": true,
"password_register_enabled": true,
"oidc_login_enabled": true
}
}`}
language="json"
/>
<h3 id="4-2-admin-configs" className="text-base md:text-lg font-semibold text-foreground mt-6 mb-2">4.2 系统配置项 CRUD (管理员)</h3>
<p><strong>说明：</strong>用于在后台对 `system_configs` 配置进行动态变更，要求管理员权限会话调用。</p>
<ul className="list-disc pl-5 space-y-2">
<li><strong>获取配置列表：</strong>GET <code className="bg-muted px-1 rounded text-xs font-mono">/api/v1/admin/system-configs?type=system</code></li>
<li><strong>新建配置项：</strong>POST <code className="bg-muted px-1 rounded text-xs font-mono">/api/v1/admin/system-configs</code></li>
<li><strong>修改指定配置值：</strong>PUT <code className="bg-muted px-1 rounded text-xs font-mono">/api/v1/admin/system-configs/:key</code></li>
<li><strong>删除配置项：</strong>DELETE <code className="bg-muted px-1 rounded text-xs font-mono">/api/v1/admin/system-configs/:key</code></li>
</ul>
</div>
),
children: [
{ value: "4-1-public-config", title: "4.1 公共系统配置" },
{ value: "4-2-admin-configs", title: "4.2 系统配置项 CRUD (管理员)" },
]
}
]
frontend/components/common/docs/how-to-use.tsx
+70 -261
View File
@@ -1,13 +1,5 @@
import { type PolicySection } from "./types"
import { CodeBlock } from "@/components/ui/code-block"
import {
DocsTable,
DocsTableHeader,
DocsTableBody,
DocsTableHead,
DocsTableRow,
DocsTableCell,
} from "@/components/ui/docs-table"
import {type PolicySection} from "./types"
import {CodeBlock} from "@/components/ui/code-block"
/**
* ------------------------------------------------------------------
@@ -21,261 +13,96 @@ export const howToUseSections: PolicySection[] = [
content: (
<div className="space-y-4 text-sm leading-relaxed">
<div className="bg-muted/50 border border-border/50 rounded-lg px-3 py-2 mb-6">
<p className="text-muted-foreground m-0">为社区开发者与用户提供完整的平台使用说明</p>
<p className="text-muted-foreground m-0">为开发者提供通用全栈开发脚手架 (Boilerplate) 平台使用说明</p>
</div>
<ul className="list-disc pl-5 space-y-2">
<li><strong>身份认证：</strong>基于 LINUX DO Connect (OAuth)</li>
<li><strong>认证方式：</strong>账户积分消耗认证</li>
<li><strong>手续费：</strong>动态费率，由服务方承担</li>
<li><strong>争议处理：</strong>支持服务方与消费方的双方争议处理</li>
<li><strong>架构底座：</strong>Go (Gin + GORM + Redis + Asynq) 后端 + React (Next.js 16 + Tailwind CSS 4 + Shadcn UI) 前端</li>
<li><strong>认证体系：</strong>支持本地常规账号密码注册登录 + 第三方自定义 OIDC (OAuth2) 认证源绑定</li>
<li><strong>访问令牌：</strong>提供开发者个人 AccessToken (API Key)，用于通过 Http Header 鉴权直接调用系统 API</li>
<li><strong>可观测性：</strong>集成 Zap 结构化日志与 OpenTelemetry 全链路 Tracing 追踪</li>
</ul>
</div>
)
},
{
value: "roles",
title: "2. 角色说明",
value: "auth-security",
title: "2. 身份认证与安全设置",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<ul className="list-disc pl-5 space-y-2">
<li><strong>服务方：</strong>最终积分流转的转入方</li>
<li><strong>消费方：</strong>最终积分流转的转出方</li>
<li><strong>认证平台：</strong>LINUX DO Credit 系统本身</li>
<p>平台采用混合式身份认证，满足不同的部署和业务场景需求：</p>
<h3 id="2-1-login" className="text-base md:text-lg font-semibold text-foreground mt-4 mb-2">2.1 常规账号密码认证</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-2">
<li><strong>自主注册与密码登录：</strong>支持普通用户通过用户名及密码直接进行注册与会话建立，密码在后端采用 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono">bcrypt</code> 高强度加盐哈希存储。</li>
<li><strong>系统开关控制：</strong>管理员可在后台配置动态开关，随时禁用自主密码注册或密码登录，以转为纯第三方认证模式。</li>
</ul>
</div>
)
},
{
value: "integration",
title: "3. 接入积分服务",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<h3 id="3-1-api" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">3.1 使用 API 接口</h3>
<ol className="list-decimal pl-4 md:pl-5 space-y-2">
<li>
<strong>创建应用</strong>
<ul className="list-disc pl-4 md:pl-5 mt-2 space-y-1 text-muted-foreground">
<li>前往 <a href="/home" className="text-primary hover:underline">控制面板</a></li>
<li>点击顶部右侧 <strong>创建应用</strong> 按钮</li>
<li>填写必要信息：应用名称、应用主页、回调地址、通知地址</li>
</ul>
</li>
<li>
<strong>获取 API 凭证</strong>
<ul className="list-disc pl-4 md:pl-5 mt-2 space-y-1 text-muted-foreground">
<li>在集市中心顶部右侧选择器中选择您的应用</li>
<li>在 <strong>API 配置</strong> 面板中获取：
<ul className="list-[circle] pl-4 md:pl-5 mt-1">
<li><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">Client ID</code>：客户端ID，用于标识您的身份</li>
<li><code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono before:content-none after:content-none">Client Secret</code>：客户端密钥，用于签名验证（<strong>请妥善保管，切勿泄露</strong>）</li>
</ul>
</li>
</ul>
</li>
<li>
<strong>使用 API 接口</strong>
<ul className="list-disc pl-4 md:pl-5 mt-2 space-y-1 text-muted-foreground">
<li>使用 API 接口创建积分流转服务</li>
<li>参考文档：<a href="/docs/api" className="text-primary hover:underline">API 接口文档</a></li>
</ul>
</li>
<h3 id="2-2-oidc" className="text-base md:text-lg font-semibold text-foreground mt-4 mb-2">2.2 第三方 OIDC 认证源</h3>
<p>用户可以在个人资料页面关联绑定外部授权账户：</p>
<ol className="list-decimal pl-4 md:pl-5 space-y-1">
<li>进入 <strong>设置 / 个人资料</strong> 页面。</li>
<li>在“第三方账号绑定”栏目下查看当前绑定的账号，或点击未绑定的可用 OIDC 认证源直接触发 OAuth2 绑定流。</li>
<li>绑定成功后，用户在登录界面可直接点击 OIDC 登录按钮实现快捷跳转。</li>
</ol>
<h3 id="3-2-online" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">3.2 使用在线服务</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-2 mb-4">
<li><strong>适用场景：</strong>无代码开发基础，或只用于简单的积分服务。</li>
<li><strong>操作步骤：</strong>
<ol className="list-decimal pl-4 md:pl-5 mt-2 space-y-1 text-muted-foreground">
<li>前往 <a href="/home" className="text-primary hover:underline">控制面板</a> 创建应用，获取 API 凭证</li>
<li>选择应用，点击 <strong>在线收款</strong> 功能</li>
<li>创建在线积分服务</li>
<li>获取唯一积分服务链接</li>
<li>发送给您所服务的客户使用</li>
</ol>
</li>
</ul>
<h3 id="3-3-new-api" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">3.3 快速集成 New API</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-2 mb-4">
<li><strong>适用场景：</strong>New API 站点，LINUX DO Credit 兼容 EasyPay 协议，公益站站长可直接集成。</li>
<li><strong>操作步骤：</strong>
<ol className="list-decimal pl-4 md:pl-5 mt-2 space-y-2 text-muted-foreground">
<li>
前往 <a href="/home" className="text-primary hover:underline">控制面板</a>，点击 <strong>创建应用</strong>，填写 New API 站点信息：
<div className="my-4">
<DocsTable>
<DocsTableHeader>
<DocsTableRow>
<DocsTableHead>字段</DocsTableHead>
<DocsTableHead>值</DocsTableHead>
</DocsTableRow>
</DocsTableHeader>
<DocsTableBody>
<DocsTableRow>
<DocsTableCell>应用名称</DocsTableCell>
<DocsTableCell><code className="bg-muted px-1 rounded text-xs before:content-none after:content-none">您的应用名称</code></DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell>应用主页</DocsTableCell>
<DocsTableCell><code className="bg-muted px-1 rounded text-xs before:content-none after:content-none">https://{"{您的 New API 域名}"}</code></DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell>回调地址</DocsTableCell>
<DocsTableCell><code className="bg-muted px-1 rounded text-xs before:content-none after:content-none">https://{"{您的 New API 域名}"}/console/log</code></DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell>通知地址</DocsTableCell>
<DocsTableCell><code className="bg-muted px-1 rounded text-xs before:content-none after:content-none">https://{"{您的 New API 域名}"}/api/user/epay/notify</code></DocsTableCell>
</DocsTableRow>
</DocsTableBody>
</DocsTable>
</div>
</li>
<li>前往 New API 站点的系统设置，找到 <strong>支付设置</strong>。</li>
<li>
配置 LINUX DO Credit 平台参数：
<div className="my-4">
<DocsTable>
<DocsTableHeader>
<DocsTableRow>
<DocsTableHead>参数</DocsTableHead>
<DocsTableHead>值</DocsTableHead>
</DocsTableRow>
</DocsTableHeader>
<DocsTableBody>
<DocsTableRow>
<DocsTableCell>支付地址</DocsTableCell>
<DocsTableCell><code className="bg-muted px-1 rounded text-xs before:content-none after:content-none">https://credit.linux.do/epay/pay</code></DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell>易支付商户ID</DocsTableCell>
<DocsTableCell>您的 <code className="bg-muted px-1 rounded text-xs before:content-none after:content-none">Client ID</code></DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell>易支付商户密钥</DocsTableCell>
<DocsTableCell>您的 <code className="bg-muted px-1 rounded text-xs before:content-none after:content-none">Client Secret</code></DocsTableCell>
</DocsTableRow>
<DocsTableRow>
<DocsTableCell>回调地址</DocsTableCell>
<DocsTableCell><code className="bg-muted px-1 rounded text-xs before:content-none after:content-none">https://{"{您的 New API 域名}"}</code></DocsTableCell>
</DocsTableRow>
</DocsTableBody>
</DocsTable>
</div>
</li>
<li>
配置充值方式（JSON 格式）：
<div className="my-4">
<CodeBlock
code={`[
{"color":"rgba(var(--semi-blue-5), 1)","name":"支付宝","type":"alipay"},
{"color":"rgba(var(--semi-green-5), 1)","name":"微信","type":"wxpay"},
{"color":"black","name":"Linux Do Credit","type":"epay"}
]`}
language="json"
/>
</div>
</li>
</ol>
</li>
</ul>
</div>
),
children: [
{ value: "3-1-api", title: "3.1 使用 API 接口" },
{ value: "3-2-online", title: "3.2 使用在线服务" },
{ value: "3-3-new-api", title: "3.3 快速集成 New API" },
{ value: "2-1-login", title: "2.1 常规账号密码认证" },
{ value: "2-2-oidc", title: "2.2 第三方 OIDC 认证源" },
]
},
{
value: "usage",
title: "4. 使用 LINUX DO Credit 积分",
value: "access-token",
title: "3. 个人访问令牌 (AccessToken) 接口对接",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<p>您可以在任意支持 LINUX DO Credit 的平台下使用积分。在其他平台点击使用 LINUX DO Credit 积分时，会自动跳转到 LINUX DO Credit 的积分流转服务页面，您只需要确认积分流转信息无误，并选择使用 LINUX DO Credit 进行账户认证，即可完成整个交易服务。</p>
</div>
)
},
{
value: "fees",
title: "5. 服务（手续）费",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<h3 id="5-1-rules" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">5.1 规则说明</h3>
<p>为了更好的维持 LINUX DO Credit 平台的积分服务机制，保证社区积分的生态可持续发展，我们会按照规范进行不同程度的服务（手续）费用收取。</p>
<p>为便于开发者或第三方工具直接调用系统 API，平台提供个人访问令牌管理功能。</p>
<h3 id="3-1-generation" className="text-base md:text-lg font-semibold text-foreground mt-4 mb-2">3.1 令牌生成与存储规范</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-2">
<li><strong>承担方：</strong>服务（手续）费默认<strong>由服务方承担</strong></li>
<li><strong>消费方使用：</strong>不会产生额外费用</li>
<li><strong>服务方实收：</strong>订单金额 - 服务（手续）费</li>
<li><strong>一次性明文展示：</strong>创建令牌时生成的随机明文 Token 值 (形如 <code className="bg-muted px-1.5 py-0.5 rounded text-xs font-mono">at_xxx</code>) 仅会在弹窗中展示一次。请立即复制保存，关闭弹窗后系统将无法重新获取。</li>
<li><strong>安全哈希存储：</strong>数据库仅存储 Token 的 SHA-256 哈希指纹，即使数据库泄漏，攻击者也无法通过摘要逆向恢复令牌原文。</li>
</ul>
<div className="mt-4">
<p className="font-mono text-xs mb-2 text-muted-foreground">计算公式：</p>
<h3 id="3-2-usage" className="text-base md:text-lg font-semibold text-foreground mt-4 mb-2">3.2 携带 Header 进行 API 调用</h3>
<p>您可以凭借保存的明文 Token 随时调用系统开放接口，系统认证支持以下两种 Http 请求头携带方式之一：</p>
<div className="space-y-2">
<p className="font-semibold text-xs text-muted-foreground">方式一：Authorization Bearer 头</p>
<CodeBlock
code={`手续费 = 订单金额 × 当前费率
商家实际到账 = 订单金额 - 手续费`}
language="text"
code={`GET /api/v1/user/self HTTP/1.1
Host: localhost:8000
Authorization: Bearer at_628d022b7a95e26b...`}
language="http"
/>
</div>
<div className="space-y-2">
<p className="font-semibold text-xs text-muted-foreground">方式二：X-Access-Token 自定义头</p>
<CodeBlock
code={`GET /api/v1/user/self HTTP/1.1
Host: localhost:8000
X-Access-Token: at_628d022b7a95e26b...`}
language="http"
/>
</div>
<h3 id="5-2-dynamic" className="text-base md:text-lg font-semibold text-foreground mt-6 md:mt-8 mb-3 md:mb-4">5.2 动态费率</h3>
<p>费率并非固定不变，会根据以下因素动态调整：</p>
<ul className="list-disc pl-4 md:pl-5 space-y-1">
<li>服务方平台等级</li>
<li>服务方平台积分</li>
<li>LINUX DO Credit 平台活动</li>
</ul>
</div>
),
children: [
{ value: "5-1-rules", title: "5.1 规则说明" },
{ value: "5-2-dynamic", title: "5.2 动态费率" },
{ value: "3-1-generation", title: "3.1 令牌生成与存储规范" },
{ value: "3-2-usage", title: "3.2 携带 Header 进行 API 调用" },
]
},
{
value: "dispute",
title: "6. 争议处理",
value: "config-system",
title: "4. 动态系统配置项",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<p>为了保障服务方与消费方的合法权益，当积分服务出现纠纷时，可使用争议功能。</p>
<p>平台内置了完备的 KV 配置管理模块，允许管理员动态调整系统运行状态：</p>
<ul className="list-disc pl-4 md:pl-5 space-y-2">
<li>作为服务方，您需要及时响应消费方的争议请求：
<ol className="list-decimal pl-4 md:pl-5 mt-1 text-muted-foreground">
<li>在集市中心或通知中查看到 <strong>待处理的争议</strong></li>
<li>查看消费方理由，选择操作：
<ul className="list-[circle] pl-5 mt-1">
<li><strong>同意：</strong>认可消费方诉求，积分原路退回给消费方</li>
<li><strong>拒绝：</strong>如果您认为已履约，请提交相关证据</li>
</ul>
</li>
</ol>
</li>
</ul>
<div className="bg-yellow-500/10 border border-yellow-500/20 text-yellow-600 dark:text-yellow-400 px-3 py-2 rounded-lg mt-4">
<p className="m-0 text-sm">
<strong>重要：</strong>建议服务方与消费方优先沟通解决。长时间未处理的争议会由 LINUX DO Credit 平台介入仲裁，这可能会影响您的服务方信誉。
</p>
</div>
</div>
)
},
{
value: "community-balance",
title: "7. 社区积分",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<p>您的 LINUX DO Credit 平台基础积分主要由 <strong>社区积分 (Community Balance)</strong> 划转而来。</p>
<ul className="list-disc pl-4 md:pl-5 space-y-2">
<li><strong>基本获取方式：</strong>通过在 LINUX DO 社区的活跃行为获得：
<ul className="list-[circle] pl-4 md:pl-5 mt-1 text-muted-foreground">
<li>获赞、解决问题等社区贡献</li>
<li>详情可见 <a href="https://linux.do/t/topic/1409175" target="_blank" rel="noopener noreferrer" className="text-primary hover:underline">LINUX DO 社区</a></li>
</ul>
</li>
<li><strong>划转规则：</strong>
<ul className="list-[circle] pl-4 md:pl-5 mt-1 text-muted-foreground">
<li>划转时间：社区积分每日凌晨 <strong>00:00</strong> 自动划转至可用余额</li>
<li>限制说明：划转前不可用于任何积分服务</li>
<li>服务费用：目前不收取任何划转 <strong>服务费</strong></li>
<li><strong>缓存读取加速：</strong>配置加载基于 GORM 读取数据库，并辅以 Redis Hash 结构进行多层缓存加速，大幅降低配置查询耗时。</li>
<li><strong>核心系统配置项说明：</strong>
<ul className="list-[circle] pl-5 mt-1 space-y-1 text-muted-foreground">
<li><code className="bg-muted px-1 rounded text-xs font-mono">site_name</code>：平台展示名称</li>
<li><code className="bg-muted px-1 rounded text-xs font-mono">password_login_enabled</code>：密码登录开关</li>
<li><code className="bg-muted px-1 rounded text-xs font-mono">registration_enabled</code>：用户自主注册开关</li>
<li><code className="bg-muted px-1 rounded text-xs font-mono">max_api_keys_per_user</code>：普通用户创建令牌的最大数限制 (默认5)</li>
</ul>
</li>
</ul>
@@ -283,46 +110,28 @@ export const howToUseSections: PolicySection[] = [
)
},
{
value: "settings",
title: "8. 账户设置",
value: "worker-scheduler",
title: "5. 异步任务与定时调度",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<p>您可以在 <strong>设置 (Settings)</strong> 页面管理您的账户信息。</p>
<h3 className="text-base md:text-lg font-semibold text-foreground mt-4 mb-2">功能列表</h3>
<ul className="list-disc pl-4 md:pl-5 space-y-1">
<li><strong>个人资料：</strong>查看当前的账户信息和会员等级</li>
<li><strong>安全设置：</strong>修改认证密码</li>
<li><strong>外观设置：</strong>切换页面主题、界面外观</li>
<p>项目借助 Cobra 实现多命令入口分发，通过独立部署 Worker 服务解耦复杂计算或高延迟IO：</p>
<ul className="list-disc pl-4 md:pl-5 space-y-2">
<li><strong>定时任务派发 (CMD scheduler)：</strong>负责按 Cron 表达式配置，定时将待执行任务推送到 Redis 队列中。</li>
<li><strong>多优先级 Worker (CMD worker)：</strong>基于 Asynq 驱动，按优先级拉取任务并并发调度执行（如定时清理临时上传目录、同步外部系统日志等）。</li>
</ul>
</div>
)
},
{
value: "scripts",
title: "9. 辅助脚本",
value: "tracing-metrics",
title: "6. 链路追踪与结构化日志",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<p>为了方便用户随时查看当前的实时积分收入，我们提供了开源的 Userscript 脚本。</p>
<p>为了保障分布式微服务架构下的可观测性，平台接入了高级监控组件：</p>
<ul className="list-disc pl-4 md:pl-5 space-y-2">
<li><strong>功能：</strong>在 LINUX DO 显示实时积分收入，支持拖拽，不影响界面。</li>
<li><strong>获取：</strong>仅需安装 Tampermonkey 插件即可使用。</li>
<li><strong>安装：</strong>
<a
href="https://linux.do/t/topic/1365853"
target="_blank"
rel="noopener noreferrer"
className="text-primary hover:underline inline-flex items-center gap-1"
>
「LINUX DO Credit」实时积分收入脚本
<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className="lucide lucide-external-link"><path d="M15 3h6v6" /><path d="M10 14 21 3" /><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" /></svg>
</a>
</li>
<li><strong>OpenTelemetry Tracing：</strong>自动传递 Tracing 上下文，所有经由 Gin 中间件、外部请求或 GORM 数据库的事务操作都将带有全局唯一的 Span，用于排查链路耗时或调用异常。</li>
<li><strong>Zap 结构化日志：</strong>将后端控制台或日志输出格式统一规范化为 JSON，方便与 ELK、Loki 等日志收集分析工具无缝对接。</li>
</ul>
<div className="bg-muted/50 border border-border/50 rounded-lg px-3 py-2 mt-2">
<p className="text-xs text-muted-foreground m-0">
注：脚本完全开源且安全，仅通过官方 API 获取公开数据，不涉及任何敏感权限。
</p>
</div>
</div>
)
}
frontend/components/common/docs/privacy.tsx
+19 -29
View File
@@ -1,4 +1,4 @@
import { type PolicySection } from "./types"
import {type PolicySection} from "./types"
/**
* ------------------------------------------------------------------
@@ -15,15 +15,11 @@ export const privacySections: PolicySection[] = [
<div className="space-y-3">
<div>
<span className="font-semibold text-foreground">1.1 身份鉴权信息：</span>
<p className="mt-1 text-muted-foreground">当您通过 LINUX DO Connect 登录时，我们会获取您的社区 OpenID（唯一标识符）、加密后的用户名及头像 URL。<strong>我们不收集您的手机号、真实姓名或身份证件信息。</strong></p>
<p className="mt-1 text-muted-foreground">当您通过本地账号注册或绑定第三方 OIDC 认证源登录时，我们会收集您的用户名、关联的邮箱、加密后的密码哈希指纹及关联的第三方 OpenID 标识符。<strong>我们不强制要求绑定手机号、身份证件或任何真实社会信用实体信息。</strong></p>
</div>
<div>
<span className="font-semibold text-foreground">1.2 服务日志信息：</span>
<p className="mt-1 text-muted-foreground">为保障系统运行安全及满足法律合规要求，我们会自动收集您的操作日志，包括 IP 地址、访问日期和时间、API 调用记录、User-Agent（浏览器/设备类型）。</p>
</div>
<div>
<span className="font-semibold text-foreground">1.3 交易与资产信息：</span>
<p className="mt-1 text-muted-foreground">若您使用支付功能，我们将记录您的商户订单号、交易金额、交易时间、交易状态摘要。这些信息是账务核对的必要依据。</p>
<span className="font-semibold text-foreground">1.2 服务与接口日志信息：</span>
<p className="mt-1 text-muted-foreground">为保障系统运行安全及满足安全审计要求，我们会自动收集您的操作日志，包括 IP 地址、访问日期和时间、个人访问令牌 API 调用历史记录、User-Agent（浏览器/设备/请求工具类型）。</p>
</div>
</div>
</div>
@@ -36,10 +32,9 @@ export const privacySections: PolicySection[] = [
<div className="space-y-4 text-sm leading-relaxed">
<p>我们深知数据安全的重要性，并采取业界领先的技术措施保护您的数据：</p>
<ul className="list-disc pl-4 md:pl-5 space-y-2">
<li><strong>存储地点：</strong>依照法规要求，我们收集和产生的用户个人信息，<strong>存储在独立</strong>的服务器上。我们不会将您的数据传输至境外管辖区。</li>
<li><strong>加密技术：</strong>敏感数据（如 支付密码）在数据库中均采用高强度加密算法存储。数据传输全链路采用 SSL/TLS 1.3 协议进行加密，防止网络嗅探。</li>
<li><strong>隔离机制：</strong>本平台数据与外部网络物理隔离，且独立于 LINUX DO 社区论坛主数据库，确保单一系统故障不会波及全局数据安全。</li>
<li><strong>访问控制：</strong>我们实行严格的最小权限原则（Least Privilege），仅有核心运维人员经授权后方可访问必要的维护数据，且所有操作均有审计日志留存。</li>
<li><strong>存储安全：</strong>用户数据独立存储于专用的云数据库或本地容器化持久层中，仅供授权系统应用挂载读取。</li>
<li><strong>加密技术：</strong>敏感的密码指纹和个人访问令牌哈希在数据库中均采用高强度算法加密存储。API 数据传输链路强制使用 SSL/TLS 进行安全加密。</li>
<li><strong>访问控制：</strong>我们实行严格的最小权限原则（Least Privilege），平台数据不会对外共享，所有系统级内部运维操作均有审计日志可查。</li>
</ul>
</div>
),
@@ -51,12 +46,11 @@ export const privacySections: PolicySection[] = [
<div className="space-y-4 text-sm leading-relaxed">
<p>我们收集的信息将仅用于以下目的：</p>
<ul className="list-disc pl-4 md:pl-5 space-y-1">
<li><strong>身份识别：</strong>用于确认您的社区身份，展示您的个人中心数据。</li>
<li><strong>业务功能：</strong>处理您的支付指令、API 请求、回调通知及账单生成。</li>
<li><strong>安全风控：</strong>利用 IP 及行为日志进行反作弊、反欺诈分析，识别恶意攻击行为，保护平台及其他用户的安全。</li>
<li><strong>客户支持：</strong>在您发起工单或申诉时，查询相关日志以协助您解决问题。</li>
<li><strong>身份识别：</strong>用于确认您的注册身份，展示您的个人中心及设置页面数据。</li>
<li><strong>业务功能：</strong>用于识别并处理您的个人访问令牌 API 鉴权指令。</li>
<li><strong>安全风控：</strong>利用 IP 及行为日志进行接口反作弊、反暴力破解分析，保障后台服务稳定性。</li>
</ul>
<p><strong>禁止用途：</strong>我们承诺<strong>绝不</strong>利用您的数据进行用户画像分析、个性化广告推送或商业营销。</p>
<p><strong>禁止用途：</strong>我们承诺<strong>绝不</strong>将您的数据出售给第三方，亦不会向任何机构提供任何用户画像分析或广告推送服务。</p>
</div>
),
},
@@ -65,12 +59,12 @@ export const privacySections: PolicySection[] = [
title: "4. 信息共享与对外披露",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<p><strong>4.1 共享原则：</strong>我们坚持<strong>数据零共享</strong>策略。除以下极端情况外，我们不会向任何第三方（包括且不限于关联公司、支付宝、微信、银行、广告商）共享您的个人信息：</p>
<p><strong>4.1 共享原则：</strong>除以下极端情况外，我们不会向任何第三方（包括且不限于关联公司、商业合作伙伴）共享您的个人信息：</p>
<ul className="list-disc pl-4 md:pl-5 space-y-1 text-muted-foreground">
<li>事先获得您的明确授权或同意；</li>
<li>根据适用的法律法规、法律程序的要求、强制性的行政或司法要求所必须的情况下进行提供。</li>
</ul>
<p><strong>4.2 转让与公开披露：</strong>我们不会将您的个人信息转让给任何公司、组织和个人。我们仅在法律法规强制要求，或为了保护平台及用户与公众的人身财产安全免受侵害时，才会公开披露您的信息。</p>
<p><strong>4.2 转让与公开披露：</strong>我们不会将您的个人信息转让给任何公司、组织和个人，亦不进行任何公开商业披露。</p>
</div>
),
},
@@ -82,16 +76,12 @@ export const privacySections: PolicySection[] = [
<p>依照《中华人民共和国个人信息保护法》，您对您的个人信息享有完整的控制权：</p>
<div className="space-y-3">
<div>
<span className="font-semibold text-foreground">5.1 查阅与复制权：</span>
<p className="mt-1 text-muted-foreground">您可以随时登录开发者后台，查阅您的概览信息、API Key 状态及历史交易账单。您可以通过“导出账单”功能获取您的数据副本。</p>
<span className="font-semibold text-foreground">5.1 查阅与管理权：</span>
<p className="mt-1 text-muted-foreground">您可以随时登录本平台，查阅您的基础个人信息，生成、轮换或撤销您的 AccessToken (API 密钥)。</p>
</div>
<div>
<span className="font-semibold text-foreground">5.2 删除与遗忘权：</span>
<p className="mt-1 text-muted-foreground">若您决定停止使用本服务，在结清所有应付费用及余额后，您可以申请<strong>注销账户</strong>。注销后，我们将立即删除您的所有敏感信息或进行匿名化处理，法律法规规定需保留的日志除外。</p>
</div>
<div>
<span className="font-semibold text-foreground">5.3 纠正与更正权：</span>
<p className="mt-1 text-muted-foreground">若您发现您的信息有误，您有权要求我们更正或补充。您可以在设置页面直接修改您的信息，或通过客服提交工单。</p>
<span className="font-semibold text-foreground">5.2 删除与注销权：</span>
<p className="mt-1 text-muted-foreground">若您决定停止使用本服务，您可以申请注销账户。注销后，我们将立即从活跃存储媒介中删除您的所有敏感信息，法律法规要求留存的安全日志除外。</p>
</div>
</div>
</div>
@@ -102,8 +92,8 @@ export const privacySections: PolicySection[] = [
title: "6. 政策更新与通知",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<p>随着业务的发展或法律法规的变动，我们可能会适时修订本《隐私政策》。</p>
<p>当条款发生重大变更时（例如收集范围扩大、使用目的改变），我们会通过站内信、公告或弹窗等显著方式通知您。若您在政策更新后继续使用本服务，即表示您同意接受更新后的隐私政策约束。</p>
<p>随着业务的发展或法律法规的变动，本《隐私政策》条款可能发生变更。</p>
<p>当条款发生重大变更时，我们会以显著方式（如平台公告、站内弹窗等）予以通知。如果您继续使用本服务，即表示您同意接受修订后的政策约束。</p>
</div>
),
},
frontend/components/common/docs/terms.tsx
+24 -43
View File
@@ -1,6 +1,6 @@
import { type PolicySection } from "./types"
import {type PolicySection} from "./types"
export const TERMS_LAST_UPDATED = "2025-12-22"
export const TERMS_LAST_UPDATED = "2026-06-07"
/**
* ------------------------------------------------------------------
@@ -13,8 +13,8 @@ export const termsSections: PolicySection[] = [
title: "1. 缔约申明与服务综述",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<p><strong>1.1 缔约主体：</strong>本《服务协议》（以下简称“本协议”）是您（以下亦称“社区用户”、“开发者”、“消费方”或“服务方”）与 LINUX DO Credit 平台运营团队（以下简称“平台”、“我们”）之间关于使用平台服务所订立的具有法律约束力的契约。</p>
<p><strong>1.2 审慎阅读：</strong>请您务必审慎阅读、充分理解各条款内容，特别是<strong>免除或者限制责任的条款、争议解决和法律适用条款</strong>。各免责或限责条款将以粗体标识，您应重点阅读。如您不同意本协议的任何内容，请立即停止注册或使用本服务。</p>
<p><strong>1.1 缔约主体：</strong>本《服务协议》（以下简称“本协议”）是您（以下称“用户”或“开发者”）与本通用开发脚手架平台（以下简称“本系统”或“平台”）运营维护方之间关于使用本系统所订立的契约。</p>
<p><strong>1.2 审慎阅读：</strong>本系统作为一个通用的、面向二次开发的全栈软件底座，旨在为用户提供基础的注册、会话、OIDC 接入、API Key 令牌鉴权及后台管理服务。若您使用本系统，请务必仔细阅读本协议各条款。</p>
<p><strong>1.3 协议构成：</strong>本协议内容包括协议正文及所有我们已经发布或将来可能发布的各类规则、声明、说明。所有规则为本协议不可分割的组成部分，与协议正文具有同等法律效力。</p>
</div>
),
@@ -24,16 +24,13 @@ export const termsSections: PolicySection[] = [
title: "2. 服务定义与性质界定",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<p><strong>2.1 社区技术服务：</strong>LINUX DO Credit 是基于 LINUX DO 社区生态构建的独立价值交换协议与技术系统。我们仅提供 API 接口调用、数据路由、账单管理等<strong>纯技术服务</strong>。</p>
<p><strong>2.2 非金融机构申明：</strong></p>
<p><strong>2.1 纯技术研发脚手架：</strong>本平台是一个开源/闭源授权的技术二次开发底座。我们仅提供用户注册、API 调用、安全配置维护等<strong>纯软件技术服务</strong>。</p>
<p><strong>2.2 非金融机构与无承兑申明：</strong></p>
<ul className="list-disc pl-4 md:pl-5 space-y-2">
<li><strong>非银行机构：</strong>我们不是商业银行、持牌支付机构（如支付宝、微信支付、银联）或清算机构。</li>
<li><strong>不提供资金沉淀：</strong>平台不设立资金池，不提供真实法币存取款、转账汇款或支付结算服务。所有涉及资金流转的行为均发生于社区用户与社区支付渠道之间，不涉及真实货币。</li>
<li><strong>不提供金融服务：</strong>平台不提供任何金融服务，包括但不限于贷款、融资、投资、理财、保险等金融服务。</li>
<li><strong>不提供积分兑现：</strong>平台不提供任何积分兑换服务，包括但不限于积分兑换为真实货币、积分兑换为实物商品、积分兑换为服务等。</li>
<li><strong>不提供真实货币交易：</strong>平台不提供任何真实货币交易服务，包括但不限于真实货币交易为积分、真实货币交易为虚拟资产、真实货币交易为服务等。</li>
<li><strong>非持牌金融或支付机构：</strong>本系统不是银行、商户收单或清算结算机构。</li>
<li><strong>不提供资金管理：</strong>系统无真实法币、加密货币或商业代金券充值、存储与兑现功能。若在二开中加入了积分等属性，其最终性质也应限制于虚拟软件积分。</li>
<li><strong>责任自担：</strong>关于用户对本系统进行二次开发并应用于其他生产环境产生的任何业务行为，由二开部署运营主体承担全部合规责任。</li>
</ul>
<p><strong>2.3 服务限定：</strong>本平台建议用于仅支持虚拟商品、软件授权、技术咨询、会员订阅等<strong>无实物交付</strong>的场景。关于实物电商、物流发货或涉及线下履约的商业场景造成的任何后果我们概不负责，请妥善保管好自己的个人财产，谨防上当受骗。</p>
</div>
),
},
@@ -42,13 +39,12 @@ export const termsSections: PolicySection[] = [
title: "3. 账号注册与使用规范",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<p><strong>3.1 账号体系：</strong>本平台采用 LINUX DO Connect (OAuth) 授权登录体系。您必须拥有合法、有效的 LINUX DO 社区账号方可使用本服务。您的平台账号权益（包括但不限于信誉分、等级）与社区账号严格绑定。</p>
<p><strong>3.2 匿名性与真实性：</strong></p>
<p><strong>3.1 账号体系：</strong>用户可通过本系统的前端注册表单自助创建账户，或通过系统管理员配置并启用的自定义第三方 OIDC 认证源进行登录关联。</p>
<p><strong>3.2 密码及令牌安全责任：</strong></p>
<ul className="list-disc pl-4 md:pl-5 space-y-2">
<li><strong>无需实名：</strong>我们尊重您的隐私，不强制要求您提供居民身份证、护照或营业执照进行实名认证。</li>
<li><strong>操作真实性：</strong>您承诺注册和使用的账号是您本人操作。严禁恶意注册、挂机脚本、自动化程序注册等破坏平台公平性的行为。</li>
<li><strong>密码安全：</strong>您应妥善保管您账户的登录密码。</li>
<li><strong>API Token 安全：</strong>个人生成的 AccessToken (API Key) 代表您账户的完整调用权限。<strong>因您保管不善导致 Token 泄漏而造成的一切数据丢失或系统损失，均由您自行承担。</strong></li>
</ul>
<p><strong>3.3 账号安全责任：</strong>您应妥善保管您账号的支付密码、Client ID 和 Client Secret。<strong>因您保管不善可能导致账号被他人非法使用、资金损失或数据泄露的责任，由您自行承担。</strong>如发现账号异常，请立即通知我们进行冻结。</p>
</div>
),
},
@@ -57,58 +53,43 @@ export const termsSections: PolicySection[] = [
title: "4. 用户行为准则（负面清单）",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<p>您在使用本服务时，必须严格遵守《中华人民共和国网络安全法》、《计算机信息网络国际联网安全保护管理办法》等法律法规。<strong>严禁利用本平台从事以下活动（“红线条款”）：</strong></p>
<p>您在使用本系统时，必须严格遵守《中华人民共和国网络安全法》、《计算机信息网络国际联网安全保护管理办法》等法律法规。<strong>严禁利用本平台从事以下活动（“红线条款”）：</strong></p>
<div className="bg-red-500/5 border border-red-500/20 rounded-lg p-3 md:p-4 space-y-3">
<ul className="list-disc pl-4 md:pl-5 space-y-2 text-red-600 dark:text-red-400 font-medium">
<li><strong>危害国家安全：</strong>反对宪法所确定的基本原则、危害国家安全、泄露国家秘密、颠覆国家政权、破坏国家统一的；</li>
<li><strong>非法信息服务：</strong>黑客攻击工具、DDoS 攻击服务、服务器爆破等其他非法信息服务平台；</li>
<li><strong>黄赌毒关联：</strong>制作、复制、发布、传播淫秽、色情、赌博、暴力、凶杀、恐怖或者教唆犯罪的；</li>
<li><strong>侵犯知识产权：</strong>销售盗版软件、盗版影视资源、非法游戏外挂、私服、黑号、社工库数据等；</li>
<li><strong>欺诈与虚假：</strong>进行电信诈骗、金融诈骗、传销、虚假广告虚假交易等；</li>
<li><strong>其他违法信息：</strong>涉及散布谣言、宣扬邪教/封建迷信、侮辱/诽谤他人、侵害他人合法权益的。</li>
</ul>
</div>
<p><strong>违约处理：</strong>一旦发现您违反上述规定，平台有权不经通知<strong>立即永久封禁您的账号、拦截所有 API 请求、冻结账户内所有关联价值，并依法向公安机关、网安部门移交相关线索。</strong></p>
</div>
),
},
{
value: "virtual-assets",
title: "5. 虚拟资产与交易规则",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<p><strong>5.1 资产性质：</strong>平台内流转的“余额”、“积分”等均为<strong>社区虚拟积分</strong>，仅代表您在社区生态内的活跃度或贡献值。它们<strong>不具有任何货币属性</strong>，严禁兑换为法定货币，也不可用于任何非平台许可的商业交易。</p>
<p><strong>5.2 交易不可逆：</strong>鉴于网络技术的实时性，<strong>一旦积分消耗或划转指令被执行，该操作即不可撤销。</strong>请您在确认相关积分活动前，务必仔细核对服务方信息。</p>
<p><strong>5.3 规则说明：</strong>为营造良好的社区积分环境，平台有权收取一定的服务费（以积分为结算单位）进行调控，具体规则以控制台公示为准。平台保留根据社区运营状况调整积分规则的权利。</p>
<p><strong>处理规则：</strong>一旦发现您违反上述规定，平台运维主体有权不经通知<strong>立即永久封禁您的账号、拦截所有 AccessToken 请求，并依法向公安机关、网安部门移交相关线索。</strong></p>
</div>
),
},
{
value: "liability-limitation",
title: "6. 免责声明与不可抗力",
title: "5. 免责声明与不可抗力",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<p><strong>6.1 基础免责：</strong>本平台服务按“现状”（As-Is）及“现有”（As-Available）状态提供。我们不保证服务一定能满足您的要求，也不保证服务不会中断，对服务的及时性、安全性、准确性都不作担保。</p>
<p><strong>6.2 不可抗力：</strong>对于因以下原因导致的服务中断、数据丢失或账号损失，平台不承担赔偿责任：</p>
<p><strong>5.1 基础免责：</strong>本开发底座按“现状”（As-Is）及“现有”（As-Available）状态提供。我们不保证服务一定能满足您的特定开发需求，对服务的及时性、安全性、准确性都不作额外担保。</p>
<p><strong>5.2 技术服务中断：</strong>对于因以下不可抗力原因导致的服务中断、数据丢失或账号损坏，平台不承担赔偿责任：</p>
<ul className="list-disc pl-4 md:pl-5 space-y-1 text-muted-foreground">
<li>自然灾害（台风、地震、海啸、洪水等）；</li>
<li>政府行为、法律法规或政策调整、行政命令；</li>
<li>电信部门技术调整、通讯线路中断、海底光缆故障；</li>
<li>黑客攻击、计算机病毒侵入或发作、技术性故障；</li>
<li>社区维护、系统升级（我们将尽可能提前公告）。</li>
<li>政府行为、网络安全法律法规调整或行政命令；</li>
<li>电信部门线路技术故障、机房海底光缆损毁；</li>
<li>黑客入侵、勒索病毒感染导致的数据损毁或宕机。</li>
</ul>
<p><strong>6.3 责任上限：</strong>在任何情况下，平台对您所承担的违约赔偿责任总额不超过您在违约行为发生前 1 个月内向平台支付的费用总额。</p>
</div>
),
},
{
value: "governing-law",
title: "7. 法律适用与争议解决",
title: "6. 法律适用与争议解决",
content: (
<div className="space-y-4 text-sm leading-relaxed">
<p><strong>7.1 法律适用：</strong>本协议的订立、执行、解释及争议的解决均适用<strong>中华人民共和国法律</strong>（不包括港澳台地区法律及冲突法）。</p>
<p><strong>7.2 争议解决：</strong>若您和平台发生任何争议或纠纷，首先应友好协商解决；协商不成的，您同意将纠纷或争议提交至<strong>平台运营团队所在地有管辖权的人民法院</strong>管辖。</p>
<p><strong>7.3 协议变更：</strong>我们有权根据法律法规变化或业务发展需要修改本协议。变更后的协议将在平台公示，自公示之日起生效。若您继续使用服务，视为您已接受修订后的协议。</p>
<p><strong>6.1 法律适用：</strong>本协议的订立、执行、解释及争议的解决均适用<strong>中华人民共和国法律</strong>（不包括港澳台地区冲突法）。</p>
<p><strong>6.2 争议解决：</strong>若发生任何争议或纠纷，首先应友好协商解决；协商不成的，应提交至本系统部署或运营方所在地有管辖权的人民法院管辖。</p>
</div>
),
},