foka-ci/docs/conventions.md

编码规范

1. 命名习惯

• 前端组件: PascalCase (如 ProjectCard.tsx)。
• 后端文件: kebab-case (如 route-scanner.ts)。
• DTO: 文件名为 dto.ts，类名为 XxxDTO。

2. 代码组织

web 项目代码组织如下：

├── web/
│   ├── pages/
│   │   ├── components/        # 页面组件
│   │   ├── index.tsx          # 页面入口组件
│   │   ├── service.ts         # 当前页面使用到的 api 请求方法和纯函数
│   │   ├── types.ts           # 当前页面使用到的类型定义
│   │   └── ...
│   └── hooks/                 # 通用 hooks （不止一个组件引用）
│   └── stores/                # 全局状态
│   └── utils/                 # 通用工具类
│   └── styles/                # 全局样式
│   └── assets/                # 静态资源
│   └── components/            # 通用组件
│   └── types/                 # 全局类型定义
│   └── ...

3. 代码规范

• 注释符合 jsdoc 规范
• 代码简洁，避免冗余，移除无用的代码引用、变量、函数和css样式
• 禁止使用 any 类型

4. 前端发送net请求示例

• 分页

import {net} from '@utils';
import type {APIPagination} from '@utils/net';

const data = await net.request<APIPagination<Deployment>>({
  method: 'GET',
  url: '/api/deployments',
  // 注意：查询参数使用 params 传递，不要手动拼接到 url 上
  params: {
    projectId: 1,
    page: 1,
    pageSize: 10,
  },
})

• 其他

import {net} from '@utils';

const data = await net.request<void>({
  method: 'POST',
  url: '/api/deployment',
  data: {
    name: 'xxx',
    description: 'xxx',
    repository: 'https://a.com',
  }
})
if (data.code === 0) {
  console.log("创建成功")
} else {
  console.log("创建失败")
}

5. 异步处理

• 统一使用 async/await。
• 后端错误通过抛出异常由 exception.ts 中间件统一捕获。

6. 格式化

• 使用 Biome 进行 Lint 和 Format。
• 提交代码前建议运行 pnpm --filter web format。