Description

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

README (SKILL.md)

Basic 基础服务接入指南

Name: Basic Integration Guide
Author: effort02

1. 服务概述

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

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

接口协议：gRPC + REST API

2. 快速接入

2.1 Maven 依赖

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

\x3Cdependency>
    \x3CgroupId>com.ginlong\x3C/groupId>
    \x3CartifactId>basic-client\x3C/artifactId>
    \x3Cversion>1.0.0-SNAPSHOT\x3C/version>
\x3C/dependency>

gRPC 接口包（含 Protobuf Stub）：

\x3Cdependency>
    \x3CgroupId>com.ginlong\x3C/groupId>
    \x3CartifactId>basic-grpc-interface\x3C/artifactId>
    \x3Cversion>1.0.0-SNAPSHOT\x3C/version>
\x3C/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);

\x3C!-- 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);

\x3C!-- 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'

\x3C!-- 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 \x3Ctoken>'

\x3C!-- 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\x3CSimpleLangDto>

5.2 Project 域

ProjectClientService — 项目管理

search(ProjectSearchDto) → List\x3CProjectDto>

ProjectAppClientService — 项目应用管理

search(ProjectAppSearchDto) → List\x3CProjectAppDto>
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\x3CDictionaryItemDto>) → List\x3CDictionaryItemDto>
update(Long id, DictionaryItemDto) → DictionaryItemDto
batchUpdate(List\x3CDictionaryItemDto>) → List\x3CDictionaryItemDto>
delete(Long id) → void
setEnabled(Long id, boolean enabled) → void

DictionaryQueryClientService — 字典查询

query(List\x3CString> projectCodes, List\x3CString> moduleCodes, List\x3CString> groupCodes) → Map\x3CString, DictionaryGroupDataDto>
queryPublished(...) → Map\x3CString, 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\x3CProjectPublishSummaryDto>

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\x3CString, String> metadata, InputStream inputStream) → void
deleteBatch(String bucketName, String keyPrefix) → void
exist(String bucketName, List\x3CString> keys) → Map\x3CString, 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 传递

Usage Guidance

This skill is a documentation-only integration guide and appears coherent with its stated purpose. Before using it in production: 1) do not use the example negotiationType: plaintext — enable TLS/mTLS for gRPC and ensure Authorization metadata is sent only over encrypted channels; 2) verify Maven coordinates and avoid pulling SNAPSHOT artifacts from untrusted repositories; 3) update host/address placeholders (dns:///basic-service:9090) to your environment and restrict network access appropriately; 4) treat bearer tokens/OIDC credentials securely (store secrets in a vault, avoid committing them); 5) test the integration in an isolated environment first. Because the skill contains no installers or requests for secrets, the immediate risk is low, but configuration examples include insecure defaults you should correct.

Capability Analysis

Type: OpenClaw Skill Name: basic-integration-guide Version: 1.0.0 The skill bundle is a comprehensive technical integration guide for a suite of internal 'Basic' services, including i18n, project management, and tenant management. It contains standard documentation elements such as Maven dependency coordinates, gRPC Protobuf definitions, REST API endpoint descriptions, and configuration environment variable references (e.g., in SKILL.md). There is no evidence of malicious intent, data exfiltration, or prompt injection designed to subvert the AI agent.

Capability Tags

requires-oauth-tokenrequires-sensitive-credentials

Capability Assessment

✓ Purpose & Capability

The name/description (basic foundation service integration: i18n, project, tenant, dict, storage, auth) matches the SKILL.md content: Maven dependencies, gRPC/REST API usage, protobuf messages, headers/metadata for tenant and auth. The required resources (none) are proportionate to a documentation/integration guide.

ℹ Instruction Scope

The SKILL.md stays within integration scope (how to add deps, configure gRPC, pass headers/metadata, protobuf definitions and call examples). It does not instruct the agent to read local files, system state, or send data to unrelated endpoints. Note: example gRPC config uses negotiationType: plaintext and address 'dns:///basic-service:9090' which are insecure/infrastructure-specific defaults and should not be used in production.

✓ Install Mechanism

No install spec and no code files are present (instruction-only). This minimizes on-disk execution risk; nothing is downloaded or installed by the skill itself.

ℹ Credentials

The skill does not declare or request environment variables or credentials. It documents passing Authorization, X-TENANT, and X-UID in headers/metadata — which is appropriate for an integration guide. Be aware examples assume bearer tokens and plaintext gRPC; ensure tokens are provided securely and transport is encrypted in real deployments. Also the Maven deps use 1.0.0-SNAPSHOT which may indicate an unstable or internal artifact source.

✓ Persistence & Privilege

always:false and default model invocation settings are used. The skill does not request persistent installation or attempt to modify agent/system settings. No elevated persistence privileges are evident.

Version History

v1.0.0

basic-integration-guide 1.0.0 - Initial Release - 提供基础服务接入指南，涵盖依赖引入、gRPC 客户端配置、REST API 使用、认证与租户上下文传递等基础用法 - 详细介绍国际化(i18n)、项目管理、租户管理等核心能力的服务接口定义与调用方式 - 包含主要 gRPC 服务（I18nService、ProjectService、TenantService）的协议与示例代码 - 列举常见 REST API 路径、方法与核心参数说明 - 适用于开发者参考、快速完成对 basic 基础服务的系统集成

Metadata

Slug basic-integration-guide

Version 1.0.0

License MIT-0

All-time Installs 0

Active Installs 0

Total Versions 1

Frequently Asked Questions

What is Basic Integration Guide?

指导开发者如何接入basic基础服务，包括依赖引入、gRPC调用、REST API使用、配置说明。涵盖国际化(i18n)、项目管理、租户管理、字典管理、存储、认证等核心能力. It is an AI Agent Skill for Claude Code / OpenClaw, with 79 downloads so far.

How do I install Basic Integration Guide?

Run "/install basic-integration-guide" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Basic Integration Guide free?

Yes, Basic Integration Guide is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Basic Integration Guide support?

Basic Integration Guide is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Basic Integration Guide?

It is built and maintained by effort02 (@effort02); the current version is v1.0.0.

More Skills

Basic Integration Guide

Basic 基础服务接入指南

1. 服务概述

2. 快速接入

2.1 Maven 依赖

2.2 gRPC 客户端配置

2.3 认证与租户上下文

3. gRPC 服务接口

3.1 I18nService

3.2 ProjectService

3.3 TenantService

4. REST API 接口

4.1 国际化管理 (i18n)

语言管理

项目应用管理

词条空间管理

词条管理

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

4.2 项目管理

4.3 租户管理

租户 CRUD

租户配置

4.4 字典管理

字典项目管理

字典模块管理

字典分组管理

字典项管理

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

字典发布版本管理

字典草稿对比

字典资产管理

4.5 内部认证

5. 客户端 SDK 接口

5.1 I18n 域

5.2 Project 域

5.3 Tenant 域

5.4 Dictionary 域

5.5 Storage 域

6. 配置参考

6.1 必填配置

6.2 可选配置

6.3 存储配置（按需）

6.4 i18n 存储配置

6.5 OIDC 认证配置

7. 最佳实践

What is Basic Integration Guide?

How do I install Basic Integration Guide?

Is Basic Integration Guide free?

Which platforms does Basic Integration Guide support?

Who created Basic Integration Guide?

💬 Comments