24 KiB
BSM Infra Full
BSM 后端服务 Go workspace，按基础服务、电商交易、资金支付、社交关系四个服务域组织。当前 module/ 下有 18 个带 go.mod 和独立入口的服务模块，加上 all 共 19 个运行时 Go module；scripts/api-docgen 是另一个独立的文档生成工具 module，不属于业务服务。Go 版本以 go.work 为准，当前为 1.26.5。
本文依据各模块的 proto、路由注册、internal/logic、数据模型和 all/internal/service 整理。功能说明描述代码职责；对已发现的空实现单独标注，不代表所有接口已经完成端到端验证。
快速开始
Windows：
go work sync
./scripts/verify-workspace.ps1
Linux/macOS：
go work sync
./scripts/verify-workspace.sh
运行独立服务：
cd module/base/passport
go run ./cmd/main
运行聚合服务：
cd all
go run ./cmd/main --workspace=default
all 默认读取 all/etc/default_.yaml。指定 --workspace=tenant01 时，开发模式读取 all/etc/tenant01_dev.yaml。workspace 仅允许字母、数字、下划线和连字符，最长 64 个字符。
服务域与模块总览
| 服务域 | 目录 | 服务模块 | 主要职责 | 接入 all |
|---|---|---|---|---|
| 基础与平台服务 | module/base |
ads、cloud、cms、feedback、fts、initial、logs、mgt、passport、sender（10 个） | 账号、后台权限、启动配置、内容、文件、通知与运营支撑 | 是 |
| 电商与交易服务 | module/ec |
address、mall、market、order（4 个） | 收货地址、店铺商品、代理供应商、购物车与订单 | 是 |
| 资金与支付服务 | module/finance |
wallet（1 个） | 钱包、资金流水、支付渠道、提现申请 | 是 |
| 社交服务 | module/social |
feed、group、relation（3 个） | 动态内容、群组成员、好友关注与匹配 | 否 |
| 服务聚合与运行入口 | all |
all | 组合 15 个基础、电商、资金服务，共享基础设施与访问入口 | 聚合宿主 |
此外，module/ec/supply 仅有说明文件，module/finance/bill、module/finance/loan 在当前工作区为空目录，均不计入已实现服务。具体状态见下文各服务域说明。
基础与平台服务域：module/base
这一服务域提供可被多类业务复用的公共能力。其中 passport 面向业务用户，mgt 面向后台管理人员；fts 负责文件上传存储接入，cloud 负责用户对文件和个人资料的组织管理。
1. passport：用户账号与身份认证
- 概述与作用：维护业务用户的身份和资料，为需要用户身份的业务接口提供账号基础。
- 主要功能：密码/验证码注册和登录、快捷登录、找回与重置密码；查询账号、修改资料和密码、账号标签及统计；提交身份核验资料、发起 Jumio 核验并接收回调。
- 服务接口：
Account、Login、Register、Forget、Verify，通过 gRPC 与 HTTP gateway 暴露。 - 边界与协作：管理用户账号、资料和核验记录；后台组织权限由
mgt管理，资金账户由wallet管理。验证码相关流程需结合验证码配置和发送能力接入，Jumio 分支依赖外部服务配置。 - 代码入口：接口定义、业务逻辑。
2. mgt：后台组织与权限管理
- 概述与作用：提供管理端的登录、组织结构和角色权限维护能力，支撑运营后台及管理应用。
- 主要功能：后台用户登录、令牌刷新与密码重置；用户、应用、角色、权限、部门管理；用户角色分配、直接权限分配、角色权限分配、部门人员与权限维护；权限树与部门树查询。
- 服务接口：Gin REST，前缀
/rest/mgt，包含/user、/app、/role、/pmn、/dpt等路由组。 - 边界与协作：采用用户、角色、权限及其关联表表达授权关系，管理操作配置 JWT 与管理员检查。这里的后台用户与
passport的业务用户是不同的模型和入口；初始化根用户由配置控制。 - 代码入口：路由、业务逻辑。
3. initial：客户端初始化与基础字典
- 概述与作用：为客户端启动阶段提供配置、版本信息和通用基础数据，减少客户端硬编码。
- 主要功能：服务探测、读取初始化配置；按应用、操作系统和架构查询发布版本；读取国家、行政区划与通用数据字典，并对基础数据进行缓存。
- 服务接口：
Check（Hello、Config、Updates）、Data（Country、Areas、Datas）。 - 边界与协作：管理应用版本、配置和基础字典；用户的具体收货地址属于
address。当前更新判断依据最新发布记录与客户端版本字符串是否相同，不是完整的语义版本升级规则。 - 代码入口：接口定义、业务逻辑。
4. sender：短信与邮件发送
- 概述与作用：集中承接通知和验证码发送，封装模板与渠道调用，供注册、登录、找回密码等场景使用。
- 主要功能：短信发送、验证码生成与 Redis 存储、验证码校验；短信黑名单和发送次数检查；查询邮件模板、替换参数并通过 SMTP 发送。
- 服务接口：
Sms.Send、Sms.Verify、Mail.Send。 - 实现边界：阿里云短信有实际调用；腾讯云客户端虽已配置，但
TencentSender仍为空实现。邮件发送当前只处理qq渠道，不能仅依据配置字段认为所有 SMTP 渠道均已接通。 - 代码入口：短信逻辑、邮件逻辑。
5. fts：文件传输与上传存储
- 概述与作用：接收文件上传，保存文件并返回访问地址，为头像、附件、图片等业务提供存储接入能力。
- 主要功能：上传参数处理、上传记录保存；本地目录存储与 MinIO 对象存储上传；提供上传配置和服务探测接口。
- 服务接口：Gin REST，
GET /rest/fts/ping、GET /rest/fts/config、POST /rest/fts/uploader；上传路由配置 JWT 校验。 - 边界与协作：负责上传通道和存储记录；个人目录树、相册、笔记及分享由
cloud管理。虽名为fts，本项目中它承担文件传输职责，不是全文搜索服务。 - 代码入口：路由、存储实现。
6. cloud：个人云空间与资料管理
- 概述与作用：围绕用户提供个人资料存储与整理能力，构成网盘、相册、笔记和收藏的业务层。
- 主要功能：目录树和文件记录的创建、修改、移动、复制与检索；相册、照片和封面管理；笔记、附件、置顶与浏览计数；书签管理与导入；私人资料分类、检索及加解密；分享记录、分享密码校验；空间容量和资源数量统计。
- 服务接口：
Disk、Album、Note、Bookmark、Private、Share、Space。 - 边界与协作：主要维护用户资源的元数据、归属关系和访问规则。接入时需区分这里的文件/照片业务记录接口与
fts的实际二进制上传接口，不能假设两者已自动组成完整上传链路。 - 代码入口：接口定义、业务逻辑。
7. cms：站点内容管理
- 概述与作用：提供文章、页面及内容分类能力，适用于资讯、帮助中心和内容站点。
- 主要功能：文章列表、详情、关键词检索与维护；页面按标识或键查询及维护；分类和标签管理；文章评论维护以及文章、评论的赞/踩计数。
- 服务接口：
Post、Pages、Category、Tags、Site。 - 实现边界：
Site站点接口已声明，但对应逻辑仍为占位；赞/踩记录去重在模型中仍有 TODO。cms面向站点内容，社交用户动态由feed承担。 - 代码入口：接口定义、业务逻辑。
8. ads：公共广告位内容分发
- 概述与作用：按广告位标识向客户端返回广告素材，支撑首页横幅、活动入口等运营展示。
- 主要功能：
Fetch.ByPos按广告位查询启用的广告，结合缓存返回内容；数据模型包含广告位、素材内容、类型和跳转地址。 - 服务接口：
Fetch.ByPos，通过 gRPC 与 HTTP gateway 暴露。 - 边界与协作：当前公开接口侧重广告读取，不能把广告位/素材模型等同于完整的广告管理 API。店铺内的广告维护由
mall.Ads提供；此模块没有完整的竞价、计费或投放效果分析流程。 - 代码入口：查询逻辑、数据模型。
9. feedback：意见反馈管理
- 概述与作用：收集和维护用户反馈，为客服、运营提供问题记录及处理入口。
- 主要功能：反馈列表和详情查询、新增、修改、删除以及备注处理，对应
List、Get、Add、Modify、Delete、Remark。 - 服务接口：
Method，通过 gRPC 与 HTTP gateway 暴露。 - 边界与协作：以反馈记录维护为核心；不应将其理解为已具备工单派单、客服会话与 SLA 管理的完整客服系统。
- 代码入口：接口定义、业务逻辑。
10. logs：业务操作日志
- 概述与作用：集中保存和查询业务操作记录，帮助追踪操作行为和排查问题。
- 主要功能：创建日志、分页查询日志、统计日志数量；日志记录包含服务名、操作人、IP、数据类型、级别和内容等字段。
- 服务接口：Gin REST，前缀
/rest/logs，包含/ping、/create、/fetch、/total。 - 边界与协作：这是业务日志存储查询服务，不会自动替代进程日志采集、指标监控或链路追踪。当前日志路由注册在匿名组，接入时需明确入口层访问控制。
- 代码入口：路由、日志模型。
电商与交易服务域：module/ec
这一服务域承接从商品展示到下单的业务数据：mall 维护店铺与商品，address 维护收货资料，order 形成交易记录，market 管理代理和供应商资料。支付渠道与资金记录由 wallet 承担。
11. address：收货地址簿
- 概述与作用：集中维护业务用户的收货联系信息，供下单和履约使用。
- 主要功能：地址新增、修改、详情、列表和删除；维护国家、省市区、详细地址、联系人、电话等信息。
- 服务接口：
Library.Create、Modify、Get、Fetch、Delete。 - 边界与协作：保存用户填写的具体地址，行政区划字典由
initial提供；order的提交逻辑会按地址标识读取address_library，并把收货资料写入订单。 - 代码入口：接口定义、业务逻辑。
12. mall：店铺与商品经营
- 概述与作用：承载商城的店铺、商品目录和商家经营资料，是订单商品信息的来源。
- 主要功能：商品列表、详情、规格、图片与评论管理；分类、店铺广告和公告管理；员工密码登录、资料及密码维护；店铺支付和邮件配置。接口还覆盖入驻、授权、运费模板及禁运区域。
- 服务接口：
Store、Staff、Product、Category、Ads、Notice、Freight。 - 边界与协作：维护商品及规格价格、库存等数据；
order下单时读取商品规格并更新库存。商品、店铺展示广告与平台公共广告ads分属不同模型。 - 实现边界：入驻申请、授权、小程序码、按规格查询商品、商品批量操作、运费及禁运区域等逻辑存在占位；员工验证码登录明确返回未实现。接口清单不等于完整商城经营闭环。
- 代码入口：接口定义、业务逻辑。
13. market：代理与供应商管理
- 概述与作用：管理交易体系中的代理商和供应商资料，为渠道合作及供货业务提供主体信息。
- 主要功能：代理商登录、创建、查询、修改、删除、密码设置、待审核列表与审核；供应商资料增删改查。接口另外定义业务概况、会员和订单统计查询。
- 服务接口：
Agency、Supply、Data。 - 实现边界：
Data下的概况、会员列表/详情、订单列表/详情仍为占位。当前可见的供应商业务代码在本模块的Supply中，不在预留目录module/ec/supply中。 - 代码入口：接口定义、业务逻辑。
14. order：购物车与订单生命周期
- 概述与作用：将选购商品转换为订单，并提供用户端与管理端的订单处理入口。
- 主要功能：购物车增删改查；从商品快速创建订单或提交购物车，按店铺拆分订单，记录商品与收货信息、计算金额并处理库存；订单列表、详情、确认与取消；按状态查询优惠券；管理端订单创建、查询、取消、退货相关处理和审核。
- 服务接口：
Cart、Summary、Coupon、Mgt。 - 边界与协作：代码直接读取
mall_product、mall_product_spec、address_library等表，存在跨服务域的数据库耦合，独立运行不意味着数据库已完全隔离。订单负责交易业务状态，支付与钱包资金记录由wallet承担。 - 实现边界：管理端
OrderModify仍为占位；SimulatePay、SimulateShipments、SimulateReceiving是模拟状态操作，不能视为真实支付渠道或物流对接。 - 代码入口：接口定义、订单提交逻辑。
预留：supply（供应商服务）
module/ec/supply 当前只有写明“供应商微服务”的 README，没有 go.mod、服务入口或业务实现，未加入 workspace 和 all。现有供应商资料管理由 market.Supply 提供，不能把该目录算作已落地的独立服务。
资金与支付服务域：module/finance
15. wallet：钱包与支付接入
- 概述与作用：承载用户资金账户和支付请求，为订单支付、充值及提现场景提供资金侧能力。
- 主要功能：钱包查询、支付密码设置、第三方支付账号绑定、交易流水查询；银行卡添加、查询和移除；提现申请；支付方式查询、支付记录查询、按订单/充值生成支付记录及回调处理。
- 服务接口：
Basic、Payment、Wechat、Alipay。渠道接口定义了微信 JSAPI、APP、Native 下单及转账，以及支付宝网页、手机网页、APP 支付及转账。 - 边界与协作：维护钱包、支付单和资金流水，业务订单由
order管理。支付方式配置和第三方渠道配置决定接入路径，声明支付接口不等于支付、回调、订单状态已完成全链路联调。 - 实现边界：支付宝上述支付/转账方法，以及微信 APP、Native 下单和转账仍为 TODO 占位；应逐个核对渠道实现，不能据模块名称认定全部支付渠道可用。
- 代码入口：接口定义、业务逻辑。
预留：bill 与 loan
当前工作区的 module/finance/bill、module/finance/loan 为空目录，没有 go.mod、接口或业务代码，也未加入 workspace 和 all。按目录名可推测分别预留给账单与借贷领域，但仓库没有足够实现或文档来确定其功能边界，不列为现有能力。空目录不会被 Git 单独跟踪，其他检出环境中可能不存在。
社交服务域：module/social
社交域三个服务均有独立 go.mod 与 cmd/main，已加入 go.work，但当前没有接入 all 的服务注册表。职责上，relation 表达用户之间的关系，group 表达群组及成员关系，feed 表达用户发布的动态内容。
16. relation：好友、关注与匹配关系
- 概述与作用：维护人与人之间的社交关系，为通讯录、关注列表和匹配场景提供关系数据。
- 主要功能：好友搜索、列表、详情、备注修改、常用好友标记与删除；好友申请、申请留言、通过和拒绝；好友标签及标签成员；关注、取消关注、关注状态与列表；匹配记录查询、加入和忽略。
- 服务接口：
Friend、Follow、Match。 - 边界与协作：负责关系数据和关系操作，不包含聊天消息传输。
Match的接口主要维护匹配记录，不应据此认定存在完整推荐算法。关注入口实际调用follow.Doing，需与目录中遗留的follow.Do占位函数区分。 - 代码入口：接口定义、业务逻辑。
17. group：群组与成员管理
- 概述与作用：维护社交群组的基础资料、入群申请和成员角色，为群组型业务提供组织关系。
- 主要功能：群组搜索、列表、详情、创建与修改；成员列表、申请加入、申请列表与审核；设置管理员、踢出成员及退出群组。
- 服务接口：
Basic、Member。 - 实现边界：
Basic.Disband解散群组仍为占位。模块负责群组与成员数据，不包含即时通讯连接、消息推送或聊天历史服务。 - 代码入口：接口定义、业务逻辑。
18. feed：社交动态与内容互动
- 概述与作用：承载用户发布的动态、标签和互动信息，作为社区内容流的业务基础。
- 主要功能：动态查询、发布、修改与删除；评论新增与删除、互动计数；标签列表与创建。接口还定义推荐、好友、关注、热门时间线，以及标签下动态、评论列表和设置信息。
- 服务接口：
Post、Tag、Timeline、Setting。 - 实现边界：四类
Timeline方法、Tag.PostList、Post.CommentList、Setting.Info和Setting.Rights仍为占位。因此当前不能认定已实现推荐排序、好友/关注动态分发或完整的社区内容流。 - 代码入口：接口定义、业务逻辑。
聚合运行域：all
all 是部署和接入宿主：在单个进程中注册 15 个基础、电商、资金服务，注入共享数据库、Redis、etcd 和内存缓存，统一管理监听端口与关闭流程。
| 访问方式 | 作用 |
|---|---|
| gRPC | 注册各模块 protobuf 服务，使用 Server.GRPC 独立监听地址 |
| HTTP gateway | 在 Server.HTTP 地址提供 protobuf 服务的 HTTP 访问 |
| 动态 RPC | /rpc/{package}/{service}/{method} 将 JSON 转换为 protobuf，通过本机 gRPC 调用 unary 方法 |
| 原生 REST | /rest/{module}/... 承载 fts、mgt、logs 等 Gin 路由 |
Services 配置决定启用哪些服务；非空的 BSM_SERVICES 环境变量优先覆盖，例如 passport,order,wallet；值为 all 时选择注册表中的全部服务。此处的“全部”不包括三个社交服务与预留目录。
模块通过 service.Expose 注册并接收依赖；聚合启动时复用共享对象，独立入口则初始化自身资源。注册入口见 all/internal/service/service.go，监听与请求分发见 all/internal/server。启用模块只代表注册其访问入口，不会自动补齐其外部渠道、数据表或跨域数据依赖。
模块协作与代码导航
| 业务场景 | 涉及模块 | 职责分工 |
|---|---|---|
| 客户端启动与登录 | initial、passport、sender | 初始化配置和字典、用户身份、验证码与通知发送 |
| 平台运营后台 | mgt、cms、ads、feedback、logs | 管理人员授权、内容维护、广告分发、反馈处理与操作记录 |
| 个人资料与附件 | passport、cloud、fts | 用户身份、资源组织与分享、文件实际上传与存储 |
| 商城交易 | mall、address、order、wallet | 商品与库存、收货资料、交易订单、资金与支付 |
| 渠道与供货资料 | market、mall、order | 代理/供应商主体信息、商品供货关联、交易记录 |
| 社区业务 | passport、relation、group、feed | 用户身份、人际关系、群组成员、动态内容 |
上表表达业务职责分工，不表示每一组都已有自动串联的调用链。现有实现同时使用共享 SDK、数据库访问和外部渠道调用，尤其 order 存在直接访问其他域数据表的情况。
典型服务目录如下；fts、mgt、logs 以 REST 为主，没有完整的 proto/pb 结构。
| 目录或文件 | 作用 |
|---|---|
go.mod / go.sum |
模块路径、依赖版本与校验信息 |
cmd/main |
独立服务进程入口、配置加载和生命周期 |
cmd/cli |
部分模块提供的命令行辅助入口 |
proto / pb |
protobuf 接口定义与生成代码 |
internal/server / internal/routers |
gRPC 服务实现与注册、Gin REST 路由 |
internal/logic |
业务规则、校验、数据操作与渠道调用 |
internal/models |
数据表模型及查询辅助逻辑 |
internal/impl |
数据库、Redis、etcd、缓存与渠道客户端等资源 |
internal/config / etc |
配置结构和环境配置样例 |
service |
已接入聚合宿主的模块对外暴露的注册与依赖注入接口 |
all |
聚合服务配置、资源初始化和统一入口 |
scripts |
workspace 校验、构建、protobuf 和 API 文档生成工具 |
wiki |
架构、接入、运维与 API 说明 |
共享能力依赖 git.apinb.com/bsm-sdk/core。当前 go.work 将其替换为相对路径 ../../bsm-sdk/core，准备开发环境时需保证该 SDK 路径存在。模块数量、接口名称和实现状态应以代码为准，历史模块 README 或 Wiki 中的数量与功能描述可能尚未同步。
配置安全
仓库内 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 | 更新全部依赖，执行后必须审阅差异 |
| scripts/api-docgen | 从 protobuf descriptor 重新生成客户端 API 文档 |
文档
开发约定
- 新模块必须加入 go.work，不得提交本机绝对路径 replace。
- 模块保留独立 cmd/main，通过 service.Expose 接入 all。
- 默认测试不得访问网络或真实基础设施；集成测试使用 integration build tag。
- protobuf 全限定名称必须跨模块唯一。
- 提交前运行 workspace 验证脚本和 git diff --check。