Chạy ReputeCast từ mã nguồn

Hướng dẫn thao tác

Dành cho:: Nhà phát triển

Hướng dẫn này thiết lập môi trường phát triển ReputeCast: chạy ứng dụng từ mã nguồn với live reload, nạp không gian làm việc demo và giới thiệu các lệnh để kiểm thử và build. Hãy dùng nó để sửa lỗi, xây dựng tính năng hoặc thử một adapter với một máy chủ thật. Để chạy ReputeCast cho thư của chính bạn, hãy cài một bản phát hành (Cài đặt bằng Docker Compose).

Trước khi bắt đầu

Go 1.27. go.mod yêu cầu Go 1.27.2; một phiên bản Go gần đây sẽ tự tải toolchain đó.
Node.js 24 (LTS) với pnpm 12 cho ứng dụng web. package.json của ứng dụng web cố định pnpm 12.11.0.
Docker kèm Compose, cho PostgreSQL 18 và Mailpit (công cụ bắt thư cục bộ).
golangci-lint v2, chỉ cần khi chạy linter Go (make lint).
Các cổng còn trống: 5432 (PostgreSQL), 1025 và 8025 (Mailpit), 8080 (API) và 5173 (ứng dụng web).

Chạy trên máy cục bộ

Lấy mã nguồn và cài đặt các module Go cùng các phụ thuộc của ứng dụng web:
Terminal
```
git clone https://github.com/hostrepute/reputecast.git
cd reputecast
make deps
```
Khởi động mọi thứ:
Terminal
```
make dev
```
Lệnh này khởi động PostgreSQL và Mailpit bằng Docker Compose, sau đó chạy API với live reload tại http://localhost:8080 và ứng dụng web (Vite) tại http://localhost:5173. API áp dụng migration cơ sở dữ liệu khi khởi động. Dừng cả hai bằng Ctrl C.
Trong terminal thứ hai, nạp dữ liệu demo, tức các không gian làm việc Acme:
Terminal
```
make seed
```
Mở http://localhost:5173 và đăng nhập bằng một tài khoản demo. Mọi email ứng dụng gửi đi đều vào Mailpit tại http://localhost:8025.

Tài khoản	Mật khẩu	Vai trò	Ghi chú
`[email protected]`	`reputecast-demo`	Chủ sở hữu, quản trị viên hệ thống	Khóa bí mật của ứng dụng xác thực `JBSWY3DPEHPK3PXP`, mã khôi phục `b4xk-9q2m-7hdn`
`[email protected]`	`reputecast-demo`	Người xem	Chỉ dùng mật khẩu (đang trong thời gian gia hạn xác thực hai lớp)

Xem một lượt gửi trực tiếp

Các nhà cung cấp gửi thư trong demo là mô phỏng: không thư nào chúng gửi rời khỏi máy của bạn. reputecast demo send bắt đầu gửi một chiến dịch qua các nhà cung cấp này, và máy chủ đang chạy tiếp tục gửi theo thời gian thực, với thư gửi thành công, thư trả lại, khiếu nại, lượt mở và lượt nhấp, để màn hình theo dõi trực tiếp có dữ liệu hiển thị:

export REPUTECAST_ENV=development   # the command refuses to run otherwise
go run ./cmd/reputecast demo send "Weekly Digest #142" --elapsed 20m
go run ./cmd/reputecast demo send "Weekly Digest #142" --scenario outlook-complaints --elapsed 20m --reset
go run ./cmd/reputecast demo send "Weekly Digest #142" --scenario postal-outage --elapsed 17m --reset

--elapsed bắt đầu lượt gửi từ khoảng thời gian đó trước đây và tua nhanh, để màn hình theo dõi mở ra khi lượt gửi đang diễn ra.
--scenario outlook-complaints khiến những người đọc Outlook lâu không tương tác gửi khiếu nại cho đến khi phần gửi tới Outlook bị tự động tạm dừng; --scenario postal-outage khiến Postal từ chối kết nối ở phút thứ 14, nên phần của Postal bị tạm giữ.
--reset xóa lượt gửi trước đó của chiến dịch, kể cả những gì nó đã thay đổi ở nơi khác (số liệu nhà cung cấp, các mục chặn gửi phát sinh từ thư trả lại của nó). Cờ này chỉ chạy trong không gian làm việc mà mọi nhà cung cấp đều là nhà cung cấp demo.

Các cờ được liệt kê trong tham chiếu CLI.

Kiểm thử, lint và build

Tác vụ	Lệnh
Mọi bài kiểm thử: kiểm thử đơn vị và tích hợp Go trên PostgreSQL thật, kiểm thử đơn vị web	`make test`
Linter: golangci-lint, ESLint và TypeScript	`make lint`
Tạo lại mã sqlc, tài liệu OpenAPI và các kiểu API của web	`make generate`
Bản build production: một tệp nhị phân có nhúng ứng dụng web, trong `bin/reputecast`	`make build`
Docker image	`make docker`
Kiểm thử trình duyệt (Playwright) với dev stack đang chạy	`make e2e`
Trang đích reputecast.com: build, hoặc live reload trên :5288	`make site`, `make site-dev`
Adapter SDK và mẫu: build và kiểm thử, rồi chạy qua runtime Go	`make sdk`
Quét khả năng tiếp cận các màn hình của ứng dụng (axe-core, WCAG 2.0–2.2 A và AA)	`cd web && pnpm a11y`
Mọi tác vụ, kèm mô tả một dòng	`make help`

Kiểm thử tích hợp khởi động PostgreSQL 18 bằng Testcontainers, hoặc dùng lại cơ sở dữ liệu của Compose nếu nó đang chạy; make test tự chọn. CI chạy bộ kiểm thử Go trên Go 1.27 với PostgreSQL 16, 17 và 18. Khi nhiều lượt kiểm thử dùng chung một máy chủ cơ sở dữ liệu, go test -p 4 ./... giữ số kết nối trong giới hạn của PostgreSQL.

Sau khi thay đổi một thao tác API, hãy tạo lại tài liệu OpenAPI và các kiểu của web, rồi commit cả hai:

go run ./cmd/reputecast openapi > web/openapi.json
cd web && pnpm api:types

Quy ước

Hãy đọc docs/dev/CONVENTIONS.md trước thay đổi đầu tiên. Tài liệu này giải thích cách xây dựng một màn hình từ đầu đến cuối. Tóm tắt:

Mỗi miền nghiệp vụ là một package Go trong internal/ với một Service và một hàm Register cho các thao tác API của nó. Mọi thao tác khai báo ai được gọi và cần quyền nào, và mọi thay đổi ghi một mục nhật ký kiểm tra trong cùng một transaction cơ sở dữ liệu.
Lỗi là problem document theo RFC 9457, kèm một câu nói rõ cần làm gì (Lỗi). Khóa bí mật là chỉ ghi.
SQL nằm trong internal/store/queries/ và đi qua sqlc; migration là các tệp goose trong migrations/, mỗi tệp có một Down, và phải chạy được trên PostgreSQL 16 đến 18.
Ứng dụng web chỉ gọi API qua client được tạo từ web/openapi.json.
Màn hình tuân theo các bảng thiết kế trong design/boards/ ở 1440, 834 và 390 px.
Văn bản giao diện được đặt trong các tệp thông điệp để có thể dịch (Dịch ReputeCast).

Mở pull request

Giữ cho make test, make lint và make build luôn đạt, và thêm kiểm thử cho thay đổi của bạn.
Viết commit message theo Conventional Commits: type(scope): description, ví dụ fix(campaigns): count only blocking issues for a blocked draft. Dòng đầu tiên dài tối đa 100 ký tự, ở thể mệnh lệnh, viết thường sau dấu hai chấm và không có dấu chấm cuối câu.
Không bao giờ thêm tường phí hay kiểm tra giấy phép: mọi tính năng trong kho mã đều miễn phí.

Kiểm tra kết quả

make dev in ra API http://localhost:8080 Web http://localhost:5173 Mail http://localhost:8025.
curl http://localhost:8080/readyz trả lời 200.
Bạn đăng nhập được bằng [email protected] và thấy không gian làm việc Acme Newsletter.

Khắc phục sự cố

make dev lỗi vì một cổng: một PostgreSQL hoặc Mailpit khác đang chạy. Hãy dừng nó, hoặc đặt cổng khác trong .env.
Lỗi “too many clients” khi kiểm thử: chạy go test -p 4 ./....
make lint báo thiếu golangci-lint: cài golangci-lint v2.
demo send từ chối chạy: đặt REPUTECAST_ENV=development trong terminal đó.

Liên quan

Dịch ReputeCastVăn bản giao diện nằm ở đâu và cách kiểm tra bản dịch.

Viết adapter cộng đồngThêm nhà cung cấp gửi thư mà không cần sửa ReputeCast.

Cấu hình ReputeCastMọi thiết lập mà máy chủ đọc.

Xây dựng trên ReputeCastAPI, webhook và MCP.