kczx-user-management 1.0.1 → 1.0.3

package/CUTOVER-RUNBOOK.md

@@ -39,7 +39,7 @@ takes a few minutes and the rollback takes one command.
 #    user-management:
 #      listenHost: '0.0.0.0'    # was 127.0.0.1 (observer mode)
 #      plaintext: false         # was true: the door terminates TLS again
-#      port: 19843
+#      port: 8088
 #      trustedSecret: ''        # no signing gateway in front of it any more
 
 # 2. remove dsh-passwords from the profile
@@ -50,7 +50,7 @@ dsh plugin --profile web remove dsh-passwords
 
 ## Verification after the switch
 
-1. `https://<host>:19843/login` renders, a wrong password is refused, a correct
+1. `https://<host>:8088/login` renders, a wrong password is refused, a correct
    one lands on the SPA.
 2. The settings page shows 用户管理 with the accounts that were migrated
    (`mxz`, `mxz1`) and their permissions intact.

package/MERGED-DEPLOYMENT.md

@@ -43,7 +43,7 @@ dsh 宿主 127.0.0.1:3080
 user-management:
   enabled: true
   listenHost: '127.0.0.1'   # 明文模式会强制为回环，配别的会被拒绝并告警
-  port: 19843
+  port: 8088
   plaintext: true           # 明文监听：登录门的 WS 升级走裸 TCP 隧道，无法对这一跳做 TLS
   trustedSecret: '<64 hex>' # 与 dsh-passwords 的 MCP_IDENTITY_SECRET 必须逐字一致
   # trustedPeers: []        # 默认即回环；仅在确有需要时覆盖
@@ -53,7 +53,7 @@ user-management:
 
 ```
 MCP_IDENTITY_SECRET=<同一个 64 hex>     # 专用密钥，不复用 MCP_INTERNAL_SECRET
-MCP_GATEWAY_UPSTREAM=http://127.0.0.1:19843
+MCP_GATEWAY_UPSTREAM=http://127.0.0.1:8088
 ```
 
 两端密钥不一致是**静默失败**——观察层会拒绝全部请求，台账停止增长而没有任何报错。

package/README.md

@@ -54,11 +54,30 @@ pnpm add ./kczx-user-management-1.0.0.tgz        # 正常路径：依赖从 regi
 node scripts/ensure-deps.mjs                     # 仅当上述解析不到 schemastery 时才需要
 ```
 
+## 首次使用（初始化）
+
+**自助注册是关闭的**：账号只能由管理员在设置页创建，第一个管理员走"初始化"流程。
+
+1. 启动 dsh。库里还没有任何账号时，启动日志会打印一行初始化密钥：
+
+   ```
+   [user-management] first-run setup key 3f0c… (also in ~/.dsh/user-management/setup-key.txt)
+   ```
+
+   密钥同时写在 `$DSH_HOME/user-management/setup-key.txt`；也可以用 `settings.yaml` 的
+   `user-management.setupKey` 自行指定（那样不会往磁盘写密钥文件）。
+
+2. 浏览器打开 `https://<主机>:8088/login` —— 此时显示**初始化页**：填初始化密钥 + 用户名 + 密码。
+3. 提交后该账号**直接成为管理员并登录**，初始化密钥当场销毁（删文件、清内存）；此后 `/login` 只显示登录表单，
+   `/user-management/api/setup` 拒绝一切后续调用。
+
+> 登录页样式与 dsh-passwords 一致（光晕背景 + 网格 + 玻璃卡片 + 渐变按钮），跟随宿主主题深浅色，右上角可切换中文 / English。
+
 ## 它做什么
 
 ### 一扇门
 
-独立的 `node:https` 监听器（默认 `0.0.0.0:19843`），自签证书（SAN 覆盖本机全部 IP + sslip.io / nip.io 别名），
+独立的 `node:https` 监听器（默认 `0.0.0.0:8088`），自签证书（SAN 覆盖本机全部 IP + sslip.io / nip.io 别名），
 未登录的页面访问跳转 `/login`、API 请求 401；登录页自带深浅色。设置页提供证书下载（PEM/DER）、指纹核对与
 各系统导入向导。
 
@@ -66,7 +85,8 @@ node scripts/ensure-deps.mjs                     # 仅当上述解析不到 sche
 
 | 能力 | 说明 |
 |---|---|
-| 用户增删改查 | 新增 / 删除 / 角色调整 / 禁用启用 / 重置密码（一次性临时密码）/ 重置两步验证 |
+| 用户增删改查 | 用户表每行一个「编辑」**全屏页**：基本资料（部门 / 角色）+ 账号操作（重置密码 / 重置两步验证 / 禁用启用 / 删除）+ 权限与配额，集中一屏；改动类走「保存」，破坏性操作仍是各自带确认的按钮 |
+| 所属部门 | 账号资料字段（trim 后 ≤ 64 字，控制字符剔除）：新增用户时可填，编辑页可随时改或清空；变更写进操作日志 |
 | 工作区白名单 | 留空 = 允许全部；填写后只允许这些目录（Windows 路径折叠大小写，末尾斜杠自动忽略） |
 | 工作区归属跟踪 | 谁创建的工作区归谁：别人看不到、也不能删改；删除后释放，账号删除后清理 |
 | 每小时 token 配额 | 由浏览器上报 dsh 自身的用量投影增量，服务端按小时窗口累计并拦截 |
@@ -79,7 +99,7 @@ node scripts/ensure-deps.mjs                     # 仅当上述解析不到 sche
 
 | 台账 | 内容 |
 |---|---|
-| 登录记录 | 登录 / 失败 / 登出 / 改密 / 注册 / 角色变更 / 删号 / 权限变更（含紧凑差异串） |
+| 登录记录 | 登录 / 失败 / 登出 / 改密 / 初始化（首次建号）/ 建号 / 删号 / 角色变更 / 资料变更 / 权限变更（含紧凑差异串） |
 | 访问记录 | 页面级访问（保留真实客户端 IP） |
 | 操作日志 | 经过网关的每次 API 调用与 WebSocket 连接（方法 / 路径 / 状态 / 来源 IP） |
 
@@ -93,11 +113,11 @@ node scripts/ensure-deps.mjs                     # 仅当上述解析不到 sche
 user-management:
   enabled: true
   listenHost: '0.0.0.0'   # 只本机可达就填 127.0.0.1
-  port: 19843
+  port: 8088
   plaintext: false        # true 时只允许回环（明文服务观察层用，见 MERGED-DEPLOYMENT.md）
   sites: []               # 空 = 自动枚举本机 IP；配域名 + 证书则按 SNI 选择
   title: 'DSH 控制台'
-  autoActivate: false     # false = 自助注册需管理员启用
+  setupKey: ''            # 首次初始化密钥；留空 = 启动时随机生成并写到 setup-key.txt
   historyMaxBytes: 67108864   # 历史改写缓冲上限（字节，默认 64 MiB，最小 1 MiB）
 ```
 
@@ -107,7 +127,7 @@ user-management:
 
 | 文件 | 内容 |
 |---|---|
-| `users.json` | 账号（scrypt 哈希；迁移进来的账号保留 bcrypt，首次登录成功后自动升级为 scrypt） |
+| `users.json` | 账号（scrypt 哈希；迁移进来的账号保留 bcrypt，首次登录成功后自动升级为 scrypt；含 `department` 所属部门） |
 | `sessions.json` | 会话令牌（重启不掉线，7 天滑动过期） |
 | `activity.jsonl` / `audit.jsonl` | 登录与访问台账 / 操作日志（滚动保留最近若干条） |
 | `bans.json` | IP 封禁 |
@@ -131,7 +151,7 @@ node scripts/import-from-dsh-passwords.mjs --from E:\path\to\dsh-passwords --ove
 ## 测试
 
 ```bash
-npm test          # 85 项：策略纯函数、store、API 层、以及真实网关的端到端用例
+npm test          # 93 项：策略纯函数、store、API 层、以及真实网关的端到端用例
 npm run check     # 全量语法检查
 ```