hyapp-server/server/admin/docs/后台服务单仓架构.md

Admin Server Monorepo Architecture

当前结论

hyapp-admin-server 已迁入 hyapp-server/server/admin，但仍保持独立 Go module。目录合并只解决开发协作和契约共享问题，不改变服务边界。

Module 边界

hyapp-server/
  go.work
  api/              独立 Go module：hyapp.local/api
  services/         app 后端服务实现
  server/admin/     独立 Go module：hyapp-admin-server

• api 只放 protobuf contract 和生成代码。
• services/* 只放 app 后端服务实现。
• server/admin 只放后台管理服务实现、后台权限、后台菜单、后台审计和后台 HTTP API。

允许依赖

• hyapp app 后端服务可以依赖 hyapp.local/api/proto/...。
• hyapp-admin-server 可以依赖 hyapp.local/api/proto/...。
• hyapp-admin-server 的 app 业务访问必须收口到 internal/integration/* 或对应业务模块内的明确 client 接口。

禁止依赖

• hyapp-admin-server 禁止 import hyapp/services/*。
• hyapp-admin-server 禁止 import hyapp/internal/*。
• hyapp-admin-server 禁止 import hyapp/pkg/*。
• 后台专属基础设施放在 server/admin/internal/platform，不要把 app 后端 pkg 当共享库使用。

运行与验证

在 hyapp-server 根目录运行：

make proto
make test
make build

在 hyapp-server/server/admin 单独运行后台：

go run ./cmd/server -config configs/config.yaml