编码规范

TypeScript 和 JavaScript 约定

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

命名规范

代码放置规则

• 应用特定代码放在 products/01mvp/apps/web/src/lib/
• 只属于 01MVP 的可复用领域逻辑放在 products/01mvp/packages/
• 多个产品都要复用的通用能力放在根目录 packages/
• 纯 shadcn/ui 原子组件只能放在 packages/ui
• 当前 Web 应用共享业务组件放在 products/01mvp/apps/web/src/shared/ui

样式规范

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

设计系统约束：

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

Git Commit 规范

使用 Conventional Commits：type(scope): description

常见 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 hooks。提交时会做两类检查：

• 暂存文件检查：对已暂存的代码运行统一修复和静态检查，避免格式、导入和基础 lint 问题混进提交。
• 提交信息检查：用 Commitlint 校验 commit message，确保每次提交都能被自动 changelog、版本追踪和问题回溯稳定识别。

这些检查让项目越做越大之后仍然容易维护。一个清晰的 commit message 应该能回答三件事：改了什么类型、影响哪个范围、具体做了什么。

# 推荐
git commit -m "docs(template): explain commit conventions"
git commit -m "fix(auth): handle expired session refresh"
git commit -m "chore(agents): remove unused skill"

# 不推荐
git commit -m "update"
git commit -m "remove jta skill"

如果遇到 type may not be empty 或 subject may not be empty，通常是提交信息缺少 type: 前缀。把 remove jta skill 改成 chore(agents): remove unused skill 这类格式即可。

分支策略

项目采用主干开发（Trunk-Based Development），所有改动直接在 main 分支上进行。短期功能分支完成后及时合并回 main。

Pull Request 和代码审查

PR 至少说明变更目标、影响范围和测试方式。审查重点：功能逻辑、边界条件、package 边界、性能安全。

合并要求：CI 自动检查通过，无冲突、无回归风险。

测试规范

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

常用命令：

vp check
vp check --fix
vpr @01mvp/product#type-check
vpr @01mvp/product#test

文档规范

• packages/*/README.md：技术参考和 API 细节
• products/01mvp/apps/web/content/docs/：Fumadocs 文档中心
• openspec/：复杂功能的提案、设计和任务清单

提交前检查清单

• 代码通过 vp check
• 相关构建可以成功完成
• UI 变更符合设计系统约束
• 文档和注释已同步更新