feat(docs): update repository api doc

docs/reference/repository.md

@@ -697,57 +697,185 @@ repository.destroy({
 ##### Definition
 
 ```ts
-interface relation {
+interface relation<R extends RelationRepository> {
   (name: string): {
-    of: (parent: any): RelationRepository;
+    of: (parent: any): R;
   }
 }
-
-// 关系数据的增删改查在 NocoBase 里非常重要
-class RelationRepository {
-  find() {}
-  findOne() {}
-  create() {}
-  update() {}
-  destroy() {}
-  set() {}
-  add() {}
-  remove() {}
-  toggle() {}
-}
 ```
 
 ##### Examples
 
-find、findOne、create、update 和 destroy 和常规 Repository API 层面是一致，这里重点列举关联操作的几个方法：
+```ts
+const userPostsRepository = User.repository.relation<HasManyRepository>('posts').of(1);
+```
+
+RelationRepository 有四类，对应四种关系的处理：
+
+- HasOneRepository
+- HasManyRepository
+- BelongsToRepository
+- BelongsToManyRepository
+
+### HasOne
+
+##### Definition
 
 ```ts
-// user_id = 1 的 post 的 relatedQuery
-const userPostsRepository = repository.relation('posts').of(1);
+interface IHasOneRepository<M extends Sequelize.Model> {
+  // 不需要 findOne，find 就是 findOne
+  find(options?: HasOneFindOptions): Promise<M>;
+  // 新增并关联，如果存在关联，解除之后，与新数据建立关联
+  create(options?: CreateOptions): Promise<M>;
+  // 更新
+  update(options?: UpdateOptions): Promise<M>;
+  // 删除
+  destroy(): Promise<Boolean>;
+  // 建立关联
+  set(primaryKey: any): Promise<void>;
+  // 移除关联
+  remove(): Promise<void>;
+}
 
-// 建立关联
-userPostsRepository.set(1);
+interface HasOneFindOptions {
+  fields?: string[];
+  expect?: string[];
+  appends?: string[];
+}
+```
 
-// 批量，仅用于 HasMany 和 BelongsToMany
-userPostsRepository.set([1,2,3]);
+##### Examples
 
-// BelongsToMany 的中间表
-userPostsRepository.set([
+以 user.profile 为例
+
+```ts
+// id = 1 的 user 的 profile
+const userProfileRepository = User.repository.relation<HasOneRepository>('profile').of(1);
+
+const profile = await userProfileRepository.find({
+  fields,
+  appends,
+  expect,
+});
+```
+
+### BelongsTo
+
+##### Definition
+
+```ts
+interface IBelongsToRepository<M extends Sequelize.Model> {
+  // 不需要 findOne，find 就是 findOne
+  find(options?: BelongsToFindOptions): Promise<M>;
+  // 新增并关联，如果存在关联，解除之后，与新数据建立关联
+  create(options?: CreateOptions): Promise<M>;
+  // 更新
+  update(options?: UpdateOptions): Promise<M>;
+  // 删除
+  destroy(): Promise<Boolean>;
+  // 建立关联
+  set(primaryKey: any): Promise<void>;
+  // 移除关联
+  remove(): Promise<void>;
+}
+
+interface HasOneFindOptions {
+  fields?: string[];
+  expect?: string[];
+  appends?: string[];
+}
+```
+
+##### Examples
+
+以 posts.user 为例
+
+```ts
+// id = 1 的 post 的 user
+const postUserRepository = Post.repository.relation<BelongsToRepository>('user').of(1);
+
+const user = await postUserRepository.find({
+  fields,
+  appends,
+  expect,
+});
+```
+
+### HasMany
+
+##### Definition
+
+```ts
+interface IHasManyRepository<M extends Sequelize.Model> {
+  find(options?: FindOptions): Promise<M>;
+  findAndCount(options?: FindAndCountOptions): Promise<[ M[], number ]>
+  findOne(options?: FindOneOptions): Promise<M>;
+  // 新增并关联
+  create(options?: CreateOptions): Promise<M>;
+  // 更新
+  update(options?: UpdateOptions): Promise<M>;
+  // 删除
+  destroy(options?: number | string | number[] | string[] | DestroyOptions): Promise<Boolean>;
+  // 建立关联
+  set(primaryKey: any | primaryKeys: any[]): Promise<void>;
+  // 附加关联
+  add(primaryKey: any | primaryKeys: any[]): Promise<void>;
+  // 移除关联
+  remove(primaryKey: any | primaryKeys: any[]): Promise<void>;
+}
+```
+
+##### Examples
+
+```ts
+repository.find();
+repository.create();
+repository.update({
+  filterByPk: 1,
+  values: {},
+});
+repository.set(1);
+repository.set([1, 2]);
+repository.add([3]);
+repository.remove(1);
+repository.remove([2, 3]);
+```
+
+### BelongsToMany
+
+##### Definition
+
+```ts
+interface IBelongsToManyRepository<M extends Sequelize.Model> {
+  find(options?: FindOptions): Promise<M[]>;
+  findAndCount(options?: FindAndCountOptions): Promise<[ M[], number ]>
+  findOne(options?: FindOneOptions): Promise<M>;
+  // 新增并关联，存在中间表数据
+  create(options?: CreateBelongsToManyOptions): Promise<M>;
+  // 更新，存在中间表数据
+  update(options?: UpdateOptions): Promise<M>;
+  // 删除
+  destroy(options?: number | string | number[] | string[] | DestroyOptions): Promise<Boolean>;
+  // 建立关联
+  set(primaryKey: any | primaryKeys: any[]): Promise<void>;
+  // 附加关联，存在中间表数据
+  add(primaryKey: any | primaryKeys: any[]): Promise<void>;
+  // 移除关联
+  remove(primaryKey: any | primaryKeys: any[]): Promise<void>;
+  toggle(primaryKey: any): Promise<void>;
+}
+```
+
+##### Examples
+
+多对多关系多了中间表的处理
+
+```ts
+repository.set(1);
+repository.set([1,2,3]);
+repository.set([
   [1, {/* 中间表数据 */}],
   [2, {/* 中间表数据 */}],
   [3, {/* 中间表数据 */}],
 ]);
-
-// 仅用于 HasMany 和 BelongsToMany
-userPostsRepository.add(1);
-
-// BelongsToMany 的中间表
-userPostsRepository.add(1, {/* 中间表数据 */});
-
-// 删除关联
-userPostsRepository.remove(1);
-
-// 建立或解除
-userPostsRepository.toggle(1);
-userPostsRepository.toggle([1, 2, 3]);
-```
+```