From b80ed7fe0a51aa4b38aa494af0ffa8466068dbd6 Mon Sep 17 00:00:00 2001
From: Leon Zhang <martianzhang@hotmail.com>
Date: Thu, 25 Oct 2018 14:14:03 +0800
Subject: [PATCH] update FAQ doc

---
 advisor/index_test.go | 3 +++
 advisor/rules.go      | 2 +-
 common/config.go      | 2 +-
 doc/FAQ.md            | 8 ++++++++
 doc/config.md         | 6 +++++-
 doc/install.md        | 2 +-
 6 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/advisor/index_test.go b/advisor/index_test.go
index a4bf8cc..a61dd2e 100644
--- a/advisor/index_test.go
+++ b/advisor/index_test.go
@@ -67,6 +67,9 @@ func TestRuleImplicitConversion(t *testing.T) {
 		"SELECT * FROM t1 WHERE title >= 60;",
 		"SELECT * FROM t1, t2 WHERE t1.title = t2.title;",
 		"SELECT * FROM t1, t3 WHERE t1.title = t3.title;",
+		// TODO:
+		// "SELECT * FROM t1 WHERE title in (60);",
+		// "SELECT * FROM t1 WHERE title in (60, '60');",
 	}
 	for _, sql := range sqls {
 		stmt, syntaxErr := sqlparser.Parse(sql)
diff --git a/advisor/rules.go b/advisor/rules.go
index 6bd1d5f..f1e0494 100644
--- a/advisor/rules.go
+++ b/advisor/rules.go
@@ -198,7 +198,7 @@ func init() {
 			Summary:  "参数比较包含隐式转换，无法使用索引",
 			Content:  "隐式类型转换有无法命中索引的风险，在高并发、大数据量的情况下，命不中索引带来的后果非常严重。",
 			Case:     "SELECT * FROM sakila.film WHERE length >= '60';",
-			Func:     (*Query4Audit).RuleOK, // 该建议在indexAdvisor中给
+			Func:     (*Query4Audit).RuleOK, // 该建议在IndexAdvisor中给，RuleImplicitConversion
 		},
 		"ARG.004": {
 			Item:     "ARG.004",
diff --git a/common/config.go b/common/config.go
index c1609d3..5abc613 100644
--- a/common/config.go
+++ b/common/config.go
@@ -537,7 +537,7 @@ func readCmdFlags() error {
 	// +++++++++++++++++其他+++++++++++++++++++
 	printConfig := flag.Bool("print-config", false, "Print configs")
 	ver := flag.Bool("version", false, "Print version info")
-	query := flag.String("query", Config.Query, "Queries for analyzing")
+	query := flag.String("query", Config.Query, "待评审的SQL或SQL文件，如SQL中包含特殊字符建议使用文件名。")
 	listHeuristicRules := flag.Bool("list-heuristic-rules", Config.ListHeuristicRules, "ListHeuristicRules, 打印支持的评审规则列表")
 	listRewriteRules := flag.Bool("list-rewrite-rules", Config.ListRewriteRules, "ListRewriteRules, 打印支持的重写规则列表")
 	listTestSQLs := flag.Bool("list-test-sqls", Config.ListTestSqls, "ListTestSqls, 打印测试case用于测试")
diff --git a/doc/FAQ.md b/doc/FAQ.md
index a9648b1..ff9206b 100644
--- a/doc/FAQ.md
+++ b/doc/FAQ.md
@@ -9,6 +9,14 @@
 * [mysql](https://www.mysql.com/) 测试时用来连接测试环境
 * [retool](https://github.com/twitchtv/retool): 管理测试开发工具,首次安装耗时会比较长,如:`gometalinter.v2`, `revive`, `golangci-lint`
 
+### 命令行参数`test-dsn`, `online-dsn`中包含特殊字符怎么办？
+
+如果`test-dsn`或`online-dsn`中包含':', '@', '/', '!'等特殊字符建议在配置文件中配置相关信息，配置文件为YAML格式，需要遵守YAML格式的要求规范。
+
+### Windows环境下双击`soar.windows-amd64`文件无反应。
+
+`soar`是命令行工具，不是图形化桌面工具，Windows环境需要在`cmd.exe`下以命令行方式运行。使用`soar`前您需要先熟悉Windows命令行使用。
+
 ### 提示语法错误
 
 * 请检查SQL语句中是否出现了不配对的引号,如 `, ", '
diff --git a/doc/config.md b/doc/config.md
index 05f6ad1..5d25662 100644
--- a/doc/config.md
+++ b/doc/config.md
@@ -4,6 +4,8 @@
 
 默认文件会按照`/etc/soar.yaml`, `./etc/soar.yaml`, `./soar.yaml`顺序加载，找到第一个后不再继续加载后面的配置文件。如需指定其他配置文件可以通过`-config`参数指定。
 
+关于数据库权限`online-dsn`需要相应库表的SELECT权限，`test-dsn`需要root最高权限。
+
 ```text
 # 线上环境配置
 online-dsn:
@@ -75,7 +77,7 @@ $ soar -h
 
 ### 命令行参数配置DSN
 
-> 账号密码中如包含特殊符号(如：'@',':','/'等)可在配置文件中设置，存在特殊字符的情况不适合在命令行中使用。
+> 账号密码中如包含特殊符号(如：'@',':','/'等)可在配置文件中设置，存在特殊字符的情况不适合在命令行中使用。目前`soar`只支持tcp协议的MySQL数据库连接方式，如需要配置本机MySQL环境建议将`localhost`修改为'127.0.0.1'，并检查对应的'user'@'127.0.0.1'账号是否存在。
 
 ```bash
 $ soar -online-dsn "user:password@ip:port/database"
@@ -104,3 +106,5 @@ $ soar -test-dsn "user:password@ip:port/database"
 不同类型的建议指定的Severity不同，严重程度数字由低到高依次排序。满分100分，扣到0分为止。L0不扣分只给出建议，L1扣5分，L2扣10分，每级多扣5分以此类推。当由时给出L1, L2两要建议时扣分叠加，即扣15分。
 
 如果您想给出不同的扣分建议或者对指引中的文字内容不满意可以为在git中提ISSUE，也可直接修改rules.go的相应配置然后重新编译自己的版本。
+
+注意：目前只有`markdown`和`html`两种`-report-type`支持评分输出显示，其他输出格式如有评分需求可以按上述规则自行计算。
diff --git a/doc/install.md b/doc/install.md
index c562407..daf6302 100644
--- a/doc/install.md
+++ b/doc/install.md
@@ -4,7 +4,7 @@
 wget https://github.com/XiaoMi/soar/releases/download/${tag}/soar.linux-amd64 -O soar
 chmod a+x soar
 如：
-wget https://github.com/XiaoMi/soar/releases/download/v0.8.0/soar.linux-amd64 -O soar
+wget https://github.com/XiaoMi/soar/releases/download/v0.8.1/soar.linux-amd64 -O soar
 chmod a+x soar
 ```
 
-- 
GitLab