audit and harden workspace

README.md

@@ -1,134 +1,70 @@
 # BSM Infra Full
 
-BSM 后端服务的 Go workspace，包含基础能力、电商、财务、社交服务，以及可选择组件运行的单体入口。所有模块统一使用 **Go 1.26.5**。
+BSM 后端服务 Go workspace，包含 19 个独立业务模块和一个统一端口运行的 all 聚合模块。Go 版本为 1.26.5。
 
-## 目录结构
+## 快速开始
 
-| 目录 | 服务 |
-| --- | --- |
-| `module/base` | ads、cloud、cms、feedback、fts、initial、logs、mgt、passport、sender |
-| `module/ec` | address、delivery、mall、market、order |
-| `module/finance` | wallet |
-| `module/social` | feed、group、relation |
-| `cmd` | 聚合上述服务的单体启动器 |
-| `go.work` | 19 个 Go 模块的 workspace 定义 |
+Windows：
 
-各服务的接口、配置和部署细节见对应 `module/**/README.md`。
-
-## 环境要求
-
-- Go 1.26.5
-- Git
-- 按所运行服务准备 PostgreSQL、Redis、etcd、MQ 或对象存储等外部依赖
-- 重新生成 protobuf 时，需要在系统 `PATH` 中安装 `protoc`、`protoc-gen-go`、`protoc-gen-go-grpc`、`protoc-gen-grpc-gateway` 和 `protoc-gen-slc`
-
-确认工具链：
-
-```bash
-go version
-go work sync
-```
-
-统一重新生成 protobuf：
-
-```bash
-bash scripts/generate-protobuf.sh
-```
-
-脚本读取每个服务的 `proto/` 目录，将模块本地的 `const.proto` 与业务 proto 一起生成 protobuf、gRPC 和 grpc-gateway 代码；默认还会运行 `protoc-gen-slc`。如仅需刷新 protobuf 代码，可设置 `GENERATE_SLC=0`。
-
-更新所有 workspace 模块的依赖：
-
-```bash
-bash scripts/update-all.sh
-```
-
-脚本会为每个模块执行 `go get -u ./...` 和 `go mod tidy`，最后运行 `go work sync`；它不会自动提交或推送 Git 变更。
-
-编译全部 19 个独立服务：
-
-```bash
-bash scripts/build-all-linux.sh
-```
-
-脚本固定交叉编译 Linux x86-64（`GOOS=linux`、`GOARCH=amd64`、`CGO_ENABLED=0`），产物写入 `.builds/<领域>-<模块>`。全部模块编译成功后，各模块的 `etc/*_prod.yaml` 会复制到 `.builds/etc/`。`.builds/` 已加入 `.gitignore`，聚合入口 `cmd` 不包含在批量构建中。
-
-## 配置
-
-每个服务的 `etc/` 目录包含 `*_dev.yaml`、`*_test.yaml` 和 `*_prod.yaml` 示例。提交到仓库的配置只能包含占位值；请在本地副本或部署系统的密钥管理中注入真实凭据，不要提交数据库密码、访问密钥、令牌或私钥。
-
-本仓库审计时已移除过明文凭据。如果这些凭据曾在真实环境使用，应立即在数据库、SMTP、对象存储及相关服务侧轮换。
-
-## 运行
-
-运行单个服务时，进入其模块目录。例如：
-
-```bash
-cd module/base/passport
-go run ./cmd/main
-```
-
-运行聚合入口：
-
-```bash
-cd all
-go run ./cmd/main
-```
-
-`all/etc/all_dev.yaml` 统一配置监听端口、数据库、Redis 以及 `Services.<name>` 服务专属配置。聚合入口在同一端口通过 h2c 同时承载 gRPC、HTTP Gateway 和 Gin 路由。可以使用 `BSM_SERVICES` 临时覆盖启用的服务：
-
-```bash
-# Linux/macOS
-BSM_SERVICES=passport,order,wallet go run ./main
-
-# PowerShell
-$env:BSM_SERVICES = "passport,order,wallet"
-go run ./main
-```
-
-可选组件为：`ads`、`cloud`、`cms`、`feedback`、`fts`、`initial`、`logs`、`mgt`、`passport`、`sender`、`address`、`mall`、`market`、`order`、`wallet`。社交服务目前作为独立模块运行，尚未接入聚合入口。
-
-## 测试
-
-根目录不是 Go module，因此不要在根目录执行 `go test ./...`。应逐 workspace 模块测试。
-
-PowerShell：
-
-```powershell
-go list -m -f '{{.Dir}}' | ForEach-Object {
-    Push-Location $_
-    try { go test ./... } finally { Pop-Location }
-}
-```
+    go work sync
+    ./scripts/verify-workspace.ps1
 
 Linux/macOS：
 
-```bash
-go list -m -f '{{.Dir}}' | while IFS= read -r module; do
-  (cd "$module" && go test ./...)
-done
-```
+    go work sync
+    ./scripts/verify-workspace.sh
 
-依赖运行中服务或真实基础设施的测试带有 `integration` build tag，默认测试不会访问外部系统。准备好测试环境和对应的 `BSM_*_TOKEN` 等变量后，在目标模块显式运行：
+运行独立服务：
 
-```bash
-go test -tags=integration ./...
-```
+    cd module/base/passport
+    go run ./cmd/main
 
-建议提交前执行：
+运行聚合服务：
 
-```bash
-gofmt -w .
-go vet ./...
-go test ./...
-```
+    cd all
+    go run ./cmd/main --workspace=default
 
-最后两条命令需在每个模块目录执行，可使用上面的 workspace 循环。
+all 默认读取 all/etc/default_<runtime>.yaml。指定 --workspace=tenant01 时，开发模式读取 all/etc/tenant01_dev.yaml。workspace 仅允许字母、数字、下划线和连字符，最长 64 个字符。
+
+## 模块
+
+| 领域 | 模块 |
+| --- | --- |
+| module/base | ads、cloud、cms、feedback、fts、initial、logs、mgt、passport、sender |
+| module/ec | address、mall、market、order |
+| module/finance | wallet |
+| module/social | feed、group、relation |
+| all | 聚合 15 个 base/ec/finance 服务，统一提供 gRPC、grpc-gateway 和 Gin HTTP |
+
+Services 配置决定 all 启用哪些服务；BSM_SERVICES 环境变量可临时覆盖，例如 passport,order,wallet。
+
+## 配置安全
+
+仓库内 YAML 仅为结构示例，凭据使用 CHANGE_ME。部署时必须通过密钥管理或发布系统注入真实值，禁止提交密码、令牌、私钥和云密钥。
+
+生产环境至少应替换全部 CHANGE_ME，关闭公网数据库/Redis/etcd，评估关闭 gRPC reflection，保持 mgt.InitRootUser=false，并在入口层启用 TLS 和访问控制。
+
+## 常用脚本
+
+| 脚本 | 用途 |
+| --- | --- |
+| scripts/verify-workspace.ps1 | Windows：gofmt、go vet、go test |
+| scripts/verify-workspace.sh | Linux/macOS：gofmt、go vet、go test |
+| scripts/build-all-linux.sh | 构建 Linux amd64 独立服务 |
+| scripts/generate-protobuf.sh | 重新生成 protobuf |
+| scripts/update-all.sh | 更新全部依赖，执行后必须审阅差异 |
+
+## 文档
+
+- [Wiki 索引](wiki/README.md)
+- [系统架构](wiki/architecture.md)
+- [开发与运维](wiki/operations.md)
+- [审计报告](wiki/audit-2026-08-10.md)
 
 ## 开发约定
 
-- Go 版本声明、Docker 构建镜像和 CI 构建镜像统一为 `1.26.5`。
-- 新模块必须加入 `go.work`，并确保本地 `replace` 使用当前 `module/...` 目录结构。
-- protobuf 描述符必须包含服务命名空间，避免多个服务聚合到同一进程时发生全局文件名冲突。
-- 外部依赖测试使用 `//go:build integration`，不得让默认测试依赖网络或已启动服务。
-- 配置和测试数据中不得包含真实凭据或个人信息。
+- 新模块必须加入 go.work，不得提交本机绝对路径 replace。
+- 模块保留独立 cmd/main，通过 service.Expose 接入 all。
+- 默认测试不得访问网络或真实基础设施；集成测试使用 integration build tag。
+- protobuf 全限定名称必须跨模块唯一。
+- 提交前运行 workspace 验证脚本和 git diff --check。