修bug，完善功能

docs/commands.md

@@ -2,13 +2,19 @@
 
 [← 返回 README](../README.md)
 
-**本页导航：** [组件命令](#组件命令) · [csql](#csql) · [chusql-web](#chusql-web) · [chusql-server](#chusql-server) · [范式分析](#范式分析)
+本页内容：
 
-ChuSQL 的主要用户命令如下：
+- [组件命令](#组件命令)
+- [csql](#csql)
+- [chusql-web](#chusql-web)
+- [chusql-server](#chusql-server)
+- [范式分析](#范式分析)
+
+本页面向命令行和 Web 使用者，说明启动参数、交互命令及编辑事务的行为。CLI 指命令行客户端。
 
 类型见 [类型与函数](types.md)，身份与授权见 [用户与角色](users-and-roles.md)。
 
-SQL 的查询、事务、类型、用户与授权语法见 [syntax.md](syntax.md)。
+查询、事务、类型、用户与授权语法见 [SQL 语法](syntax.md)。
 
 ## 组件命令
 
@@ -47,13 +53,17 @@ csql [options]
 | `--config FILE` | 指定配置文件 |
 | `-h, --help` | 显示帮助 |
 
-CLI 历史只记录完整 SQL 和元命令。包含 `IDENTIFIED` 或 `PASSWORD`（忽略大小写）的输入不记录，多行口令输入和未完成语句也不会逐行写入历史；包含这些文本的普通字符串或标识符同样会被排除。已有历史文件不会自动清理。含这些文本的 SQL 解析错误会隐藏输入原文。
+### 历史记录与口令输入
 
-示例：
+CLI 历史只记录完整 SQL 和元命令。包含 `IDENTIFIED` 或 `PASSWORD`（忽略大小写）的输入不记录，多行口令输入和未完成语句也不会逐行写入历史；包含这些文本的普通字符串或标识符同样会被排除。
+
+已有历史文件不会自动清理。含这些文本的 SQL 解析错误会隐藏输入原文。
+
+示例假定 `sales.orders` 已存在：
 
 ```sh
 csql -d sales -e "SELECT * FROM orders LIMIT 5"
-csql -f json -e "SELECT count(*) FROM orders"
+csql -d sales -f json -e "SELECT count(*) FROM orders"
 ```
 
 在脚本里非交互使用（配合 `-e`）：
@@ -101,11 +111,27 @@ chusql-web [options]
 
 ### 表格编辑与事务
 
-首次打开业务数据表时建立编辑快照。同一页面内、同一数据库的跨表修改统一暂存；“提交全部”在服务端事务中执行，全部成功才持久化。逐项撤销只移除本地编辑项，下次提交从原快照重放剩余编辑；“撤销全部”执行 ROLLBACK 并重新加载表和统计。
+首次打开业务数据表时建立编辑快照。同一页面内、同一数据库的跨表修改统一暂存。
+
+编辑操作的效果如下：
+
+| 操作 | 效果 |
+| --- | --- |
+| 提交全部 | 在服务端事务中执行，全部成功才持久化 |
+| 逐项撤销 | 只移除本地编辑项，下次提交从原快照重放剩余编辑 |
+| 撤销全部 | 执行 ROLLBACK，重新加载表和统计 |
+
+### 编辑失败与提交重试
 
 途中发生约束错误时，整批语句退回编辑保存点，完整编辑内容仍可修正。写写冲突不会覆盖其他会话，必须撤销并重新加载后重新编辑。提交响应断线时冻结编辑集；再次点击提交使用同一标识确认或重试同一批修改，已成功的提交不会重复执行。
 
-编辑事务绑定登录会话、页面和数据库；待提交修改存在时，先提交或撤销才能换库或运行 SQL。关闭最后一个表标签且没有待提交修改时释放快照。关闭页面会请求回滚，退出登录会关闭连接并丢弃快照；若页面断线、回滚请求未送达，后台每分钟按配置的会话空闲与最长寿命清理连接。重新登录不能继续旧事务。
+### 页面关闭与快照释放
+
+编辑事务绑定登录会话、页面和数据库；待提交修改存在时，先提交或撤销才能换库或运行 SQL。
+
+关闭最后一个表标签且没有待提交修改时释放快照。关闭页面会请求回滚，退出登录会关闭连接并丢弃快照；若页面断线、回滚请求未送达，后台每分钟按配置的会话空闲与最长寿命清理连接。重新登录不能继续旧事务。
+
+### SQL 控制台事务
 
 SQL 控制台使用另一条服务端连接；SQL 的 BEGIN / COMMIT / ROLLBACK 绑定发起它的页面与查询标签。事务尚未结束时，其他控制台和普通 REST 写操作不能占用该连接；关闭所属查询标签或页面时请求回滚。系统身份修改不支持数据事务，账号表只读，使用 SQL 用户与角色命令管理。
 
@@ -133,9 +159,13 @@ chusql-server [options]
 
 ## 范式分析
 
+范式分析检查表结构是否符合声明的业务依赖，用于发现结构上的冗余。schema 指列名、类型和约束等表结构信息。
+
 分析只读取 schema 和业务依赖声明，要求当前数据库的 `CONNECT` 与目标表的 `SELECT` 权限；系统对象拒绝分析。它不检查样本数据，也不执行数据迁移。
 
-声明文件使用 UTF-8 JSON，字段名须与表结构一致：
+声明文件使用 UTF-8 JSON，字段名须与表结构一致。`declared_keys` 声明键列，`dependencies` 声明函数依赖，即哪些列能唯一决定其他列；`lhs` 是决定列，`rhs` 是被决定列。
+
+`dependencies_complete` 表示声明是否覆盖全部业务依赖，`atomic_attributes` 表示字段是否具有业务上的原子性。示例如下：
 
 ```json
 {
@@ -146,6 +176,8 @@ chusql-server [options]
 }
 ```
 
+将声明保存为 `dependencies.json` 后，执行以下命令。示例假定 `school` 数据库及 `enrollment` 表已存在：
+
 ```sh
 csql -d school --normalize enrollment --declaration dependencies.json --format json
 ```
@@ -161,4 +193,13 @@ csql -d school --normalize enrollment --declaration dependencies.json --format j
 
 报告包含候选键、1NF / 2NF / 3NF / BCNF 结论、违反证据及一次 BCNF 分解建议。子关系可能仍需分析，分解不保证依赖保持，也不证明现有 SQL 数据满足声明。Web 使用发起页面或控制台的事务视图；对象或 schema 变化须重新分析。
 
-最多分析 12 列，依赖和键声明各最多 256 项，运行预算 5 秒；超限、权限或输入错误明确返回失败，不截断为完整报告。CLI 成功获得报告时退出码为 `0`，即使结论违反或信息不足；请求失败时退出非零。
+分析的资源限制和退出码如下：
+
+| 项目 | 限制或行为 |
+| --- | --- |
+| 表列数 | 最多 12 列 |
+| 依赖声明、键声明 | 各最多 256 项 |
+| 运行时间 | 预算 5 秒 |
+| 超限、权限或输入错误 | 明确返回失败，不把截断结果当成完整报告 |
+| CLI 成功获得报告 | 退出码为 `0`，包括违反范式或信息不足的结论 |
+| CLI 请求失败 | 退出码非零 |