create-windy 0.1.0

package/template/docs/platform/bulk-data-jobs.md

@@ -0,0 +1,156 @@
+# 批量导入导出后台任务
+
+## V1 范围
+
+DATA-01 先用 canonical `dictionaries`（字典）资源完成一个真实纵向切片，同时把任务、artifact、资源处理器和路由 Guard 做成可扩展边界。V1 支持：
+
+- 字典 NDJSON 后台导入，`create` 与 `upsert` 两种模式；
+- 字典 NDJSON 后台导出；
+- PostgreSQL 持久化任务状态、进度、重试和文件内容；
+- 逐行失败明细、导入汇总和导出结果下载；
+- 到期 artifact 自动清理，任务元数据和审计继续保留。
+
+原有小数据同步 JSON API 继续保留，但 Web 字典页已切换到本章的后台 NDJSON 工作流，不再展示同步 JSON 导入导出按钮。其它系统资源页面仍使用原有小数据入口。用户、角色、菜单等资源尚未注册为批量处理器，不能只改请求中的 `resource` 绕过 V1 白名单。
+
+## NDJSON 契约与边界
+
+导入采用 UTF-8 NDJSON，每一个非空逻辑行是一条完整字典记录。空行被忽略，失败明细中的 `line` 是非空逻辑行序号。每行至少包含稳定的 `id`、`code`、`name`：
+
+```json
+{
+  "id": "dict_order_status",
+  "code": "order_status",
+  "name": "订单状态",
+  "status": "active",
+  "items": [
+    { "label": "待处理", "value": "pending", "status": "active", "order": 10 }
+  ]
+}
+```
+
+约束如下：
+
+- `id`：1-64 位字母、数字、点、横线或下划线；重试时用它定位同一实体，禁止省略或临时生成；
+- `code`：1-80 位字母、数字、点、横线或下划线；
+- `name`：非空字符串；
+- `status`：`active`、`disabled` 或 `archived`，省略时为 `active`；
+- `items`：数组；每项包含非空 `label`、`value`、合法 `status` 和非负整数 `order`。
+
+V1 固定安全边界：单次输入最多 10 MiB、50,000 个非空逻辑行，单行最多 256 KiB。API 当前接收 JSON body 中的 `content` 字符串，不是无限流式上传；超过任一边界返回 `413`，不会创建任务。
+
+逐行失败文件也是 NDJSON，每行结构为：
+
+```json
+{
+  "line": 2,
+  "code": "INVALID_ROW",
+  "message": "id 仅允许 1-64 位字母、数字、点、横线或下划线",
+  "inputDigest": "<sha256>"
+}
+```
+
+`code` 可能是 `INVALID_JSON`、`INVALID_ROW` 或 `IMPORT_FAILED`。失败文件不回显原始输入行，只保留行号、稳定错误分类、安全消息和输入行 SHA-256，避免把潜在敏感内容复制到错误报告。格式/业务行错误只影响该行；数据库不可用等系统性错误终止本次尝试并进入任务重试。
+
+## 幂等与重试
+
+调用方必须提供 8-160 位的 `idempotencyKey`。唯一作用域是：
+
+```text
+requestedBy + kind(import/export) + resource + idempotencyKey
+```
+
+同一作用域、同一输入摘要重复提交返回原任务，不会重复排队；同一作用域复用到不同输入返回 `409 IDEMPOTENCY_CONFLICT`。不同用户、导入/导出或不同资源可安全使用相同文本键。导出请求的幂等键会固定到原任务及其结果；需要导出最新数据时必须使用新键。
+
+导入要求每行有稳定 `id`。`create` 模式在目标 ID 已存在时按现有 Repository 语义跳过；`upsert` 模式重放同一行会更新同一实体。因此进程在部分提交后发生系统错误，整份 NDJSON 重试也不会生成重复 ID。
+
+任务最多尝试 3 次，系统性失败默认 30 秒后重试。每次领取在 PostgreSQL 中递增 `attempt`，状态为：
+
+- `queued`：等待执行；
+- `running`：已原子领取；
+- `retry-pending`：系统性失败，等待下次尝试；
+- `succeeded`：全部成功；
+- `completed-with-errors`：任务完成但存在行级失败；
+- `failed`：达到最大尝试次数。
+
+每处理 100 行持久化一次中间进度；任务完成时保存最终 `processedRows`、`succeededRows`、`failedRows`。PostgreSQL 使用 `FOR UPDATE SKIP LOCKED` 领取任务，多个 Server 实例不会领取同一 job。
+
+## 复用 OPS-02
+
+DATA-01 没有新增 timer 或通用调度核心，而是向 OPS-02 注册两个代码任务：
+
+- `system.bulk-data.dispatch`：每 5 秒领取并执行一个排队或到期重试的 job；
+- `system.bulk-data.cleanup`：每小时清理到期 artifact。
+
+因此 Worker 防 tick 重入、定时任务单 `running`、执行历史、手动触发、动态 Feature、Entitlement、RBAC 和审计都复用 OPS-02。DATA-01 的 job 状态用于描述一份业务数据文件，OPS-02 的 run 状态用于描述一次派发/清理 handler 执行，两个层次不互相冒充。
+
+进程在 scheduler handler 内直接崩溃时，OPS-04 允许运维确认后把 stale 调度 run 终结为 `blocked`，但该动作只释放 OPS-02 的调度占用，不会修改、重跑或补偿 DATA-01 的批量 job。批量 job 自身若已被置为 `running`，仍不会被另一个派发自动抢占；操作员必须先检查已处理行和外部副作用，再按独立的业务处置流程处理。在没有 lease/heartbeat 之前，这是防止重复写入的 fail-closed 取舍。
+
+## Guard 与审计
+
+`system.bulk-data` 是代码注册 Feature，要求 `capability.scheduler` Entitlement。Guard 顺序固定为：
+
+1. License 限制模式；
+2. Entitlement；
+3. 数据库动态 `system.bulk-data` Feature；
+4. RBAC；
+5. 成功动作审计。
+
+到期限制不会被管理员、调度身份或下载接口绕过。导入创建要求 `system.dict.manage`，导出创建、本人任务查询和 artifact 下载要求 `system.dict.read`；调度执行身份要求 `system.bulk-data.manage`。申请人只能读取和下载自己的任务，不能猜测 job ID 读取他人的结果。
+
+审计动作包括 `data.bulk-import.create`、`data.bulk-export.create` 和 `data.bulk-artifact.download`；OPS-02 对人工触发、真实执行、失败和拒绝记录 `task.trigger` / `task.execute`。定时派发没有领取到任务时属于 idle，不写执行历史或审计，避免 5 秒轮询淹没业务事件。审计只保存任务 ID、数量、artifact 类型和摘要，不保存 NDJSON 内容。
+
+## API
+
+- `POST /api/system/bulk-data/dictionaries/import`
+  - body：`{"idempotencyKey":"...","mode":"create|upsert","content":"<NDJSON>"}`；
+  - 新建返回 `202`，幂等命中返回 `200`。
+- `POST /api/system/bulk-data/dictionaries/export`
+  - body：`{"idempotencyKey":"..."}`；
+  - 新建返回 `202`，幂等命中返回 `200`。
+- `GET /api/system/bulk-data/jobs?limit=50`：查询本人最近任务；
+- `GET /api/system/bulk-data/jobs/:id`：查询本人任务及进度；
+- `GET /api/system/bulk-data/jobs/:id/artifacts/result`：下载导出结果或导入汇总；
+- `GET /api/system/bulk-data/jobs/:id/artifacts/failures`：下载行级失败 NDJSON。
+
+## Web 字典页闭环
+
+`/system/dictionaries` 继续复用 `SystemResourcePage` 完成字典 CRUD，批量数据部分由独立组件和 composable 组合：
+
+- `DictionaryBulkActions` 只负责用户可理解的导入/导出输入；幂等键是浏览器自动生成的 opaque retry token，不作为普通业务字段要求用户手填；
+- `DictionaryBulkJobList` 只展示 Server 返回的当前登录用户任务，包含状态、进度、尝试次数和下次重试时间；页面没有任意 job ID 输入框；
+- `DictionaryBulkJobDetail` 只展示所选本人任务的安全元数据，并在终态提供 `result` / `failures` 下载；失败明细内容不在页面回显；
+- `useDictionaryBulkJobs` 统一处理加载、提交、选中、下载和错误状态；存在非终态任务时每 5 秒刷新一次，也可手动刷新；
+- `services/bulk-data-api.ts` 复用统一认证 HTTP 客户端；artifact 下载保留 Server 返回的原始 `Response`、文件名和内容类型，不另建绕过会话或 Guard 的下载通道。
+
+浏览器在提交前先检查 10 MiB、50,000 个非空逻辑行和 256 KiB 单行限制；Server 仍是最终校验权威。客户端为一次操作生成幂等键：请求失败或响应丢失时重试复用原键，Server 返回成功后才为下一次操作生成新键。任务详情把该键收纳在“技术信息”中只读展示，便于排障但不让普通用户承担协议字段。
+
+错误提示按 API 语义区分：
+
+- `401`：会话失效，统一认证客户端同时触发登录导航；
+- `missing-permission` / `role-not-allowed`：RBAC 权限不足；
+- `license-restricted` / `entitlement-not-granted`：License 受限或未授权后台任务；
+- `feature-disabled`：`system.bulk-data` Feature Flag 已关闭；
+- 输入上限、幂等冲突或其它请求错误：保留 Server 的安全错误说明。
+
+Web 不增加其它资源的伪入口，也不改变 DATA-01 的 PostgreSQL 模型、`0011` migration、本人任务隔离、License → Entitlement → Feature → RBAC Guard 顺序或审计策略。
+
+## 留存和存储取舍
+
+source、result、failures artifact 默认从各自创建时间保留 7 天，可用 `BULK_DATA_RETENTION_DAYS` 调整为正整数天。清理任务只删除 `succeeded`、`completed-with-errors` 或 `failed` 终态 job 的到期 artifact，不会删除仍在排队、运行或等待重试的 source。任务元数据不随 artifact 清理，下载到期文件返回 404。
+
+V1 把 artifact 文本和 SHA-256 一起保存在 PostgreSQL `text` 列。这保证生产状态只有一个权威来源，并避免多副本共享本地目录，但只适用于上述 10 MiB / 50,000 行明确上限，不代表 PostgreSQL 适合无限大文件。后续若提升容量，应实现保持 `BulkDataRepository` 契约的对象存储 Adapter，并把 PostgreSQL 继续作为任务、权限和 artifact 元数据权威；不能直接扩大限制而把数据库当通用对象存储。
+
+无 PostgreSQL 时只使用进程内 Repository，限开发和测试，重启即丢失。生产必须配置 PostgreSQL 并执行到包含 `bulk_data_jobs`、`bulk_data_artifacts` 的最新 migration。本功能不访问国产数据库，也不向 RuoYi 旧库或旧 Redis 写入。
+
+## 运维验证
+
+```bash
+bun run db:migrate
+bun run test:db:migrations
+bun run typecheck
+bun test
+bun run lint
+bun run build
+```
+
+真实 PostgreSQL Repository 测试需要提供 `BULK_DATA_TEST_DATABASE_URL`，覆盖并发幂等创建、`SKIP LOCKED` 单领取、进度/终态、进程重建后的到期重试和 artifact 清理。

package/template/docs/platform/data-access-control.md

@@ -0,0 +1,62 @@
+# 数据访问范围
+
+## 目标与边界
+
+Windy V1 是单组织、单租户、私有部署优先的 Starter。RBAC Permission 决定 Actor 能否调用一种能力；数据访问范围进一步决定该 Actor 能读取或修改哪些记录。页面隐藏不构成授权，Server 必须在分页、导出和按 ID 写入之前执行同一套范围规则。
+
+当前验收资源是系统用户。后续业务模块可复用同一服务，但必须显式声明资源归属；没有 `ownerId` 或 `departmentId` 的资源不得假装自动支持部门范围。
+
+## 类型化上下文
+
+Actor Resolver 从用户主部门和全部启用角色构造 `DataAccessContext`：
+
+- `tenantId`：V1 固定为 `single-tenant`，不代表已经具备多租户隔离；
+- `actorId`：当前用户 ID，用于 `self`；
+- `departmentId`：当前用户唯一主部门；
+- `roleIds`：参与本次判定的启用角色；
+- `grants`：由角色策略转换后的类型化范围集合。
+
+支持的范围如下：
+
+| 范围                      | 用户资源含义                                                     |
+| ------------------------- | ---------------------------------------------------------------- |
+| `all`                     | 当前平台全部用户                                                 |
+| `tenant`                  | V1 单租户内全部用户，当前与 `all` 的结果相同，但保留不同业务语义 |
+| `department`              | 当前 Actor 主部门用户                                            |
+| `department-and-children` | 当前主部门及全部下级部门用户                                     |
+| `self`                    | 当前 Actor 自己的用户记录                                        |
+| `custom`                  | 角色配置的指定部门用户                                           |
+
+多个角色按可访问记录并集合并。停用角色不参与上下文；不能用字符串拼接或页面配置临时推导范围。
+
+## Server 强制点
+
+`DataScopedResourceService` 组合资源 Repository、归属映射和部门后代解析器。用户资源映射为 `{ ownerId: user.id, departmentId: user.departmentId }`，并统一约束：
+
+- `list`、`count`、搜索和分页；
+- `all` 与同步导出；
+- `get-by-id`；
+- `create`；
+- `update`，同时校验原记录和更新后的归属，禁止把可管理记录移动到无权部门；
+- `softDelete`；
+- 模块选择开放时的受控导入。
+
+越权直接 ID 不伪装成成功，也不依赖前端列表是否曾展示该记录；Server 返回 403 和稳定原因 `data-scope-denied`。开发管理员的 `super-admin` 回退仅存在于显式非生产开发通道，真实数据库 Actor 使用角色生成的上下文。
+
+## 业务模块接入
+
+业务模块接入数据范围时至少完成以下步骤：
+
+1. 在领域模型中明确 `ownerId`、`departmentId` 或该模块自己的可解释归属；
+2. 使用 `DataScopedResourceService`，或实现相同 `ScopedResourceAccess` 契约；
+3. 菜单、页面、按钮和 API 仍注册同一 Module Manifest Feature / Permission Key；数据范围不能替代 RBAC Guard；
+4. list、count、export、Agent Tool、直接 ID 读取和所有写入复用同一范围规范；需要继承申请人范围的后台任务必须保存不可篡改的 context snapshot，平台全量任务则必须显式使用 Server 构造的 nominal `all` context；
+5. 测试至少覆盖全部范围、多角色并集、搜索分页、导出、跨部门直接 ID、归属移动、停用角色与组织结构变化。
+
+工单等业务模块可把 `{ ownerId: ticket.createdBy, departmentId: ticket.departmentId }` 作为映射复用当前服务，不需要复制用户模块的条件判断。
+
+## 性能与部署取舍
+
+用户和 Work Order 已把类型化范围规范编译为 Drizzle Query Specification，在 PostgreSQL 中完成谓词、count 和分页下推。`DataScopedResourceService` 不在内存中裁剪生产候选集；它只接受 scoped Repository，并把 Server context 编译后传入 Repository。
+
+同步导出与 Agent Tool 使用相同 scoped access。通用资源必须显式声明 `request` 或 `platform` 访问模式，不能因配置缺失静默走裸 Repository。V1 bulk handler 只允许平台资源；如果未来增加请求级异步导出，必须先持久化并验证不可篡改的 context snapshot，不能把客户端范围参数或 scope-less Actor 放进队列。

package/template/docs/platform/module-configuration.md

@@ -0,0 +1,98 @@
+# 类型化模块配置与 Secret 边界
+
+更新时间：2026-07-16。
+
+## 目标与边界
+
+平台配置不是任意 Key-Value 存储。每个可配置模块必须先注册 `ModuleConfigDefinition<T>`，声明稳定模块 Key、严格 Zod schema、允许的环境变量、逻辑字段路径、默认值和 Secret 属性。未注册字段不能通过环境变量、API 或数据库临时增加。
+
+当前首批定义只有：
+
+- `platform.runtime`：平台名称、数据库方言、平台 Redis、Session、License 公钥元数据、审计和 RuoYi 只读兼容开关；
+- `license.signing-service`：loopback 地址、端口、Vault 地址与 mount、速率限制、签名 key 白名单，以及签名服务 Bearer Token/Vault Token 的受保护文件引用。
+
+配置版本治理只允许消费同一 Registry，不能新增一张绕过 Definition 的通用 KV 表。
+
+## 启动加载契约
+
+`ModuleConfigDefinition` 同时定义字段类型和它负责的环境变量命名空间。严格 Loader 在业务服务开始监听前执行：
+
+1. Definition 所属命名空间出现未知环境变量时，返回 `CONFIG_UNKNOWN_ENV`；
+2. 布尔值只接受 `true/false/1/0`，整数必须是安全整数，Zod schema 继续检查枚举、范围、URL 和严格对象结构；
+3. 必填 Secret 没有引用时返回 `CONFIG_SECRET_REQUIRED`；
+4. Resolver 无法读取 Secret 时返回 `CONFIG_SECRET_UNAVAILABLE`；
+5. 错误只包含模块 Key 与逻辑字段路径，不回显输入值、Secret、环境变量内容或文件路径。
+
+unknown 检查只作用于 Definition 明确拥有的 prefix 或 exact key，避免把操作系统、Bun、测试工具或其它服务环境变量误判为平台配置。
+
+## SecretRef 与 SecretResolver
+
+Secret 配置分成引用和运行时值两层：
+
+- env Secret 的 `SecretRef` 只指向环境变量名，Registry 不保存数据库/Redis URL；
+- file Secret 的 `SecretRef` 只指向受保护文件，签名服务通过 `ProtectedFileSecretResolver` 检查普通文件、Unix `0600` 权限和非空内容；
+- `SecretRef` 的 locator 使用私有字段，不可枚举，`JSON.stringify` 会省略该对象，普通 `String()` 只得到 `[SecretRef]`；
+- Registry 的公开描述只返回逻辑字段路径、是否 Secret、是否必填，不返回 env key、文件路径、引用 locator 或有效值；
+- 解析后的 Secret 只能进入进程内的 typed runtime config，禁止交给普通 API、结构化日志、审计 metadata 或配置 diff。
+
+平台 Server 在创建数据库连接、初始化审计恢复和监听端口前加载 `platform.runtime`。数据库、平台 Redis、RuoYi 连接和机器码通过 env Resolver 解析；Server 的 foundation 快照只投影名称、Feature 等非敏感字段。独立签名服务在连接 Vault 和监听端口前加载 `license.signing-service`，Bearer/Vault Token 只经受保护文件 Resolver 进入对应客户端。
+
+## 新模块接入规则
+
+新增配置模块时必须：
+
+1. 使用 `defineModuleConfig` 和 `z.strictObject` 定义类型；
+2. 为每个 env source 指定唯一逻辑路径，声明自己拥有的 prefix/exact key；
+3. Secret 字段只能声明 Provider 和是否必填，不能把默认 Secret 或明文值写入 Definition；
+4. 注册重复、未知 env、错误类型、缺失/不可读 Secret、JSON/日志无泄露必须有单元测试；
+5. 若需要动态修改，必须接入 C2 的版本、apply、rollback、RBAC、Feature 和审计链路，不能自行写数据库或创建旁路 API。
+
+## 版本治理与运行时应用
+
+`module_config_versions` 保存不可变的模块配置版本，而不是平台通用 KV。每行包含模块 Key、连续版本号、已注册非敏感字段值、字段级 diff、应用状态、稳定错误、变更原因、操作者和可选回滚来源。状态固定为：
+
+- `applying`：版本已入库，正在调用模块 Apply Adapter；
+- `effective`：当前生效版本，同模块同时只能有一个；
+- `failed`：schema 已通过但运行时应用失败，稳定错误不包含底层异常正文；
+- `superseded`：曾经生效，已被后续版本替代。
+
+版本号由 PostgreSQL transaction 内的 module-key advisory lock 分配，唯一索引继续提供最终并发保护。应用成功后，Repository 在事务内把旧 `effective` 标为 `superseded` 并把新版本标为 `effective`；应用失败只标记新版本为 `failed`，原生效版本不变。Server 启动时先读取每个已注册模块的生效版本并通过同一 schema 与 Apply Adapter 恢复，再建立 foundation 和探活运行时。
+
+当前首批允许动态管理的 `platform.runtime` 字段只有：
+
+- `enableAI`：更新 foundation 平台能力投影；
+- `cache.healthTimeoutMs`：后续 Redis 探活按最新值创建 probe。
+
+数据库、Redis URL、Session、License 机器码、签名 Token 和 Vault Token 等 Secret 或引用均不进入版本表、diff、普通 API、管理界面或审计 metadata。
+
+## 回滚、权限与审计
+
+回滚从不改写历史行。`POST /api/system/configurations/:moduleKey/versions/:version/rollback` 复制目标版本的已注册值，要求 8 至 500 字原因，并按正常 apply 流程创建一个带 `rollbackOfVersion` 的新版本。
+
+配置读取要求 `system.config.read`，创建版本和回滚要求 `system.config.manage`；菜单、Web Router 和所有四个 API 绑定统一引用 `system.config` Feature 与 System Module Manifest。mutation 在改配置前先写 `critical` intent 审计，审计不可持久化或进入恢复队列时返回 `503 AUDIT_UNAVAILABLE` 且不创建版本。结果审计只记录 module Key、版本、状态、回滚来源和 changed paths，不记录 before/after 值、请求值、Secret 或 `SecretRef`。
+
+管理端 `/system/configurations` 只根据服务端字段描述生成编辑表单，显示环境/版本来源、生效版本、diff、失败状态和历史；回滚必须经过带原因的显式确认。编辑值或原因未保存时，路由离开和刷新分别使用应用 Dialog 与原生 `beforeunload` 保护，保存失败会保留当前输入。
+
+## 运维与验证
+
+```bash
+bun run test:db:migrations
+bun run test:db:config
+bun test apps/server/src/configuration packages/modules/src/system-modules.test.ts
+bun run --cwd apps/web test -- ModuleConfigurationEditor.webtest.ts router/index.webtest.ts
+```
+
+`test:db:migrations` 在 fresh PostgreSQL 17 上执行全部正式 migration 并二次执行验证 tracker 指纹不变；`test:db:config` 使用真实 PostgreSQL 验证并发版本分配、生效替代、失败状态、Repository 重建后的恢复、回滚新版本和 Secret marker 不落库。
+
+## 验证
+
+定向验证：
+
+```bash
+bun test packages/config/index.test.ts apps/signing-service/src/config.test.ts
+bun test apps/server/src/configuration
+bun run --cwd apps/server typecheck
+bun run --cwd apps/signing-service typecheck
+```
+
+测试使用明显 marker 证明错误、Registry 描述和 JSON 序列化不包含 Secret 值或文件引用。签名测试使用临时 `0600` 文件并在结束后清理，不写入仓库。

package/template/docs/platform/navigation-registry.md

@@ -0,0 +1,36 @@
+# Manifest 菜单注册与导航结构
+
+## 权威边界
+
+Module Manifest 是菜单身份、标题、类型、路由、图标、Feature Key 和 Permission Key 的唯一权威。数据库 `menus` 表不允许创建未注册页面，也不允许改写路由；它只保存管理员可调整的结构状态：
+
+- `parent_key`：上级目录；
+- `order`：同级顺序，以 10 为步长归一化；
+- `visible`：Sidebar 显隐。
+
+服务启动时 `ManifestMenuRegistry` 执行兼容同步：新增 Manifest 菜单，刷新受代码管理的元数据，保留合法的父级、顺序和显隐，并软删除已取消注册、旧水印入口或 `type=button` 的历史行。个人设置仍通过右上角头像进入，不会作为 Sidebar 菜单；全局设置的真实路由固定为 `/settings`，Sidebar 将它放在底部。
+
+## 管理行为
+
+`/system/menus` 是专用导航结构页，不再暴露通用新增、导入、任意编辑和删除操作。具备 `system.menu.manage` 的用户可以：
+
+- 将菜单移到根级或另一个目录；
+- 在当前同级上移、下移；
+- 控制是否显示在 Sidebar。
+
+服务端拒绝不存在的父级、非目录父级、自引用，以及把目录放入自身后代形成的循环。成功调整写入 `menu.structure.update` 审计事件。`GET /api/foundation` 每次从注册表构建菜单树，因此调整后刷新授权快照即可影响真实 Sidebar。
+
+## API
+
+```text
+GET /api/system/menus
+GET /api/system/menus/:id
+GET /api/system/menus/export
+PUT /api/system/menus/:id/placement
+```
+
+`placement` 请求体支持 `parentKey`（`null` 表示根级）、`direction`（`up` 或 `down`）和 `visible`。所有入口继续经过 `system.rbac` Feature 与 `system.menu.read/manage` RBAC Guard。
+
+## 扩展约束
+
+新增页面时先在所属 Module Manifest 用同一能力 Key 注册 Feature、权限、菜单和 API 绑定，再新增 Router 页面。Router 契约测试会比较所有 `type=menu` 的 Manifest 路径与 Web 路由，避免出现“菜单有入口但页面不存在”或“页面绕过注册表”的漂移。

package/template/docs/platform/notifications.md

@@ -0,0 +1,33 @@
+# 站内通知设计
+
+## 产品行为
+
+通知管理页 `/system/notifications` 提供广播发布与历史管理。当前一条通知发布后，会进入所有同时具备 `system.notification.read` 权限且 `system.notification` Feature 可用的用户收件箱。Header 点击通知后打开完整正文，并为当前用户写入跨设备共享的已读回执。
+
+管理页通过页头的“发布新通知”按钮打开发布对话框，避免让常驻表单挤占历史列表。发布过程必须显式提交、点击取消或关闭按钮；点击遮罩层不会误关对话框和丢失已填写内容。对话框遵循全局布局约束：设置适合表单的最小高度且不超过当前屏幕，只有 Body 区域滚动，标题与底部操作始终可见。发布成功后对话框自动关闭并清空表单。
+
+管理列表与用户收件箱共享平台分页契约：默认每页 10 条，服务端上限 100；管理页允许输入范围内任意正整数页大小，并按跨页连续序号展示通知。已发布通知的刷新操作固定在列表右上角，仅显示刷新图标，通过立即出现的组件库 Tooltip 和 `aria-label` 提供名称；加载期间图标旋转且按钮不可重复提交。
+
+通知管理页的人工发布范围仍是全体授权用户，不能通过普通发布 API 伪造定向受众。平台业务端口可以创建受控的用户或角色通知，并携带通用 `TargetRef` 业务目标；当前仅最小审批工作流接入。业务通知使用稳定 `sourceKey` 去重，收件箱查询和已读写入都按当前 Actor 的用户 ID 与角色集合执行最终可见性校验。
+
+组织范围、管理端定向/定时发布、用户偏好、策略化合并，以及邮件、短信、企业微信等渠道 Adapter 仍属于 P1，不在现有广播管理页或审批接入中伪装支持。
+
+## 生命周期与数据
+
+- `platform_notifications` 保存标题、摘要、正文、分类、发布时间和审计字段；业务端口还可写入可选 TargetRef、用户/角色受众和唯一 source key。
+- `notification_reads` 以“通知 ID + 用户 ID”为复合主键保存已读时间，重复点击幂等。
+- 管理操作使用归档而不是物理删除。归档后通知立即退出用户收件箱，但通知历史、操作者信息和既有已读回执继续保留。
+- 无数据库时仅允许开发态内存 Repository；生产部署必须配置 `DATABASE_URL` 并执行迁移。
+
+## Feature、RBAC 与审计
+
+能力基础 Key 为 `system.notification`：
+
+- 用户收件箱和已读接口要求 `system.notification.read`；
+- 后台列表、发布和归档要求 `system.notification.manage`；
+- 菜单、Router、Header、Server API 都引用 Manifest 中的同一 Feature / Permission Key；
+- Feature 或权限不可用时 Header 隐藏且不发请求，Server 仍执行最终 Guard；
+- 普通管理发布只接受广播字段；受众和 TargetRef 只由经过组合根注入的业务端口生成，猜测通知 ID 不能绕过已读可见性检查；
+- 发布记录 `notification.publish`，首次阅读记录 `notification.read`，归档记录 `notification.archive`；重复已读不重复制造审计事件。
+
+发布和归档使用关键审计写入策略。普通已读使用常规审计，避免审计存储短暂降级时阻止用户阅读正文。

package/template/docs/platform/operations-overview.md

@@ -0,0 +1,35 @@
+# 运维总览设计
+
+## 产品边界
+
+运维总览面向平台运维人员，纵向展示服务资源、在线会话、缓存和调度状态。页面不再展示“代码生成”和“系统接口”：CRUD 代码生成是开发期 CLI（`bun run generate:crud`），接口目录属于 Manifest、OpenAPI 与安全校验基础设施，两者都不是生产运行监控指标。
+
+页面每 5 秒刷新一次基础监控快照，手动刷新会同时刷新已获授权的调度状态。`system.scheduler` Feature 未启用或当前用户没有 `system.scheduler.read` 时，前端不会请求调度接口，避免把符合预期的 Guard 拒绝渲染成加载故障。
+
+## 在线会话与 IP
+
+“在线”定义为满足以下全部条件的登录会话：
+
+- 会话状态为 `active`、未撤销且未过期；
+- 用户仍处于启用状态；
+- `lastSeenAt`（首次请求前使用 `issuedAt`）处于最近 15 分钟窗口内。
+
+数据来自认证会话 Repository，而不是当前运维请求的 Actor。IP 在登录时持久化，来源是 Bun Server 读取的直接网络对端地址。服务端不直接信任客户端传入的 `X-Forwarded-For`；部署在反向代理后若要展示原始客户端 IP，应在可信代理边界增加受控的地址解析适配器。
+
+## 数据库和磁盘监控
+
+运维 DTO 只包含方言无关字段：数据库引擎、版本、库名和逻辑数据量。当前启动入口注入 PostgreSQL Probe，通过 `server_version`、`current_database()` 和 `pg_database_size()` 读取信息。MySQL、达梦、人大金仓等数据库应各自实现相同 `DatabaseMonitorProbe`，业务页面不感知 SQL 方言。
+
+磁盘监控按独立数据源展示，不再用“文件系统已用量减数据库逻辑量”推算：
+
+- 宿主机总容量：非容器部署读取 `/`；容器部署只有显式配置只读宿主机挂载 `WINDY_HOST_DISK_PATH` 时才展示，否则返回“未知”，避免把容器 overlay 当成电脑总容量；
+- 系统占用：递归汇总 `WINDY_SYSTEM_USAGE_PATHS` 指定的一组应用自有目录的实际文件字节；
+- 数据占用：数据库 Probe 返回的逻辑数据量，加上 `WINDY_IMPORT_DATA_PATHS` 指定的数据库外独立导入目录。
+
+路径列表使用英文逗号分隔。嵌套系统路径会自动去重；与导入目录完全相同的路径会从系统路径中排除，部署时仍应避免把数据库物理目录或导入目录的父目录配置为系统路径。目录统计缓存 60 秒，页面的 5 秒刷新不会触发无界重复遍历。数据库内的导入内容已经包含在数据库逻辑量中，不得再配置为独立导入目录。
+
+Docker 或 Kubernetes 无法可靠读取物理宿主机容量时，保留“未知”比展示 overlay 容量更准确。若数据库位于独立主机或卷，数据库逻辑量也不应和应用宿主机总容量解释为同一物理磁盘的占用比例。
+
+## 时间与刷新
+
+服务端返回 ISO 时间，Web 端统一按 `Asia/Shanghai` 格式化为 `yyyy-mm-dd hh:mm:ss`。服务卡展示进程启动时间，内存条展示 Bun Server 进程 RSS 相对主机总内存的实时占比。

package/template/docs/platform/organization-membership.md

@@ -0,0 +1,31 @@
+# 部门组织与用户归属
+
+## 设计依据
+
+Windy V1 采用单组织、单租户的企业私有化模型。canonical schema 保留 RuoYi-Vue 兼容导入所需的部门树、用户主部门和角色自定义部门范围，但新模块不得直接依赖旧 `sys_dept` 或其它 `sys_*` 表。
+
+- `departments.parent_id` 表示上级部门，空值为根部门；
+- `users.department_id` 表示用户唯一主部门；
+- `roles.data_scope` 和 `roles.department_ids` 表示角色数据范围策略；
+- 岗位、兼职部门和多组织成员关系属于后续独立模型，不复用 `department_id` 暗中表达。
+
+这些边界延续 [RuoYi-Vue 兼容与迁移设计](../adapters/ruoyi-vue-compatibility.md) 的 Adapter 原则，也与 [Starter 产品缺口分析](../product/starter-product-gap-analysis.md) 中“单组织 V1”和“数据权限必须进入查询约束”的结论一致。
+
+## 用户表单闭环
+
+用户新增和编辑表单从 `GET /api/system/departments` 加载启用部门，并以受控下拉框写入 `users.department_id`；角色区域从 `GET /api/system/roles` 加载启用角色，显示中文名称、稳定编码和数据范围。创建用户必须选择一个启用部门和至少一个启用角色，服务端会再次验证，不能通过直接调用 API 写入悬空部门、空角色或停用角色。
+
+具备以下任一管理能力时，用户表单显示“新建部门”快捷入口：
+
+- `system.department.create`：调用受限的 `POST /api/system/departments/quick`；
+- `system.department.manage`：兼容既有管理员，调用通用部门创建接口。
+
+快捷创建只接收名称、编码、可选上级和排序，成功后刷新部门列表并自动选中新部门。`system.department.create` 与既有 `system.department.read/manage` 使用同一能力基础 Key `system.department`，接口继续经过 `system.rbac` Feature Guard，并写入 `crud.create` 审计事件。没有创建或管理权限时，表单只显示部门选择，不渲染快捷入口。
+
+## 权限边界
+
+用户页面的新增、编辑和删除入口要求 `system.user.manage`；只有 `system.user.read` 时保持只读。部门下拉还需要 `system.department.read`，快捷创建需要上述 create 或 manage 权限，Server 是最终授权边界。
+
+当前用户资源已接入类型化数据访问上下文。Actor Resolver 从全部启用角色生成 `all`、`tenant`、`department`、`department-and-children`、`self` 或 `custom` grant；多个角色按可见集合并集计算。用户列表、总数、搜索、分页、导出、按 ID 读取、更新、删除和组织移动使用同一约束，跨部门猜测 ID 返回稳定的 `data-scope-denied`，不会只依赖 Web 隐藏。
+
+详细接入契约见 [数据访问范围](./data-access-control.md)。V1 当前只承诺用户资源已经闭环；没有明确 `ownerId` / `departmentId` 归属的资源不会自动套用部门范围。部门树循环、唯一根节点、含下级或用户节点的停用/删除/迁移策略仍属于 `ORG-02`，不能从当前后代解析能力推导为已经完成。

package/template/docs/platform/platform-authentication.md

@@ -0,0 +1,127 @@
+# 客户业务平台认证与会话
+
+## 运行模型
+
+客户业务平台账号保存在 canonical PostgreSQL `users` 表，和 License 签发中心操作员账号完全隔离。认证链路为：
+
+1. Admin Web 通过 `POST /api/auth/login` 校验用户名和密码并只接收 `HttpOnly` Cookie；明确需要 Bearer 的非浏览器客户端使用独立的 `POST /api/auth/api/login`。
+2. 密码只以 Argon2id hash 保存；策略为 12-128 个字符，服务端不会记录或返回明文密码。
+3. 登录成功后签发 256-bit 随机会话 Token；数据库 `server_sessions` 只保存 Token 的 SHA-256 hash。
+4. 浏览器通过 `windy.sid` Cookie 使用会话，登录 JSON 不返回 Token；API 客户端只能从独立 Bearer 签发入口取得 Token，再使用 `Authorization: Bearer <token>`。
+5. Web 启动时通过 `GET /api/auth/session` 恢复当前 Actor，再按 License 状态读取权限快照；Actor Resolver 校验会话状态、吊销时间、过期时间和用户状态，然后从活跃角色聚合角色代码与权限，交给 Role / Permission Guard。
+
+默认会话时长为 8 小时，可通过 `SESSION_TTL_SECONDS` 调整。Cookie 使用 `HttpOnly`、`SameSite=Strict` 和 `Path=/`；`NODE_ENV=production` 时还会启用 `Secure`。
+
+## API
+
+```text
+POST /api/auth/login
+POST /api/auth/api/login
+GET  /api/auth/session
+POST /api/auth/logout
+POST /api/auth/password/change
+GET  /api/auth/sessions
+POST /api/auth/sessions/:id/revoke
+POST /api/auth/sessions/revoke-all
+GET  /api/auth/login-events
+POST /api/auth/users/:id/password
+```
+
+- `POST /auth/login` 是 Admin Web 的 Cookie-only 登录：返回 Session ID、到期时间和非敏感用户信息，设置 `HttpOnly` Cookie，但 JSON 明确不包含 `token` 或 `tokenType`。
+- `POST /auth/api/login` 是非浏览器集成的显式 Bearer 签发缝：返回 Token、`Bearer` 类型、Session ID、到期时间和非敏感用户信息，但不设置 Cookie。它不是 OAuth/OIDC Token Endpoint，也不应被 Admin Web 调用；正式对外开放前仍需在部署层明确客户端、网络、限流和凭据管理边界。
+- `session` 只返回当前 Actor，不返回 Token，并设置 `Cache-Control: no-store`；匿名请求返回 401。
+- `logout` 吊销当前 Bearer/Cookie 会话并清除 Cookie。
+- `GET /auth/sessions` 只按服务端解析出的当前 Session Actor 查询有效会话，不接受客户端 `userId`，并返回 `current`、IP、User-Agent、签发/最近活动/到期时间；不会返回用户 ID、原始 Token 或 Token hash。
+- 用户可以通过 `POST /auth/sessions/:id/revoke` 吊销自己的单个会话；具备 `system.user.manage` 权限的用户仍可吊销其他用户会话。响应显式返回 `currentSessionRevoked`；若吊销的是当前会话，会同时清除 Cookie，后续请求立即变为未认证。
+- `POST /auth/sessions/revoke-all` 默认只吊销本人其它会话并保留当前会话，响应返回吊销数量以及当前会话是否保留。只有显式提交 `{ "includeCurrent": true }` 才会吊销包括当前会话在内的全部本人会话并清除 Cookie；客户端不能提交目标用户 ID。
+- `GET /auth/login-events` 返回当前 Session Actor 最近 20 条登录成功/失败事件。查询条件固定为服务端 Actor，客户端即使提交 `actorId` 也不能读取他人的事件；响应只保留结果、时间、IP、User-Agent 和稳定失败原因，不暴露审计 Actor 或目标账号字段。未知账号登录失败继续归属匿名 Actor，不能借该接口探测账号是否存在。
+- 只有具备 `system.user.manage` 权限的用户可以重置密码。接口接收 `password`，服务端生成 Argon2id hash；通用用户 CRUD 不读写或返回 `password_hash`。重置后账号进入 `must-change-password`，`password_changed_at` 保持空值，并立即吊销该用户全部活跃会话。
+- 已认证用户通过 `POST /api/auth/password/change` 提交当前密码和新密码。服务端固定使用 Session Actor 作为目标用户，不接受客户端 `userId`；校验当前密码、拒绝复用当前密码，并在成功后把状态恢复为 `active`、记录 `password_changed_at`。成功改密会吊销包括当前会话在内的全部会话、清除 Cookie，用户必须用新密码重新登录。
+
+登录成功、登录失败、退出、会话吊销、密码更新和越权拒绝都会写入审计。审计只记录用户、Session ID、结果和稳定原因，不记录明文密码、Bearer Token 或 Cookie。
+
+## Authentication Provider 边界
+
+`AuthService` 不再直接查询密码 hash 或调用 Argon2，而是只调用 `AuthenticationProviderRegistry` 选中的默认 `AuthenticationProvider`。当前默认注册 `LocalArgon2AuthenticationAdapter`：它通过 `AuthRepository` 读取 canonical 用户、使用既有 `PasswordHasher` 验证 Argon2id，并只把启用用户映射回平台 Session。密码修改与管理员重置仍由独立凭据服务负责，不混入 Provider 登录职责。
+
+Provider 契约显式区分 `local`、`oidc`、`ldap` 三类 Provider，以及 `password`、`authorization-code`、`mfa` 能力；认证输入为密码、OIDC 授权码或 MFA challenge 的判别联合，结果为已认证、拒绝或需要 MFA challenge。Registry 会拒绝空 Key、重复 Key 和未注册的默认 Provider，并提供稳定的类型化描述。该端口只是组合与替换边界：当前没有 OIDC callback、LDAP 配置、MFA challenge 存储或企业微信/钉钉实现，不能把契约存在解释为已经支持这些客户集成。真实 Provider 必须在客户场景明确后作为 Adapter 接入并补充配置校验、失败/超时、账号映射、审计和集成回归。
+
+## 管理端账号生命周期
+
+用户创建和编辑继续使用受 Guard 保护的系统资源入口，但身份配置附加领域策略，不能等同于任意 JSON CRUD：
+
+- 创建必须选择启用部门和至少一个启用角色；用户与角色资源不支持通用 JSON 导入，避免绕过这些不变量。
+- Web 创建账号时必须填写一次性初始密码。账号资料保存后调用专用密码接口；密码字段不会进入用户资料、列表响应或通用 CRUD 审计。
+- 管理员可在同一表单执行密码重置。停用、软删除或密码更新都会吊销该用户全部活跃会话；Actor Resolver 同时要求用户仍为启用状态，因此停用后的既有 Token 不能继续访问。
+- 系统必须至少保留一个启用且持有启用 `super-admin` 角色的账号。用户停用、删除、移除角色，以及内置超级管理员角色停用、改码、缩小数据范围、移除用户管理权限或删除，都会被领域策略拒绝。
+- 用户与角色关键变更共享串行 mutation runner，最后管理员检查和写入在当前单 Server 进程内保持原子顺序，并有并发停用回归。多副本部署前仍需把该互斥升级为 PostgreSQL 事务锁或分布式单写者。
+
+自助修改密码、首次登录强制改密、本人设备会话 API、最近登录事件 API、类型化企业身份 Provider 边界与浏览器 Token 返回收口已经闭环。OIDC、LDAP、MFA、企业微信或钉钉的真实接入继续等待客户场景，不是当前完成度的隐含声明。
+
+## Web 登录与权限刷新
+
+Web 路由进入顺序固定为：当前会话 → 强制改密状态 → License 运行状态 → `/api/foundation` 权限快照。会话、License 和权限读取都使用同一轮 single-flight，避免并发组件重复请求；正常路由切换会刷新 License 和权限快照，因此角色、权限、Feature Flag 或新 License 在下一次导航时生效，无需重新构建前端。
+
+会话 Actor 除角色和权限外，只携带当前用户自己的 `username`、`displayName`、`phone`、`email` 可选字段，供账号菜单和页面水印等当前会话体验使用；不会借此返回其他用户资料。
+
+- 未登录访问受保护路径会跳转 `/login?returnTo=...`。`returnTo` 只接受本站绝对路径，拒绝协议相对地址、反斜线、控制字符和登录页自身，防止开放重定向与循环。
+- 登录成功后重新读取 `/auth/session`，清空旧 License/权限缓存并返回安全的原路径。
+- Session Actor 为 `must-change-password` 时，Web 只进入 `/change-password`；服务端同时只放行会话探测、本人改密和退出，避免绕过前端直接访问业务 API。该入口在 License 受限状态下也保持可用。
+- 任意业务请求返回 401 时全局清除会话、License 和权限状态并跳转登录；403 仍按 License、Feature 或权限拒绝处理，不会误判为退出。
+- 退出成功后吊销服务端会话并返回登录页；网络错误不会在客户端伪造“已退出”。
+- License 到期、缺失或无效时，已认证用户仍可读取会话、退出以及进入 License 查看/上传页，不会先请求受限的权限快照。
+- 会话到期后不做客户端静默续期，用户需要重新登录。
+
+## 浏览器凭据与同源边界
+
+Web 只使用服务端设置的 `HttpOnly` Cookie；浏览器登录响应已经不再携带 Bearer Token，因此前端类型也不存在 Token 字段，更不会把 Token 保存到 localStorage、sessionStorage、Pinia 或其它 JavaScript 持久化位置。生产前端所有请求默认使用 `credentials: same-origin` 和相对 `/api` 地址；Bun Web 服务通过 `API_UPSTREAM` 把 `/api` 转发给内部 Server，浏览器始终看到同一 Origin。当前不支持跨 Origin 的带凭据 Web 部署，也没有开启 credentialed CORS。
+
+当前 Cookie 请求的 CSRF 边界由 `SameSite=Strict`、同源 `/api` 和不开放跨域凭据共同组成。它不能防御同源 XSS、被攻陷的同站点应用或错误的反向代理边界；生产仍应只托管可信同源内容并配置合适的 CSP。未来若必须把 Web 与 API 部署到不同 Origin，必须先增加严格 Origin 白名单和独立 CSRF Token/请求头校验，不能只把 `credentials` 改成 `include`。
+
+## 首次初始化
+
+新数据库可在第一次启动 Server 时临时设置：
+
+```text
+WINDY_BOOTSTRAP_ADMIN_PASSWORD=<至少 12 个字符的初始密码>
+```
+
+Server 会幂等创建默认开发管理员和 `developer` 角色；仅当默认管理员尚无密码 hash 时写入初始密码，并把凭据状态设为 `must-change-password`。初始化成功后应从运行环境删除该变量，首次登录完成自助改密，后续通过受权限保护的密码重置 API 管理密码。Feature Flag 修改除 `system.feature.manage` 权限外，还要求活跃角色代码为 `super-admin` 或 `developer`；普通管理员不能通过单独获配该权限绕过角色边界。已有数据库不会自动把既有普通管理员提升为开发角色，需要显式分配 `developer` 角色。
+
+## 开发直通与生产约束
+
+真实会话是默认认证路径。开发直通只在非生产环境可用：
+
+- 配置 `WINDY_DEV_ADMIN_TOKEN` 会显式启用该开发 Token。
+- 配置 `WINDY_DEV_AUTH_BYPASS=1` 会启用默认 `dev-admin-token`，并允许 `user:<userIdOrUsername>` 直通。
+- `WINDY_DB_USER_TOKEN_PREFIX` 只能修改开发直通前缀。
+- `NODE_ENV=production` 时，上述 Token 与 `user:` 直通无条件关闭，即使环境变量误配置也不会生效。
+
+Web 不提供默认开发 Token。只有 Vite 开发模式同时设置 `VITE_DEV_AUTH_BYPASS=1` 和非空 `VITE_DEV_ADMIN_TOKEN` 时，前端才会携带显式 Bearer Token，并在登录页和应用壳持续显示警告；生产构建无条件忽略这两个变量。完成一次真实密码登录后，当前页面生命周期内会停用开发 Token，后续请求只使用 Cookie。Docker Compose 不再注入默认 `dev-admin-token`。
+
+未配置 `DATABASE_URL` 时不会注册真实登录 API；只允许显式的非生产开发直通，不存在内存生产账号或默认生产密码。
+
+## PostgreSQL 交付回归
+
+在安装了 Docker 的交付机或 CI 上运行：
+
+```bash
+bun run test:db:auth
+```
+
+该命令会临时启动 `postgres:17-alpine`、执行正式 migration、写入使用真实 Argon2id 密码的 fixture，并启动两次正式 Server 进程完成以下验证：
+
+- Admin Web 的 `POST /api/auth/login` 响应不返回 Token、只签发 `HttpOnly` Cookie；独立 `POST /api/auth/api/login` 返回 Bearer Token 且不设置 Cookie，数据库在两条路径都只保存密码 hash 和 Session Token 的 SHA-256 hash；
+- Bearer Token 经 Actor Resolver 解析授权快照：`users.role_ids` 只要是数组（包括 `[]`）就是用户角色的 canonical 真相，只有字段为 `NULL` 或非数组旧值时才回退 `user_roles`；对选中的每个启用角色，`roles.permission_keys` 同样只要是数组（包括 `[]`）就覆盖该角色的兼容关系，只有字段缺失时才回退 `role_permissions`；
+- `roleCodes`、`permissionKeys` 和 data access 只从同一组启用角色生成，并对角色 ID、权限 Key 和自定义部门 ID 稳定去重；停用角色及其 JSON/关系权限都不会进入快照；
+- Server 进程退出并重启后，已有 PostgreSQL Session 仍能鉴权；
+- 过期、主动吊销和退出的 Session 均立即失效；
+- 管理员重置后 PostgreSQL 凭据状态为 `must-change-password`、业务 API 返回 `PASSWORD_CHANGE_REQUIRED`，会话探测和本人改密仍可用；本人改密写入 `password_changed_at` 并吊销包括当前会话在内的全部会话，新密码重登后恢复业务访问；
+- 本人会话列表不能被客户端 `userId` 扩大范围，且只标识一个当前会话；单个吊销、默认保留当前会话的批量吊销、显式包含当前会话的全退都会按响应语义立即生效；
+- 本人登录事件同时包含已知账号的登录成功与失败，读取条件固定为服务端 Session Actor，客户端 `actorId` 不能改写查询范围；
+- 即使误配 `WINDY_DEV_AUTH_BYPASS` 和 `WINDY_DEV_ADMIN_TOKEN`，生产环境也拒绝开发 Token 与 `user:` 直通；
+- 认证关键动作落入 PostgreSQL 审计表。
+
+脚本使用随机容器名、随机宿主端口和临时审计恢复文件，并等待 PostgreSQL 连续两次真实 SQL 探活后再迁移，避免镜像初始化阶段的临时 Server 被误判为就绪。成功或失败都会先停止当前 Server，再强制删除 PostgreSQL 容器和临时文件。它验证的是 Server、PostgreSQL 与认证链路，不覆盖反向代理 TLS、浏览器 Cookie 策略或多实例负载均衡；这些属于部署环境验收。
+
+迁移期契约是“canonical 存在即覆盖、缺失才兼容回退”，不是无条件并集。权限策略页面的勾选和取消直接更新 `roles.permission_keys`；空数组表示明确撤销全部权限，不能被残留 `role_permissions` 重新授予。`user_roles` 与 `role_permissions` 仅服务尚未回填 JSON 列的旧记录，导入完成后必须归并到 `users.role_ids` / `roles.permission_keys`。在关系表被前向迁移移除前，不得把 canonical 列重新写成 `NULL`，否则会重新启用兼容回退。