# personal-knowledge

**Repository Path**: knowledge_12/personal-knowledge

## Basic Information

- **Project Name**: personal-knowledge
- **Description**: 个人知识库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-11-16
- **Last Updated**: 2025-11-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 个人知识库系统设计文档

本项目基于 NestJS 构建，目标是提供一套支持多用户、标签管理、层级文件夹以及协作功能的个人知识库后端服务。本文件用于帮助开发者快速了解系统架构、技术栈、数据库设计与后续迭代规划。

## 目录

1. 项目概览  
2. 技术栈与依赖  
3. 快速开始  
4. 配置管理  
5. 项目结构说明  
6. 模块职责  
7. 数据库设计  
8. API 设计约定  
9. 安全与权限模型  
10. 日志与监控  
11. 部署建议  
12. 迭代规划

---

## 1. 项目概览

- **项目名称**：Personal Knowledge  
- **架构风格**：单体 NestJS 应用，按领域模块化组织  
- **核心能力**：
  - 用户注册、登录、鉴权与多角色支持
  - 文件夹层级管理、标签管理、笔记富文本存储
  - 笔记与标签的多对多关联
  - 协作成员与权限划分
  - 操作日志记录（预留）
- **目标人群**：需要构建个人/团队知识管理平台的开发者

## 2. 技术栈与依赖

- **运行时**：Node.js 18+（建议使用 pnpm 进行依赖管理）
- **框架**：NestJS 10
- **ORM**：TypeORM 0.3，数据库默认 MySQL 8
- **认证**：`@nestjs/jwt`，可扩展 `passport` 策略
- **配置**：`@nestjs/config` + `dotenv`
- **文档**：`@nestjs/swagger`
- **数据验证**：推荐补充 `class-validator`/`class-transformer`（项目已包含 `class-transformer`）
- **日志**：Nest 内置 Logger（建议结合自定义拦截器/管道）
- **测试**：Jest + Supertest
- **其他建议依赖**（后续引入）：
  - `bcrypt` / `argon2`：密码加密
  - `class-validator`：DTO 校验
  - `@nestjs/passport` + `passport-jwt`：标准化鉴权
  - `cache-manager`、`@nestjs/throttler`：缓存与限流

## 3. 快速开始

1. 安装依赖  
   ```bash
   pnpm install
   ```
2. 准备环境变量 `.env`，包含数据库与 JWT 配置（详见下一节）。  
3. 初始化数据库（可使用 TypeORM migration，后续补充命令）。  
4. 开发模式启动  
   ```bash
   pnpm start:dev
   ```
5. 构建与生产启动  
   ```bash
  pnpm build
  pnpm start:prod
   ```

## 4. 配置管理

项目依赖 `.env` 文件，建议最小化配置如下：

```
NODE_ENV=development
APP_PORT=3000
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_USER=root
DATABASE_PASSWORD=secret
DATABASE_NAME=personal_knowledge
JWT_SECRET=replace_with_strong_secret
JWT_EXPIRES_IN=3600s
```

推荐通过 `@nestjs/config` 结合 Joi 校验配置合法性，并按环境拆分 `config` 目录（如 `config/database.config.ts`、`config/jwt.config.ts`）。

## 5. 项目结构说明

```
src
├── app.controller.ts        # 健康检查或示例接口
├── app.module.ts            # 根模块，聚合全局 Provider
├── app.service.ts
├── common
│   ├── context
│   │   └── request-context.service.ts  # 请求级上下文（当前用户等）
│   ├── entities
│   │   └── base.ts                     # 基础实体抽象（待扩展）
├── interfaces
│   ├── pagination.interface.ts         # 通用分页接口定义
│   └── response.interface.ts           # 统一响应结构
├── modules
│   ├── auth                            # 认证登录相关
│   ├── user                            # 用户管理
│   ├── folder                          # 文件夹管理
│   ├── note                            # 笔记管理
│   ├── tags                            # 标签管理
│   ├── roles                           # 角色/权限
│   └── logs                            # 操作日志
├── utils
│   └── response.util.ts                # 响应封装工具
└── main.ts                             # 应用入口
```

> 大部分模块仅创建空壳文件，需逐步补充 Controller、Service、DTO、Entity 及对应测试。

## 6. 模块职责

- **auth**：用户认证、JWT 颁发、刷新、密码加密、登录日志。
- **user**：用户资料维护、密码修改、个人设置。
- **folder**：文件夹 CRUD、层级查询、拖拽排序（可扩展）。
- **note**：笔记 CRUD、富文本/Markdown 存储、版本控制（规划中）。
- **tags**：标签管理、标签与笔记关联维护。
- **roles**：角色定义、权限点与菜单（后续补充 permissions 模块）。
- **logs**：记录用户操作和系统事件，用于审计和统计。

建议创建 `shared`/`common` 目录用于存放装饰器、拦截器、守卫、过滤器等可复用组件。

## 7. 数据库设计

### 7.1 实体关系概览

```
User 1─n Folder      Folder 1─n Folder (自关联)
User 1─n Note        Folder 1─n Note
User 1─n Tag         Note n─m Tag (NoteTag)
User 1─n Collaboration
Note 1─n Collaboration
Role 1─n UserRole    Role n─m Permission (规划)
```

### 7.2 数据表定义

#### users

| 字段名     | 类型        | 约束                 | 描述           |
| ---------- | ----------- | -------------------- | -------------- |
| id         | varchar(36) | PK, cuid             | 用户主键       |
| username   | varchar(50) | unique               | 用户名         |
| email      | varchar(100)| unique               | 邮箱           |
| password   | varchar(255)| not null             | 加密后的密码   |
| name       | varchar(100)| nullable             | 显示名称       |
| avatar     | varchar(255)| nullable             | 头像 URL       |
| status     | tinyint     | default 1            | 状态（1=启用） |
| created_at | datetime    | default CURRENT_TIMESTAMP | 创建时间 |
| updated_at | datetime    | on update CURRENT_TIMESTAMP | 更新时间 |

索引：`PRIMARY(id)`、`UNIQUE(username)`、`UNIQUE(email)`

#### folders

| 字段名     | 类型        | 约束                             | 描述          |
| ---------- | ----------- | -------------------------------- | ------------- |
| id         | varchar(36) | PK, cuid                         | 文件夹主键    |
| name       | varchar(100)| not null                         | 文件夹名称    |
| description| text        | nullable                         | 描述          |
| color      | varchar(20) | nullable                         | 颜色标记      |
| icon       | varchar(50) | nullable                         | 图标名        |
| parent_id  | varchar(36) | FK → folders.id, nullable        | 父级文件夹    |
| user_id    | varchar(36) | FK → users.id                    | 所属用户      |
| sort_order | int         | default 0                        | 排序          |
| created_at | datetime    | default CURRENT_TIMESTAMP        | 创建时间      |
| updated_at | datetime    | on update CURRENT_TIMESTAMP      | 更新时间      |

索引：`PRIMARY(id)`、`INDEX(parent_id)`、`INDEX(user_id)`、`UNIQUE(user_id, name, parent_id)`

#### notes

| 字段名       | 类型        | 约束                            | 描述             |
| ------------ | ----------- | ------------------------------- | ---------------- |
| id           | varchar(36) | PK, cuid                        | 笔记主键         |
| title        | varchar(200)| not null                        | 标题             |
| content      | longtext    | not null                        | 内容（富文本/MD）|
| excerpt      | text        | nullable                        | 摘要             |
| is_public    | tinyint     | default 0                       | 是否公开         |
| public_slug  | varchar(100)| unique, nullable                | 公开访问 slug    |
| is_deleted   | tinyint     | default 0                       | 软删除标记       |
| content_type | varchar(30) | default 'rich-text'             | 内容类型         |
| user_id      | varchar(36) | FK → users.id                   | 所属用户         |
| folder_id    | varchar(36) | FK → folders.id, nullable       | 所属文件夹       |
| created_at   | datetime    | default CURRENT_TIMESTAMP       | 创建时间         |
| updated_at   | datetime    | on update CURRENT_TIMESTAMP     | 更新时间         |

索引：`PRIMARY(id)`、`UNIQUE(public_slug)`、`INDEX(user_id)`、`INDEX(folder_id)`、`INDEX(user_id, is_deleted)`

#### tags

| 字段名     | 类型        | 约束                      | 描述     |
| ---------- | ----------- | ------------------------- | -------- |
| id         | varchar(36) | PK, cuid                  | 标签主键 |
| name       | varchar(50) | unique                    | 标签名   |
| color      | varchar(20) | nullable                  | 颜色     |
| icon       | varchar(50) | nullable                  | 图标     |
| user_id    | varchar(36) | FK → users.id             | 所属用户 |
| created_at | datetime    | default CURRENT_TIMESTAMP | 创建时间 |
| updated_at | datetime    | on update CURRENT_TIMESTAMP | 更新时间 |

索引：`PRIMARY(id)`、`UNIQUE(user_id, name)`、`INDEX(user_id)`

#### note_tags

| 字段名     | 类型        | 约束                      | 描述     |
| ---------- | ----------- | ------------------------- | -------- |
| id         | varchar(36) | PK, cuid                  | 主键     |
| note_id    | varchar(36) | FK → notes.id             | 笔记 ID  |
| tag_id     | varchar(36) | FK → tags.id              | 标签 ID  |
| created_at | datetime    | default CURRENT_TIMESTAMP | 创建时间 |

索引：`PRIMARY(id)`、`UNIQUE(note_id, tag_id)`、`INDEX(tag_id)`

#### collaborations

| 字段名     | 类型        | 约束                                  | 描述         |
| ---------- | ----------- | ------------------------------------- | ------------ |
| id         | varchar(36) | PK, cuid                              | 协作主键     |
| note_id    | varchar(36) | FK → notes.id                         | 笔记 ID      |
| user_id    | varchar(36) | FK → users.id                         | 协作者 ID    |
| role       | varchar(30) | default 'collaborator'                | 协作角色     |
| created_at | datetime    | default CURRENT_TIMESTAMP             | 创建时间     |
| updated_at | datetime    | on update CURRENT_TIMESTAMP           | 更新时间     |

索引：`PRIMARY(id)`、`UNIQUE(note_id, user_id)`、`INDEX(user_id)`

#### roles

| 字段名     | 类型        | 约束                      | 描述         |
| ---------- | ----------- | ------------------------- | ------------ |
| id         | varchar(36) | PK, cuid                  | 角色主键     |
| code       | varchar(50) | unique                    | 角色编码     |
| name       | varchar(50) | not null                  | 角色名称     |
| description| varchar(255)| nullable                  | 描述         |
| is_system  | tinyint     | default 0                 | 是否系统内置 |
| created_at | datetime    | default CURRENT_TIMESTAMP | 创建时间     |
| updated_at | datetime    | on update CURRENT_TIMESTAMP | 更新时间   |

规划中还可补充 `permissions`、`role_permissions`、`user_roles` 等表以完善 RBAC/ABAC。

## 8. API 设计约定

- **风格**：RESTful，路径使用复数资源名，如 `/api/v1/notes`。
- **版本管理**：通过全局前缀 `api/v1` 实现。
- **认证**：所有受保护接口要求 `Authorization: Bearer <token>`。
- **请求校验**：DTO + ValidationPipe（需引入 `class-validator`）。
- **分页**：统一使用 `page`/`pageSize`，返回 `Pagination<T>` 接口定义。
- **响应结构**：使用 `response.util.ts` 提供的统一格式 `{ code, message, data }`。
- **错误处理**：Global Exception Filter 统一封装错误码与日志。
- **文档**：Swagger 暴露在 `/docs`，需在 `main.ts` 中启用。

## 9. 安全与权限模型

- 使用 JWT 进行认证，建议配合 Refresh Token 与黑名单机制。
- 引入角色（Role）与权限点（Permission），结合自定义 `@Permissions()` 装饰器与 Guard。
- 支持资源级权限：如笔记可设为私有/共享/公开；协作者拥有特定操作权限（读/写/管理）。
- 增加常见安全策略：密码强度校验、防止暴力破解（限流/验证码）、敏感操作双重确认。

## 10. 日志与监控

- **请求日志**：通过拦截器记录请求耗时与状态码。
- **操作日志**：`logs` 模块记录重要业务事件（创建/删除笔记、分享、权限变更）。
- **错误监控**：可接入 Sentry/阿里云日志服务。
- **性能监控**：建议配合 Prometheus + Grafana 或 APM。

## 11. 部署建议

- **Docker**：编写 `Dockerfile` 与 `docker-compose.yml` 以便快速部署（待补充）。
- **CI/CD**：利用 GitHub Actions 或 GitLab CI 自动执行 lint/test/build。
- **环境区分**：开发/测试/生产环境使用不同 `.env` 与数据库实例。
- **备份策略**：对 MySQL 定期备份，配合对象存储保存附件与导出文件。

## 12. 迭代规划

- ✅ 搭建基础 NestJS 模板与模块结构
- 🚧 开发核心实体与 TypeORM 配置，完善 DTO、Service、Controller
- 🚧 引入 `class-validator`、全局异常过滤器、统一响应
- 🚧 完善认证授权（登录、刷新、角色、权限校验）
- 🚧 实现笔记协作、历史版本、变更记录
- 📅 未来计划：全文搜索（Elasticsearch）、富文本协作（WebSocket）、第三方存储（S3/OSS）、多租户支持

---

如需贡献代码，请遵循项目代码规范与提交信息格式，并在提交前运行 `pnpm lint` 与 `pnpm test` 保障质量。