📝 更新枚举定义文档，简化结构并添加命名规范

2026-05-17 04:46:46 +08:00 · 2026-03-25 17:54:45 +08:00
parent 87782187d7
commit 09211c8b7f
4 changed files with 178 additions and 250 deletions
--- a/.trae/rules/typescript-rules.md
+++ b/.trae/rules/typescript-rules.md
@@ -0,0 +1,79 @@
+# TypeScript 开发规则
+
+## 禁止使用原生 enum
+
+使用 `const` 对象模式替代原生 `enum`：
+
+```typescript
+// 正确
+const GameServerEnum = <const>{
+  CN_GF01: "cn_gf01",
+  CN_QD01: "cn_qd01",
+};
+```
+
+## 类型定义
+
+类型定义放在 `src/types/<Module>/<Module>.d.ts` 或 `types/<Module>/<Module>.d.ts`
+
+Enum 常量放在 `src/enum/<Module>.ts`
+
+```typescript
+declare namespace TGApp.BBS.Post {
+  const NewsType = <const>{
+    NOTICE: 1,
+    ACTIVITY: 2,
+    NEWS: 3,
+  };
+
+  type NewsTypeEnum = (typeof NewsType)[keyof typeof NewsType];
+}
+```
+
+枚举常量引用 `const` 对象类型，而非 union type：
+
+```typescript
+// 正确
+const PostNewsTypeEnum: typeof TGApp.BBS.Post.NewsType = { ... };
+
+// 错误
+const PostNewsTypeEnum: TGApp.BBS.Post.NewsTypeEnum = { ... };
+```
+
+## 命名规范
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| Interface/Type | PascalCase | `UserProfile` |
+| const 对象 | PascalCase | `NewsType` |
+| type alias | PascalCase + Enum | `NewsTypeEnum` |
+| enum 常量 | PascalCase + Enum | `PostNewsTypeEnum` |
+| readonly 列表 | PascalCase + List | `PostNewsTypeList` |
+| 描述函数 | camelCase + Desc | `getPostNewsTypeDesc` |
+| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+
+## JSDoc 注释
+
+所有导出函数必须包含 `@since` 标签：
+
+```typescript
+/**
+ * 获取角色信息
+ * @since Beta v0.9.6
+ * @param id - 角色 ID
+ */
+function getCharacter(id: number): Character;
+```
+
+常用标签：`@param` `@returns` `@remarks` `@see` `@example` `@deprecated`
+
+## 类型注解
+
+- 函数参数和返回值必须显式类型注解
+- 优先用 `type` 而非 `interface`
+- 用 `unknown` 而非 `any`
+- 避免类型断言 (`as`)
+
+## 相关文档
+
+- [typescript-standards skill](./skills/typescript-standards/)
--- a/.trae/skills/typescript-standards/SKILL.md
+++ b/.trae/skills/typescript-standards/SKILL.md
@@ -0,0 +1,46 @@
+---
+name: "typescript-standards"
+description: "TypeScript 开发规范，包含 Enum 定义和 TSDoc 注释规范。编写 TypeScript 代码时调用此技能。"
+---
+
+# TypeScript 开发规范
+
+## 目录结构
+
+```
+src/types/<Module>/<Module>.d.ts   # 类型定义 (.d.ts)
+types/<Module>/<Module>.d.ts       # 根目录类型定义
+src/enum/<Module>.ts               # 枚举常量 (.ts)
+```
+
+## 命名规范
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| Interface/Type | PascalCase | `UserProfile` |
+| const 对象 | PascalCase | `NewsType` |
+| type alias | PascalCase + Enum | `NewsTypeEnum` |
+| enum 常量 | PascalCase + Enum | `PostNewsTypeEnum` |
+| readonly 列表 | PascalCase + List | `PostNewsTypeList` |
+| 描述函数 | camelCase + Desc | `getPostNewsTypeDesc` |
+| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+
+## 核心规则
+
+1. **禁止原生 enum** - 使用 `const` 对象模式
+2. **使用 `<const>` 断言** - 确保 readonly
+3. **类型派生** - `(typeof Type)[keyof typeof Type]`
+4. **JSDoc 注释** - 必须包含 `@since`，枚举还需 `@see`
+5. **聚合导出** - 相关枚举分组在 default export 对象中
+
+## 类型注解
+
+- 函数参数和返回值必须显式类型注解
+- 优先用 `type` 而非 `interface`
+- 用 `unknown` 而非 `any`
+- 避免类型断言 (`as`)
+
+## 详细规范
+
+- Enum 定义：见 [enum.md](./enum.md)
+- TSDoc 注释：见 [tsdoc.md](./tsdoc.md)
--- a/.trae/skills/typescript-standards/enum.md
+++ b/.trae/skills/typescript-standards/enum.md
@@ -1,54 +1,22 @@
-# Enum Type Definitions
+# Enum 定义规范

-This document defines the enumeration types used throughout the TeyvatGuide project, following the project's standard definition pattern.
-
-## Directory Structure
-
-Types can be defined in `src/types/` or at project root `types/`. Enum constants go in `enum/`. See [SKILL.md](./SKILL.md) for the complete project structure.
-
-## Definition Steps
-
-### Step 1: Define Type
-
-In `src/types/<Module>/<Module>.d.ts` or `types/<Module>.d.ts`, define a `const` object and its corresponding type:
+## 类型定义 (.d.ts)

 ```typescript
-// src/types/BBS/Post.d.ts (or types/BBS/Post.d.ts)
 declare namespace TGApp.BBS.Post {
-  /**
-   * News type
-   * @since Beta v0.9.1
-   */
  const NewsType = <const>{
-    /** Notice */
    NOTICE: 1,
-    /** Activity */
    ACTIVITY: 2,
-    /** News */
    NEWS: 3,
  };

-  /**
-   * News type enum
-   * @since Beta v0.9.1
-   */
  type NewsTypeEnum = (typeof NewsType)[keyof typeof NewsType];
 }
 ```

-### Step 2: Define Enum Constant
-
-In `src/enum/<Module>.ts`, define the corresponding enum constant:
+## 枚举常量 (.ts)

 ```typescript
-// src/enum/bbs.ts
-import TGApp from "../types/BBS/Post.d.ts";
-
-/**
- * News type
- * @since Beta v0.9.1
- * @see TGApp.BBS.Post.NewsType
- */
 const PostNewsTypeEnum: typeof TGApp.BBS.Post.NewsType = {
  NOTICE: 1,
  ACTIVITY: 2,
@@ -56,80 +24,44 @@ const PostNewsTypeEnum: typeof TGApp.BBS.Post.NewsType = {
 };
 ```

-## Naming Conventions
+注意：引用 `const` 对象类型 (`typeof TGApp.BBS.Post.NewsType`)，而非 union type (`NewsTypeEnum`)

-| Type | Naming Rule | Example |
-|------|-------------|---------|
-| const object | `<Feature>Type` | `NewsType`, `PostViewType` |
-| type alias | `<Feature>TypeEnum` | `NewsTypeEnum`, `ViewTypeEnum` |
-| enum constant | `<Feature>TypeEnum` | `PostNewsTypeEnum`, `AvatarExtTypeEnum` |
-| readonly list | `<Feature>TypeList` | `PostNewsTypeList` |
-| description function | `get<Type>Desc` | `getPostNewsTypeDesc` |
-
-## Complete Example
-
-### 1. Define Type (Post.d.ts)
+## 辅助工具

 ```typescript
-declare namespace TGApp.BBS.Post {
-  /**
-   * View type
-   * @since Beta v0.8.4
-   */
-  const PostViewType = <const>{
-    /** Normal post */
-    NORMAL: 1,
-    /** Image post, such as fan art, COS */
-    PIC: 2,
-    /** Video post */
-    VOD: 5,
-    /** UGC Thousand Stars Realm */
-    UGC: 7,
-  };
+// 只读列表
+const PostNewsTypeList: ReadonlyArray<TGApp.BBS.Post.NewsTypeEnum> = [
+  PostNewsTypeEnum.NOTICE,
+  PostNewsTypeEnum.ACTIVITY,
+  PostNewsTypeEnum.NEWS,
+];

-  /**
-   * View type enum
-   * @since Beta v0.8.4
-   */
-  type ViewTypeEnum = (typeof PostViewType)[keyof typeof PostViewType];
+// 描述函数
+function getPostNewsTypeDesc(newsType: TGApp.BBS.Post.NewsTypeEnum): string {
+  switch (newsType) {
+    case PostNewsTypeEnum.NOTICE: return "公告";
+    case PostNewsTypeEnum.ACTIVITY: return "活动";
+    case PostNewsTypeEnum.NEWS: return "资讯";
+  }
 }
 ```

-### 2. Define Enum Constant (bbs.ts)
+## 聚合导出

 ```typescript
-/**
- * Post view type
- * @since Beta v0.8.4
- * @see TGApp.BBS.Post.ViewTypeEnum
- */
-const PostViewTypeEnum: typeof TGApp.BBS.Post.PostViewType = {
-  NORMAL: 1,
-  PIC: 2,
-  VOD: 5,
-  UGC: 7,
-};
-```
-
-### 3. Export Aggregated Object (bbs.ts)
-
-```typescript
-/** MiHoYo BBS related enums */
 const bbsEnum = {
-  /** Post related enums */
  post: {
    viewType: PostViewTypeEnum,
-    // ...
+    newsType: PostNewsTypeEnum,
  },
 };

 export default bbsEnum;
 ```

-## Key Rules
+## 核心规则

-1. **Use `<const>` assertion**: Ensures the type is readonly
-2. **Type derivation**: Use `(typeof Type)[keyof typeof Type]` pattern to derive union types
-3. **JSDoc comments**: Every enum needs `@since` and `@see` comments
-4. **Naming consistency**: Enum constant names in .ts files should match const object names in .d.ts files
-5. **Export aggregated objects**: Group related enums in a default export object
+1. 使用 `<const>` 断言确保 readonly
+2. 类型派生：`(typeof Type)[keyof typeof Type]`
+3. JSDoc 必须包含 `@since` 和 `@see`
+4. 枚举常量名与 .d.ts 中的 const 对象名一致
--- a/.trae/skills/typescript-standards/tsdoc.md
+++ b/.trae/skills/typescript-standards/tsdoc.md
@@ -1,76 +1,45 @@
 # TSDoc 注释规范

-本文档定义了 TeyvatGuide 项目中 TypeScript 文件的 TSDoc 注释规范。
+## 支持的标签

-## 配置
+`@example` `@link` `@param` `@remarks` `@returns` `@see` `@since` `@typeParam` `@deprecated`

-项目 `tsdoc.json` 支持以下标签：
+## 必须标签

- `@example` - 用法示例
- `@link` - 链接引用
- `@param` - 参数说明
- `@remarks` - 备注说明
- `@returns` - 返回值说明
- `@see` - 参考引用
- `@since` - 版本信息（**必须**）
- `@TODO` - 待办事项
- `@typeParam` - 类型参数说明
- `@deprecated` - 废弃标记
+### `@since` - 版本信息

-## 必选标签
+所有导出类型、函数、枚举必须包含：

-### `@since`
+```typescript
+/**
+ * @since Beta v0.9.6
+ */
+function getCharacter(id: number): Character;
+```

-所有导出类型、函数、枚举必须包含 `@since` 标签：
+## 常用标签
+
+| 标签 | 用途 |
+|------|------|
+| `@param name - 描述` | 参数说明 |
+| `@returns 描述` | 返回值说明 |
+| `@remarks 备注` | 备注说明 |
+| `@see TGApp.BBS.Post.NewsType` | 参考引用 |
+| `@example` | 用法示例 |
+| `@deprecated` | 废弃标记 |
+
+## 示例

 ```typescript
 /**
 * 获取角色信息
 * @since Beta v0.9.6
+ * @param id - 角色 ID
+ * @returns 角色信息对象
+ * @throws {NotFoundError} 当角色不存在时
 */
-function getCharacter(id: number): Character;
+function getCharacter(id: number): Character { ... }

-/**
- * 咨讯类型
- * @since Beta v0.9.1
- */
-const NewsType = <const>{
-  NOTICE: 1,
-  ACTIVITY: 2,
-  NEWS: 3,
-};
-```
-
-## 常用标签
-
-### `@param`
-
-文档化函数参数：
-
-```typescript
-/**
- * @param name - 角色名称
- * @param level - 角色等级
- */
-function greetUser(name: string, level: number): string { ... }
-```
-
-### `@returns`
-
-文档化函数返回值：
-
-```typescript
-/**
- * @returns 格式化后的角色信息字符串
- */
-function formatCharacter(character: Character): string { ... }
-```
-
-### `@remarks`
-
-添加额外备注说明：
-
-```typescript
 /**
 * 搜索结果返回数据
 * @remarks token_list 和 databox 目前用途不明
@@ -78,127 +47,29 @@ function formatCharacter(character: Character): string { ... }
 type SearchRes = { ... };
 ```

-### `@see`
-
-引用相关文档或代码：
-
-```typescript
-/**
- * 用户头像类型
- * @since Beta v0.7.9
- * @see TGApp.BBS.User.AvatarExtTypeEnum
- */
-const AvatarExtTypeEnum = { ... };
-```
-
-### `@example`
-
-提供用法示例：
-
-```typescript
-/**
- * @example
- * const result = getPostNewsTypeDesc(PostNewsTypeEnum.NOTICE);
- * // result === "公告"
- */
-function getPostNewsTypeDesc(newsType: NewsTypeEnum): string { ... }
-```
-
-### `@deprecated`
-
-标记废弃代码：
-
-```typescript
-/**
- * @deprecated Use `getCharacterV2` instead
- */
-function getCharacter(id: number): Character { ... }
-```
-
 ## 类型定义文件 (.d.ts)

-命名空间内的类型定义注释规范：
-
 ```typescript
 declare namespace TGApp.BBS.Post {
  /**
   * 咨讯类型
   * @since Beta v0.9.1
-   * @remarks 用于相关接口参数请求
   */
  const NewsType = <const>{
-    /** 公告 */
    NOTICE: 1,
-    /** 活动 */
    ACTIVITY: 2,
-    /** 咨讯 */
    NEWS: 3,
  };
-
-  /**
-   * 咨讯类型枚举
-   * @since Beta v0.9.1
-   */
-  type NewsTypeEnum = (typeof NewsType)[keyof typeof NewsType];
 }
 ```

-## Enum 常量文件 (.ts)
-
-枚举常量的注释规范：
-
-```typescript
-/**
- * 咨讯类型
- * @since Beta v0.9.1
- * @see TGApp.BBS.Post.NewsType
- */
-const PostNewsTypeEnum: typeof TGApp.BBS.Post.NewsType = {
-  NOTICE: 1,
-  ACTIVITY: 2,
-  NEWS: 3,
-};
-```
-
-## 接口和类型
-
-```typescript
-/**
- * 帖子数据
- * @since Beta v0.9.8
- */
-type FullData = {
-  /** 帖子信息 */
-  post: Post;
-  /** 所属版块，可能为 null */
-  forum: Forum | null;
-  /** 图片列表 */
-  image_list: Array<Image>;
-};
-```
-
 ## 内联成员注释

-对象类型内部成员可以直接在成员前添加 JSDoc：
-
 ```typescript
 type TGHttpParams = {
  /** 请求方法 */
  method: "GET" | "POST";
  /** 请求头 */
  headers?: Record<string, string>;
-  /** 是否是Blob */
-  isBlob?: boolean;
 };
-```
-
-## 命名规范
-
-| 类型 | 注释规范 |
-|------|----------|
-| 文件级 | 放在 `declare namespace` 之前 |
-| 类型/接口 | 放在 `type` 之前，描述数据类型 |
-| const 对象 | 放在 `const` 之前，描述枚举用途 |
-| 函数 | 放在函数前，描述功能 |
-| 参数 | 使用 `@param` 或内联 `/** */` |
-| 成员 | 使用内联 `/** */` |
+```