update go mod

README.md

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