add more cn

bab22bda · sinat_25235033 · 84472532 · bab22bda · bab22bda · bab22bda
9 changed file
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -3,10 +3,10 @@
  - [快速开始](quickstart.md "quick start greatest")  

 - 进阶扩展
-  - [扩展点]()
-  - [自定义数据源]()
-  - [自定义subject]()
-  - [自定义processor]()
+  - [扩展点](extend-point.md)
+  - [自定义数据源](custom-datasource.md)
+  - [自定义subject](custom-subject.md)
+  - [自定义processor](custom-processor.md)

 - 集成案例
  - [10分钟项目集成](sample-bootstrap.md)
@@ -14,5 +14,4 @@

 - 其它
  - [参与贡献](contributing.md)
-  - [change]()
-  - [我们的愿景]()
+  - [change](https://github.com/tomsun28/sureness/commits/master ':ignore')
--- a/docs/custom-datasource.md
+++ b/docs/custom-datasource.md
+## 自定义数据源    
+
+实现 `PathTreeProvider`的接口, 加载到`DefaultPathRoleMatcher`中   
+实现 `SurenessAccountProvider`的接口,加载到需要的`processor`中  
+
+具体扩展实践请参考 [使用sureness30分钟搭建权限项目--sample-tom](https://github.com/tomsun28/sureness)  
--- a/docs/custom-processor.md
+++ b/docs/custom-processor.md
+## 自定义processor    
+
+一个`subject`当然也可以被不同的`processor`处理,所以可以单独自定义`processor`   
+实现`Processor`接口,设置支持的`subject`,实现处理该`subject`的逻辑  
+
+具体扩展实践请参考 [使用sureness30分钟搭建权限项目--sample-tom](https://github.com/tomsun28/sureness)  
--- a/docs/custom-subject.md
+++ b/docs/custom-subject.md
+## 自定义subject  
+
+实现`Subject`接口,添加自定义的`subject`内容  
+实现`SubjectCreate`接口方法,创建出自定义的`subject`  
+实现`Processor`接口,支持处理自定义的`subject`    
+
+具体扩展实践请参考 [使用sureness30分钟搭建权限项目--sample-tom](https://github.com/tomsun28/sureness)  
--- a/docs/extend-point.md
+++ b/docs/extend-point.md
+### 进阶扩展  
+
+如果了解 [处理流程](#处理流程),就大概知道`sureness`提供的扩展点    
+`sureness`支持自定义`subject`，自定义`subjectCreator`注册，自定义`processor`处理器等  
+
+扩展之前需要了解以下接口:  
+
+- `Subject`: 认证鉴权对象接口,提供访问对象的账户密钥,请求资源,角色等信息  
+- `SubjectCreate`: 创建`Subject`接口,根据请求内容创建不同类型的`Subject`对象    
+- `Processor`: `Subject`处理接口,根据Subject信息,进行认证鉴权  
+- `PathTreeProvider`: 资源的数据源接口,实现从数据库,文本等加载数据  
+- `SurenessAccountProvider`: 用户的账户密钥信息接口,实现从数据库,文本等加载数据  
+
+`sureness`大致流程:  
+
+```mermaid
+graph TD
+A(用户请求体进来) --> B(s)
+B(subjectCreate根据请求头内容创建不同的钥匙subject,每把钥匙都可以尝试) --> C(s)
+C(不同的钥匙认证方式即不同的锁processor来处理进来的钥匙subject) --> D(s)
+D(以上一次成功即成功并结束,失败即下一个钥匙锁尝试直到所有尝试结束)
+
+```
--- a/docs/index.html
+++ b/docs/index.html
@@ -23,8 +23,17 @@
      mergeNavbar: true,
      maxLevel: 4,
      name: 'sureness',
-      search: 'auto',
-
+      search: {
+        noData: {
+          '/': '没有结果!',
+          '/en/': 'No results!'
+        },
+        paths: 'auto',
+        placeholder: {
+          '/': '搜索',
+          '/en': 'Search'
+        }
+      },
      <!-- 字数统计 -->
      count:{
        countable:true,

--- a/docs/quickstart.md
+++ b/docs/quickstart.md
-# 快速开始

-推荐全局安装 `docsify-cli` 工具，可以方便地创建及在本地预览生成的文档。
+## 仓库的组成部分:  
+- [sureness的核心代码--sureness-core](https://github.com/tomsun28/sureness)  
+- [使用sureness10分钟搭建权限项目--sample-bootstrap](https://github.com/tomsun28/sureness)  
+- [使用sureness30分钟搭建权限项目--sample-tom](https://github.com/tomsun28/sureness)  

-```bash
-npm i docsify-cli -g
-```
-
-## 初始化项目
-
-如果想在项目的 `./docs` 目录里写文档，直接通过 `init` 初始化项目。
-
-```bash
-docsify init ./docs
-```
-
-## 开始写文档
-
-初始化成功后，可以看到 `./docs` 目录下创建的几个文件
-
- `index.html` 入口文件
- `README.md` 会做为主页内容渲染
- `.nojekyll` 用于阻止 GitHub Pages 忽略掉下划线开头的文件
+## <font color="red">一些约定</font>  

-直接编辑 `docs/README.md` 就能更新文档内容，当然也可以[添加更多页面](zh-cn/more-pages.md)。
+- 基于`RABC`,但只有(角色-资源)的映射,没有(权限)动作
+- 我们将`restful api`请求视作一个资源,资源格式为: `requestUri===httpMethod`  
+  即请求的路径加上其请求方式(`post,get,put,delete...`)作为一个整体被视作一个资源  
+  `eg: /api/v2/book===get` `get`方式请求`/api/v2/book`接口数据     
+- 用户所属角色--角色拥有资源--用户拥有资源(用户就能访问此`api`)   

-## 本地预览

-通过运行 `docsify serve` 启动一个本地服务器，可以方便地实时预览效果。默认访问地址 http://localhost:3000 。
+## 使用  

-```bash
-docsify serve docs
+`maven`坐标  
 ```
-
-?> 更多命令行工具用法，参考 [docsify-cli 文档](https://github.com/docsifyjs/docsify-cli)。
-
-## 手动初始化
-
-如果不喜欢 npm 或者觉得安装工具太麻烦，我们可以直接手动创建一个 `index.html` 文件。
-
-*index.html*
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
-  <meta name="viewport" content="width=device-width,initial-scale=1">
-  <meta charset="UTF-8">
-  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
-</head>
-<body>
-  <div id="app"></div>
-  <script>
-    window.$docsify = {
-      //...
-    }
-  </script>
-  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
-</body>
-</html>
+<!-- https://mvnrepository.com/artifact/com.usthe.sureness/sureness-core -->
+<dependency>
+    <groupId>com.usthe.sureness</groupId>
+    <artifactId>sureness-core</artifactId>
+    <version>0.0.2.2</version>
+</dependency>
 ```

-如果你的系统里安装了 Python 的话，也可以很容易地启动一个静态服务器去预览你的网站。
+`gradle`坐标  
+```
+compile group: 'com.usthe.sureness', name: 'sureness-core', version: '0.0.2.2'
+```

-```bash
-cd docs && python -m SimpleHTTPServer 3000
+入口,一般放在拦截所有请求的`filter`:  
+```
+SurenessSecurityManager.getInstance().checkIn(servletRequest)
 ```

-## Loading 提示
+认证鉴权成功直接通过,失败抛出特定异常,捕获异常: 

-初始化时会显示 `Loading...` 内容，你可以自定义提示信息。
+```
+        try {
+            SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest);
+        } catch (ProcessorNotFoundException | UnknownAccountException | UnsupportedSubjectException e4) {
+            // 账户创建相关异常 
+        } catch (DisabledAccountException | ExcessiveAttemptsException e2 ) {
+            // 账户禁用相关异常
+        } catch (IncorrectCredentialsException | ExpiredCredentialsException e3) {
+            // 认证失败相关异常
+        } catch (UnauthorizedException e5) {
+            // 鉴权失败相关异常
+        } catch (RuntimeException e) {
+            // 其他自定义异常
+        }
+```

+sureness异常                              | 异常描述
+---                                       | ---
+SurenessAuthenticationException           | 基础认证异常,认证相关的子异常应该继承此异常 
+SurenessAuthorizationException            | 基础鉴权异常,鉴权相关的子异常应该继承此异常
+ProcessorNotFoundException                | 认证异常,未找到支持此subject的processor
+UnknownAccountException                   | 认证异常,不存在此账户
+UnSupportedSubjectException               | 认证异常,不支持的请求,未创建出subject
+DisabledAccountException                  | 认证异常,账户禁用
+ExcessiveAttemptsException                | 认证异常,账户尝试认证次数过多
+IncorrectCredentialsException             | 认证异常,密钥错误
+ExpiredCredentialsException               | 认证异常,密钥认证过期
+UnauthorizedException                     | 鉴权异常,没有权限访问此资源

-```html
-  <!-- index.html -->
-  
-  <div id="app">加载中</div>
-```
+自定义异常需要继承`SurenessAuthenticationException`或`SurenessAuthorizationException`才能被最外层捕获  

-如果更改了 `el` 的配置，需要将该元素加上 `data-app` 属性。

-```html
-  <!-- index.html -->
-  <div data-app id="main">加载中</div>
+若权限配置数据来自文本,请参考[使用sureness10分钟搭建权限项目--sample-bootstrap](https://github.com/tomsun28/sureness)  

-  <script>
-    window.$docsify = {
-      el: '#main'
-    }
-  </script>
-```
+若权限配置数据来自数据库,请参考[使用sureness30分钟搭建权限项目--sample-tom](https://github.com/tomsun28/sureness)  

-对比 [el 设置](configuration.md#el)。
+HAVE FUN
\ No newline at end of file
--- a/docs/sample-bootstrap.md
+++ b/docs/sample-bootstrap.md
 ## sample-bootstrap  

-sureness 10分钟例子项目  
+[sureness 10分钟例子项目](https://github.com/tomsun28/sureness/tree/master/sample-bootstrap)  

 - 基于`springboot`
 - 从默认的配置文件`sureness.yml`加载账户信息,资源角色,过滤资源等信息  

--- a/docs/sample-tom.md
+++ b/docs/sample-tom.md
 ## sample-tom  

-sureness 30分钟例子项目  
+[sureness 30分钟例子项目](https://github.com/tomsun28/sureness/tree/master/sample-tom)  

- 基于`springboot,jpa...`，[数据源sql](src/main/resources/db)  
+- 基于`springboot,jpa...`
 - 自定义数据源,使用从数据库加载账户信息,资源角色,过滤资源等信息,这样便于动态调整      
 - 除了使用了默认的`jwt,basic auth`方式认证鉴权,新增自定义认证鉴权(自定义`subject subjectCreator processor...`)
 - 推荐使用`postman`测试,测试样例为`sample-tom-postman.json`,导入`postman`即可  
\ No newline at end of file