npm - @zeyue0329/xiaoma-cli - Versions diffs - 1.6.4 → 1.7.0 - Mend

@zeyue0329/xiaoma-cli 1.6.4 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (950) hide show

package/docs/rag/rag.md DELETED Viewed

@@ -1,856 +0,0 @@
-# 知识库 - RAG 文档
-> 本文档作为全自动迭代开发的知识库数据源，包含业务知识和技术知识。
-> 在 MCP 知识库服务上线前，智能体将从此文件检索所需知识。
----
-# 第一部分：业务知识
----
-## 1. 业务术语表
-<!-- KB-TYPE: business_term -->
-<!-- KB-KEYWORDS: 术语, 定义, 概念 -->
-### 术语: 用户 (User)
-- **定义**: 系统的注册使用者，拥有唯一的账号标识
-- **属性**: 用户ID、邮箱、手机号、昵称、头像、注册时间、最后登录时间
-- **相关概念**: 账号、会员、角色
-### 术语: 偏好设置 (Preference)
-- **定义**: 用户的个性化配置项，影响系统行为和展示方式
-- **类型**: 显示偏好、通知偏好、隐私偏好、功能偏好
-- **存储**: 键值对形式，支持JSON复杂值
-### 术语: 角色 (Role)
-- **定义**: 用户在系统中的身份类型，决定其权限范围
-- **预设角色**: 管理员(admin)、普通用户(user)、访客(guest)
-- **权限关联**: 每个角色关联一组权限
-### 术语: 权限 (Permission)
-- **定义**: 对系统资源或操作的访问控制标识
-- **格式**: `resource:action`，如 `user:read`、`preference:write`
-- **继承**: 角色继承权限，用户继承角色
----
-## 2. 业务规则
-<!-- KB-TYPE: business_rule -->
-<!-- KB-KEYWORDS: 规则, 业务逻辑, 约束 -->
-### 规则: BR-001 用户注册规则
-- **描述**: 新用户注册时必须满足的条件
-- **规则内容**:
-  1. 邮箱必须唯一，格式合法
-  2. 密码长度 8-32 位，必须包含字母和数字
-  3. 手机号可选，如填写必须唯一
-  4. 昵称长度 2-20 个字符
-  5. 必须同意服务条款
-- **例外**: 第三方OAuth注册可跳过密码设置
-### 规则: BR-002 用户认证规则
-- **描述**: 用户登录认证的业务规则
-- **规则内容**:
-  1. 支持邮箱+密码、手机号+验证码、OAuth三种方式
-  2. 连续5次密码错误锁定账号30分钟
-  3. 登录成功生成JWT Token，有效期7天
-  4. 敏感操作需要二次验证
-- **安全要求**: 密码传输必须加密，存储使用bcrypt哈希
-### 规则: BR-003 偏好设置规则
-- **描述**: 用户偏好设置的业务规则
-- **规则内容**:
-  1. 每个用户可设置最多100个偏好项
-  2. 偏好键名长度不超过100字符
-  3. 偏好值大小不超过10KB
-  4. 支持批量导入导出
-  5. 偏好变更记录保留30天
-- **默认值**: 新用户使用系统默认偏好
-### 规则: BR-004 数据验证规则
-- **描述**: 通用的数据验证规则
-- **规则内容**:
-  1. 所有用户输入必须验证和清理
-  2. ID字段使用UUID格式
-  3. 时间字段使用ISO 8601格式
-  4. 金额字段保留2位小数
-  5. 字符串字段去除首尾空格
-- **安全**: 防止XSS和SQL注入
-### 规则: BR-005 权限控制规则
-- **描述**: 系统权限控制的业务规则
-- **规则内容**:
-  1. 未登录用户只能访问公开资源
-  2. 普通用户只能操作自己的数据
-  3. 管理员可以操作所有用户数据
-  4. 敏感操作需要记录审计日志
-- **最小权限原则**: 默认拒绝，显式授权
----
-## 3. 业务流程
-<!-- KB-TYPE: business_process -->
-<!-- KB-KEYWORDS: 流程, 步骤, 工作流 -->
-### 流程: 用户注册流程
-```
-1. 用户填写注册信息
-   ↓
-2. 系统验证信息格式
-   ├─ 验证失败 → 返回错误提示
-   ↓
-3. 检查邮箱/手机号唯一性
-   ├─ 已存在 → 提示已注册
-   ↓
-4. 创建用户账号
-   ↓
-5. 发送验证邮件/短信
-   ↓
-6. 用户验证
-   ├─ 超时未验证 → 账号待激活状态
-   ↓
-7. 激活账号，注册完成
-```
-### 流程: 用户登录流程
-```
-1. 用户输入凭证
-   ↓
-2. 验证凭证格式
-   ├─ 格式错误 → 返回错误提示
-   ↓
-3. 查询用户信息
-   ├─ 用户不存在 → 返回"用户不存在"
-   ↓
-4. 验证密码/验证码
-   ├─ 验证失败 → 记录失败次数，检查是否锁定
-   ↓
-5. 检查账号状态
-   ├─ 账号锁定/禁用 → 返回相应提示
-   ↓
-6. 生成Token
-   ↓
-7. 更新最后登录时间
-   ↓
-8. 返回登录成功
-```
-### 流程: 偏好设置更新流程
-```
-1. 用户发起偏好更新请求
-   ↓
-2. 验证用户身份（Token验证）
-   ├─ 验证失败 → 返回401
-   ↓
-3. 验证请求数据格式
-   ├─ 格式错误 → 返回400
-   ↓
-4. 检查偏好键名是否合法
-   ├─ 非法键名 → 返回错误
-   ↓
-5. 检查用户偏好数量限制
-   ├─ 超出限制 → 返回错误
-   ↓
-6. 更新/创建偏好记录
-   ↓
-7. 记录变更日志
-   ↓
-8. 返回更新成功
-```
----
-## 4. 用户角色定义
-<!-- KB-TYPE: user_role -->
-<!-- KB-KEYWORDS: 角色, 用户类型, 权限 -->
-### 角色: 管理员 (Admin)
-- **职责**: 系统管理、用户管理、配置管理
-- **权限范围**:
-  - 所有用户数据的读写权限
-  - 系统配置的管理权限
-  - 审计日志的查看权限
-- **使用场景**: 后台管理、运维操作
-### 角色: 普通用户 (User)
-- **职责**: 使用系统功能、管理个人数据
-- **权限范围**:
-  - 自己数据的读写权限
-  - 公开数据的只读权限
-- **使用场景**: 日常业务操作
-### 角色: 访客 (Guest)
-- **职责**: 浏览公开内容
-- **权限范围**:
-  - 公开数据的只读权限
-- **使用场景**: 未登录状态
----
-## 5. 验收标准参考
-<!-- KB-TYPE: acceptance_criteria -->
-<!-- KB-KEYWORDS: 验收, 测试场景, 边界条件 -->
-### 验收标准模板: 列表查询功能
-```gherkin
-# 正常场景
-Given 用户已登录
-When 用户请求查询列表
-Then 返回用户有权限的数据列表
-# 分页场景
-Given 用户已登录
-And 数据总数超过单页限制
-When 用户请求第N页数据
-Then 返回第N页的数据
-And 返回总数和分页信息
-# 空数据场景
-Given 用户已登录
-And 无匹配数据
-When 用户请求查询列表
-Then 返回空列表
-And 返回总数为0
-# 权限不足场景
-Given 用户已登录
-And 用户无查询权限
-When 用户请求查询列表
-Then 返回403权限不足
-```
-### 验收标准模板: 表单提交功能
-```gherkin
-# 正常提交
-Given 用户已登录
-And 用户有提交权限
-When 用户提交有效数据
-Then 数据保存成功
-And 返回成功响应
-# 数据验证失败
-Given 用户已登录
-When 用户提交无效数据
-Then 返回验证错误详情
-And 数据未保存
-# 重复提交
-Given 用户已登录
-And 用户已提交相同数据
-When 用户再次提交相同数据
-Then 返回重复提交错误
-```
----
-# 第二部分：技术知识
----
-## 6. 技术栈规范
-<!-- KB-TYPE: tech_spec -->
-<!-- KB-KEYWORDS: 技术栈, 框架, 版本 -->
-### 前端技术栈
-- **框架**: React 18.x
-- **状态管理**: Zustand / Redux Toolkit
-- **UI组件库**: Ant Design 5.x
-- **HTTP客户端**: Axios
-- **构建工具**: Vite
-- **语言**: TypeScript 5.x
-### 后端技术栈
-- **运行时**: Node.js 20.x LTS
-- **框架**: Express 4.x / Fastify 4.x
-- **ORM**: Prisma 5.x
-- **验证**: Zod
-- **日志**: Pino
-- **语言**: TypeScript 5.x
-### 数据库
-- **主数据库**: PostgreSQL 15.x
-- **缓存**: Redis 7.x
-- **搜索**: Elasticsearch 8.x (可选)
-### 测试工具
-- **单元测试**: Vitest
-- **E2E测试**: Playwright
-- **API测试**: Supertest
----
-## 7. 编码规范
-<!-- KB-TYPE: coding_standard -->
-<!-- KB-KEYWORDS: 命名, 格式, 代码风格 -->
-### 命名规范
-#### 变量和函数
-```typescript
-// 变量: camelCase
-const userName = 'John';
-const isActive = true;
-const maxRetryCount = 3;
-// 函数: camelCase，动词开头
-function getUserById(id: string): User {}
-function validateEmail(email: string): boolean {}
-async function fetchUserPreferences(userId: string): Promise<Preference[]> {}
-```
-#### 类和接口
-```typescript
-// 类: PascalCase
-class UserService {}
-class PreferenceRepository {}
-// 接口: PascalCase，不加I前缀
-interface User {}
-interface CreateUserDto {}
-// 类型: PascalCase
-type UserId = string;
-type PreferenceKey = string;
-```
-#### 常量和枚举
-```typescript
-// 常量: UPPER_SNAKE_CASE
-const MAX_RETRY_COUNT = 3;
-const DEFAULT_PAGE_SIZE = 20;
-// 枚举: PascalCase，成员 PascalCase
-enum UserStatus {
-  Active = 'active',
-  Inactive = 'inactive',
-  Suspended = 'suspended',
-}
-```
-#### 文件命名
-```
-# 组件: PascalCase
-UserProfile.tsx
-PreferenceList.tsx
-# 服务/工具: camelCase
-userService.ts
-preferenceRepository.ts
-# 测试: 原文件名.test.ts
-userService.test.ts
-PreferenceList.test.tsx
-```
-### 代码格式规范
-- 缩进: 2空格
-- 行宽: 100字符
-- 分号: 必须
-- 引号: 单引号（JSX中双引号）
-- 尾逗号: ES5模式
----
-## 8. 架构模式
-<!-- KB-TYPE: architecture_pattern -->
-<!-- KB-KEYWORDS: 架构, 模式, 设计 -->
-### 分层架构
-```
-┌─────────────────────────────────────┐
-│          Controller Layer           │  处理HTTP请求/响应
-├─────────────────────────────────────┤
-│           Service Layer             │  业务逻辑
-├─────────────────────────────────────┤
-│         Repository Layer            │  数据访问
-├─────────────────────────────────────┤
-│           Database Layer            │  数据存储
-└─────────────────────────────────────┘
-```
-### Repository Pattern
-```typescript
-// 仓储接口
-interface UserRepository {
-  findById(id: string): Promise<User | null>;
-  findByEmail(email: string): Promise<User | null>;
-  create(data: CreateUserDto): Promise<User>;
-  update(id: string, data: UpdateUserDto): Promise<User>;
-  delete(id: string): Promise<void>;
-}
-// 仓储实现
-class PrismaUserRepository implements UserRepository {
-  constructor(private prisma: PrismaClient) {}
-  async findById(id: string): Promise<User | null> {
-    return this.prisma.user.findUnique({ where: { id } });
-  }
-  // ... 其他方法
-}
-```
-### Service Layer Pattern
-```typescript
-// 服务类
-class UserService {
-  constructor(
-    private userRepository: UserRepository,
-    private emailService: EmailService,
-  ) {}
-  async createUser(dto: CreateUserDto): Promise<User> {
-    // 1. 验证业务规则
-    await this.validateCreateUser(dto);
-    // 2. 创建用户
-    const user = await this.userRepository.create(dto);
-    // 3. 发送欢迎邮件
-    await this.emailService.sendWelcome(user.email);
-    return user;
-  }
-}
-```
----
-## 9. API 设计规范
-<!-- KB-TYPE: api_spec -->
-<!-- KB-KEYWORDS: API, RESTful, 接口 -->
-### URL 命名规范
-```
-# 资源命名: 复数名词
-GET    /api/v1/users           # 获取用户列表
-GET    /api/v1/users/:id       # 获取单个用户
-POST   /api/v1/users           # 创建用户
-PUT    /api/v1/users/:id       # 更新用户
-DELETE /api/v1/users/:id       # 删除用户
-# 子资源
-GET    /api/v1/users/:id/preferences    # 获取用户偏好
-POST   /api/v1/users/:id/preferences    # 创建用户偏好
-# 操作
-POST   /api/v1/users/:id/activate       # 激活用户
-POST   /api/v1/auth/login               # 登录
-POST   /api/v1/auth/logout              # 登出
-```
-### 响应格式规范
-```typescript
-// 成功响应
-{
-  "code": 200,
-  "message": "success",
-  "data": {
-    // 实际数据
-  }
-}
-// 列表响应
-{
-  "code": 200,
-  "message": "success",
-  "data": {
-    "items": [...],
-    "pagination": {
-      "page": 1,
-      "pageSize": 20,
-      "total": 100,
-      "totalPages": 5
-    }
-  }
-}
-// 错误响应
-{
-  "code": 400,
-  "message": "Validation failed",
-  "errors": [
-    {
-      "field": "email",
-      "message": "Invalid email format"
-    }
-  ]
-}
-```
-### 错误码规范
-```typescript
-// HTTP 状态码使用
-200 - OK                 // 成功
-201 - Created            // 创建成功
-204 - No Content         // 删除成功
-400 - Bad Request        // 请求参数错误
-401 - Unauthorized       // 未认证
-403 - Forbidden          // 无权限
-404 - Not Found          // 资源不存在
-409 - Conflict           // 冲突（如重复创建）
-422 - Unprocessable      // 业务规则验证失败
-500 - Internal Error     // 服务器错误
-// 业务错误码
-{
-  "USER_NOT_FOUND": "用户不存在",
-  "USER_ALREADY_EXISTS": "用户已存在",
-  "INVALID_CREDENTIALS": "凭证无效",
-  "ACCOUNT_LOCKED": "账号已锁定",
-  "PREFERENCE_LIMIT_EXCEEDED": "偏好数量超出限制",
-}
-```
----
-## 10. 测试规范
-<!-- KB-TYPE: testing_standard -->
-<!-- KB-KEYWORDS: 测试, 单元测试, 覆盖率 -->
-### 单元测试规范
-#### 测试文件组织
-```
-src/
-├── services/
-│   └── userService.ts
-tests/
-├── services/
-│   └── userService.test.ts
-```
-#### 测试命名规范
-```typescript
-describe('UserService', () => {
-  describe('createUser', () => {
-    it('should create user when valid data provided', async () => {});
-    it('should throw error when email already exists', async () => {});
-    it('should send welcome email after user created', async () => {});
-  });
-});
-```
-#### AAA 模式
-```typescript
-it('should return user preferences', async () => {
-  // Arrange - 准备测试数据和依赖
-  const userId = 'user-123';
-  const mockPreferences = [{ key: 'theme', value: 'dark' }];
-  mockRepository.findByUserId.mockResolvedValue(mockPreferences);
-  // Act - 执行被测方法
-  const result = await service.getPreferences(userId);
-  // Assert - 验证结果
-  expect(result).toEqual(mockPreferences);
-  expect(mockRepository.findByUserId).toHaveBeenCalledWith(userId);
-});
-```
-### 覆盖率要求
-- **语句覆盖率**: >= 80%
-- **分支覆盖率**: >= 75%
-- **函数覆盖率**: >= 85%
-- **行覆盖率**: >= 80%
-### 测试边界条件
-```typescript
-// 必须测试的边界条件
-- 空输入 (null, undefined, '')
-- 空数组 ([])
-- 边界值 (最小值、最大值)
-- 无效格式
-- 权限不足
-- 资源不存在
-- 并发操作
-```
----
-## 11. 错误处理规范
-<!-- KB-TYPE: error_handling -->
-<!-- KB-KEYWORDS: 错误, 异常, 处理 -->
-### 自定义错误类
-```typescript
-// 基础业务错误
-class BusinessError extends Error {
-  constructor(
-    public code: string,
-    message: string,
-    public statusCode: number = 400,
-  ) {
-    super(message);
-    this.name = 'BusinessError';
-  }
-}
-// 具体错误类型
-class NotFoundError extends BusinessError {
-  constructor(resource: string, id: string) {
-    super('NOT_FOUND', `${resource} with id ${id} not found`, 404);
-  }
-}
-class ValidationError extends BusinessError {
-  constructor(public errors: Array<{ field: string; message: string }>) {
-    super('VALIDATION_ERROR', 'Validation failed', 400);
-  }
-}
-class UnauthorizedError extends BusinessError {
-  constructor(message = 'Unauthorized') {
-    super('UNAUTHORIZED', message, 401);
-  }
-}
-```
-### 错误处理中间件
-```typescript
-function errorHandler(err: Error, req: Request, res: Response, next: NextFunction) {
-  // 记录错误日志
-  logger.error({
-    error: err.message,
-    stack: err.stack,
-    path: req.path,
-    method: req.method,
-  });
-  // 业务错误
-  if (err instanceof BusinessError) {
-    return res.status(err.statusCode).json({
-      code: err.statusCode,
-      message: err.message,
-      errorCode: err.code,
-    });
-  }
-  // 未知错误
-  return res.status(500).json({
-    code: 500,
-    message: 'Internal server error',
-  });
-}
-```
----
-## 12. 安全规范
-<!-- KB-TYPE: security_standard -->
-<!-- KB-KEYWORDS: 安全, 认证, 授权 -->
-### 认证规范
-```typescript
-// JWT Token 结构
-{
-  "sub": "user-id",           // 用户ID
-  "email": "user@example.com", // 用户邮箱
-  "role": "user",              // 用户角色
-  "iat": 1234567890,           // 签发时间
-  "exp": 1234567890            // 过期时间
-}
-// Token 有效期
-- Access Token: 15分钟
-- Refresh Token: 7天
-```
-### 输入验证规范
-```typescript
-// 使用 Zod 进行验证
-const createUserSchema = z.object({
-  email: z.string().email(),
-  password: z.string().min(8).max(32),
-  nickname: z.string().min(2).max(20),
-});
-// 验证并清理输入
-function validateInput<T>(schema: ZodSchema<T>, data: unknown): T {
-  return schema.parse(data);
-}
-```
-### 敏感数据处理
-```typescript
-// 密码哈希
-import bcrypt from 'bcrypt';
-const SALT_ROUNDS = 12;
-async function hashPassword(password: string): Promise<string> {
-  return bcrypt.hash(password, SALT_ROUNDS);
-}
-// 日志脱敏
-function sanitizeLog(data: object): object {
-  const sensitiveFields = ['password', 'token', 'secret'];
-  return Object.entries(data).reduce((acc, [key, value]) => {
-    acc[key] = sensitiveFields.includes(key) ? '***' : value;
-    return acc;
-  }, {});
-}
-```
----
-## 13. 性能规范
-<!-- KB-TYPE: performance_standard -->
-<!-- KB-KEYWORDS: 性能, 响应时间, 优化 -->
-### 响应时间要求
-| 操作类型  | 目标响应时间 | 最大响应时间 |
-| --------- | ------------ | ------------ |
-| 简单查询  | < 100ms      | < 500ms      |
-| 复杂查询  | < 500ms      | < 2s         |
-| 列表分页  | < 200ms      | < 1s         |
-| 创建/更新 | < 200ms      | < 1s         |
-| 文件上传  | < 3s         | < 10s        |
-### 数据库优化
-```sql
--- 必须添加索引的场景
-- 主键
-- 外键
-- 经常作为查询条件的字段
-- 排序字段
-- 唯一约束字段
--- 示例
-CREATE INDEX idx_users_email ON users(email);
-CREATE INDEX idx_preferences_user_id ON user_preferences(user_id);
-```
-### 分页规范
-```typescript
-// 默认分页参数
-const DEFAULT_PAGE = 1;
-const DEFAULT_PAGE_SIZE = 20;
-const MAX_PAGE_SIZE = 100;
-// 分页响应
-interface PaginatedResponse<T> {
-  items: T[];
-  pagination: {
-    page: number;
-    pageSize: number;
-    total: number;
-    totalPages: number;
-  };
-}
-```
----
-# 第三部分：项目特定知识
----
-## 14. 项目约定
-<!-- KB-TYPE: project_convention -->
-<!-- KB-KEYWORDS: 项目, 约定, 配置 -->
-### 目录结构
-```
-project-root/
-├── src/
-│   ├── controllers/     # 控制器
-│   ├── services/        # 业务服务
-│   ├── repositories/    # 数据仓储
-│   ├── models/          # 数据模型
-│   ├── middlewares/     # 中间件
-│   ├── utils/           # 工具函数
-│   ├── types/           # 类型定义
-│   └── config/          # 配置
-├── tests/
-│   ├── unit/            # 单元测试
-│   ├── integration/     # 集成测试
-│   └── e2e/             # E2E测试
-├── prisma/
-│   └── schema.prisma    # 数据库Schema
-├── docs/
-│   └── rag/             # 知识库文档
-└── package.json
-```
-### 环境配置
-```bash
-# 开发环境
-DATABASE_URL=postgresql://localhost:5432/dev
-REDIS_URL=redis://localhost:6379
-JWT_SECRET=dev-secret
-# 测试环境
-DATABASE_URL=postgresql://localhost:5432/test
-REDIS_URL=redis://localhost:6379
-JWT_SECRET=test-secret
-```
----
-## 更新日志
-| 日期       | 版本  | 更新内容 |
-| ---------- | ----- | -------- |
-| 2024-01-15 | 1.0.0 | 初始版本 |