init: 初始化项目文档中心

- 添加前端设计文档（rui-admin、收银系统、模块打包） - 添加前端实施计划（收银后台功能完善） - 添加通用规范（API、编码、数据库、前端开发规则） - 建立文档索引和使用指南
2026-06-04 08:44:20 +08:00
parent 106e1c14fe
commit 6b83b7cbc9
15 changed files with 9041 additions and 0 deletions
@@ -0,0 +1,505 @@
+# API 设计规范
+
+> 睿核科技通用平台框架 RESTful API 统一设计标准
+
+---
+
+## 一、接口分类
+
+| 分类 | 路径前缀 | 认证 | 说明 |
+|------|---------|------|------|
+| **对外接口** | `/{模块}/api/**` | OAuth2 Token | 对外提供的业务接口 |
+| **内部接口** | `/{模块}/inner/**` | `@Inner` + `INTERNAL_REQUEST` | 微服务间 Feign 调用 |
+| **入口接口** | `/{模块}/entry/**` | 无需认证 | 对外入口（登录、注册） |
+| **回调接口** | `/{模块}/notify/**` | 无需认证 | 第三方回调（支付、Webhook） |
+| **管理接口** | `/{模块}/admin/**` | 需管理员权限 | 后台管理 |
+
+---
+
+## 二、URL 设计规范
+
+### 2.1 对外接口（RESTful）
+
+```
+GET    /{version}/{模块}/{资源}          # 列表查询
+GET    /{version}/{模块}/{资源}/{id}     # 详情查询
+POST   /{version}/{模块}/{资源}          # 新增
+PUT    /{version}/{模块}/{资源}/{id}     # 全量更新
+PATCH  /{version}/{模块}/{资源}/{id}     # 局部更新
+DELETE /{version}/{模块}/{资源}/{id}     # 删除
+```
+
+**示例**：
+```
+GET    /v1/user/users?page=1&size=10     # 查询用户列表
+GET    /v1/user/users/1001               # 查询用户详情
+POST   /v1/user/users                    # 新增用户
+PUT    /v1/user/users/1001               # 全量更新用户
+PATCH  /v1/user/users/1001               # 局部更新（如只改状态）
+DELETE /v1/user/users/1001               # 删除用户
+```
+
+### 2.2 内部接口（Feign）
+
+```
+GET /{模块}/inner/{功能}/{方法}
+```
+
+**示例**：
+```
+GET /user/inner/auth/loadByUsername/{username}
+GET /system/inner/client/getById/{clientId}
+```
+
+### 2.3 版本控制
+
+- **URI 版本**（推荐）：`/v1/user/users`
+- **Header 版本**（可选）：`Accept: application/vnd.rui.v1+json`
+
+---
+
+## 三、请求规范
+
+### 3.1 HTTP 方法
+
+| 方法 | 用途 | 幂等性 |
+|------|------|--------|
+| GET | 查询 | ✅ |
+| POST | 新增/提交 | ❌ |
+| PUT | 全量更新 | ✅ |
+| PATCH | 局部更新 | ❌ |
+| DELETE | 删除 | ✅ |
+
+### 3.2 Content-Type
+
+```
+Content-Type: application/json; charset=utf-8
+```
+
+### 3.3 请求头规范
+
+| Header | 必填 | 说明 |
+|--------|------|------|
+| Authorization | 是（除 entry/notify） | `Bearer {access_token}` |
+| Content-Type | 是 | `application/json` |
+| X-Request-Id | 否 | 请求追踪 ID（网关自动生成） |
+| X-Tenant-Id | 否 | 租户 ID（后端自动注入） |
+| Accept-Language | 否 | 语言偏好 `zh-CN` / `en-US` |
+
+### 3.4 分页参数
+
+```
+GET /v1/user/users?page=1&size=10&sort=createdAt,desc
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| page | int | 1 | 当前页码（从1开始） |
+| size | int | 10 | 每页条数（最大100） |
+| sort | string | createdAt,desc | 排序字段和方向 |
+
+### 3.5 查询参数
+
+```
+GET /v1/user/users?username=admin&status=1&createdAt_start=2024-01-01&createdAt_end=2024-12-31
+```
+
+**规则**：
+- 精确匹配：字段名直接等于值 `status=1`
+- 模糊匹配：字段名加后缀 `_like` `username_like=admin`
+- 范围查询：字段名加后缀 `_start` / `_end` `createdAt_start=2024-01-01`
+- 多值查询：字段名加后缀 `_in` `status_in=1,2`
+
+---
+
+## 四、响应规范
+
+### 4.1 统一响应格式
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {}
+}
+```
+
+### 4.2 分页响应格式
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "records": [],
+    "total": 100,
+    "size": 10,
+    "current": 1,
+    "pages": 10
+  }
+}
+```
+
+### 4.3 HTTP 状态码
+
+| 状态码 | 含义 | 使用场景 |
+|--------|------|---------|
+| 200 | OK | 查询成功、更新成功 |
+| 201 | Created | 新增成功 |
+| 204 | No Content | 删除成功（无返回体） |
+| 400 | Bad Request | 参数校验失败 |
+| 401 | Unauthorized | 未登录/Token 过期 |
+| 403 | Forbidden | 无权限访问 |
+| 404 | Not Found | 资源不存在 |
+| 409 | Conflict | 资源冲突（如重复提交） |
+| 429 | Too Many Requests | 请求过于频繁 |
+| 500 | Internal Server Error | 服务器内部错误 |
+
+### 4.4 错误码规范
+
+| 区间 | 模块 | 示例 |
+|------|------|------|
+| 1000-1999 | 通用 | 1001: 参数校验失败, 1002: 资源不存在 |
+| 2000-2999 | 用户模块 | 2001: 用户名已存在, 2002: 密码错误 |
+| 3000-3999 | 系统模块 | 3001: 字典不存在, 3002: 配置错误 |
+| 4000-4999 | 认证模块 | 4001: Token 过期, 4002: 无权访问 |
+| 5000-5999 | 文件模块 | 5001: 上传失败, 5002: 文件过大 |
+| 6000-6999 | 消息模块 | 6001: 发送失败, 6002: 模板不存在 |
+
+**错误响应示例**：
+```json
+{
+  "code": 2001,
+  "msg": "用户名已存在",
+  "data": null
+}
+```
+
+---
+
+## 五、Controller 命名与路径映射
+
+### 5.1 命名规则
+
+| 类型 | Controller 命名 | 路径 | 说明 |
+|------|----------------|------|------|
+| 对外业务 | `UserController` | `/v1/user/users/**` | 常规 CRUD |
+| 内部调用 | `UserInnerController` | `/user/inner/**` | Feign 调用 |
+| 对外入口 | `UserEntryController` | `/user/entry/**` | 免认证入口 |
+| 第三方回调 | `PayNotifyController` | `/pay/notify/**` | Webhook |
+| 后台管理 | `UserAdminController` | `/v1/user/admin/**` | 管理接口 |
+
+### 5.2 方法命名
+
+| 操作 | 方法名 | HTTP | 路径 |
+|------|--------|------|------|
+| 列表 | `list` / `page` | GET | `/{资源}` |
+| 详情 | `getById` | GET | `/{资源}/{id}` |
+| 新增 | `add` / `save` | POST | `/{资源}` |
+| 更新 | `update` / `edit` | PUT | `/{资源}/{id}` |
+| 局部更新 | `patch` | PATCH | `/{资源}/{id}` |
+| 删除 | `remove` / `delete` | DELETE | `/{资源}/{id}` |
+| 批量删除 | `batchRemove` | DELETE | `/{资源}/batch` |
+| 导出 | `export` | GET | `/{资源}/export` |
+| 导入 | `import` | POST | `/{资源}/import` |
+
+---
+
+## 六、Swagger 注解规范
+
+### 6.1 Controller 注解
+
+```java
+@Tag(name = "用户管理", description = "用户相关接口")
+@RestController
+@RequestMapping("/v1/user/users")
+public class UserController {
+
+    @Operation(summary = "查询用户列表", description = "支持分页、排序、条件查询")
+    @GetMapping
+    public Result<PageResult<UserVO>> list(
+            @Parameter(description = "页码") @RequestParam(defaultValue = "1") Integer page,
+            @Parameter(description = "每页条数") @RequestParam(defaultValue = "10") Integer size) {
+        // ...
+    }
+
+    @Operation(summary = "新增用户")
+    @PostMapping
+    public Result<Long> add(@RequestBody @Valid UserDTO dto) {
+        // ...
+    }
+}
+```
+
+### 6.2 DTO / VO 注解
+
+```java
+@Schema(description = "用户新增DTO")
+@Data
+public class UserDTO {
+
+    @Schema(description = "用户名", requiredMode = Schema.RequiredMode.REQUIRED, example = "admin")
+    @NotBlank(message = "用户名不能为空")
+    @Size(min = 2, max = 50, message = "用户名长度2-50字符")
+    private String username;
+
+    @Schema(description = "状态 0:禁用 1:启用", example = "1")
+    private Integer status;
+}
+```
+
+---
+
+## 七、数据校验规范
+
+### 7.1 分组校验
+
+```java
+public interface AddGroup {}    // 新增分组
+public interface UpdateGroup {} // 更新分组
+```
+
+### 7.2 使用示例
+
+```java
+@Data
+public class UserDTO {
+
+    @NotNull(message = "ID不能为空", groups = UpdateGroup.class)
+    private Long id;
+
+    @NotBlank(message = "用户名不能为空", groups = {AddGroup.class, UpdateGroup.class})
+    private String username;
+}
+
+// Controller
+@PostMapping
+public Result<Long> add(@RequestBody @Validated(AddGroup.class) UserDTO dto) {
+    // 新增
+}
+
+@PutMapping("/{id}")
+public Result<Void> update(@RequestBody @Validated(UpdateGroup.class) UserDTO dto) {
+    // 更新
+}
+```
+
+---
+
+## 八、Feign 接口规范
+
+### 8.1 接口定义
+
+```java
+/**
+ * 远程用户服务
+ */
+@Headers("INTERNAL_REQUEST: INTERNAL")
+@FeignClient(
+    contextId = "remoteUserService",
+    value = "${feign.providers.user:rui-service-user}",
+    path = "/user/inner"
+)
+public interface RemoteUserService {
+
+    @GetMapping("/auth/loadByUsername/{username}")
+    Result<Map<String, Object>> loadUser(@PathVariable String username);
+}
+```
+
+### 8.2 调用规范
+
+```java
+@Service
+@RequiredArgsConstructor
+public class UserRemoteService {
+
+    private final RemoteUserService remoteUserService;
+
+    public UserVO getUserById(Long userId) {
+        Result<UserVO> result = remoteUserService.getById(userId);
+        if (result.isSuccess()) {
+            return result.getData();
+        }
+        throw new BizException(result.getCode(), result.getMsg());
+    }
+}
+```
+
+---
+
+## 九、文件上传接口规范
+
+### 9.1 单文件上传
+
+```
+POST /v1/file/files/upload
+Content-Type: multipart/form-data
+
+file: [二进制文件]
+module: user
+bizId: 1001
+```
+
+**响应**：
+```json
+{
+  "code": 200,
+  "msg": "上传成功",
+  "data": {
+    "fileId": "123456",
+    "fileName": "avatar.jpg",
+    "fileUrl": "https://oss.example.com/avatar/123456.jpg",
+    "fileSize": 102400
+  }
+}
+```
+
+### 9.2 多文件上传
+
+```
+POST /v1/file/files/batchUpload
+Content-Type: multipart/form-data
+
+files: [文件1, 文件2, 文件3]
+module: user
+```
+
+---
+
+## 十、导出接口规范
+
+### 10.1 Excel 导出
+
+```
+GET /v1/user/users/export?username=admin&status=1
+Accept: application/vnd.ms-excel
+```
+
+**响应**：
+```
+Content-Type: application/vnd.ms-excel
+Content-Disposition: attachment; filename="用户列表_20240101.xlsx"
+```
+
+### 10.2 CSV 导出
+
+```
+GET /v1/user/users/export?format=csv
+Accept: text/csv
+```
+
+---
+
+## 十一、WebSocket 接口规范（预留）
+
+```
+ws://gateway:9300/ws/{模块}/{topic}
+```
+
+**示例**：
+```
+ws://localhost:9300/ws/msg/notification  # 消息通知
+ws://localhost:9300/ws/monitor/metrics   # 实时监控
+```
+
+---
+
+## 十二、接口文档生成
+
+### 12.1 配置 SpringDoc
+
+```yaml
+springdoc:
+  swagger-ui:
+    path: /swagger-ui.html
+    enabled: true
+  api-docs:
+    path: /v3/api-docs
+    enabled: true
+  group-configs:
+    - group: 用户服务
+      display-name: 用户服务 API
+      paths-to-match: /v1/user/**
+    - group: 系统服务
+      display-name: 系统服务 API
+      paths-to-match: /v1/system/**
+```
+
+### 12.2 访问地址
+
+```
+http://localhost:9300/swagger-ui.html        # 网关聚合文档
+http://localhost:9301/swagger-ui.html        # 认证服务文档
+http://localhost:9302/swagger-ui.html        # 系统服务文档
+http://localhost:9303/swagger-ui.html        # 用户服务文档
+```
+
+---
+
+## 十三、Postman / APIFox 集合规范
+
+### 13.1 目录结构
+
+```
+睿核科技通用平台
+├── 01-认证中心
+│   ├── 获取Token
+│   ├── 刷新Token
+│   └── 退出登录
+├── 02-用户中心
+│   ├── 用户管理
+│   ├── 等级管理
+│   └── 用户查询
+├── 03-系统管理
+│   ├── 租户管理
+│   ├── 菜单管理
+│   ├── 角色管理
+│   ├── 字典管理
+│   └── 参数配置
+├── 04-文件管理
+│   ├── 文件上传
+│   └── 文件下载
+└── 99-内部接口（Feign）
+    ├── 用户服务
+    └── 系统服务
+```
+
+### 13.2 环境变量
+
+```json
+{
+  "baseUrl": "http://localhost:9300",
+  "token": "{{login_response_token}}",
+  "tenantId": "1"
+}
+```
+
+---
+
+## 十四、接口变更管理
+
+### 14.1 变更类型
+
+| 类型 | 说明 | 版本处理 |
+|------|------|---------|
+| 新增接口 | 新增资源/功能 | 当前版本可用 |
+| 新增字段 | 请求/响应增加字段 | 当前版本可用（兼容） |
+| 废弃字段 | 字段标记 deprecated | 当前版本可用，下版本移除 |
+| 废弃接口 | 接口标记 deprecated | 保留至少2个版本后移除 |
+| 破坏性变更 | 字段删除/类型变更 | 升级版本号（v1 → v2） |
+
+### 14.2 版本迭代策略
+
+```
+v1.0 —— 初始版本
+v1.1 —— 新增字段（兼容）
+v1.2 —— 新增接口（兼容）
+v2.0 —— 破坏性变更（不兼容）
+```
+
+---
+
+> **文档版本**: v1.0
+> **创建日期**: 2026-05-28
+> **适用范围**: 睿核科技通用平台框架所有 RESTful API
@@ -0,0 +1,280 @@
+# 编码规范
+
+## 🎯 通用原则
+
+1. **可读性优先** - 代码是写给人看的，顺便给机器执行
+2. **DRY 原则** - Don't Repeat Yourself
+3. **单一职责** - 一个类/方法只做一件事
+4. **开闭原则** - 对扩展开放，对修改关闭
+
+---
+
+## 📝 Java 编码规范
+
+### 命名规范
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 类名 | 大驼峰 | `UserService`, `OrderController` |
+| 方法名 | 小驼峰 | `getUserById()`, `createOrder()` |
+| 变量名 | 小驼峰 | `userName`, `orderList` |
+| 常量 | 全大写下划线 | `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT` |
+| 包名 | 全小写 | `com.rui.service.user` |
+
+### 代码格式
+
+```java
+// 正确的类定义
+@Service
+public class UserServiceImpl implements IUserService {
+    
+    private final UserMapper userMapper;
+    private final RedisUtil redisUtil;
+    
+    // 构造器注入（推荐）
+    public UserServiceImpl(UserMapper userMapper, RedisUtil redisUtil) {
+        this.userMapper = userMapper;
+        this.redisUtil = redisUtil;
+    }
+    
+    // 方法注释
+    /**
+     * 根据ID获取用户信息
+     * @param userId 用户ID
+     * @return 用户信息
+     */
+    @Override
+    public UserDTO getUserById(Long userId) {
+        // 先查缓存
+        UserDTO user = redisUtil.get("user:" + userId);
+        if (user != null) {
+            return user;
+        }
+        
+        // 再查数据库
+        User entity = userMapper.selectById(userId);
+        if (entity == null) {
+            throw new BizException("用户不存在");
+        }
+        
+        // 转换并缓存
+        user = convertToDTO(entity);
+        redisUtil.set("user:" + userId, user, 3600);
+        
+        return user;
+    }
+}
+```
+
+### 注释规范
+
+```java
+/**
+ * 用户服务实现类
+ * 
+ * @author pigeon
+ * @since 2024-01-01
+ */
+@Service
+public class UserServiceImpl {
+    
+    /**
+     * 获取用户详情
+     * 
+     * @param userId 用户ID，不能为空
+     * @return 用户详情DTO
+     * @throws BizException 用户不存在时抛出
+     */
+    public UserDetailDTO getDetail(Long userId) {
+        // ...
+    }
+}
+```
+
+---
+
+## 🌐 TypeScript/Vue 编码规范
+
+### 命名规范
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 组件名 | 大驼峰 | `UserTable.vue`, `OrderForm.vue` |
+| 组合式函数 | use前缀 | `useUser()`, `useOrder()` |
+| 类型定义 | 大驼峰 | `UserDTO`, `OrderFormData` |
+| 常量 | 全大写下划线 | `API_BASE_URL`, `PAGE_SIZE` |
+| 变量/函数 | 小驼峰 | `userList`, `getUserList()` |
+
+### 组件规范
+
+```vue
+<script setup lang="ts">
+/**
+ * 用户管理组件
+ * 
+ * @description 展示用户列表，支持增删改查
+ * @author pigeon
+ */
+import { ref, onMounted } from 'vue'
+import type { UserDTO } from '@/types'
+
+// Props 定义
+interface Props {
+  deptId?: number
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  deptId: undefined
+})
+
+// Emits 定义
+const emit = defineEmits<{
+  refresh: []
+}>()
+
+// 响应式数据
+const userList = ref<UserDTO[]>([])
+const loading = ref(false)
+
+// 方法
+async function loadUserList() {
+  loading.value = true
+  try {
+    const res = await userApi.getList({ deptId: props.deptId })
+    userList.value = res.data
+  } finally {
+    loading.value = false
+  }
+}
+
+// 生命周期
+onMounted(() => {
+  loadUserList()
+})
+</script>
+```
+
+---
+
+## 🗄️ 数据库规范
+
+### 命名规范
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 表名 | 下划线、复数 | `sys_user`, `cashier_order` |
+| 字段名 | 下划线 | `user_name`, `created_at` |
+| 索引名 | idx_前缀 | `idx_user_name` |
+| 外键 | fk_前缀 | `fk_order_user` |
+
+### 必备字段
+
+```sql
+-- 所有表必须包含以下字段
+CREATE TABLE example_table (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '主键ID',
+    -- 业务字段
+    name VARCHAR(100) NOT NULL COMMENT '名称',
+    
+    -- 审计字段（由框架自动填充）
+    create_by VARCHAR(64) COMMENT '创建者',
+    create_time DATETIME COMMENT '创建时间',
+    update_by VARCHAR(64) COMMENT '更新者',
+    update_time DATETIME COMMENT '更新时间',
+    deleted TINYINT DEFAULT 0 COMMENT '删除标志（0-正常，1-删除）',
+    tenant_id BIGINT COMMENT '租户ID',
+    
+    -- 索引
+    INDEX idx_name (name)
+) COMMENT='示例表';
+```
+
+---
+
+## 🔒 安全规范
+
+1. **SQL 注入防护** - 使用 MyBatis 参数绑定，禁止字符串拼接 SQL
+2. **XSS 防护** - 前端转义输出，后端校验输入
+3. **敏感信息** - 密码必须加密存储，日志中禁止输出敏感信息
+4. **接口鉴权** - 所有接口必须校验权限（白名单除外）
+
+---
+
+## 🧪 测试规范
+
+### Java 测试
+
+```java
+@SpringBootTest
+class UserServiceTest {
+    
+    @Autowired
+    private IUserService userService;
+    
+    @Test
+    @DisplayName("根据ID查询用户-正常情况")
+    void getUserById_Success() {
+        // Given
+        Long userId = 1L;
+        
+        // When
+        UserDTO user = userService.getUserById(userId);
+        
+        // Then
+        assertThat(user).isNotNull();
+        assertThat(user.getId()).isEqualTo(userId);
+    }
+    
+    @Test
+    @DisplayName("根据ID查询用户-用户不存在")
+    void getUserById_NotFound() {
+        // Given
+        Long userId = 999L;
+        
+        // Then
+        assertThrows(BizException.class, () -> {
+            userService.getUserById(userId);
+        });
+    }
+}
+```
+
+---
+
+## 📝 Git 提交规范
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Type 类型
+
+| 类型 | 说明 |
+|------|------|
+| feat | 新功能 |
+| fix | 修复 bug |
+| docs | 文档更新 |
+| style | 代码格式（不影响功能） |
+| refactor | 重构 |
+| test | 测试相关 |
+| chore | 构建/工具相关 |
+
+### 示例
+
+```bash
+feat(cashier): 添加订单退款功能
+
+- 支持部分退款
+- 支持原路退回
+- 添加退款记录表
+
+Closes #123
+```
+
+---
+
+> **最后提醒**：编码规范是为了团队协作，请务必遵守！
@@ -0,0 +1,111 @@
+# 前端开发规则
+
+> 适用于 {root} 仓库下所有前端工程
+
+## 技术栈
+
+| 场景 | 框架 | UI 库 | CSS |
+|------|------|------|-----|
+| **管理后台 PC** | Vue 3 + TypeScript + Vite | Element Plus | UnoCSS |
+| **移动端/小程序** | uniapp (Vue 3) + TypeScript | uView Plus | UnoCSS |
+| **H5 官网** | Vue 3 + TypeScript + Vite | — | UnoCSS |
+
+## 统一规范
+
+### 必选
+
+- **Vue 3** Composition API（`<script setup lang="ts">`）
+- **TypeScript** 严格模式
+- **UnoCSS** 原子化 CSS（替代 Tailwind / 手写 CSS）
+- **pnpm** 包管理器
+- **ESLint** + `@antfu/eslint-config`
+- **Vite** 构建工具
+
+### 推荐
+
+- **Pinia** 状态管理
+- **Vue Router** 路由
+- **Axios** HTTP 请求（统一拦截器 + Token 刷新）
+- **unplugin-auto-import** 自动导入 Vue/API
+- **unplugin-vue-components** 自动导入组件
+- **Vitest** 单元测试
+
+### 禁止
+
+- Vue 2 / Options API
+- JavaScript（必须 TS）
+- CSS 文件（使用 UnoCSS 原子类）
+- npm/yarn（必须 pnpm）
+- 多行 CSS 样式块（用 UnoCSS 属性化或原子类替代）
+
+## 项目结构
+
+```
+admin-ui/（或 web-ui/）
+├── package.json
+├── vite.config.ts
+├── uno.config.ts
+├── tsconfig.json
+├── index.html
+├── src/
+│   ├── App.vue
+│   ├── main.ts
+│   ├── router/
+│   ├── stores/           # Pinia
+│   ├── api/              # Axios 封装 + 接口
+│   ├── views/            # 页面组件
+│   ├── components/       # 公共组件
+│   ├── composables/      # 组合函数
+│   ├── utils/            # 工具函数
+│   └── styles/           # 仅放 UnoCSS 快捷方式或极少全局样式
+└── public/
+```
+
+## API 调用规范
+
+```typescript
+// api/user.ts
+import { request } from '@/utils/request'
+
+export interface UserInfo {
+  id: number
+  username: string
+  nickname: string
+}
+
+export const userApi = {
+  page: (params: any) => request.get<PageResult<UserInfo>>('/user/info/page', { params }),
+  create: (data: UserInfo) => request.post('/user/info/create', data),
+  update: (data: UserInfo) => request.put('/user/info/update', data),
+  remove: (id: number) => request.delete(`/user/info/${id}`),
+}
+```
+
+## UnoCSS 使用
+
+```vue
+<template>
+  <!-- 原子类 -->
+  <div class="flex items-center gap-4 p-4 bg-white rounded shadow">
+    <span class="text-lg font-bold text-primary">标题</span>
+    <el-button type="primary" class="ml-auto">
+      操作
+    </el-button>
+  </div>
+</template>
+
+<style lang="scss" scoped>
+// 仅极少情况下使用，优先用 UnoCSS 原子类或 shortcuts
+</style>
+```
+
+## 命名规范
+
+| 类型 | 规则 | 示例 |
+|------|------|------|
+| 文件名 | PascalCase | `UserList.vue`, `useTable.ts` |
+| 目录名 | kebab-case | `user-info/`, `order-detail/` |
+| 变量/函数 | camelCase | `userList`, `fetchData` |
+| 组件 | PascalCase | `<UserCard />` |
+| Pinia store | useXxxStore | `useUserStore` |
+| 路径 | 小写短横线 | `/user/info`, `/order/detail` |