@dofe/sso-contracts 0.1.2

package/README.md

@@ -0,0 +1,303 @@
+# @repo/contracts - API 契约
+
+使用 ts-rest 实现的前后端类型安全 API 契约。
+
+## 安装
+
+```json
+{
+  "dependencies": {
+    "@repo/contracts": "workspace:*"
+  }
+}
+```
+
+## 使用
+
+### 前端使用
+
+```typescript
+import { teamContract } from '@repo/contracts/api';
+import { initClient } from '@ts-rest/core';
+
+const client = initClient(teamContract, {
+  baseUrl: '/api',
+});
+
+const { data } = await client.getInfo({ params: { teamId: '123' } });
+```
+
+### 后端使用
+
+```typescript
+import { teamContract } from '@repo/contracts/api';
+import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';
+import { success } from '@/common/ts-rest';
+
+@Controller()
+export class TeamController {
+  @TsRestHandler(teamContract.getInfo)
+  async getInfo() {
+    return tsRestHandler(teamContract.getInfo, async ({ params }) => {
+      const team = await this.teamService.getInfo(params.teamId);
+      return success(team);
+    });
+  }
+}
+```
+
+## 错误码系统
+
+错误码按业务域组织，从 `@repo/contracts/errors` 导出。
+
+### 错误码域
+
+| 域      | 前缀    | 导入               |
+| ------- | ------- | ------------------ |
+| Team    | 1xx     | `TeamErrorCode`    |
+| User    | 2xx     | `UserErrorCode`    |
+| Space   | 3xx     | `SpaceErrorCode`   |
+| Folder  | 4xx     | `FolderErrorCode`  |
+| File    | 5xx     | `FileErrorCode`    |
+| Comment | 56x-57x | `CommentErrorCode` |
+| Payment | 7xx     | `PaymentErrorCode` |
+| Common  | 9xx     | `CommonErrorCode`  |
+
+### 后端错误处理
+
+```typescript
+import { TeamErrorCode, apiError } from '@repo/contracts/errors';
+import { ApiExceptionV2 } from '@/filter/exception/api-exception-v2';
+
+// 简单错误
+throw apiError(TeamErrorCode.TeamNotFound);
+
+// 带数据的错误
+throw apiError(TeamErrorCode.TeamNotFound, { teamId: '123' });
+
+// 直接使用 ApiExceptionV2
+throw ApiExceptionV2.fromCode(TeamErrorCode.TeamNotFound);
+```
+
+### 前端错误处理
+
+```typescript
+import {
+  TeamErrorCode,
+  handleApiError,
+  createErrorHandler,
+} from '@repo/contracts/errors';
+
+// 创建类型安全的错误处理器
+const teamErrorHandler = createErrorHandler({
+  [TeamErrorCode.TeamNotFound]: {
+    message: '团队不存在',
+    action: () => router.push('/teams'),
+  },
+  [TeamErrorCode.TeamOpNoPermission]: {
+    message: '您没有权限执行此操作',
+  },
+});
+
+// 处理 API 响应
+const handleTeamError = (errorCode: number) => {
+  const result = teamErrorHandler(errorCode);
+  if (result) {
+    toast.error(result.message);
+    result.action?.();
+  }
+};
+```
+
+### 契约中的类型化错误响应
+
+```typescript
+import { TeamErrorCode } from '../errors/domains/team.errors';
+import { createTypedErrorResponse } from '../errors/error-response';
+
+export const teamContract = c.router({
+  getInfo: {
+    method: 'GET',
+    path: '/:teamId',
+    responses: {
+      200: createApiResponse(TeamInfoSchema),
+      400: createTypedErrorResponse([
+        TeamErrorCode.TeamNotFound,
+        TeamErrorCode.TeamMemberViewNoPermission,
+      ] as const),
+    },
+  },
+});
+```
+
+### 验证 Schema
+
+```typescript
+import { TeamNameSchema, PaginationQuerySchema } from '@repo/contracts/schemas';
+
+// 在表单中使用
+const teamForm = useForm({
+  resolver: zodResolver(
+    z.object({
+      name: TeamNameSchema,
+    }),
+  ),
+});
+
+// 在 API 查询中使用
+const query = PaginationQuerySchema.parse(searchParams);
+```
+
+## 目录结构
+
+```
+src/
+├── api/                    # API 契约
+│   ├── team.contract.ts
+│   ├── user.contract.ts
+│   ├── space.contract.ts
+│   └── index.ts
+├── errors/                 # 错误码系统
+│   ├── domains/            # 域错误定义
+│   │   ├── team.errors.ts
+│   │   ├── user.errors.ts
+│   │   └── ...
+│   ├── codes.ts            # 统一错误码
+│   ├── error-response.ts   # 类型化错误响应辅助函数
+│   └── index.ts
+├── schemas/                # Zod Schema
+│   ├── team.schema.ts
+│   ├── user.schema.ts
+│   └── ...
+├── base.ts                 # 基础 Schema (createApiResponse 等)
+└── index.ts                # 主导出
+```
+
+## 构建
+
+```bash
+pnpm --filter @repo/contracts build
+```
+
+## 迁移
+
+从旧错误系统迁移请参阅：
+
+- [错误系统迁移指南](./ERROR-MIGRATION.md) - 从旧系统迁移到新系统的指南
+- [错误码管理优化方案](./错误码管理方案.md) - 错误码枚举字符串化优化方案及实施情况
+
+### 错误码系统状态
+
+✅ **已完成**：
+
+- 所有错误码已迁移到 `@packages/contracts/src/errors`
+- 错误码枚举已改为字符串格式（避免打包类型问题）
+- i18n 错误消息已迁移到 `errors.json`
+- 过期文件已清理
+
+✅ **已完成**：
+
+- 所有文件已迁移到新系统或桥接文件
+- `code.enum.ts` 已无任何直接引用（可安全删除）
+
+📊 **实施进度**：**100%** ✅
+
+---
+
+## NPM 发布流程
+
+### 发布说明
+
+本包在 workspace 内使用名称 `@repo/contracts`，发布到 npmjs 时使用名称 `@dofe/sso-contracts`。
+
+发布脚本会自动处理名称转换：
+- `prepack` - 发布前将名称改为 `@dofe/sso-contracts`
+- `postpack` - 发布后恢复为 `@repo/contracts`
+
+### 发布命令
+
+```bash
+# 进入 contracts 目录
+cd sso.dofe.ai/packages/contracts
+
+# 发布 patch 版本 (0.1.0 → 0.1.1)
+pnpm release:patch
+
+# 发布 minor 版本 (0.1.0 → 0.2.0)
+pnpm release:minor
+
+# 发布 major 版本 (0.1.0 → 1.0.0)
+pnpm release:major
+
+# 带 OTP 发布（如果启用了 2FA）
+npm publish --access public --otp=<你的OTP码>
+```
+
+### 发布流程详解
+
+```bash
+pnpm release:patch
+```
+
+执行步骤：
+1. `npm version patch` - 升级版本号
+2. `pnpm run prepack` - 将 package.json 名称改为 `@dofe/sso-contracts`
+3. `npm publish --access public` - 发布到 npmjs
+4. `pnpm run postpack` - 恢复 package.json 名称为 `@repo/contracts`
+
+### 前置条件
+
+1. npm 账户登录：
+   ```bash
+   npm login
+   ```
+
+2. 验证登录状态：
+   ```bash
+   npm whoami
+   ```
+
+### 其他项目引用
+
+发布后，agents.dofe.ai、models.dofe.ai 等项目可通过以下方式引用：
+
+```json
+{
+  "dependencies": {
+    "@dofe/sso-contracts": "^0.1.0"
+  }
+}
+```
+
+```typescript
+import { InternalTenantSchema, TeamMemberRoleSchema } from '@dofe/sso-contracts';
+import { internalContract } from '@dofe/sso-contracts/api';
+```
+
+### 可用导出
+
+| 导出路径 | 内容 |
+|---------|------|
+| `@dofe/sso-contracts` | 所有 schemas、contracts、errors |
+| `@dofe/sso-contracts/api` | API contracts |
+| `@dofe/sso-contracts/schemas` | Zod schemas |
+| `@dofe/sso-contracts/schemas/internal` | Internal API schemas (Tenant/Team) |
+| `@dofe/sso-contracts/errors` | Error codes |
+| `@dofe/sso-contracts/base` | Base utilities (createApiResponse) |
+
+### 常见问题
+
+**Q: 发布失败 "You do not have permission"**
+
+A: 确保 npm 账户有权限发布 `@dofe` scope 包。需要先在 npmjs 创建或加入 `@dofe` organization。
+
+**Q: 发布失败 "Package already exists"**
+
+A: 版本号已存在，需要升级版本：
+```bash
+pnpm release:patch
+```
+
+**Q: 本地安装失败 "Cannot resolve @repo/contracts"**
+
+A: 这是因为 workspace 依赖问题。确保在 sso.dofe.ai 项目根目录运行 `pnpm install`。

package/dist/api/admin-setting.contract.d.ts

@@ -0,0 +1,69 @@
+export declare const adminSettingContract: {
+    getConfig: {
+        summary: "Get system configuration";
+        method: "GET";
+        path: "/admin/settings";
+        responses: {
+            200: import("zod").ZodObject<{
+                code: import("zod").ZodNumber;
+                msg: import("zod").ZodString;
+                data: import("zod").ZodObject<{
+                    siteName: import("zod").ZodNullable<import("zod").ZodString>;
+                    siteDescription: import("zod").ZodNullable<import("zod").ZodString>;
+                    defaultLanguage: import("zod").ZodString;
+                    timezone: import("zod").ZodString;
+                    rateLimit: import("zod").ZodObject<{
+                        enabled: import("zod").ZodDefault<import("zod").ZodBoolean>;
+                        points: import("zod").ZodDefault<import("zod").ZodNumber>;
+                        duration: import("zod").ZodDefault<import("zod").ZodNumber>;
+                        blockDuration: import("zod").ZodDefault<import("zod").ZodNumber>;
+                    }, import("zod/v4/core").$strip>;
+                    corsAllowedOrigins: import("zod").ZodArray<import("zod").ZodString>;
+                    updatedAt: import("zod").ZodString;
+                }, import("zod/v4/core").$strip>;
+            }, import("zod/v4/core").$strip>;
+        };
+    };
+    updateConfig: {
+        summary: "Update system configuration";
+        method: "PUT";
+        body: import("zod").ZodObject<{
+            siteName: import("zod").ZodOptional<import("zod").ZodString>;
+            siteDescription: import("zod").ZodOptional<import("zod").ZodString>;
+            defaultLanguage: import("zod").ZodOptional<import("zod").ZodEnum<{
+                en: "en";
+                "zh-CN": "zh-CN";
+            }>>;
+            timezone: import("zod").ZodOptional<import("zod").ZodString>;
+            rateLimit: import("zod").ZodOptional<import("zod").ZodObject<{
+                enabled: import("zod").ZodDefault<import("zod").ZodBoolean>;
+                points: import("zod").ZodDefault<import("zod").ZodNumber>;
+                duration: import("zod").ZodDefault<import("zod").ZodNumber>;
+                blockDuration: import("zod").ZodDefault<import("zod").ZodNumber>;
+            }, import("zod/v4/core").$strip>>;
+            corsAllowedOrigins: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        }, import("zod/v4/core").$strip>;
+        path: "/admin/settings";
+        responses: {
+            200: import("zod").ZodObject<{
+                code: import("zod").ZodNumber;
+                msg: import("zod").ZodString;
+                data: import("zod").ZodObject<{
+                    siteName: import("zod").ZodNullable<import("zod").ZodString>;
+                    siteDescription: import("zod").ZodNullable<import("zod").ZodString>;
+                    defaultLanguage: import("zod").ZodString;
+                    timezone: import("zod").ZodString;
+                    rateLimit: import("zod").ZodObject<{
+                        enabled: import("zod").ZodDefault<import("zod").ZodBoolean>;
+                        points: import("zod").ZodDefault<import("zod").ZodNumber>;
+                        duration: import("zod").ZodDefault<import("zod").ZodNumber>;
+                        blockDuration: import("zod").ZodDefault<import("zod").ZodNumber>;
+                    }, import("zod/v4/core").$strip>;
+                    corsAllowedOrigins: import("zod").ZodArray<import("zod").ZodString>;
+                    updatedAt: import("zod").ZodString;
+                }, import("zod/v4/core").$strip>;
+            }, import("zod/v4/core").$strip>;
+        };
+    };
+};
+//# sourceMappingURL=admin-setting.contract.d.ts.map

package/dist/api/admin-setting.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-setting.contract.d.ts","sourceRoot":"","sources":["../../src/api/admin-setting.contract.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwBhC,CAAC"}

package/dist/api/admin-setting.contract.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adminSettingContract = void 0;
+const core_1 = require("@ts-rest/core");
+const base_1 = require("../base");
+const admin_system_schema_1 = require("../schemas/admin-system.schema");
+const c = (0, core_1.initContract)();
+exports.adminSettingContract = c.router({
+    getConfig: {
+        method: 'GET',
+        path: '/settings',
+        responses: {
+            200: (0, base_1.ApiResponseSchema)(admin_system_schema_1.SystemConfigResponseSchema),
+        },
+        summary: 'Get system configuration',
+    },
+    updateConfig: {
+        method: 'PUT',
+        path: '/settings',
+        body: admin_system_schema_1.UpdateSystemConfigBodySchema,
+        responses: {
+            200: (0, base_1.ApiResponseSchema)(admin_system_schema_1.SystemConfigResponseSchema),
+        },
+        summary: 'Update system configuration',
+    },
+}, {
+    pathPrefix: '/admin',
+});
+//# sourceMappingURL=admin-setting.contract.js.map

package/dist/api/admin-setting.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-setting.contract.js","sourceRoot":"","sources":["../../src/api/admin-setting.contract.ts"],"names":[],"mappings":";;;AAAA,wCAA6C;AAC7C,kCAA4C;AAC5C,wEAGwC;AAExC,MAAM,CAAC,GAAG,IAAA,mBAAY,GAAE,CAAC;AAEZ,QAAA,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAC1C;IACE,SAAS,EAAE;QACT,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,WAAW;QACjB,SAAS,EAAE;YACT,GAAG,EAAE,IAAA,wBAAiB,EAAC,gDAA0B,CAAC;SACnD;QACD,OAAO,EAAE,0BAA0B;KACpC;IAED,YAAY,EAAE;QACZ,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,kDAA4B;QAClC,SAAS,EAAE;YACT,GAAG,EAAE,IAAA,wBAAiB,EAAC,gDAA0B,CAAC;SACnD;QACD,OAAO,EAAE,6BAA6B;KACvC;CACF,EACD;IACE,UAAU,EAAE,QAAQ;CACrB,CACF,CAAC"}