移除已弃用的文件:content_upload.py、content-manager.html、middleware.ts,以及与VIP会员和内容管理相关的各种API路由。此次清理通过移除未使用的代码和文件,提高了项目的可维护性
This commit is contained in:
70
.cursor/rules/api-reliability.mdc
Normal file
70
.cursor/rules/api-reliability.mdc
Normal file
@@ -0,0 +1,70 @@
|
||||
---
|
||||
description: next-project API 稳定性与提现规范(仅 next-project 参考,soul-api 为 Go 不适用)
|
||||
globs: ["next-project/**/*"]
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# API 稳定性与提现模块开发规范(next-project)
|
||||
|
||||
**适用范围**:本规则仅适用于 **next-project**(Next.js + lib/db.ts)。当前线上后端为 **soul-api**(Go + GORM),不涉及 `query()`、`toArray`、`ensureTableExists`,请勿在 soul-api 中套用本规则。
|
||||
|
||||
## 核心原则
|
||||
|
||||
在 **next-project** 中开发 API(尤其是涉及财务和管理后台的接口)时,必须遵守以下稳定性规则,以防止常见的 JavaScript 运行时错误。
|
||||
|
||||
## 1. 数据库查询安全性 (防御 `undefined.length`)
|
||||
|
||||
**问题背景**:`lib/db.ts` 中的 `query()` 在网络波动或表不存在时可能返回 `undefined`。
|
||||
|
||||
**要求**:
|
||||
|
||||
- 所有调用 `query()` 的结果必须经过 `toArray` 处理。
|
||||
- 在 API 文件顶部定义 `toArray` 辅助函数:
|
||||
```typescript
|
||||
function toArray<T>(x: any): T[] {
|
||||
if (x == null) return [];
|
||||
if (Array.isArray(x)) return x;
|
||||
return [x];
|
||||
}
|
||||
```
|
||||
- 使用方式:`const rows = toArray(await query(sql))`。
|
||||
|
||||
## 2. 数据库自愈 (Self-Healing Tables)
|
||||
|
||||
**要求**:
|
||||
|
||||
- 在 `GET` 接口逻辑开始前,必须调用 `ensureTableExists()` 函数。
|
||||
- 确保核心表(如 `withdrawals`)在查询前已存在,避免 `Table 'xxx' doesn't exist` 导致的 500 错误。
|
||||
|
||||
## 3. 提现模块状态映射
|
||||
|
||||
**映射标准**:
|
||||
|
||||
- **数据库存值**:`pending` (待处理), `processing` (处理中), `success` (成功), `failed` (失败)
|
||||
- **前端显示值**:`pending`, `processing`, `completed` (已完成), `rejected` (已拒绝)
|
||||
- **转换逻辑**:
|
||||
```typescript
|
||||
const displayStatus = dbStatus === 'success' ? 'completed' : (dbStatus === 'failed' ? 'rejected' : dbStatus);
|
||||
```
|
||||
|
||||
## 4. 财务字段处理
|
||||
|
||||
- **金额转换**:从数据库读取的 `decimal` 类型必须经过 `parseFloat()` 转换后再进行数学运算。
|
||||
- **配置归一化**:分成比例字段(如 `distributorShare`)必须兼容 `90` 和 `0.9` 两种存值:
|
||||
```typescript
|
||||
let rate = Number(val);
|
||||
if (rate >= 1) rate = rate / 100; // 将 90 转为 0.9
|
||||
```
|
||||
|
||||
## 5. 管理后台列表必备字段
|
||||
|
||||
所有管理后台的 API 必须包含以下映射字段以支持通用 UI 组件:
|
||||
|
||||
- `user_name` 或 `userNickname`: 展示用户名称。
|
||||
- `userAvatar`: 展示头像(若无,前端需展示首字母)。
|
||||
- `status`: 统一后的显示状态。
|
||||
- `amount`: 格式化后的数字金额。
|
||||
|
||||
## 6. 调试模式
|
||||
|
||||
- 遇到顽固 500 错误时,优先采用“最小化接口法”:移除所有业务逻辑,仅返回 `{success: true, data: []}`,确认通路正常后再分步加回代码。
|
||||
Reference in New Issue
Block a user