English | 中文说明

WorkPal 是一个基于 Go 和 React 的团队协作平台。当前项目处于 WorkPal 2.0 重构后的收敛阶段，目标不是继续横向堆模块，而是把项目管理、即时沟通、通知、搜索、文档和日程打通成可验收的项目协作闭环。

一句话定位：

面向中小研发/产品团队的私有化项目协作工作台。

长期方向：

让团队围绕“工作项”完成讨论、决策、执行、沉淀和复盘，而不是在聊天、文档、日历和项目管理工具之间来回搬运上下文。

这份 README 以当前代码为准。完整设计目标请看 WorkPal 2.0 设计说明书，长期优化路线请看 产品与架构长期优化方案。

• 前端 React + Vite 工作台，统一访问 API Gateway。
• API Gateway 提供统一入口、路由目录、服务目录、限流、重试、熔断、健康检查和服务发现 fallback。
• 用户登录、用户目录、部门、基础 RBAC、项目角色和项目成员。
• IM 会话、群聊、消息收发、编辑、撤回、WebSocket、Redis Pub/Sub 多实例扇出、outbox 发布。
• IM Channel/Thread 后端持久化路由已经存在，前端专用频道入口仍需补齐。
• 文件上传、下载、分享、删除，支持 MinIO 和本地文件回退。
• Workspace 任务和日程，包含基础 Saga 编排示例。
• Project Service 支持项目、Issue、默认 Issue 类型、工作流、状态流转、自定义字段、关联和基础报表 API。
• Notification Service 支持通知列表、未读数、标记已读和全部已读，前端 Topbar 已轮询接入。
• Search Service 使用 Bleve + Redis Streams 索引 IM 消息。
• Docs、Calendar、Approval、AI 服务入口和基础前端面板已经存在。
• Docker Compose 已包含 11 个后端服务、核心基础设施和监控组件。

• 当前正式 API 路径是 /api/v1/*，不要把设计稿中的 /api/v2/* 当作已落地接口。
• Search 主线仍是 Bleve；Elasticsearch 容器和客户端是预留设施，尚未接入 Search Service。
• 事件主线仍是 Redis Streams；Kafka/Redpanda 容器和 pkg/kafka 是后续扩展选项。
• Docs Service 当前是文档 CRUD + revision；TipTap、Yjs、CRDT 协同编辑尚未实现。
• Approval Service 当前是模板、实例、approve/reject 基础版；复杂流程 DSL 尚未执行。
• Calendar 会议室当前是进程内存 map；WebRTC 信令、音视频和屏幕共享尚未实现。
• AI Service 当前使用 noopSearch 和简单字符串摘要；真实检索增强和 LLM provider 尚未接入。
• Electron 目前只有 electron-builder.json，缺少完整 main/preload 入口、依赖和构建脚本。

当前推荐路线来自 产品与架构长期优化方案：

先打透项目协作闭环
再补文档和评审闭环
再做流程、报表和运营能力
最后上 AI、多端和规模化事件基础设施

近期最重要的闭环：

1. 创建项目 -> 创建 Issue -> 看板推进 -> 通知责任人。
2. 在聊天中讨论 Issue -> 从消息创建 Issue -> Issue 变更同步到频道。
3. 搜索消息和 Issue -> 跳回准确上下文。
4. 文档、日程、审批逐步围绕项目和 Issue 发生关联。

frontend React/Vite
        |
        v
API Gateway :8080
        |
        +-- user-service          :8081
        +-- im-service            :8082
        +-- file-service          :8083
        +-- search-service        :8084
        +-- workspace-service     :8085
        +-- project-service       :8086
        +-- docs-service          :8087
        +-- calendar-service      :8088
        +-- approval-service      :8089
        +-- notification-service  :8090
        +-- ai-service            :8091

PostgreSQL | Redis | MinIO | Bleve | Redpanda/Kafka 预留 | Elasticsearch 预留
Prometheus | Grafana | Jaeger

核心设计原则：

• 业务闭环优先于服务数量。
• 服务间同步调用用于查询和低频操作，跨服务副作用逐步事件化。
• Redis Streams 是当前业务事件主线，Kafka/Redpanda 迁移需要明确收益和回滚方案。
• 搜索、通知、权限、审计、AI 都必须围绕统一对象和权限上下文治理。
• 新能力必须有测试、指标和可运维入口。

检查工具：

docker --version && go version && node --version && npm --version

docker compose -f docker/docker-compose.yaml build
docker compose -f docker/docker-compose.yaml up -d

查看 Compose 服务列表：

docker compose -f docker/docker-compose.yaml config --services

cd frontend
npm ci
npm run dev -- --host 127.0.0.1

访问：

http://localhost:3000

如果不使用完整 Compose 服务，可以先启动基础设施：

docker compose -f docker/docker-compose.yaml up -d postgres redis minio

再按需在独立终端运行服务：

cd backend && go run ./cmd/user-service
cd backend && go run ./cmd/im-service
cd backend && go run ./cmd/file-service
cd backend && go run ./cmd/search-service
cd backend && go run ./cmd/workspace-service
cd backend && go run ./cmd/project-service
cd backend && go run ./cmd/docs-service
cd backend && go run ./cmd/calendar-service
cd backend && go run ./cmd/approval-service
cd backend && go run ./cmd/notification-service
cd backend && go run ./cmd/ai-service
cd backend && go run ./cmd/gateway

Invoke-RestMethod http://localhost:8080/health/live
Invoke-RestMethod http://localhost:8080/health/ready
Invoke-RestMethod http://localhost:8080/health
Invoke-RestMethod http://localhost:8080/gateway/routes
Invoke-RestMethod http://localhost:8080/gateway/services

你应该能看到：

• 网关存活结果。
• 网关及下游服务健康状态。
• 显式路由目录。
• 带 discovery_mode、实例信息、超时、重试和熔断状态的服务目录。

迁移文件位于 backend/migrations/<service>/。

手动迁移：

cd backend
make migrate-install
make migrate-up SERVICE=user-service
make migrate-down SERVICE=user-service

创建迁移：

make migrate-create SERVICE=im-service NAME=add_message_attachments

后端：

cd backend
go vet ./...
go test ./...
go test -race ./...

如果本机 Go module cache 无法写入，可以把缓存指到仓库内或用户可写目录：

$env:GOCACHE="$PWD\.cache\go-build"
$env:GOMODCACHE="$PWD\.cache\gomod"
go test ./...

前端：

cd frontend
npm run lint
npm test
npm run build

端到端烟测：

cd testing/e2e
npm install
npx playwright install chromium
node playwright.mjs

性能压测：

cd testing/performance
npm install
k6 run 群发消息压测.js

建议优先处理这些会直接影响产品闭环和长期架构质量的事项：

1. 补齐 Project Service 测试，覆盖默认 Issue 类型、工作流、状态流转、自定义字段和 associations。
2. 增加 Issue 详情页，承载描述、字段、动态、关联、评论和变更历史。
3. 实现消息转 Issue，并定义 Issue 卡片消息 metadata 契约。
4. 将频道 UI 接入现有 IM Channel/Thread 后端。
5. 将 Project/IM 事件接入 Notification，形成负责人通知闭环。
6. 将 Issue 索引接入 Search，形成消息 + Issue 的统一搜索雏形。
7. 改造 DocsPanel，支持编辑已有文档和版本列表。
8. 为 Calendar、Approval、Notification 补充 service/handler 测试。
9. 梳理 Prometheus 配置，确认 11 个后端服务均有指标覆盖。
10. 建立 docs/adr/，记录 Bleve/ES、Redis Streams/Kafka、文档编辑器、AI provider 等关键决策。

• 产品与架构长期优化方案
• WorkPal 2.0 重构进度追踪
• WorkPal 2.0 设计说明书
• backend/README.md
• frontend/README.md

• 生产环境必须通过环境变量或 Kubernetes Secret 覆盖 SERVER_JWTSECRET、SERVER_INTERNALTOKEN、DATABASE_PASSWORD、FILE_MINIO_ACCESSKEY、FILE_MINIO_SECRETKEY 等敏感配置。
• 不要提交本地 .env、backend/configs/config.yaml、数据库密码、MinIO 密钥或真实令牌。
• backend/configs/生产配置模板.yaml 仅作为模板，不应直接携带真实密钥。
• 首次上线前请替换所有默认开发账号密码，并检查 Grafana、MinIO、数据库等控制台默认口令。
• 敏感操作会写入 audit_logs 表，生产环境应定期归档并限制查询权限。
• AI、搜索和通知在接入真实数据前必须完成权限过滤、审计和脱敏策略设计。