Basic Integration Guide

指导开发者如何接入basic基础服务，包括依赖引入、gRPC调用、REST API使用、配置说明。涵盖国际化(i18n)、项目管理、租户管理、字典管理、存储、认证等核心能力

Basic 基础服务接入指南

1. 服务概述

Basic 是畅远飞轮平台的基础服务，提供以下核心能力：

• 国际化 (i18n)：词条空间管理、词条翻译、多语言发布、导入导出（JSON/CSV/Excel）
• 项目管理：项目与应用实体管理、项目-应用关联与语言配置
• 租户管理：多租户创建、配置、域名绑定
• 字典管理：字典项目/模块/分组/字典项的 CRUD、版本发布与回滚、草稿对比、资产导入导出
• 存储服务：虚拟存储操作（OSS / CopyParty 适配）
• 内部认证：OIDC 认证、JWT 验证

接口协议：gRPC + REST API

2. 快速接入

2.1 Maven 依赖

轻量客户端（仅接口定义和 DTO）：

<dependency>
    <groupId>com.ginlong</groupId>
    <artifactId>basic-client</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

gRPC 接口包（含 Protobuf Stub）：

<dependency>
    <groupId>com.ginlong</groupId>
    <artifactId>basic-grpc-interface</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

2.2 gRPC 客户端配置

在调用方的 application.yaml 中配置 gRPC 通道：

grpc:
  client:
    basic-grpc-server:
      address: 'dns:///basic-service:9090'
      negotiationType: plaintext
      enableKeepAlive: true
      keepAliveTime: 30s
      keepAliveTimeout: 5s

注入 gRPC Stub 示例：

@GrpcClient("basic-grpc-server")
private I18nServiceGrpc.I18nServiceBlockingStub i18nStub;

@GrpcClient("basic-grpc-server")
private ProjectServiceGrpc.ProjectServiceBlockingStub projectStub;

@GrpcClient("basic-grpc-server")
private TenantServiceGrpc.TenantServiceBlockingStub tenantStub;

2.3 认证与租户上下文

REST API 调用时需传递以下 Header：

Header	说明	必填
X-TENANT	租户编码	是
X-UID	用户ID	视接口而定
Authorization	Bearer Token (OIDC)	认证接口必填

gRPC 调用时通过 Metadata 传递：

Metadata metadata = new Metadata();
metadata.put(Metadata.Key.of("X-TENANT", Metadata.ASCII_STRING_MARSHALLER), tenantCode);
metadata.put(Metadata.Key.of("X-UID", Metadata.ASCII_STRING_MARSHALLER), userId);

3. gRPC 服务接口

3.1 I18nService

包名： com.ginlong.basic.grpc.i18n

RPC 方法	请求类型	响应类型	说明
findProject	FindProjectReqPB	FindProjectRespPB	查询项目应用信息
searchTermSpaces	SearchTermSpacesReqPB	SearchTermSpacesRespPB	搜索词条空间
findTermSpace	FindTermSpaceReqPB	TermSpaceRespPB	查询词条空间详情
createTermSpace	CreateTermSpaceReqPB	CreateTermSpaceRespPB	创建词条空间
deleteTermSpace	DeleteTermSpaceReqPB	DeleteTermSpaceRespPB	删除词条空间
publishTermSpace	PublishTermSpaceReqPB	PublishTermSpaceRespPB	发布词条空间
importTermSpace	ImportTermSpaceReqPB	ImportTermSpaceRespPB	导入词条空间
exportTermSpace	ExportTermSpaceReqPB	ExportTermSpaceRespPB	导出词条空间
searchTerms	SearchTermsReqPB	SearchTermsRespPB	搜索词条
findTerm	FindTermReqPB	TermRespPB	查询词条详情
saveTerm	SaveTermReqPB	SaveTermRespPB	保存词条
deleteTerm	DeleteTermReqPB	DeleteTermRespPB	删除词条

关键 Message 定义：

// 查询项目应用
message FindProjectReqPB {
  string projectCode = 1;  // 项目编码（必填）
  string appCode = 2;      // 应用编码（必填）
}

message FindProjectRespPB {
  string projectCode = 1;
  string appCode = 12;
  string name = 2;
  string description = 3;
  string defaultLangCode = 4;           // 默认语言编码
  repeated string supportLangCodes = 5; // 支持的语言编码列表
  google.protobuf.Struct extraProps = 6;
  google.protobuf.Struct langCodeNameMap = 7; // 语言编码-名称映射
}

// 搜索词条
message SearchTermsReqPB {
  string projectCode = 1;
  string appCode = 12;
  string spaceCode = 2;     // 词条空间编码
  string codeLike = 3;      // 编码模糊匹配
  string codeEqual = 8;     // 编码精确匹配
  string contentLike = 4;   // 内容模糊匹配
  int32 size = 5;           // 每页大小
  int32 pageInx = 6;        // 页码
  repeated string codeLikes = 7; // 批量编码模糊匹配
}

// 词条响应
message TermRespPB {
  string projectCode = 1;
  string appCode = 12;
  string spaceCode = 2;
  string code = 3;
  google.protobuf.Struct content = 4;     // 多语言内容 {langCode: text}
  int64 gmtPublished = 5;                 // 发布时间戳
  int64 gmtSaved = 6;                     // 保存时间戳
  google.protobuf.Struct extraProps = 7;
}

// 导入方法枚举
enum ImportMethodEnumPb {
  UNKNOWN_IMP_METHOD = 0;
  RESET_AND_APPEND = 1;          // 清空后追加
  APPEND_AND_OVERWRITE = 2;      // 追加并覆盖已有
  APPEND_AND_NOT_OVERWRITE = 3;  // 追加但不覆盖已有
}

// 导入导出格式枚举
enum ImportExportTypeEnumPB {
  UNKNOWN_IMP_EXP_TYPE = 0;
  JSON = 1;
  CVS = 2;
  XLS = 3;
}

调用示例：

// 搜索词条
SearchTermsReqPB req = SearchTermsReqPB.newBuilder()
    .setProjectCode("my-project")
    .setAppCode("web")
    .setSpaceCode("common")
    .setSize(20)
    .setPageInx(0)
    .build();
SearchTermsRespPB resp = i18nStub.searchTerms(req);

<!-- PLACEHOLDER_SECTION_3_2 -->

3.2 ProjectService

包名： com.ginlong.basic.grpc.project

RPC 方法	请求类型	响应类型	说明
findProject	FindProjectReqPB	ProjectRespPB	查询项目详情
searchProjects	SearchProjectsReqPB	SearchProjectsRespPB	搜索项目列表
findProjectApp	FindProjectAppReqPB	ProjectAppRespPB	查询项目应用详情
searchProjectApps	SearchProjectAppsReqPB	SearchProjectAppsRespPB	搜索项目应用列表

关键 Message 定义：

message FindProjectReqPB {
  string projectCode = 1;  // 项目编码（必填）
}

message ProjectRespPB {
  string code = 1;
  string name = 2;
  string note = 3;
  google.protobuf.Struct publicProp = 4;    // 公开属性
  google.protobuf.Struct internalProp = 5;  // 内部属性
}

message FindProjectAppReqPB {
  string projectCode = 1;  // 项目编码（必填）
  string code = 2;         // 应用编码（必填）
}

message ProjectAppRespPB {
  string code = 1;
  string projectCode = 2;
  string name = 3;
  string note = 4;
  string endType = 5;            // 端类型
  repeated string endTag = 6;    // 端标签
  bool isDefault = 7;            // 是否默认应用
  bool isVirtual = 8;            // 是否虚拟应用
  google.protobuf.Struct publicProp = 9;
  google.protobuf.Struct internalProp = 10;
}

调用示例：

// 查询项目
FindProjectReqPB req = FindProjectReqPB.newBuilder()
    .setProjectCode("my-project")
    .build();
ProjectRespPB resp = projectStub.findProject(req);

3.3 TenantService

包名： com.ginlong.basic.grpc.tenant

RPC 方法	请求类型	响应类型	说明
findTenant	FindTenantReqPB	TenantRespPB	按编码查询租户
findTenantByHost	FindTenantByHostReqPB	TenantRespPB	按域名查询租户

关键 Message 定义：

message FindTenantReqPB {
  string tenantCode = 1;  // 租户编码（必填）
}

message FindTenantByHostReqPB {
  string host = 1;  // 域名（必填）
}

message TenantRespPB {
  string code = 1;
  string name = 2;
  repeated string hosts = 3;          // 绑定域名列表
  string countryRegionCode = 4;       // 国家/地区编码
  int32 status = 5;                   // 状态
  google.protobuf.Struct contactInfo = 6; // 联系信息
  repeated TenantConfRespPB confs = 7;    // 租户配置列表
}

message TenantConfRespPB {
  string tenantCode = 1;
  string projectCode = 2;
  string bizType = 3;      // 业务类型
  string confKey = 4;      // 配置键
  string confValue = 5;    // 配置值
  int32 isPrivate = 6;     // 是否私有
  int32 status = 7;
  string note = 8;
}

调用示例：

// 按域名查询租户
FindTenantByHostReqPB req = FindTenantByHostReqPB.newBuilder()
    .setHost("app.example.com")
    .build();
TenantRespPB resp = tenantStub.findTenantByHost(req);

<!-- PLACEHOLDER_SECTION_4 -->

4. REST API 接口

4.1 国际化管理 (i18n)

基础路径前缀： internal/i18nmng-api/

语言管理

方法	路径	说明
GET	lang	查看语言列表
POST	lang	创建语言
PUT	lang/{langCode}	更新语言
DELETE	lang/{langCode}	删除语言

项目应用管理

方法	路径	说明
GET	project/app	项目应用列表
POST	project/app	创建项目应用
GET	project/{projectCode}/app/{appCode}	获取项目应用详情
PUT	project/{projectCode}/app/{appCode}	更新项目应用
DELETE	project/{projectCode}/app/{appCode}	删除项目应用

词条空间管理

基础路径： internal/i18nmng-api/project/{projectCode}/app/{appCode}/termspace

方法	路径	说明
GET	page	词条空间分页搜索
GET	{spaceCode}	查询词条空间详情
POST	``	创建词条空间
POST	copy	拷贝词条空间
PUT	{code}	更新词条空间
DELETE	{spaceCode}	删除词条空间
POST	{spaceCode}/action/publish	发布词条空间
GET	{spaceCode}/action/publish	查看发布历史
DELETE	{spaceCode}/action/publish	删除发布历史
GET	{spaceCode}/version/diff	发布差异对比
PUT	{spaceCode}/reset	重置词条空间
PUT	{spaceCode}/import	导入词条（multipart）
GET	{spaceCode}/export/json	导出词条（JSON）
GET	{spaceCode}/export	导出词条（文件下载）

词条管理

基础路径： internal/i18nmng-api/project/{projectCode}/app/{appCode}/termspace/{spaceCode}/term

方法	路径	说明
GET	``	词条分页搜索
POST	``	创建词条
PUT	{termCode}	更新词条
DELETE	{termCode}	删除词条

生产使用接口（无需 internal 前缀）

基础路径： i18nmng-api/project/termspace

方法	路径	说明
GET	package/export/file	对象存储词条文件导出（项目打包用）
GET	project/{projectCode}/app/{appCode}/lang	列出项目相关语言
GET	project/{projectCode}/app/{appCode}/translation/version	词条空间最新版本和语言信息

curl 示例：

# 搜索词条空间
curl -X GET 'http://basic-service/internal/i18nmng-api/project/my-project/app/web/termspace/page?size=20&pageInx=0' \
  -H 'X-TENANT: tenant001'

# 创建词条
curl -X POST 'http://basic-service/internal/i18nmng-api/project/my-project/app/web/termspace/common/term' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT: tenant001' \
  -d '{"code":"btn.submit","content":{"zh_CN":"提交","en_US":"Submit"}}'

# 获取翻译版本信息（生产使用）
curl -X GET 'http://basic-service/i18nmng-api/project/termspace/project/my-project/app/web/translation/version' \
  -H 'X-TENANT: tenant001'

<!-- PLACEHOLDER_SECTION_4_2 -->

4.2 项目管理

基础路径前缀： project-api/project

方法	路径	说明
GET	``	搜索项目列表
GET	app	搜索项目应用列表

curl 示例：

curl -X GET 'http://basic-service/project-api/project' \
  -H 'X-TENANT: tenant001'

4.3 租户管理

基础路径前缀： internal/tenant-api/

租户 CRUD

方法	路径	说明
POST	tenant	创建租户
GET	tenant/page	分页查询租户列表
GET	tenant/{code}	按编码查询租户详情
PUT	tenant/{id}	更新租户
DELETE	tenant/{id}	删除租户（级联删除配置）

租户配置

方法	路径	说明
POST	tenant-conf	创建租户配置
GET	tenant-conf/page	分页查询租户配置
PUT	tenant-conf/{id}	更新租户配置
DELETE	tenant-conf/{id}	删除租户配置

curl 示例：

# 按编码查询租户
curl -X GET 'http://basic-service/internal/tenant-api/tenant/tenant001' \
  -H 'X-TENANT: tenant001'

# 创建租户配置
curl -X POST 'http://basic-service/internal/tenant-api/tenant-conf' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT: tenant001' \
  -d '{"tenantCode":"tenant001","projectCode":"proj1","bizType":"config","confKey":"theme","confValue":"dark"}'

4.4 字典管理

字典项目管理

基础路径： dictionary-api/project

方法	路径	说明
POST	``	创建字典项目
GET	/page	分页查询字典项目列表
DELETE	/{id}	删除字典项目

字典模块管理

基础路径： internal/dictionary-api/module

方法	路径	说明
POST	``	创建字典模块
GET	/page	分页查询字典模块列表
PUT	/{id}	更新字典模块
DELETE	/{id}	删除字典模块

字典分组管理

基础路径： internal/dictionary-api/group

方法	路径	说明
POST	``	创建字典分组
GET	/page	分页查询字典分组列表
GET	/{groupCode}	按编码查询分组详情（含字典项）
PUT	/{id}	更新字典分组
DELETE	/{id}	删除字典分组（级联删除字典项）
POST	/{groupCode}/module	关联分组到模块
DELETE	/{groupCode}/module/{moduleCode}	解除分组与模块关联
GET	/by-module/{moduleCode}	按模块查询关联分组列表

字典项管理

基础路径： internal/dictionary-api/item

方法	路径	说明
POST	``	创建字典项
POST	/batch	批量创建字典项
PUT	/{id}	更新字典项
PUT	/batch	批量更新字典项
DELETE	/{id}	删除字典项（递归删除子节点）
PUT	/{id}/enable	启用字典项
PUT	/{id}/disable	禁用字典项

字典统一查询（生产使用）

基础路径： dictionary-api/query

方法	路径	说明
GET	``	统一查询接口，读取已发布版本数据，支持 projectCode@versionNumber 格式增量更新

字典发布版本管理

基础路径： internal/dictionary-api/publish

方法	路径	说明
GET	/project	查询已发布过的项目列表
POST	/{projectCode}	发布项目字典
POST	/{projectCode}/rollback/{versionNumber}	回滚到指定版本
GET	/{projectCode}/version	分页查询版本历史
GET	/{projectCode}/version/{versionNumber}	查询版本详情

字典草稿对比

基础路径： internal/dictionary-api/diff

方法	路径	说明
GET	/{projectCode}	查询草稿与最新发布版本的差异

字典资产管理

基础路径： internal/dictionary-api/asset

方法	路径	说明
GET	/{projectCode}/export	导出字典资产
POST	/{projectCode}/import	导入字典资产
DELETE	/{projectCode}/draft	清空草稿资产

curl 示例：

# 统一查询字典（生产使用）
curl -X GET 'http://basic-service/dictionary-api/query?projectCodes=proj1&groupCodes=gender,status' \
  -H 'X-TENANT: tenant001'

# 发布字典
curl -X POST 'http://basic-service/internal/dictionary-api/publish/proj1' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT: tenant001' \
  -d '{"remark":"v2 release"}'

# 查询草稿差异
curl -X GET 'http://basic-service/internal/dictionary-api/diff/proj1' \
  -H 'X-TENANT: tenant001'

4.5 内部认证

基础路径前缀： internal/auth-api/

方法	路径	说明
GET	user/info	获取用户信息（需 Authorization Header）
GET	route/info	获取路由信息

curl 示例：

curl -X GET 'http://basic-service/internal/auth-api/user/info' \
  -H 'Authorization: Bearer <token>'

<!-- PLACEHOLDER_SECTION_5 -->

5. 客户端 SDK 接口

basic-client 模块提供以下 ClientService 接口，供域内服务直接依赖调用。

5.1 I18n 域

I18nTermClientService — 词条管理

• searchTerms(SearchTermsQuery) → SearchTermsDto
• findTerm(FindTermQuery) → TermDto
• saveTerm(SaveTermCmd) → SaveTermDto
• deleteTerm(DeleteTermCmd) → DeleteTermDto

I18nLangClientService — 语言管理

• listLangs(ListLangQuery) → ListLangDto
• saveLang(SaveLangCmd) → SaveLangDto
• deleteLang(DeleteLangCmd) → DeleteLangDto

I18nTermSpaceClientService — 词条空间管理

• searchTermSpaces(SearchTermSpacesQuery) → SearchTermSpacesDto
• findTermSpace(FindTermSpaceQuery) → TermSpaceDto
• saveTermSpace(SaveTermSpaceCmd) → SaveTermSpaceDto
• copyTermSpace(CopyTermSpaceCmd) → CopyTermSpaceDto
• deleteTermSpace(DeleteTermSpaceCmd) → DeleteTermSpaceDto
• publishTermSpace(PublishTermSpaceCmd) → PublishTermSpaceDto
• importTerms(ImportTermsCmd) → ImportTermsDto
• exportTerms(ExportTermsQuery) → ExportTermsDto
• exportFile(ExportFileCmd) → ExportFileDto
• translationVersion(TranslationVersionQuery) → TranslationVersionDto
• 更多方法见源码

I18nProjectAppClientService — 项目应用管理

• findProjectApp(FindProjectAppQuery) → ProjectAppDto
• listProjectApps(ListProjectAppsQuery) → ListProjectAppsDto
• saveProjectApp(SaveProjectAppCmd) → SaveProjectAppDto
• deleteProjectApp(DeleteProjectAppCmd) → DeleteProjectsAppDto
• listProjectAppSupportLang(ListProjectAppSupportLang) → List<SimpleLangDto>

5.2 Project 域

ProjectClientService — 项目管理

• search(ProjectSearchDto) → List<ProjectDto>

ProjectAppClientService — 项目应用管理

• search(ProjectAppSearchDto) → List<ProjectAppDto>
• find(ProjectAppFindDto) → ProjectAppDto

5.3 Tenant 域

TenantClientService — 租户查询

• findByCode(String tenantCode) → TenantDto
• findByHost(String host) → TenantDto

TenantManageService — 租户管理

• create(TenantDto) → TenantDto
• update(Long id, ...) → TenantDto
• delete(Long id) → void
• findByCode(String code) → TenantDto
• search(String name, int page, int size) → SearchTenantsDto

TenantConfManageService — 租户配置管理

• create(TenantConfDto) → TenantConfDto
• update(Long id, TenantConfDto) → TenantConfDto
• delete(Long id) → void
• search(String tenantCode, String projectCode, String bizType, int page, int size) → SearchTenantConfsDto

5.4 Dictionary 域

DictionaryProjectClientService — 字典项目

• create(String projectCode) → DictionaryProjectDto
• delete(Long id) → void
• page(int page, int size) → SearchDictionaryProjectsDto

DictionaryModuleClientService — 字典模块

• create(DictionaryModuleDto) → DictionaryModuleDto
• update(Long id, String moduleName, String description) → DictionaryModuleDto
• delete(Long id) → void
• search(String projectCode, String moduleName, int page, int size) → SearchDictionaryModulesDto

DictionaryGroupClientService — 字典分组

• create(DictionaryGroupDto) → DictionaryGroupDto
• update(Long id, String groupName, String type, String description) → DictionaryGroupDto
• delete(Long id) → void
• findByGroupCode(String projectCode, String groupCode) → DictionaryGroupDto
• search(String projectCode, String groupName, int page, int size) → SearchDictionaryGroupsDto
• bindModule(String groupCode, String moduleCode) → void
• unbindModule(String groupCode, String moduleCode) → void

DictionaryItemClientService — 字典项

• create(DictionaryItemDto) → DictionaryItemDto
• batchCreate(List<DictionaryItemDto>) → List<DictionaryItemDto>
• update(Long id, DictionaryItemDto) → DictionaryItemDto
• batchUpdate(List<DictionaryItemDto>) → List<DictionaryItemDto>
• delete(Long id) → void
• setEnabled(Long id, boolean enabled) → void

DictionaryQueryClientService — 字典查询

• query(List<String> projectCodes, List<String> moduleCodes, List<String> groupCodes) → Map<String, DictionaryGroupDataDto>
• queryPublished(...) → Map<String, ProjectQueryDataDto>

DictionaryPublishClientService — 字典发布

• publish(String projectCode, String remark) → DictionaryPublishVersionDto
• rollback(String projectCode, int targetVersionNumber) → DictionaryPublishVersionDto
• listVersions(String projectCode, int page, int size) → SearchPublishVersionsDto
• getVersionDetail(String projectCode, int versionNumber) → DictionaryPublishVersionDto
• getActiveVersionNumber(String projectCode) → Integer
• listPublishedProjects() → List<ProjectPublishSummaryDto>

DictionaryDiffClientService — 字典对比

• diff(String projectCode) → DiffResult

DictionaryAssetClientService — 字典资产

• export(String projectCode, Integer versionNumber) → ExportPackage
• importAsset(String projectCode, ExportPackage, boolean strictParent) → ImportResultDto
• clearDraft(String projectCode) → ClearResultDto

5.5 Storage 域

PhysicalStorageOperationClientService — 物理存储操作

• upload(String bucketName, String key, Map<String, String> metadata, InputStream inputStream) → void
• deleteBatch(String bucketName, String keyPrefix) → void
• exist(String bucketName, List<String> keys) → Map<String, Boolean>

6. 配置参考

6.1 必填配置

环境变量	说明	示例
K8S_ALL_REDIS_HOST	Redis 主机	redis.svc
K8S_ALL_REDIS_PORT	Redis 端口	6379
K8S_ALL_REDIS_PASSWORD	Redis 密码	-
K8S_ALL_REDIS_DB	Redis 数据库	0
K8S_ALL_MYSQL_HOST	MySQL 主机	mysql.svc
K8S_ALL_MYSQL_PORT	MySQL 端口	3306
K8S_BASIC_MYSQL_USERNAME	MySQL 用户名	basic
K8S_BASIC_MYSQL_PASSWORD	MySQL 密码	-

6.2 可选配置

环境变量	说明	默认值
K8S_BASIC_MYSQL_DATABASE	MySQL 数据库名	basic
K8S_ALL_MYSQL_POOL_SIZE_IDLE	连接池最小空闲	1
K8S_ALL_MYSQL_POOL_SIZE_MAX	连接池最大连接	10
K8S_ALL_MID_COPYPARTY_ENABLED	CopyParty 存储开关	true

6.3 存储配置（按需）

环境变量	说明
K8S_ALL_STORAGE_OSS_ENABLED	OSS 存储开关
K8S_ALL_STORAGE_OSS_ENDPOINT	OSS 端点
K8S_ALL_STORAGE_OSS_KEY	OSS Access Key
K8S_ALL_STORAGE_OSS_SECRET	OSS Access Secret
K8S_ALL_MID_COPYPARTY_ADDR	CopyParty 地址
K8S_ALL_MID_COPYPARTY_PREFIX	CopyParty 路径前缀
K8S_ALL_MID_COPYPARTY_USER	CopyParty 用户名
K8S_ALL_MID_COPYPARTY_PASS	CopyParty 密码

6.4 i18n 存储配置

环境变量	说明
K8S_BASIC_I18N_STORAGE_CDN_HOST	i18n CDN 域名
K8S_BASIC_I18N_STORAGE_BUCKET_HOST	i18n 存储桶名

6.5 OIDC 认证配置

环境变量	说明
K8S_BASIC_OIDC_CLIENT_ID	OIDC 客户端 ID
K8S_BASIC_OIDC_CLIENT_SECRET	OIDC 客户端密钥
K8S_BASIC_OIDC_PROVIDER_ADDR	OIDC 提供者地址

7. 最佳实践

• 超时配置：gRPC 调用建议设置 5s 超时，导入导出等大文件操作可放宽至 30s
• 重试策略：查询类接口可安全重试（幂等），写入类接口需确认幂等性后再重试
• 缓存策略：租户信息、项目信息变更频率低，建议本地缓存 5 分钟；字典查询接口支持版本号增量更新，利用 projectCode@versionNumber 格式减少全量拉取
• 多租户：所有请求必须携带 X-TENANT Header，gRPC 通过 Metadata 传递