优化阅读页跳转逻辑，优先传递章节中间ID（mid），以提升分享功能的一致性。更新相关页面以支持新逻辑，并在多个页面中添加mid数据绑定，确保数据传递的完整性。
This commit is contained in:
Alex-larget
102
.cursor/skills/admin-dev/SKILL.md
Normal file
102
.cursor/skills/admin-dev/SKILL.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
name: soul-admin-dev
|
||||
description: Soul 创业派对管理端开发规范。在 soul-admin/ 下编辑时必遵循。React、Vite、client.ts、/api/admin/*、/api/db/*、Radix UI、鉴权。Use when editing soul-admin, 管理端, React 管理后台.
|
||||
---
|
||||
# Soul 创业派对 - 管理端开发 Skill
|
||||
|
||||
当你在 **soul-admin/** 目录下新增、优化或编辑代码时，必须遵循本 Skill。管理端仅对接 soul-api 的管理端与 DB 接口，禁止调用小程序专属路径，防止与 miniprogram、soul-api 路由互窜。
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目定位与边界
|
||||
|
||||
- **soul-admin**：React + TypeScript + Vite 管理后台，使用 React Router、Tailwind CSS、Radix UI 系组件（见 `src/components/ui/`）。
|
||||
- **唯一后端**：所有接口请求 **soul-api**（Go），通过 `VITE_API_BASE_URL` 或默认 baseUrl 配置。
|
||||
- **禁止**：不得调用 `/api/miniprogram/*`（小程序专属）；管理端只使用 `/api/admin/*`、`/api/db/*`、`/api/orders` 等 soul-api 中挂载在 admin/db 下的路由。
|
||||
|
||||
---
|
||||
|
||||
## 2. API 调用规范（防互窜）
|
||||
|
||||
- **路径**：仅使用管理端与数据类路径，例如：
|
||||
- 登录/登出：`POST /api/admin`、`POST /api/admin/logout`、`GET /api/admin`（校验）
|
||||
- 业务数据：`GET /api/admin/withdrawals`、`GET /api/orders`、`GET /api/db/users`、`GET/POST/PUT/DELETE /api/admin/chapters`、`/api/admin/content`、`/api/db/config/full` 等
|
||||
- **禁止**：不得使用 `/api/miniprogram/login`、`/api/miniprogram/book/...`、`/api/miniprogram/withdraw/...` 等小程序端路径。
|
||||
- **发起方式**：统一通过 `src/api/client.ts` 的 `get`、`post`、`put`、`del`、`request`；自动带 `Authorization: Bearer <admin_token>`（见 `src/api/auth.ts`）。
|
||||
- **示例**：
|
||||
- 正确：`get('/api/admin/withdrawals')`、`put('/api/admin/withdrawals', { id, action: 'approve' })`、`get('/api/db/users')`
|
||||
- 错误：`get('/api/miniprogram/xxx')`、在管理端实现「用小程序登录接口拿 token」
|
||||
|
||||
---
|
||||
|
||||
## 3. 代码风格与结构
|
||||
|
||||
- **技术栈**：React 18、TypeScript、Vite、React Router v6、Tailwind CSS、Radix UI、lucide-react、zustand（若用状态）。
|
||||
- **目录**：
|
||||
- `src/api/`：请求封装（client.ts）、鉴权（auth.ts）；可在此扩展管理端专用 API 方法。
|
||||
- `src/pages/`：按功能分页（如 DashboardPage、WithdrawalsPage、UsersPage、ChaptersPage）；页面内用 useState/useEffect 或 zustand 拉数。
|
||||
- `src/components/ui/`：通用 UI（button、card、input、dialog、table、badge 等）；业务模块可放在 `src/components/modules/`。
|
||||
- `src/layouts/`：AdminLayout 等布局与侧栏路由。
|
||||
- **命名**：组件 PascalCase；文件与组件名一致（如 `WithdrawalsPage.tsx`）；接口/类型用 PascalCase 或小驼峰按习惯。
|
||||
- **类型**：请求响应用 TypeScript 接口定义（如 `interface Withdrawal { ... }`），可用 `get<WithdrawalsRes>(...)` 泛型。
|
||||
|
||||
---
|
||||
|
||||
## 4. 列表页标准（必守）
|
||||
|
||||
新增或修改列表页时，必须包含：
|
||||
|
||||
**必做**：
|
||||
- **分页**：后端支持时接入 `page`、`pageSize`、`total`，使用 `src/components/ui/Pagination.tsx`
|
||||
- **搜索**：使用 `useDebounce` 对输入做 300ms 防抖（见 `src/hooks/useDebounce.ts`）
|
||||
- **筛选**：按业务提供下拉/按钮筛选
|
||||
- **刷新**：提供刷新按钮，加载时禁用并显示 loading
|
||||
- **加载状态**：请求中显示 loading
|
||||
- **空状态**：无数据时显示友好提示
|
||||
- **错误提示**：catch 后设置 error 状态，页面顶部展示可关闭的红底错误条
|
||||
|
||||
**可选**：导出 CSV、列头排序、批量操作。
|
||||
|
||||
**禁止**：不得用原生 `alert` 做加载失败提示；不得调用 `/api/miniprogram/*`。
|
||||
|
||||
**检查清单**：分页、搜索防抖、刷新、loading、空状态、错误条、仅 admin/db 路径。详见 `开发文档/列表标准与角色分工.md`。
|
||||
|
||||
### 4.1 输入框 padding（前端通用）
|
||||
|
||||
设置 input 的 padding、背景、边框时，用 div 包裹 input；padding 写在容器上，input 仅做文字样式。可避免光标截断、布局异常。React：`<div className="form-input"><input ... /></div>`。
|
||||
|
||||
### 4.2 表单弹窗与「可选择+可手动填写」（吸收 SetVipModal 经验）
|
||||
|
||||
当表单需支持「从预设选项选择」或「手动填写自定义值」时：
|
||||
|
||||
- **下拉**：`<select>` 从 `GET /api/db/xxx` 拉取预设列表，选项包含「其他（手动填写）」；
|
||||
- **自定义输入**：当选中「其他」时展示 `<Input>`，最终提交时取「选中项」或「自定义输入」；
|
||||
- **独立弹窗**：功能入口在列表行操作按钮（如「设置 VIP」），点击打开独立 `XxxModal`，不塞进详情页，保持详情页纯粹；
|
||||
- **路由与菜单**：新增管理页（如 VIP 角色）时，在 `App.tsx` 加 Route，在 `AdminLayout` 的 `menuItems` 加菜单项。
|
||||
|
||||
---
|
||||
|
||||
## 5. 业务逻辑约定（与 soul-api 对齐）
|
||||
|
||||
- **鉴权**：登录后 token 存 localStorage（`admin_token`）；请求头由 client 自动带 Bearer token；401 时跳转登录页并清除 token。
|
||||
- **提现**：列表/统计用 `GET /api/admin/withdrawals`；审核/拒绝用 `PUT /api/admin/withdrawals`（如 action: approve/reject）；状态与 soul-api 一致（如 pending、processing、success、failed），前端展示可映射为「已完成/已拒绝」等文案。
|
||||
- **用户/订单**：用户列表 `GET /api/db/users`；订单 `GET /api/orders`；字段名与 soul-api 返回一致（如 userNickname、userAvatar、status、amount）。
|
||||
- **内容/章节**：`/api/admin/chapters`、`/api/admin/content` 等 CRUD；配置类用 `/api/admin/settings`、`/api/admin/referral-settings`、`/api/db/config/full`。
|
||||
- **列表与表格**：管理端列表需有 user_name/userNickname、userAvatar、status、amount 等字段以便通用展示；若 soul-api 返回字段不同，仅在管理端做字段映射，不修改 soul-api 的 miniprogram 接口。
|
||||
|
||||
---
|
||||
|
||||
## 6. 与 soul-api 的对接要点
|
||||
|
||||
- **响应格式**：成功多为 `{ success: true, data?: ..., withdrawals?: ..., ... }`；失败 `{ success: false, error?: string }` 或 HTTP 4xx/5xx；client 在 `!res.ok` 时 throw，页面 catch 后展示错误。
|
||||
- **新增需求**：新功能应在 soul-api 的 **admin** 或 **db** 组下新增接口，管理端只调 `/api/admin/...` 或 `/api/db/...`，不得新增对 `/api/miniprogram/...` 的依赖。
|
||||
|
||||
---
|
||||
|
||||
## 7. 何时使用本 Skill
|
||||
|
||||
- 在 **soul-admin/** 下新增或修改页面、组件、API 调用时。
|
||||
- 在管理端新增任何网络请求时（必须仅使用 admin/db 等管理端路径）。
|
||||
- 做提现、用户、订单、内容、配置等后台功能时。
|
||||
|
||||
遵循本 Skill 可保证管理端只与 soul-api 的管理端路由对接，避免与小程序接口混用或误用 next-project 接口。
|
||||
Reference in New Issue
Block a user