编码规范

TypeScript、Git、测试、文档和协作流程的统一约定

本页是项目开发规范的统一入口。架构边界请结合项目结构、Monorepo 架构指南和包开发规范一起阅读。

TypeScript 和 JavaScript 约定

基础原则

启用 TypeScript strict mode
默认优先 interface，只有在联合类型、映射类型等场景再使用 type
避免使用 enum，改用 as const 对象
保持函数签名明确，避免 any

const Status = {
  ACTIVE: "active",
  INACTIVE: "inactive",
} as const;

type Status = (typeof Status)[keyof typeof Status];

命名规范

类型	风格	示例
变量 / 函数	camelCase	`getUserName`, `isActive`
组件 / 类型	PascalCase	`UserProfile`, `EventCard`
常量	UPPER_SNAKE_CASE	`MAX_RETRY_COUNT`
文件名	kebab-case	`user-profile.tsx`, `event-card.ts`

组件文件结构

推荐顺序：

类型定义
主组件导出
子组件
工具函数

type UserCardProps = {
  name: string;
};

export function UserCard({ name }: UserCardProps) {
  return <div>{name}</div>;
}

function formatName(name: string) {
  return name.trim();
}

Import 和文件组织

Import 顺序

// 1. React / Next.js
import Link from "next/link";
import { useState } from "react";

// 2. 第三方库
import { z } from "zod";

// 3. 内部别名
import { Button } from "@mono/ui";
import { db } from "@/lib/database/client";

// 4. 相对路径
import { formatDate } from "./utils";

放置规则

应用特定代码放在 apps/mono-web/src/lib/
可复用领域逻辑放在 packages/
纯 shadcn/ui 原子组件只能放在 packages/ui
跨项目共享业务组件放在 packages/ui-shared

样式规范

Tailwind 约定

class 组织顺序：布局 -> 间距 -> 颜色 -> 边框 -> 效果

<div className="flex items-center gap-4 px-6 py-3 bg-background text-foreground border rounded-lg shadow-sm">

设计系统约束

不要硬编码颜色，统一使用语义化 token
间距遵循 4px 基准
焦点状态统一使用 ring-2 ring-ring
详细视觉规范见 UI 设计规范

Git Commit 规范

项目使用 Conventional Commits：

type(scope): description

常用 type：

type	说明
`feat`	新功能
`fix`	Bug 修复
`docs`	文档更新
`style`	仅样式或格式调整
`refactor`	重构
`perf`	性能优化
`test`	测试相关
`chore`	构建、工具或杂项维护
`ci`	CI/CD 相关
`build`	构建系统或依赖调整

常见 scope：

auth
db
ui
api
i18n
payment
config

示例：

git commit -m "feat(auth): add WeChat login support"
git commit -m "fix(db): resolve connection pool timeout"
git commit -m "docs(ui): update design system guide"

分支策略

项目采用简化版 Git Flow：

main：生产分支
develop：开发分支
feature/*：功能分支，从 develop 创建
hotfix/*：紧急修复，从 main 创建
docs/*：文档调整分支

命名示例：

feature/add-wechat-login
fix/event-date-bug
docs/update-deployment-guide

Pull Request 和代码审查

PR 描述建议

PR 中至少说明：

变更目标
影响范围
测试方式
是否包含 breaking change

审查重点

评审时优先看这些问题：

功能行为是否正确
边界条件和异常路径是否处理完整
是否破坏 package 边界或设计系统约束
是否引入性能或安全风险
是否补齐必要测试与文档

合并前要求

所有自动检查通过
至少一位审查者批准
已处理评论中的阻断问题
无冲突、无明显回归风险

测试规范

测试层次

单元测试：核心业务逻辑
集成测试：API、数据库、第三方服务协作
E2E 测试：关键用户流程，使用 Playwright

基本要求

新功能优先补测试
修 Bug 至少补一个复现用例
涉及 Prisma schema 变更时，确保 migration 和类型生成同步

常用命令：

pnpm lint
pnpm lint:fix
pnpm format
pnpm type-check:packages
pnpm test:packages

文档规范

文档分层

packages/*/README.md：技术参考和 API 细节
apps/mono-web/content/docs/：Fumadocs 用户文档和开发指南
openspec/：复杂功能的提案、设计和任务清单

更新规则

当规范、架构或使用方式发生变化时，至少同步更新：

对应的 Fumadocs 页面
相关 package README
CLAUDE.md 中与 AI 助手有关的项目约束

规划工具

小型任务

直接使用 Claude Code plan mode 或其他 AI 编码助手进行小步迭代，适合：

Bug 修复
小功能添加
文档更新
局部重构

复杂任务

涉及重大架构变更或跨模块功能时，使用 openspec/ 工作流：

创建提案
审查设计
实施任务
部署后归档

提交前检查清单

代码通过 pnpm lint
相关构建可以成功完成
新功能或修复包含合理测试
文档和注释已同步更新
UI 变更符合设计系统约束

编码规范

On this page