update doc

CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# 贡献指南
+
+感谢您有兴趣为本项目做出贡献！我们欢迎各种形式的贡献，但请先阅读如下文档，以节省您和我们的时间。
+
+当您在使用 Claude Code, Gemini CLI 等 Vibe-coding 工具时，推荐将此文档内容附加到上下文内。
+
+## 我们不接受的更改
+
+出于包括但不限于项目可持续性与可维护性考虑，我们不接受如下类型的更改。  
+如果您提交的 PR 包含以下类型的更改，我们可能会包括但不限于忽略、关闭或要求您更改 PR 内容。
+
+- 导致项目整体性能下降的更改；
+- 仅修改注释、空格、格式的小 PR；
+- 仅修正无影响力的拼写错误（typo）或代码注释，不提升可读性或准确性；
+- 重构已稳定工作的逻辑而不带来可维护性或功能上的实质提升；
+- 未经讨论的接口或 API 命名改动；
+
+**请注意：判断标准不是改动大小，而是改动是否有实际作用。**
+
+为提高协作效率，我们建议您在提交 PR 前，先通过 Issue 简要说明动机与背景。  
+
+
+## 贡献步骤
+
+1. **Fork 本仓库** 并创建您的分支（建议使用有意义的分支名）。
+2. **编写代码**，确保遵循项目的代码风格和最佳实践。
+3. **添加/更新测试**，确保您的更改不会破坏现有功能。
+4. **本地测试**，确认所有测试通过。
+5. **提交 Pull Request**，请详细描述您的更改内容和动机。
+
+
+## 代码规范
+
+### 后端
+
+**基础检查**
+
+需要通过 CodeQL 扫描，较长的代码建议增加 Copilot 检查。
+
+**API 文档**
+
+所有接口需要写 Swagger 文档，提交前通过 make swagger 更新文档后再提交。
+
+**响应格式**
+
+```json
+# 响应数据最外层有两个字段，error_msg 和 data
+{
+    "error_msg": "",
+    "data": null
+}
+
+# 如果是非列表数据
+{
+    "error_msg": "",
+    "data": {}
+}
+
+# 如果是分页数据
+{
+    "error_msg": "",
+    "data": {
+        "total": 0,
+        "results": []
+    }
+}
+```
+
+**数据库**
+
+- 禁止使用外键，但需要保留对应字段的索引；
+- 字段如有默认值，需要与 struct 默认值相同，如 nil，0，false，空字符串等，避免初始化时未填写或漏填写导致的数据异常。
+
+### 前端
+
+**基础检查**
+
+代码需要通过 ESLint 检查和 CodeQL 扫描。
+
+**类型安全**
+
+- 禁止使用 `any` 类型，`any` 类型绕过了 TypeScript 的类型检查系统，会导致潜在的运行时错误；
+- `unknown` 是类型安全的 `any`，但必须立即进行类型断言或类型收窄；
+- `never` 类型表示永远不会发生的值类型，必须谨慎使用，并提供清晰的注释说明。
+
+**组件规范**
+
+- 组件应按功能分类
+- 公共组件放在 `components/common` 目录
+- ShadcnUI 组件放在 `components/ui` 目录
+- 自定义图标应放置在 `/components/icons/` 目录下以命名导出形式管理，对于常规的图标，我们使用 Lucide 库
+
+**服务层**
+
+服务层架构是前端与API交互的统一入口，基于以下原则：
+1. 关注点分离 - 每个服务负责一个业务领域
+2. 统一入口 - 通过services对象导出所有服务
+3. 类型安全 - 所有请求和响应有明确类型定义
+
+
+**如何新建接口服务**
+
+1. **创建目录结构**:
+   ```
+   /services/新服务名/
+     - types.ts       // 类型定义
+     - 服务名.service.ts  // 服务实现
+     - index.ts       // 导出服务
+   ```
+
+2. **实现服务类**:
+   ```typescript
+   // 新服务名/服务名.service.ts
+   import {BaseService} from '../core/base.service';
+
+   export class 新服务类 extends BaseService {
+     protected static readonly basePath = '/api/v1/路径';
+
+     static async 方法名(参数): Promise<返回类型> {
+       return this.get<返回类型>('/endpoint');
+     }
+   }
+   ```
+
+3. **在services/index.ts注册**:
+   ```typescript
+   import {新服务类} from './新服务名';
+
+   const services = {
+     auth: AuthService,
+     新服务名: 新服务类
+   };
+   ```
+
+**使用方法**
+
+```typescript
+import services from '@/lib/services';
+
+// 调用服务方法
+const 结果 = await services.新服务名.方法名(参数);
+```