init: 初始化项目文档中心

- 添加前端设计文档（rui-admin、收银系统、模块打包） - 添加前端实施计划（收银后台功能完善） - 添加通用规范（API、编码、数据库、前端开发规则） - 建立文档索引和使用指南
2026-06-04 08:47:08 +08:00
commit d0771597a6
9 changed files with 5310 additions and 0 deletions
@@ -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
+```
+
+---
+
+> **最后提醒**：编码规范是为了团队协作，请务必遵守！