参考手册
编码规范
TypeScript、Git、测试、文档和协作流程的统一约定
本页是项目开发规范的统一入口。架构边界请结合 项目结构、Monorepo 架构指南 和 包开发规范 一起阅读。
TypeScript 和 JavaScript 约定
- 启用 TypeScript strict mode
- 默认优先
interface，联合类型、映射类型等场景再使用type - 避免使用
enum，改用as const对象 - 保持函数签名明确，避免
any
命名规范
| 类型 | 风格 | 示例 |
|---|---|---|
| 变量 / 函数 | camelCase | getUserName, isActive |
| 组件 / 类型 | PascalCase | UserProfile, EventCard |
| 常量 | UPPER_SNAKE_CASE | MAX_RETRY_COUNT |
| 文件名 | kebab-case | user-profile.tsx, event-card.ts |
代码放置规则
- 应用特定代码放在
apps/01mvp-web/src/lib/ - 可复用领域逻辑放在
packages/ - 纯 shadcn/ui 原子组件只能放在
packages/ui - 跨项目共享业务组件放在
packages/ui-shared
样式规范
class 组织顺序：布局 -> 间距 -> 颜色 -> 边框 -> 效果。
设计系统约束：
- 不要硬编码颜色，统一使用语义化 token
- 间距遵循 4px 基准
- 焦点状态统一使用
ring-2 ring-ring - 详细视觉规范见 UI 设计规范
Git Commit 规范
使用 Conventional Commits：type(scope): description
| type | 说明 |
|---|---|
feat | 新功能 |
fix | Bug 修复 |
docs | 文档更新 |
style | 仅样式或格式调整 |
refactor | 重构 |
perf | 性能优化 |
test | 测试相关 |
chore | 构建、工具或杂项维护 |
常见 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"分支策略
项目采用主干开发（Trunk-Based Development），所有改动直接在 main 分支上进行。短期功能分支完成后及时合并回 main。
Pull Request 和代码审查
PR 至少说明变更目标、影响范围和测试方式。审查重点：功能逻辑、边界条件、package 边界、性能安全。
合并要求：CI 自动检查通过，无冲突、无回归风险。
测试规范
- 单元测试：核心业务逻辑
- 集成测试：API、数据库、第三方服务协作
- E2E 测试：关键用户流程，使用 Playwright
常用命令：
pnpm lint
pnpm lint:fix
pnpm format
pnpm type-check:packages
pnpm test:packages文档规范
packages/*/README.md：技术参考和 API 细节apps/01mvp-web/content/docs/：Fumadocs 文档中心openspec/：复杂功能的提案、设计和任务清单
提交前检查清单
- 代码通过
pnpm lint - 相关构建可以成功完成
- UI 变更符合设计系统约束
- 文档和注释已同步更新