贡献指南

参与 ShopFaaS 开源贡献：代码规范、提交规范、PR 流程。

感谢你对 ShopFaaS 开源项目的关注！本文档介绍如何参与贡献。

行为准则

参与本项目贡献需遵守以下原则：

友善包容：尊重不同背景与经验的贡献者
专业严谨：代码与讨论基于事实与技术
协作开放：欢迎提问、讨论与代码审查

贡献方式

类型	说明
Bug 修复	修复已报告的 Bug
新功能	提出新功能提案并实现
文档改进	完善文档、修正错误、补充示例
性能优化	提升性能、减少资源占用
测试补充	增加测试覆盖、改进测试质量
国际化	翻译文档与界面文案

开发环境搭建

详见开始使用 → 本地开发。

Fork 与克隆

# 1. 在 GitHub Fork 仓库
# https://github.com/shopfaas/shopfaas/fork

# 2. 克隆你的 Fork
git clone https://github.com/<your-username>/shopfaas.git
cd shopfaas

# 3. 添加上游仓库
git remote add upstream https://github.com/shopfaas/shopfaas.git

创建分支

# 从 main 创建功能分支
git checkout -b feat/your-feature-name

# Bug 修复分支
git checkout -b fix/issue-number-description

分支命名规范：

前缀	用途	示例
`feat/`	新功能	`feat/multi-currency-support`
`fix/`	Bug 修复	`fix/order-total-calculation`
`docs/`	文档改进	`docs/api-reference-update`
`refactor/`	代码重构	`refactor/extract-pagination-component`
`test/`	测试补充	`test/order-actions-coverage`
`chore/`	构建/工具	`chore/update-dependencies`

代码规范

TypeScript

严格模式：tsconfig 启用 strict: true
禁止 any：必要时使用 unknown + 类型守卫
禁止 as { ... } 类型断言绕过后端返回类型
临时 as unknown as 必须在类型完善后立即移除

注释（JSDoc）

每个 .ts / .tsx 文件顶部必须有 @file 块注释，导出函数必须有 JSDoc：

/**
 * @file 订单退款 Action
 * @description 处理订单退款请求，含权限校验与库存回滚
 */

/**
 * 处理订单退款
 * @param input - 退款输入（订单 ID、金额、原因）
 * @param ctx - Astro 上下文
 * @returns 退款结果
 * @throws {NotFoundError} 订单不存在
 * @throws {BusinessError} 订单状态不允许退款
 */
export const refund = defineJsonAction(refundInputSchema, async (input, ctx) => {
  // ...
});

Schema 校验（Zod v4）

使用 Astro 内置的 Zod v4（import { z } from "astro/zod"）：

必须用 v4 写法：z.email() / z.url() / z.uuid() / z.ip() 顶层 API
禁止新代码用 v3 写法（z.string().email() 等）
错误消息：统一用 { message: "..." } 中文消息

命名规范

类型	规范	示例
文件	kebab-case	`order-detail.ts`
函数	camelCase	`getOrderById`
类	PascalCase	`OrderService`
接口	PascalCase	`OrderItem`
常量	UPPER_SNAKE_CASE	`MAX_PAGE_SIZE`
Zod schema	`xxxInputSchema`	`refundInputSchema`
权限码	`module:submodule:action`	`order:refund`

目录约定

功能页面入口为 feature/index.astro（非 feature.astro），除非极其简单
非公开 API 使用 Astro Actions 定义在 _actions/ 并在 src/actions/index.ts 导入
对外公开 API 保留 api.ts 端点形式
路由专属代码在 _components / _actions / _services / _utils 内

测试规范

测试框架

Bun 内置 bun:test：

import { describe, test, expect } from "bun:test";

describe("formatMoney", () => {
  test("格式化人民币", () => {
    expect(formatMoney(99.5, "CNY")).toBe("¥99.50");
  });

  test("格式化美元", () => {
    expect(formatMoney(99.5, "USD")).toBe("$99.50");
  });

  test("金额为 0", () => {
    expect(formatMoney(0, "CNY")).toBe("¥0.00");
  });
});

测试位置

测试文件放在被测代码当前目录下的 __test__/ 子目录：

src/utils/string.ts
src/utils/__test__/string.test.ts

测试策略

纯函数：直接测试输入输出，覆盖正常用例 + 边界值（空值/null/极值）+ 错误路径
有依赖的模块：优先采用真实调用测试（直接导入被测模块并调用其函数，连接真实基础设施如数据库、Redis），仅当真实依赖不可用或测试成本过高时才用 mock.module() 替换
异步函数：用 async/await，超时测试用 withTimeout

运行测试

# 运行所有测试
bun test

# 按目录过滤
bun test src/utils

# 运行特定文件
bun test src/utils/__test__/string.test.ts

提交规范

Conventional Commits

使用 Conventional Commits 规范：

<type>(<scope>): <subject>

<body>

<footer>

Type 清单

Type	说明
`feat`	新功能
`fix`	Bug 修复
`docs`	文档变更
`style`	代码格式（不影响功能）
`refactor`	代码重构（既不是 feat 也不是 fix）
`perf`	性能优化
`test`	测试相关
`chore`	构建/工具/依赖变更
`ci`	CI 配置变更
`revert`	回滚之前的 commit

示例

feat(order): 支持订单退款

- 新增 order:refund 权限码
- 实现 refund Action（含库存回滚）
- 添加退款单元测试

Closes #123

fix(product): 修复商品库存为负数的问题

根因：并发扣减未加分布式锁
修复：使用 @shopfaas/shared/lock 加锁

Fixes #456

PR 流程

1. 提交前自检

提交 PR 前必须通过以下检查：

# 类型检查 + Astro 检查 + ESLint + Prettier
bun run check

# 运行测试
bun test

# 自动格式化
bun run format:fix

2. 创建 PR

在 GitHub 创建 Pull Request，PR 标题遵循 Conventional Commits 规范。

3. PR 描述

PR 描述需包含：

## 变更说明

<!-- 简述本次变更的目的与内容 -->

## 变更类型

- [ ] 新功能（feat）
- [ ] Bug 修复（fix）
- [ ] 文档改进（docs）
- [ ] 代码重构（refactor）
- [ ] 性能优化（perf）
- [ ] 测试补充（test）
- [ ] 其他（chore）

## 检查清单

- [ ] `bun run check` 通过
- [ ] `bun test` 通过
- [ ] 新增功能已编写测试
- [ ] 文档已更新（如有需要）
- [ ] 提交消息遵循 Conventional Commits

## 关联 Issue

Closes #<issue-number>

4. 代码审查

至少需要 1 位 maintainer 审查通过
审查意见需在 3 个工作日内响应
修改后重新推送，自动触发审查

5. 合并

审查通过后由 maintainer 合并
合并方式：Squash and merge（保持 commit 历史整洁）

开发者功能（店长即开发者）

ShopFaaS 不存在独立的开发者角色。店长即开发者：

应用开发入口：/admin/settings/apps/development
应用开发权限码：app:develop / app:export / app:share / app:pricing
店长默认拥有全部应用开发权限

详见开发者指南。

开源协议

提交的贡献将基于 MIT 协议发布。

联系方式

GitHub Issues：提交 Bug 报告或功能请求
GitHub Discussions：讨论问题或想法
Pull Requests：提交代码贡献

致谢

感谢所有为 ShopFaaS 开源项目做出贡献的开发者！