@robsun/create-keystone-app 0.2.6 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robsun/create-keystone-app",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "scripts": {
     "build": "node scripts/build.js",
     "prepublishOnly": "node scripts/build.js && node scripts/prune-template-deps.js"
@@ -20,4 +20,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}

package/template/.claude/skills/keystone-dev/SKILL.md

@@ -10,10 +10,11 @@ description: 基于 Keystone 平台开发业务模块。当用户需要创建新
 ## 工作流程
 
 1. **解析需求** → 识别所需能力
-2. **生成前端模块** → routes.tsx, pages/, services/, types.ts
-3. **生成后端模块** → handler/, service/, repository/, migrations/
-4. **自动注册** → main.tsx + manifest.go + config.yaml
-5. **输出调整建议**
+2. **生成前端模块** → routes.tsx, pages/, services/, types.ts
+3. **生成后端模块** → handler/, service/, repository/, migrations/
+4. **自动注册** → main.tsx + manifest.go + config.yaml
+5. **输出调整建议**
+6. **补测试并执行** → 见 references/testing.md
 
 ## 能力选择矩阵
 
@@ -26,11 +27,13 @@ description: 基于 Keystone 平台开发业务模块。当用户需要创建新
 | 导入、批量 | DataImporter | ImportHandler + Job队列 |
 | 导出、下载 | DataExporter | ExportHandler + Job队列 |
 | 上传、附件 | FileUpload | UploadHandler + 存储服务 |
-| 审批、流程 | ApprovalFlowEditor | 审批引擎 |
-| 权限 | PermissionGuard | 权限中间件 |
-
-详细能力清单见 [CAPABILITIES.md](CAPABILITIES.md)。
-代码模板见 [TEMPLATES.md](TEMPLATES.md)。
+| 审批、流程 | ApprovalFlowEditor | 审批引擎 |
+| 权限 | PermissionGuard | 权限中间件 |
+
+审批流程与接入说明见 [references/approval.md](references/approval.md)。
+测试清单见 [references/testing.md](references/testing.md)。
+详细能力清单见 [references/CAPABILITIES.md](references/CAPABILITIES.md)。
+代码模板见 [references/TEMPLATES.md](references/TEMPLATES.md)。
 
 ## 模块结构约定
 

package/template/.claude/skills/keystone-dev/references/APPROVAL.md

@@ -0,0 +1,74 @@
+# Keystone 审批接入流程
+
+## 目标
+本文只描述审批接入所需的表单 schema 与 context 映射等开发工作，
+流程节点与审批路径由人工在审批配置页面完成。
+
+## 适用场景
+- 新业务需要审批门禁（新业务类型）。
+- 既有业务接入审批门禁（在业务表单提交或关键业务动作前加审批）。
+
+## 不在范围
+- 配置审批流程与节点（由人工在流程配置页面完成）。
+- 修改 approval 基础模块或审批页面本身。
+- 改造审批权限体系或审批路由结构。
+
+## 开发路径选择
+- Greenfield：新业务从零引入审批。
+- Retrofit：已有业务接入审批。
+
+## 开发步骤 A：新业务（Greenfield）
+1) 前端配置 `approval.businessTypes` 标签映射（用于流程配置时选择表单），
+   流程配置页面的业务类型选择会作为 schema code 加载表单字段，需保持一致。
+2) 注册表单 schema（条件节点字段来源）。
+3) 在业务提交处创建审批实例，写入 context JSON 用于条件路由。
+4) 绑定 OnApproved/OnRejected 回调更新业务状态。
+5) 按测试清单执行（见 testing.md）。
+
+## 开发步骤 B：已有业务接入（Retrofit）
+1) 确认触发点与审批边界（业务表单提交或关键业务动作前）。
+2) 将现有字段映射为 context JSON（供条件节点判断）。
+3) 做幂等：按业务类型 + 业务 ID 查已有实例再创建。
+4) pending 期间阻断业务动作（状态拦截或硬拦截）。
+5) 决定是否回填存量数据（跳过或补建实例）。
+
+## 业务侧改动清单
+
+后端（业务模块内）
+- 在业务 service/handler 中调用审批服务创建实例（必要时通过 FlowMatcher 选 flow）。
+- 在业务模块注册审批回调，审批通过/驳回时更新业务状态。
+- 需要数据范围过滤时，实现 ApprovalContextResolver 并在应用装配时注入。
+- 如需默认 flow 或 schema，放在业务模块的迁移/seed 中，不改动审批模块。
+
+前端（业务模块内）
+- 配置 `approval.businessTypes` 标签映射，保证业务类型显示正确。
+- 流程配置使用已有审批管理页面，不做二次开发。
+
+## 权限说明
+使用系统既有审批权限码：
+approval:flow:view|create|edit|delete  
+approval:instance:view|approve|cancel  
+approval:record:view|export
+
+## 集成自检
+- Flow code <= 50 且使用大写；business type 用短字符串。
+- approve/reject/cancel 使用 version 做乐观锁。
+- 变更接口时更新 OpenAPI 合同。
+- 新增默认流程时补迁移或 seed。
+
+测试清单见 [testing.md](testing.md)。
+
+## 参考入口
+
+后端
+- domain/approval/service/service.go
+- domain/approval/service/flow_matcher.go
+- domain/approval/service/callback_registry.go
+- api/routes/approval_routes.go
+- contracts/011-approvals/approvals-api.yaml
+
+前端
+- packages/keystone-web-core/src/platform/config/appConfig.ts
+- packages/keystone-web-core/src/platform/core/approval/services/approvalService.ts
+- packages/keystone-web-core/src/platform/core/approval/stores/approvalStore.ts
+- packages/keystone-web-core/src/modules/keystone/approval/pages/*

package/template/.claude/skills/keystone-dev/{CAPABILITIES.md → references/CAPABILITIES.md}

@@ -41,6 +41,7 @@ import {
   ApprovalHistory        // 审批历史
 } from '@robsun/keystone-web-core'
 ```
+审批流程与接入说明见 [approval.md](approval.md)。
 
 ### 4. 帮助系统
 ```typescript

package/template/.claude/skills/keystone-dev/{TEMPLATES.md → references/TEMPLATES.md}

@@ -5,6 +5,7 @@
 ### Ant Design v6 注意事项
 - `Space` 使用 `orientation`，不要用 `direction`。
 - `Modal` 使用 `destroyOnHidden`，不要用 `destroyOnClose`。
+- `Drawer` 使用 `size`，不要用 `width`。
 
 ### routes.tsx
 ```tsx

package/template/.claude/skills/keystone-dev/references/TESTING.md

@@ -0,0 +1,44 @@
+# Keystone 开发测试清单
+
+## 快速入口
+- 仓库根目录：`pnpm test`（模板测试 + `go test ./...`）
+- 仅 Go：`go test ./...`
+- 模板项目：`pnpm -C packages/create-keystone-app/template test`
+
+## 按改动范围选择
+后端（api/domain/infra/bootstrap/server）
+- `go test ./...`
+- 若改动较大可补 `go vet ./...`
+
+模板前端（packages/create-keystone-app/template/apps/web）
+- `pnpm -C packages/create-keystone-app/template/apps/web typecheck`
+- `pnpm -C packages/create-keystone-app/template/apps/web lint`
+- `pnpm -C packages/create-keystone-app/template/apps/web test`
+
+前端核心包（packages/keystone-web-core）
+- `pnpm -C packages/keystone-web-core build`
+
+脚手架/模板变更
+- `pnpm scaffold:verify`
+
+合同变更
+- `pnpm contracts:check`
+- 如更新了合同内容，执行 `pnpm contracts:sync`
+
+## 写测试（必做）
+后端
+- 领域/服务逻辑新增或改动：在 `tests/unit/platform/service` 或对应 domain 下补单测。
+- Repository 变更：在 `tests/unit/platform/repository` 补单测。
+- 新增/调整 API：在 `tests/integration/platform/api` 补集成测试。
+- 参考用例：`tests/unit/platform/approval/service_test.go`、`tests/integration/platform/api/approval_schema_test.go`。
+
+前端（模板 web）
+- 新增页面/交互：在 `packages/create-keystone-app/template/apps/web/tests` 新增 `*.test.tsx`。
+- 使用 vitest + Testing Library（已在 `vite.config.ts` 配好 test 配置）。
+
+前端核心包（keystone-web-core）
+- 新增核心组件/逻辑：优先在模板 web 侧写集成测试覆盖。
+- 如必须在包内写单测，需要补齐包内测试配置后再添加用例。
+
+## 最小通过标准
+- 单点改动跑对应子项；跨域改动直接跑 `pnpm test`。

package/template/.codex/skills/keystone-dev/SKILL.md

@@ -10,10 +10,11 @@ description: 基于 Keystone 平台开发业务模块。当用户需要创建新
 ## 工作流程
 
 1. **解析需求** → 识别所需能力
-2. **生成前端模块** → routes.tsx, pages/, services/, types.ts
-3. **生成后端模块** → handler/, service/, repository/, migrations/
-4. **自动注册** → main.tsx + manifest.go + config.yaml
-5. **输出调整建议**
+2. **生成前端模块** → routes.tsx, pages/, services/, types.ts
+3. **生成后端模块** → handler/, service/, repository/, migrations/
+4. **自动注册** → main.tsx + manifest.go + config.yaml
+5. **输出调整建议**
+6. **补测试并执行** → 见 references/testing.md
 
 ## 能力选择矩阵
 
@@ -26,11 +27,13 @@ description: 基于 Keystone 平台开发业务模块。当用户需要创建新
 | 导入、批量 | DataImporter | ImportHandler + Job队列 |
 | 导出、下载 | DataExporter | ExportHandler + Job队列 |
 | 上传、附件 | FileUpload | UploadHandler + 存储服务 |
-| 审批、流程 | ApprovalFlowEditor | 审批引擎 |
-| 权限 | PermissionGuard | 权限中间件 |
-
-详细能力清单见 [CAPABILITIES.md](CAPABILITIES.md)。
-代码模板见 [TEMPLATES.md](TEMPLATES.md)。
+| 审批、流程 | ApprovalFlowEditor | 审批引擎 |
+| 权限 | PermissionGuard | 权限中间件 |
+
+审批流程与接入说明见 [references/approval.md](references/approval.md)。
+测试清单见 [references/testing.md](references/testing.md)。
+详细能力清单见 [references/CAPABILITIES.md](references/CAPABILITIES.md)。
+代码模板见 [references/TEMPLATES.md](references/TEMPLATES.md)。
 
 ## 模块结构约定
 

package/template/.codex/skills/keystone-dev/references/APPROVAL.md

@@ -0,0 +1,74 @@
+# Keystone 审批接入流程
+
+## 目标
+本文只描述审批接入所需的表单 schema 与 context 映射等开发工作，
+流程节点与审批路径由人工在审批配置页面完成。
+
+## 适用场景
+- 新业务需要审批门禁（新业务类型）。
+- 既有业务接入审批门禁（在业务表单提交或关键业务动作前加审批）。
+
+## 不在范围
+- 配置审批流程与节点（由人工在流程配置页面完成）。
+- 修改 approval 基础模块或审批页面本身。
+- 改造审批权限体系或审批路由结构。
+
+## 开发路径选择
+- Greenfield：新业务从零引入审批。
+- Retrofit：已有业务接入审批。
+
+## 开发步骤 A：新业务（Greenfield）
+1) 前端配置 `approval.businessTypes` 标签映射（用于流程配置时选择表单），
+   流程配置页面的业务类型选择会作为 schema code 加载表单字段，需保持一致。
+2) 注册表单 schema（条件节点字段来源）。
+3) 在业务提交处创建审批实例，写入 context JSON 用于条件路由。
+4) 绑定 OnApproved/OnRejected 回调更新业务状态。
+5) 按测试清单执行（见 testing.md）。
+
+## 开发步骤 B：已有业务接入（Retrofit）
+1) 确认触发点与审批边界（业务表单提交或关键业务动作前）。
+2) 将现有字段映射为 context JSON（供条件节点判断）。
+3) 做幂等：按业务类型 + 业务 ID 查已有实例再创建。
+4) pending 期间阻断业务动作（状态拦截或硬拦截）。
+5) 决定是否回填存量数据（跳过或补建实例）。
+
+## 业务侧改动清单
+
+后端（业务模块内）
+- 在业务 service/handler 中调用审批服务创建实例（必要时通过 FlowMatcher 选 flow）。
+- 在业务模块注册审批回调，审批通过/驳回时更新业务状态。
+- 需要数据范围过滤时，实现 ApprovalContextResolver 并在应用装配时注入。
+- 如需默认 flow 或 schema，放在业务模块的迁移/seed 中，不改动审批模块。
+
+前端（业务模块内）
+- 配置 `approval.businessTypes` 标签映射，保证业务类型显示正确。
+- 流程配置使用已有审批管理页面，不做二次开发。
+
+## 权限说明
+使用系统既有审批权限码：
+approval:flow:view|create|edit|delete  
+approval:instance:view|approve|cancel  
+approval:record:view|export
+
+## 集成自检
+- Flow code <= 50 且使用大写；business type 用短字符串。
+- approve/reject/cancel 使用 version 做乐观锁。
+- 变更接口时更新 OpenAPI 合同。
+- 新增默认流程时补迁移或 seed。
+
+测试清单见 [testing.md](testing.md)。
+
+## 参考入口
+
+后端
+- domain/approval/service/service.go
+- domain/approval/service/flow_matcher.go
+- domain/approval/service/callback_registry.go
+- api/routes/approval_routes.go
+- contracts/011-approvals/approvals-api.yaml
+
+前端
+- packages/keystone-web-core/src/platform/config/appConfig.ts
+- packages/keystone-web-core/src/platform/core/approval/services/approvalService.ts
+- packages/keystone-web-core/src/platform/core/approval/stores/approvalStore.ts
+- packages/keystone-web-core/src/modules/keystone/approval/pages/*

package/template/.codex/skills/keystone-dev/{CAPABILITIES.md → references/CAPABILITIES.md}

@@ -41,6 +41,7 @@ import {
   ApprovalHistory        // 审批历史
 } from '@robsun/keystone-web-core'
 ```
+审批流程与接入说明见 [approval.md](approval.md)。
 
 ### 4. 帮助系统
 ```typescript

package/template/.codex/skills/keystone-dev/{TEMPLATES.md → references/TEMPLATES.md}

@@ -5,6 +5,7 @@
 ### Ant Design v6 注意事项
 - `Space` 使用 `orientation`，不要用 `direction`。
 - `Modal` 使用 `destroyOnHidden`，不要用 `destroyOnClose`。
+- `Drawer` 使用 `size`，不要用 `width`。
 
 ### routes.tsx
 ```tsx

package/template/.codex/skills/keystone-dev/references/TESTING.md

@@ -0,0 +1,44 @@
+# Keystone 开发测试清单
+
+## 快速入口
+- 仓库根目录：`pnpm test`（模板测试 + `go test ./...`）
+- 仅 Go：`go test ./...`
+- 模板项目：`pnpm -C packages/create-keystone-app/template test`
+
+## 按改动范围选择
+后端（api/domain/infra/bootstrap/server）
+- `go test ./...`
+- 若改动较大可补 `go vet ./...`
+
+模板前端（packages/create-keystone-app/template/apps/web）
+- `pnpm -C packages/create-keystone-app/template/apps/web typecheck`
+- `pnpm -C packages/create-keystone-app/template/apps/web lint`
+- `pnpm -C packages/create-keystone-app/template/apps/web test`
+
+前端核心包（packages/keystone-web-core）
+- `pnpm -C packages/keystone-web-core build`
+
+脚手架/模板变更
+- `pnpm scaffold:verify`
+
+合同变更
+- `pnpm contracts:check`
+- 如更新了合同内容，执行 `pnpm contracts:sync`
+
+## 写测试（必做）
+后端
+- 领域/服务逻辑新增或改动：在 `tests/unit/platform/service` 或对应 domain 下补单测。
+- Repository 变更：在 `tests/unit/platform/repository` 补单测。
+- 新增/调整 API：在 `tests/integration/platform/api` 补集成测试。
+- 参考用例：`tests/unit/platform/approval/service_test.go`、`tests/integration/platform/api/approval_schema_test.go`。
+
+前端（模板 web）
+- 新增页面/交互：在 `packages/create-keystone-app/template/apps/web/tests` 新增 `*.test.tsx`。
+- 使用 vitest + Testing Library（已在 `vite.config.ts` 配好 test 配置）。
+
+前端核心包（keystone-web-core）
+- 新增核心组件/逻辑：优先在模板 web 侧写集成测试覆盖。
+- 如必须在包内写单测，需要补齐包内测试配置后再添加用例。
+
+## 最小通过标准
+- 单点改动跑对应子项；跨域改动直接跑 `pnpm test`。

package/template/apps/server/go.mod

@@ -4,7 +4,7 @@ go 1.24.3
 
 require (
 	github.com/gin-gonic/gin v1.11.0
-	github.com/robsuncn/keystone v0.1.1
+	github.com/robsuncn/keystone v0.2.0
 	github.com/swaggo/files v1.0.1
 	github.com/swaggo/gin-swagger v1.6.0
 	github.com/swaggo/swag v1.16.2

package/template/apps/server/go.sum

@@ -144,6 +144,7 @@ github.com/richardlehane/msoleps v1.0.4 h1:WuESlvhX3gH2IHcd8UqyCuFY5yiq/GR/yqaSM
 github.com/richardlehane/msoleps v1.0.4/go.mod h1:BWev5JBpU9Ko2WAgmZEuiz4/u3ZYTKbjLycmwiWUfWg=
 github.com/robsuncn/keystone v0.1.1 h1:0BK2lL9wGjp9/0ZWnwoNnEHqGvAkGYLQbkwlVemDSzQ=
 github.com/robsuncn/keystone v0.1.1/go.mod h1:VPNHWG9pZi00SRC8hqy47EvfxnI795/ZC1vSkLm6x1c=
+github.com/robsuncn/keystone v0.2.0/go.mod h1:qIpuWlWXmuwy+lEuyMDLy5FLzjRWki/oJ3nGO5jyIFc=
 github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
 github.com/sagikazarmark/locafero v0.11.0 h1:1iurJgmM9G3PA/I+wWYIOw/5SyBtxapeHDcg+AAIFXc=

package/template/apps/server/internal/modules/example/api/handler/item_handler.go

@@ -6,7 +6,9 @@ import (
 	"github.com/gin-gonic/gin"
 	hcommon "github.com/robsuncn/keystone/api/handler/common"
 	"github.com/robsuncn/keystone/api/response"
+	"github.com/robsuncn/keystone/infra/i18n"
 
+	examplei18n "__APP_NAME__/apps/server/internal/modules/example/i18n"
 	"__APP_NAME__/apps/server/internal/modules/example/domain/models"
 	"__APP_NAME__/apps/server/internal/modules/example/domain/service"
 )
@@ -38,14 +40,14 @@ const defaultTenantID uint = 1
 
 func (h *ItemHandler) List(c *gin.Context) {
 	if h == nil || h.items == nil {
-		response.ServiceUnavailable(c, "example items unavailable")
+		response.ServiceUnavailableI18n(c, examplei18n.MsgServiceUnavailable)
 		return
 	}
 	tenantID := resolveTenantID(c)
 
 	items, err := h.items.List(c.Request.Context(), tenantID)
 	if err != nil {
-		response.InternalError(c, "failed to load example items")
+		response.InternalErrorI18n(c, examplei18n.MsgItemLoadFailed)
 		return
 	}
 
@@ -54,14 +56,14 @@ func (h *ItemHandler) List(c *gin.Context) {
 
 func (h *ItemHandler) Create(c *gin.Context) {
 	if h == nil || h.items == nil {
-		response.ServiceUnavailable(c, "example items unavailable")
+		response.ServiceUnavailableI18n(c, examplei18n.MsgServiceUnavailable)
 		return
 	}
 	tenantID := resolveTenantID(c)
 
 	var input itemInput
 	if err := c.ShouldBindJSON(&input); err != nil {
-		response.BadRequest(c, "invalid payload")
+		response.BadRequestI18n(c, examplei18n.MsgInvalidPayload)
 		return
 	}
 
@@ -71,36 +73,34 @@ func (h *ItemHandler) Create(c *gin.Context) {
 		Status:      input.Status,
 	})
 	if err != nil {
-		switch {
-		case errors.Is(err, service.ErrTitleRequired):
-			response.BadRequest(c, "title is required")
-		case errors.Is(err, service.ErrStatusInvalid):
-			response.BadRequest(c, "invalid status")
-		default:
-			response.InternalError(c, "failed to create example item")
+		var i18nErr *i18n.I18nError
+		if errors.As(err, &i18nErr) {
+			response.BadRequestI18n(c, i18nErr.Key)
+			return
 		}
+		response.InternalErrorI18n(c, examplei18n.MsgItemCreateFailed)
 		return
 	}
 
-	response.Created(c, item)
+	response.CreatedI18n(c, examplei18n.MsgItemCreated, item)
 }
 
 func (h *ItemHandler) Update(c *gin.Context) {
 	if h == nil || h.items == nil {
-		response.ServiceUnavailable(c, "example items unavailable")
+		response.ServiceUnavailableI18n(c, examplei18n.MsgServiceUnavailable)
 		return
 	}
 	tenantID := resolveTenantID(c)
 
 	id, err := hcommon.ParseUintParam(c, "id")
 	if err != nil || id == 0 {
-		response.BadRequest(c, "invalid id")
+		response.BadRequestI18n(c, examplei18n.MsgInvalidID)
 		return
 	}
 
 	var input itemUpdateInput
 	if err := c.ShouldBindJSON(&input); err != nil {
-		response.BadRequest(c, "invalid payload")
+		response.BadRequestI18n(c, examplei18n.MsgInvalidPayload)
 		return
 	}
 
@@ -110,45 +110,48 @@ func (h *ItemHandler) Update(c *gin.Context) {
 		Status:      input.Status,
 	})
 	if err != nil {
-		switch {
-		case errors.Is(err, service.ErrItemNotFound):
-			response.NotFound(c, "item not found")
-		case errors.Is(err, service.ErrTitleRequired):
-			response.BadRequest(c, "title is required")
-		case errors.Is(err, service.ErrStatusInvalid):
-			response.BadRequest(c, "invalid status")
-		default:
-			response.InternalError(c, "failed to update example item")
+		var i18nErr *i18n.I18nError
+		if errors.As(err, &i18nErr) {
+			if i18nErr.Key == examplei18n.MsgItemNotFound {
+				response.NotFoundI18n(c, i18nErr.Key)
+			} else {
+				response.BadRequestI18n(c, i18nErr.Key)
+			}
+			return
 		}
+		response.InternalErrorI18n(c, examplei18n.MsgItemUpdateFailed)
 		return
 	}
 
-	response.SuccessWithMessage(c, "updated", item)
+	response.SuccessI18n(c, examplei18n.MsgItemUpdated, item)
 }
 
 func (h *ItemHandler) Delete(c *gin.Context) {
 	if h == nil || h.items == nil {
-		response.ServiceUnavailable(c, "example items unavailable")
+		response.ServiceUnavailableI18n(c, examplei18n.MsgServiceUnavailable)
 		return
 	}
 	tenantID := resolveTenantID(c)
 
 	id, err := hcommon.ParseUintParam(c, "id")
 	if err != nil || id == 0 {
-		response.BadRequest(c, "invalid id")
+		response.BadRequestI18n(c, examplei18n.MsgInvalidID)
 		return
 	}
 
 	if err := h.items.Delete(c.Request.Context(), tenantID, id); err != nil {
-		if errors.Is(err, service.ErrItemNotFound) {
-			response.NotFound(c, "item not found")
-			return
+		var i18nErr *i18n.I18nError
+		if errors.As(err, &i18nErr) {
+			if i18nErr.Key == examplei18n.MsgItemNotFound {
+				response.NotFoundI18n(c, i18nErr.Key)
+				return
+			}
 		}
-		response.InternalError(c, "failed to delete example item")
+		response.InternalErrorI18n(c, examplei18n.MsgItemDeleteFailed)
 		return
 	}
 
-	response.SuccessWithMessage(c, "deleted", gin.H{"id": id})
+	response.SuccessI18n(c, examplei18n.MsgItemDeleted, gin.H{"id": id})
 }
 
 func resolveTenantID(c *gin.Context) uint {

package/template/apps/server/internal/modules/example/domain/service/errors.go

@@ -7,3 +7,16 @@ var (
 	ErrTitleRequired = errors.New("title is required")
 	ErrStatusInvalid = errors.New("status is invalid")
 )
+
+// I18n version (uncomment when using keystone with i18n support):
+//
+// import (
+// 	"github.com/robsuncn/keystone/infra/i18n"
+// 	examplei18n "your-app/apps/server/internal/modules/example/i18n"
+// )
+//
+// var (
+// 	ErrItemNotFound  = &i18n.I18nError{Key: examplei18n.MsgItemNotFound}
+// 	ErrTitleRequired = &i18n.I18nError{Key: examplei18n.MsgTitleRequired}
+// 	ErrStatusInvalid = &i18n.I18nError{Key: examplei18n.MsgStatusInvalid}
+// )

package/template/apps/server/internal/modules/example/i18n/i18n.go

@@ -0,0 +1,16 @@
+package examplei18n
+
+import (
+	"embed"
+
+	"github.com/robsuncn/keystone/infra/i18n"
+)
+
+//go:embed locales/*.json
+var localeFS embed.FS
+
+// RegisterLocales registers the example module's locale files with the i18n system.
+// Call this during module initialization.
+func RegisterLocales() error {
+	return i18n.LoadModuleLocales(localeFS, "locales")
+}

package/template/apps/server/internal/modules/example/i18n/keys.go

@@ -0,0 +1,23 @@
+package examplei18n
+
+// Example module i18n message keys
+const (
+	// Item messages
+	MsgItemCreated      = "example.item.created"
+	MsgItemUpdated      = "example.item.updated"
+	MsgItemDeleted      = "example.item.deleted"
+	MsgItemNotFound     = "example.item.notFound"
+	MsgItemLoadFailed   = "example.item.loadFailed"
+	MsgItemCreateFailed = "example.item.createFailed"
+	MsgItemUpdateFailed = "example.item.updateFailed"
+	MsgItemDeleteFailed = "example.item.deleteFailed"
+
+	// Validation messages
+	MsgTitleRequired = "example.validation.titleRequired"
+	MsgStatusInvalid = "example.validation.statusInvalid"
+	MsgInvalidID     = "example.validation.invalidId"
+	MsgInvalidPayload = "example.validation.invalidPayload"
+
+	// Service messages
+	MsgServiceUnavailable = "example.service.unavailable"
+)

package/template/apps/server/internal/modules/example/i18n/locales/en-US.json

@@ -0,0 +1,18 @@
+{
+  "example.item.created": "Item created successfully",
+  "example.item.updated": "Item updated successfully",
+  "example.item.deleted": "Item deleted successfully",
+  "example.item.notFound": "Item not found",
+  "example.item.loadFailed": "Failed to load items",
+  "example.item.createFailed": "Failed to create item",
+  "example.item.updateFailed": "Failed to update item",
+  "example.item.deleteFailed": "Failed to delete item",
+  "example.validation.titleRequired": "Title is required",
+  "example.validation.statusInvalid": "Invalid status value",
+  "example.validation.invalidId": "Invalid ID",
+  "example.validation.invalidPayload": "Invalid request payload",
+  "example.service.unavailable": "Example service is unavailable",
+  "permission.example.item": "Example Items",
+  "permission.example.item.view": "View Items",
+  "permission.example.item.manage": "Manage Items"
+}

package/template/apps/server/internal/modules/example/i18n/locales/zh-CN.json

@@ -0,0 +1,18 @@
+{
+  "example.item.created": "项目创建成功",
+  "example.item.updated": "项目更新成功",
+  "example.item.deleted": "项目删除成功",
+  "example.item.notFound": "项目不存在",
+  "example.item.loadFailed": "加载项目列表失败",
+  "example.item.createFailed": "创建项目失败",
+  "example.item.updateFailed": "更新项目失败",
+  "example.item.deleteFailed": "删除项目失败",
+  "example.validation.titleRequired": "标题不能为空",
+  "example.validation.statusInvalid": "状态值无效",
+  "example.validation.invalidId": "无效的 ID",
+  "example.validation.invalidPayload": "请求参数无效",
+  "example.service.unavailable": "示例服务暂不可用",
+  "permission.example.item": "示例项目",
+  "permission.example.item.view": "查看项目",
+  "permission.example.item.manage": "管理项目"
+}