参与开发

配置 Melso 本地开发环境，运行测试，并按仓库约定提交改动。

Melso 是 Go backend 与 pnpm monorepo。最简单的本地启动方式是 make dev；它会为当前 checkout 准备环境、数据库和 migration，再启动 Web 与 API。

环境要求

Node.js 22；
pnpm 10.28.2；
Go 1.26.6；
Docker Engine 或 Docker Desktop；
Git 和 Make。

版本以根目录 package.json、server/go.mod 和 CI workflow 为准。

第一次启动

git clone https://github.com/albertsalgueda/melso.git
cd multica
make dev

主 checkout 会使用 .env。文件不存在时，make dev 会从 .env.example 创建；然后启动共享 PostgreSQL、安装依赖、执行 migration，并运行 API 与 Web。

默认地址：

Web: http://localhost:3000
API: http://localhost:8080

本地固定验证码来自开发环境配置。不要把本地 .env 用到公网部署。

在 worktree 中开发

仓库支持主 checkout 和多个 worktree 同时运行。它们共用一个 PostgreSQL 容器，但使用不同数据库和端口。

git worktree add ../multica-feature -b feat/my-change main
cd ../multica-feature
make setup-worktree
make start-worktree

make setup-worktree 会生成 .env.worktree，数据库名和端口根据路径确定。再次启动：

make start-worktree

停止当前 worktree 的 Web 与 API：

make stop-worktree

也可以直接运行 make dev，脚本会通过 .git 文件识别 worktree 并选择 .env.worktree。

不同 worktree 共用 PostgreSQL 容器，不共用数据库。不要为每个 worktree 启动新的 Compose project；先检查 .env.worktree 中的 POSTGRES_DB、PORT 和 FRONTEND_PORT。

常用命令

整体流程

make dev              # 准备并启动当前 checkout
make start            # 使用已有环境启动 API 与 Web
make stop             # 停止当前 checkout 的进程
make check            # 完整本地验证流程
make build            # 构建 server、CLI 和 migrate 二进制

前端

pnpm install
pnpm dev:web
pnpm dev:desktop
pnpm build
pnpm typecheck
pnpm lint
pnpm test

根命令默认排除 Mobile。移动端有独立脚本和 CI，修改前先阅读 apps/mobile/CLAUDE.md。

Backend

make server
make daemon
make test
make migrate-up
make migrate-down
make sqlc

从源码运行某条 CLI 命令：

make cli ARGS="issue list"

修改前端功能

Web 与 Desktop 都需要的功能按职责放置：

API 类型、query、mutation 和平台无关逻辑放在 packages/core/；
基础 UI 放在 packages/ui/，不能依赖业务代码；
业务页面和组件放在 packages/views/；
Next.js、Electron 和路由适配留在对应 app；
共享页面需要同时接入 Web 与 Desktop。

服务端数据由 TanStack Query 管理，筛选、草稿和布局等客户端状态由 Zustand 管理。具体边界见项目架构和根目录 CLAUDE.md。

新增或修改 API 时，要同步更新 packages/core/api/ 中的 zod schema，并为缺失字段、未知枚举或格式错误增加解析测试。

修改数据库

Migration 位于 server/migrations/，查询位于 server/pkg/db/queries/。

使用下一个未占用的数字前缀，同时创建 .up.sql 和 .down.sql；
不添加数据库 foreign key、级联删除或级联更新；关系检查和清理由应用层完成；
每个新索引都使用 CREATE INDEX CONCURRENTLY 或 CREATE UNIQUE INDEX CONCURRENTLY；
一个 concurrent index 单独放在只包含这一条语句的 migration 文件中；
修改查询后运行 make sqlc，提交生成的 server/pkg/db/generated/ 变化；
不直接编辑 sqlc 生成文件。

需要让多项写操作一起成功或回滚时，在 service 层使用应用事务。

测试位置

改动	测试位置
共享业务逻辑、query、store	`packages/core/*.test.ts`
共享页面和组件	`packages/views/*.test.tsx`
Web 或 Desktop 平台 wiring	对应 `apps/*` 目录
端到端流程	`e2e/*.spec.ts`
Backend	相关 Go package 的 `*_test.go`

先运行与改动最接近的检查，再扩大范围。例如只改 Docs：

pnpm --filter @multica/docs typecheck

共享前端改动：

pnpm typecheck
pnpm test

Backend 改动：

make test

提交前运行：

make check

make check 会执行 TypeScript typecheck 与单元测试、Go 测试和 Playwright E2E。CI 还会按改动范围构建、lint，并运行平台或安装器专项测试。

重置当前开发数据库

需要干净数据时，可以重置当前 checkout 在环境文件中指定的数据库：

make stop
make db-reset
make start

make db-reset 会删除并重建当前 POSTGRES_DB，且会拒绝连接远程数据库。操作前检查 .env 或 .env.worktree，确认目标数据库正确。

提交前检查

阅读根目录 CLAUDE.md 和相关子目录说明；
只修改当前任务需要的范围；
代码注释使用英文；
不提交 .env、令牌、构建产物或本机路径；
使用 feat(scope)、fix(scope)、docs 等 conventional commit；
在 PR 中写清行为变化和实际运行的验证命令。

接下来

开发规范 — 命名、术语和中文文案的仓库契约。
项目架构 — 分层、共享包和一次执行的代码路径。

本页目录