create-windy 0.1.0

package/template/docs/platform/platform-shell-settings.md

@@ -0,0 +1,88 @@
+# 平台外壳、品牌设置与水印
+
+## 定位
+
+平台外壳负责所有业务模块共用的导航、搜索、品牌和身份水印。入口必须来自 Module Manifest，并同时经过 Feature、RBAC 与 License 有效态裁剪，不能在 Header、Sidebar 和路由中各维护一套权限判断。
+
+## 导航与搜索
+
+- Sidebar 保留 Manifest 的目录层级，当前默认分为“组织与权限”“平台配置”“安全与合规”“运维”。分组可独立折叠，展开状态保存在当前浏览器。
+- 菜单管理只持久化父目录、同级顺序和显隐；路由、权限、Feature 和标题仍由 Manifest 注册。启动同步会软删除旧水印、按钮型和已经撤销注册的历史菜单行，细节见 [Manifest 菜单注册与导航结构](./navigation-registry.md)。
+- 平台 Logo 和软件名称区域始终跳转工作台首页。
+- 桌面端外壳固定为视口高度，Sidebar 与右侧内容区各自滚动；Header 位于内容滚动容器之外，页面上下滚动时保持固定。
+- Header 搜索以 `system.search` 为能力基础 Key，并由 `system.search.read` 权限控制；它只索引当前用户可访问的菜单，支持点击打开、`Ctrl/Command + K`、关键词过滤和 Enter 打开首项。
+- 系统通用资源页使用 `resourceKey` 作为实例 Key。资源切换必须重建请求与表格状态，禁止把功能开关响应继续渲染为角色数据。
+- 字典批量任务只有在 `system.bulk-data` 最终有效且当前用户具有字典读取权限时才挂载；未获 License Entitlement 时显示说明，不发出必然失败的请求。
+
+## 全局品牌设置
+
+能力基础 Key 为 `system.settings`：
+
+- Feature：`system.settings`
+- 权限：`system.settings.read`、`system.settings.manage`
+- Sidebar 入口：侧边栏底部 / 全局设置
+- 审计动作：`config.update`
+
+公开接口 `GET /api/platform/branding` 只返回非敏感的 `softwareName`、可选 `logoUrl` 和可选 `description`，供登录页和应用外壳使用。管理接口 `GET/PUT /api/system/settings/branding` 经过 Feature 与 RBAC Guard。全局设置使用独立 `/settings` 页面，不使用 Modal；Sidebar 从授权后的 Manifest 菜单中提取该入口并固定在底部。页面使用 shadcn-vue Tabs 组织“基本信息”和“水印设置”；水印 Tab 仍独立经过 Feature 与权限裁剪，后续邮件、存储、安全等设置应按同一方式增加类型化分类。
+
+全局设置的 Tab 必须反映在 URL hash 中：基本信息使用 `/settings#basic`，水印设置使用 `/settings#watermark`。直接访问、刷新、浏览器前进后退和复制链接都应恢复到对应 Tab；缺失或未知 hash 回退到 `#basic`。由代码切换 Tab 时先完成未保存编辑确认，确认完成前不能提前修改 hash。
+
+配置 PostgreSQL 时，品牌信息写入 `platform_branding_settings` 单例记录；未配置数据库的开发环境使用内存 Repository。未保存运营配置时回退到 `PLATFORM_NAME`、`PLATFORM_LOGO_URL`。Logo 可以使用 HTTP、HTTPS、以 `/` 开头的站内路径，或由页面读取本地 PNG、JPEG、WebP 后生成的不超过 1 MiB 的受限图片数据；拒绝 SVG、任意 `data:`、`javascript:` 等可能执行内容的协议。
+
+数据库连接、Cookie Secret、License 公钥、Vault 和签发凭据不属于运营品牌设置，不能加入这个运营设置页面。
+
+## 未保存编辑保护
+
+该规则适用于全局设置，也适用于所有具有编辑状态的页面、抽屉、Modal 和 Dialog：
+
+- 各编辑区以最近一次成功加载或保存的数据作为基线，使用规范化后的当前值与基线比较得到 `dirty` 状态。不能仅在首次输入时把状态永久设为脏，也不能因 Tab 暂时卸载而丢失编辑内容。
+- 当 `dirty` 为真时，关闭抽屉、Modal 或 Dialog，切换页面、设置 Tab、菜单或路由都必须先打开统一确认 Dialog。文案需明确说明当前修改尚未保存，继续离开不会保存这些修改。
+- 确认 Dialog 提供“取消”和“保存”两个主要动作。取消会关闭确认框并留在当前编辑态；保存使用原编辑区相同的校验和提交函数，按钮显示 loading、禁止重复提交，成功后更新基线并继续之前被拦截的动作。
+- 校验或保存失败时不得关闭编辑容器、切换 Tab、修改 URL 或跳转路由；保留用户输入，恢复按钮可操作状态，并在当前编辑区显示错误。
+- 应用内跳转由统一的组件关闭拦截和 Vue Router Guard 处理。受保护的 Tab 切换也视为导航，包含 `/settings#basic` 与 `/settings#watermark` 之间的 hash 变化；确认流程应保存一个待继续动作，避免保存成功后再次触发确认。
+- 浏览器刷新、关闭标签页或窗口使用原生 `beforeunload`。仅在 `dirty` 且未处于已确认的成功保存流程时注册或触发提示；浏览器决定提示文案，应用不依赖自定义文本。
+- 保存成功、用户明确重置或服务端数据重新加载后才清除 `dirty`。禁止用路由卸载、组件销毁或切换 Tab 的副作用静默清除未保存状态。
+
+通用实现应沉淀为可复用的未保存编辑保护 composable 和确认 Dialog，而不是在各页面复制路由判断。新增可编辑页面至少覆盖：无修改直接离开、取消后保留输入、保存 loading、防重复提交、保存成功后继续、保存失败后停留、hash/路由切换拦截和 `beforeunload` 注册清理测试。
+
+## 水印
+
+能力基础 Key 为 `system.watermark`：
+
+- Feature：`system.watermark`
+- 权限：`system.watermark.read`、`system.watermark.manage`
+- 页面入口：全局设置 / 页面水印，不注册独立 Sidebar 菜单
+
+只有 Feature 最终有效且当前用户具有读取权限时才渲染水印及全局设置中的水印区块。当前版本的显示开关与自定义内容是用户在当前浏览器的偏好；默认内容从当前 Actor 派生，顺序为用户名加手机、邮箱或姓名。
+
+后续若引入平台强制水印策略，应由服务端持久化并审计，生效关系为：Feature 开启，且平台强制显示，或平台允许用户控制且个人偏好开启。普通用户不能覆盖“强制显示”。
+
+## 个人设置
+
+- 右上角账号头像菜单提供“个人设置”入口，路由为 `/profile`；该入口不会重复出现在 Sidebar 导航中。
+- 当前用户可查看账号名，并在拥有 `system.profile.manage` 权限时修改姓名、邮箱和手机。账号名仍由管理员在用户管理中维护。
+- `system.profile` 同时注册 Feature Flag、`system.profile.read/manage` 权限、页面入口和 API 绑定。功能关闭或权限缺失时，页面路由和服务端 API 都会拒绝访问。
+- `PUT /api/system/profile` 只修改当前会话对应的用户，不接受目标用户 ID；成功后写入 `user.profile.update` 审计事件，Web 端会刷新会话和授权快照，使 Header 中的姓名立即更新。
+
+## Feature 开关交互
+
+开关使用 Reka UI 的 `data-state="checked|unchecked"` 状态选择器。切换时先乐观显示目标状态，只锁定当前行；服务端失败时恢复原状态并显示原因。管理资格只由 `system.feature.manage` 决定，不再硬编码 `developer`、`super-admin` 等角色名称。
+
+内置 `developer` 角色在启动时会补充 Manifest 新增的权限和菜单 Key，避免模板升级后管理员因为旧数据库角色快照而看不到新控制面；已有自定义授权不会被删除。
+
+## 权限中文元数据
+
+角色权限树的模块与资源标题直接读取 Module Manifest 中必填的 `moduleLabel` 和 `resourceLabel`，不在前端维护 License、notification、profile 等英文 key 的翻译表。新能力缺少中文分组元数据会在 TypeScript 类型检查阶段失败；CRUD 生成器也会同步生成这两个字段。
+
+## 运维验证
+
+修改这些能力时至少执行：
+
+```bash
+bun run typecheck
+bun test apps/server/src/settings apps/server/src/system/seed.test.ts
+bun run --cwd apps/web test -- NavigationSearchDialog.webtest.ts SystemResourceRoutePage.webtest.ts Switch.webtest.ts
+bun run build
+```
+
+涉及 schema 时还需运行 `bun run test:db:migrations`，确认全量迁移和二次执行均通过。

package/template/docs/platform/scheduled-task-executor.md

@@ -0,0 +1,89 @@
+# 平台定时任务执行器
+
+## 目标与边界
+
+平台定时任务由服务端代码注册，数据库保存当前调度状态和执行历史。控制台或 API 不能创建任意可执行代码，避免把数据库配置变成远程代码执行入口。
+
+本期支持：
+
+- 固定间隔调度；
+- 单任务并发控制；
+- 手动触发；
+- 有上限的失败重试；
+- 疑似停滞执行的受控人工恢复；
+- 执行结果、错误和重试链路查询；
+- Permission、动态 Feature Flag、Entitlement Guard；
+- 读取、触发、执行和拒绝事件审计。
+
+本期不实现 Cron 表达式、分布式工作流编排、任务代码在线编辑和 RuoYi 旧库任务写入。
+
+## 定义与注册
+
+任务定义位于 `apps/server/src/scheduler/definitions.ts`。每个定义必须提供稳定且唯一的 `key`，并声明：
+
+- 中文名称与说明；
+- 执行间隔；
+- 最大尝试次数与重试延迟；
+- 所需权限；
+- 所属 Feature；
+- 服务端 handler。
+
+服务启动时会幂等同步定义元数据。已移除的定义会归档并停用，历史执行记录仍保留；重新加入代码注册表后恢复为活跃定义。
+
+## Guard 模型
+
+调度器使用 `system.scheduler` Feature，其商业授权标识是 `capability.scheduler`。每次定时执行、失败重试、手动触发和人工恢复都按以下顺序重新判定：
+
+1. License 是否处于允许业务运行的状态；
+2. License 是否包含 `capability.scheduler`；
+3. 数据库中的 `system.scheduler` 动态 Feature 是否启用且可见；
+4. 执行身份是否具备 `system.scheduler.manage`。
+
+查询定义和历史还要求 `system.scheduler.read`。Feature 停用后，不需要重启服务；新的调度、重试和手动触发都不会进入 handler。已领取但在 Guard 阶段被拒绝的后台执行记录为 `blocked`，用于解释为什么到期任务没有运行。
+
+## 并发与调度
+
+`scheduled_tasks` 保存下一次执行时间。领取到期任务时，Repository 在 PostgreSQL 事务中取得任务级 advisory lock，确认任务仍然到期、活跃且没有运行中的实例，再推进下一次执行时间并创建执行记录。
+
+`scheduled_task_runs` 还有一个条件唯一索引：同一 `task_key` 在 `status = 'running'` 时最多存在一行。事务锁负责正常竞争，唯一索引作为数据库最终防线。因此同一进程的重复 tick、多个 Server 实例以及手动触发和调度竞争，都不能让同一任务并发失控。
+
+进程内 worker 同样禁止 tick 重入。轮询间隔由 `SCHEDULER_POLL_INTERVAL_MS` 设置，默认一秒；任务自己的执行间隔仍以持久化定义为准。
+
+## 重试与历史
+
+handler 抛出错误后，本次记录进入 `retry-pending`，并保存经过长度限制的错误消息和 `nextAttemptAt`。到达重试时间后，调度器原子地把旧记录固定为 `failed`，创建 `trigger = 'retry'` 的下一次记录，并递增 `attempt`。
+
+达到 `maxAttempts` 后不再重试。成功记录为 `succeeded`；Guard 拒绝为 `blocked`。每次尝试都是独立历史行，`retryOfRunId` 保留重试链路，不覆盖之前的错误。
+
+## API
+
+- `GET /api/system/scheduled-tasks`：查询已注册任务和下一次执行时间；
+- `GET /api/system/scheduled-task-runs?page=1&pageSize=10`：分页查询执行历史，默认每页 10 条，单页最大 100 条；
+- `GET /api/system/operations/scheduler`：查询运维总览使用的代码注册定义、持久状态、最近历史和运行/重试/stale 派生状态；
+- `POST /api/system/scheduled-tasks/:id/trigger`：手动触发任务；
+- `POST /api/system/scheduled-tasks/:id/runs/:runId/recover`：人工确认并解除一条疑似停滞执行对后续调度的占用。
+
+以上 GET 与 POST 均登记在 System Module Manifest：总览要求 `system.scheduler.read`，手动触发和人工恢复要求 `system.scheduler.manage`，并完整执行 `License → Entitlement → Feature → RBAC` 顺序。同一任务正在运行时，手动触发返回 `409 TASK_ALREADY_RUNNING`；未知任务返回 `404 TASK_NOT_FOUND`；Guard 拒绝返回 `403 FORBIDDEN`。handler 业务失败会形成可查询、可重试的执行记录，不伪装成并发或权限错误。
+
+手动触发属于关键审计事件，使用 AUDIT-01 的可靠写入与恢复队列。只有 `task.trigger` 成功持久化或进入可恢复队列后才会调用 handler；两者均不可用时，本次 run 会落为 `blocked` 并返回 `503 AUDIT_UNAVAILABLE`，不会遗留 `running`。
+
+## 运维总览与 stale 语义
+
+Web `/system/operations` 通过独立 typed composable 读取调度总览，不再展示硬编码的 `planned` 占位任务。页面展示代码注册定义、数据库中的启用/归档和下次执行状态、每个任务的最近执行、等待重试数量和脱敏限长的错误摘要，并在手动触发前二次确认。
+
+最近执行历史使用独立的服务端分页表格，默认每页 10 条，允许输入 1 至 100 的任意页大小；首页和末页的翻页按钮按状态禁用。表格直接显示中文任务名称、触发方式、结果、执行次数和开始时间，稳定任务 key 只在零延迟组件库 Tooltip 中显示。手动触发或人工恢复成功后同时刷新任务概览和当前历史页。
+
+`stale` 本身仍是纯观察状态：当一条 `running` 记录持续至少 15 分钟，总览将其派生为“疑似停滞”。派生判断不会修改 `scheduled_task_runs`，不会自动领取、终止或重试任务。该阈值是没有 heartbeat/lease 之前的告警启发式，不等同于任务已经失败。
+
+只有总览中满足上述条件的记录才显示“人工确认恢复”。操作员必须先确认旧 Server 进程和 handler 已停止、核查可能已经产生的业务副作用，再填写 8 至 500 字且包含中文的处置原因并勾选二次确认。普通 `running` 记录不显示恢复按钮。
+
+恢复请求必须同时提交当前页面观察到的 `runId`、`taskKey` 和 `expectedStartedAt`。Repository 使用原子 compare-and-set，只有目标记录仍为 `running`、`startedAt` 与预期完全一致且仍超过 15 分钟阈值时，才把原历史行终结为 `blocked`，写入恢复编号、操作者、脱敏限长原因和 `automaticRetry: false` 元数据，并释放同任务单 `running` 条件唯一索引。任何状态变化、时间版本变化或未达到阈值都返回 `409`；不会调用 handler，也不会创建重试执行。历史行不会删除或覆盖成成功，后续正常调度仅按原任务计划重新领取。
+
+`task.recover` 采用两阶段审计边界：原子恢复前先可靠写入关键 intent 事件，包含恢复编号、run、预期开始时间、操作者和脱敏原因摘要；数据库与恢复队列都不可用时返回 `503 AUDIT_UNAVAILABLE`，且不改变 run。CAS 成功或冲突后再写普通 outcome 事件。由于审计与 scheduler Repository 不是同一事务，竞争冲突可能留下 intent 但不会留下未经关键 intent 的状态变更；CAS 后普通 outcome 写入失败按 AUDIT-01 降级状态和告警处理。
+
+## 运维注意事项
+
+- 正式环境应配置 PostgreSQL；未配置数据库时只使用开发态内存 Repository，重启后不保留历史。
+- 任务 handler 应保持幂等，因为数据库可以保证领取不重入，但无法回滚 handler 已经提交到外部系统的副作用。
+- 当前没有运行中任务的租约和强制中断。人工恢复只是经确认后终结 stale 调度记录并释放后续调度，不会停止仍存活的旧 handler，也不会补偿它已经产生的外部副作用；在没有可靠心跳和业务幂等证明前绝不自动抢占或重跑。
+- 总览不返回 handler `result`，错误摘要会对常见凭据字段和 Bearer token 脱敏并限制为 240 字符；handler 仍不得把密钥或完整外部凭据写入异常消息。

package/template/docs/platform/system-crud-api.md

@@ -0,0 +1,100 @@
+# 系统基础模块 CRUD API
+
+## 当前状态
+
+Server 端已提供系统基础模块 Repository API，用于打通权限、查询、分页、排序、过滤、软删除和审计事件闭环。
+资源 API 已支持 JSON 导入和导出，用于客户单机部署时快速迁移基础配置或生成现场备份。
+
+默认无数据库时使用内存 Repository；配置 `DATABASE_URL` 后，系统资源 CRUD 会切换为 Drizzle Repository，并把用户、角色、部门、菜单、字典和功能开关持久化到 PostgreSQL。
+
+<!-- @windy-module system.license begin -->
+选择离线 License 模块时，原型 License 兼容记录也会持久化到 PostgreSQL。
+<!-- @windy-module system.license end -->
+
+当前覆盖资源：
+
+- `users`：用户。
+- `roles`：角色。
+- `departments`：部门。
+- `menus`：菜单。
+- `dictionaries`：字典。
+- `features`：功能开关。
+<!-- @windy-module system.license begin -->
+- `licenses`：License 记录。
+<!-- @windy-module system.license end -->
+- `audit-logs`：审计日志查询。
+
+## 路由
+
+资源路由统一挂在 `/api/system` 下。
+
+```text
+GET    /api/system/:resource
+GET    /api/system/:resource/export
+GET    /api/system/:resource/:id
+POST   /api/system/:resource
+POST   /api/system/departments/quick
+POST   /api/system/:resource/import
+PUT    /api/system/:resource/:id
+DELETE /api/system/:resource/:id
+GET    /api/system/audit-logs
+```
+
+其中 `audit-logs` 目前只提供查询；配置 `DATABASE_URL` 后优先读取 PostgreSQL `audit_logs`，未配置时读取当前进程内存审计事件。
+
+## 导入导出
+
+- 导出：`GET /api/system/:resource/export`，复用 `q`、`status`、`includeDeleted`、`sort` 查询参数，返回 JSON 快照。
+- 导入：`POST /api/system/:resource/import`，请求体支持 `{ "mode": "create" | "upsert", "items": [...] }`。
+- `create` 模式遇到已有 `id` 会跳过，`upsert` 模式遇到已有 `id` 会更新。
+- 导入成功写入 `data.import` 审计事件，导出成功写入 `data.export` 审计事件。
+
+## 查询参数
+
+- `page`：页码，默认 `1`。
+- `pageSize`：每页条数，默认 `10`。Web 端允许直接输入 `1` 至 `100` 的任意整数，不限于固定档位。
+- `q`：关键词，按资源配置的字段模糊匹配。
+- `status`：状态过滤。
+- `includeDeleted=true`：包含软删除数据。
+- `sort`：排序字段，逗号分隔；前缀 `-` 表示倒序，例如 `-updatedAt,name`。
+
+`audit-logs` 额外支持 `actorId`、`action`、`resource`、`resourceId` 过滤。
+
+`page` 必须是正整数，`pageSize` 必须是 `1` 至 `100` 的整数；越界或非整数请求返回 `400 INVALID_PAGINATION`，响应同时给出 `maxPageSize`，不会静默截断。通用数据表首列使用 `(page - 1) * pageSize + rowIndex + 1` 显示跨页连续序号；没有服务端分页的短列表只显示本地序号，不伪造总数和页码。
+
+## 权限
+
+路由使用统一 Guard：
+
+- 读操作：`system.<resource>.read`。
+- 用户表单快捷创建部门：`system.department.create`；既有通用部门创建仍要求 `system.department.manage`。
+- 写操作：`system.<resource>.manage`。
+- 审计日志：`system.audit.read`。
+- 系统资源默认绑定 `system.rbac` Feature，审计日志绑定 `system.audit`。
+<!-- @windy-module system.license begin -->
+- License 资源绑定 `system.license`。
+<!-- @windy-module system.license end -->
+- Guard 固定按 Entitlement、动态 Feature Flag、RBAC 顺序判定。Feature 声明了 `requiredEntitlement` 但 License 快照缺失该能力、开关关闭/隐藏或用户缺少权限时，路由返回带稳定 `reason` 的 `403`，并记录 `security.denied`。
+
+配置 `DATABASE_URL` 后，Admin Web 使用 `/api/auth/login` 签发的 `windy.sid` HttpOnly Cookie；明确的非浏览器集成使用 `/api/auth/api/login` 独立签发的 Bearer Token。Server 只用 Token hash 查询未过期、未吊销的服务端会话，再从数据库活跃用户和角色聚合权限。开发 Token 必须显式配置，且 `NODE_ENV=production` 时强制关闭；完整说明见 [客户业务平台认证与会话](./platform-authentication.md)。
+
+## 当前边界
+
+- 未配置 `DATABASE_URL` 时仍使用内存 Repository，服务重启后数据会丢失。
+- 配置 `DATABASE_URL` 后，系统资源使用 Drizzle Repository，启动时会按 `id` / `key` 幂等写入默认种子数据，不覆盖已有记录。
+- Feature Flag 是受控资源：Key 和元数据由 Module Manifest 幂等同步，API 只允许修改 `enabled` / `visible`，不提供创建、导入或删除入口。Manifest 移除的 Key 会归档保留历史状态。
+- Feature Guard 在配置数据库时按请求、按 Key 读取运行态；同一请求缓存结果，下一请求重新读取。开发无数据库时回退 Manifest，生产无数据库或读取失败时 fail closed。
+- CRUD 成功和权限拒绝会先进入进程内审计 sink；配置 `DATABASE_URL` 后由可靠写入器写入 PostgreSQL `audit_logs`。普通事件持续失败时业务继续并告警；用户、角色、License 与 Feature Flag 等关键变更必须落库或进入本地原子恢复队列。策略、状态和恢复步骤见 [平台审计可靠写入](./audit-reliability.md)。
+- 密码登录、服务端会话、退出和吊销已闭环；通用用户 CRUD 不读写或返回密码 hash，密码更新走受权限保护的认证 API。
+<!-- @windy-module system.license begin -->
+- 正式运行时 License 通过 `/api/license/runtime` 查看，并通过 `/api/license/runtime/install` 复用 SDK 验签和单槽原子替换；通用 `legacy_licenses` CRUD 只保留为显式原型兼容面，不能提供生产授权。
+- License 限制模式只对显式列举的系统资源 JSON 导出放行，导出仍需通过原有 Feature 与 RBAC Guard；其它 API、Agent Tool 和后台任务先由 License Guard 阻断。
+<!-- @windy-module system.license end -->
+- `feature_flags` 的 Drizzle 路径已补齐完整审计字段和软删除列；`0005` migration 会回填既有数据的 `created_by` 后再设置非空约束。
+- 通用系统资源仍保留同步 JSON 文件能力；字典已额外接入后台 NDJSON 任务、本人进度查询、失败明细和结果留存，Web 字典页默认使用后台工作流。其它实体尚未注册批量处理器。
+
+## 已完成补强与后续边界
+
+- 审计写入已有有界重试、失败/丢弃/排队计数、健康状态、结构化告警和关键事件恢复队列；关键业务写入与审计仍不是同一数据库/文件事务，失败重试前必须先查询业务状态。
+- Web 菜单、路由和按钮已经使用服务端 Feature/权限快照；Feature 修改同时要求 `system.feature.manage` 和 `super-admin` / `developer` 角色，Server 继续执行最终强制校验。
+- 按真实资源处理器继续扩展后台任务；当前不能用字典批量接口处理其它实体。现有 PostgreSQL artifact 仅适用于 10 MiB、50,000 行和 256 KiB 单行上限，扩大容量前应增加对象存储 Adapter。

package/template/docs/platform/web-system-crud.md

@@ -0,0 +1,96 @@
+# Web 系统基础模块页面
+
+## 当前状态
+
+Web 端已从单页静态首页推进为带真实会话的 Router 应用壳：
+
+- `App.vue` 按 route meta 切换登录布局与 `AppShell`，未认证用户不会先看到业务壳。
+- 首页内容迁移到 `pages/dashboard/DashboardPage.vue`，只展示平台状态指标和需要处理的提醒；导航入口统一由 Sidebar 和 Header 搜索提供，账号信息与个人设置统一由 Header 头像菜单提供。
+- 侧边栏菜单可点击跳转，并按当前路由高亮。
+- 顶部面包屑读取 route meta 标题。
+- 顶部账号菜单展示当前 Actor 并提供服务端退出；401 会全局清理会话并返回登录页。
+- 顶部通知入口读取服务端通知收件箱，可打开正文并跨设备保存当前用户已读回执；无 `system.notification.read` 权限或 Feature 关闭时不显示入口，也不会请求通知 API。
+
+## 页面范围
+
+当前已接入以下系统页面：
+
+- `/system/users`：用户体系。
+- `/system/roles`：权限策略。
+- `/system/departments`：部门组织。
+- `/system/menus`：菜单管理。
+- `/system/dictionaries`：字典管理。
+- `/system/features`：功能开关。
+- `/system/license`：License。
+- `/system/audit`：审计日志。
+- `/system/operations`：在线会话、应用与数据库资源、Redis 探活和定时任务。
+- `/system/notifications`：通知发布、历史管理和归档。
+
+用户、角色、部门、字典、功能开关和审计日志等通用资源页面共享 `SystemResourcePage`、`SystemResourceTable`、`SystemResourceForm` 和 `useSystemResource`，资源差异通过 `resource-config.ts` 声明。菜单管理是 Manifest 驱动的专用导航结构页，只允许调整父目录、同级顺序和显隐；License 和运维总览也使用各自的专用页面与 composable。
+
+权限策略使用 `/api/foundation` 返回的 Manifest 权限目录，按模块、资源和操作三级级联勾选。数据范围使用受控枚举下拉框；不在当前 Manifest 中的历史权限会明确列出，管理员可以保留或取消，不会在编辑时静默丢失。`roles.permission_keys` 是运行时唯一权限事实来源，因此取消勾选后不会被旧关系表重新授予。
+
+用户新增和编辑表单使用启用部门下拉和启用角色多选，并由 Server 校验 `departmentId`、`roleIds` 和角色状态。创建账号必须填写一次性初始密码，编辑时可按需重置；密码只发送到专用认证接口。具有 `system.department.create` 或既有 `system.department.manage` 权限时，表单提供新建部门快捷入口，创建成功后自动选中。停用账号会吊销全部活跃会话，最后一个超级管理员受到服务端保护；组织模型和数据范围见 [部门组织与用户归属](./organization-membership.md) 与 [数据访问范围](./data-access-control.md)。
+
+## API 对接
+
+Web 通过 `services/` 下的资源、License、运维和批量任务 API service 复用统一同源 HTTP 客户端访问 Server：
+
+```text
+GET    /api/system/:resource
+POST   /api/system/:resource
+POST   /api/system/departments/quick
+POST   /api/auth/users/:id/password
+PUT    /api/system/:resource/:id
+DELETE /api/system/:resource/:id
+PUT    /api/system/menus/:id/placement
+GET    /api/system/:resource/export
+POST   /api/system/:resource/import
+GET    /api/system/audit-logs
+GET    /api/license/runtime
+POST   /api/license/runtime/install
+GET    /api/system/operations
+GET    /api/system/operations/scheduler
+POST   /api/system/scheduled-tasks/:id/trigger
+GET    /api/system/bulk-data/jobs
+GET    /api/system/bulk-data/jobs/:id
+GET    /api/system/bulk-data/jobs/:id/artifacts/:kind
+POST   /api/system/bulk-data/dictionaries/import
+POST   /api/system/bulk-data/dictionaries/export
+GET    /api/notifications
+POST   /api/notifications/:id/read
+GET    /api/system/notifications
+POST   /api/system/notifications
+DELETE /api/system/notifications/:id
+```
+
+开发服务把 `/api` 代理到 `http://localhost:3000`。默认不携带开发 Token；需要调试直通时必须同时显式设置：
+
+```text
+VITE_API_BASE=/api
+VITE_DEV_AUTH_BYPASS=1
+VITE_DEV_ADMIN_TOKEN=<显式开发 Token>
+```
+
+该直通只在 Vite 开发模式生效并持续显示警告。生产构建使用相对 `/api`，由 Bun Web 服务通过 `API_UPSTREAM` 转发到内部 Server；浏览器只使用同源 HttpOnly Cookie，不持久化 Bearer Token。
+
+## 当前边界
+
+- 当前页面对接 Server 端系统资源 Repository；未配置 `DATABASE_URL` 时刷新后服务端数据不持久，配置后由 Drizzle Repository 持久化。正式部署必须配置数据库，不能把内存 Repository 当作生产权威。
+- 审计日志页面只读，不提供删除入口；可按动作精确筛选，并提供“功能开关变更”等常用快捷筛选。时间统一按 `Asia/Shanghai` 显示为 `yyyy-mm-dd HH:mm:ss`。
+- `/system/license` 已从原型记录 CRUD 切换为所有已认证用户可用的运行状态和文件上传入口；它只安装厂商内部 `apps/license` 签发服务生成的文件，不在客户现场提供签发能力。普通用户只看到必要状态、到期时间和联系管理员提示，具备 `system.license.manage` 的维护人员才看到完整 License 与设备详情。页面提供 60/30/7 天分级提醒，并在限制模式下收敛导航。
+- Web 导航源于 `/api/foundation` 返回的 Module Manifest 菜单声明，并按当前 Actor 权限和服务端 Feature 有效状态过滤；Router Guard 会重新获取快照阻断直接访问，按钮使用同一快照。Feature 管理页只允许修改 `enabled` / `visible`，编辑能力同时要求 `system.feature.manage` 和 `super-admin` / `developer` 角色；Server 仍是最终授权边界。
+- Feature 管理页在列表最右侧操作栏直接显示启停开关，不再打开通用编辑弹窗；修改仍调用受 Guard 和关键审计保护的 Server API。
+- Feature 开关成功修改会写入 `feature.update`，可在审计日志页通过“功能开关变更”直接查看。
+- 系统资源表和字典后台任务表加载时保留表头与列宽，并显示带 `animate-pulse` 的骨架行；加载失败和空数据仍使用各自独立状态。
+- 全局水印默认开启，内容按“用户名 + 手机号 / 邮箱 / 姓名”的顺序从当前会话 Actor 派生。`system.watermark` Feature 和 `system.watermark.read` 权限共同控制渲染及“全局设置”页内的水印区块；水印不注册独立 Sidebar 入口。用户可关闭或写入最多 80 个字符的自定义内容，偏好只保存在当前浏览器，不是平台级强制策略。服务端只向当前用户自己的会话响应补充这些身份字段。
+- 站内通知由 PostgreSQL `platform_notifications` 和 `notification_reads` 持久化；管理人员可在 `/system/notifications` 广播发布和归档，用户从 Header 收件箱阅读正文并幂等写入已读回执。归档是生命周期操作，不物理删除通知或回执。当前发布范围是全体有阅读权限的用户，尚未提供组织、角色、用户定向和外部渠道投递。
+- 字典页已切换为后台 NDJSON 导入导出，展示本人任务状态、进度、重试和终态文件下载；其它系统资源仍保留小数据同步 JSON 入口。详细契约见 [批量导入导出后台任务](./bulk-data-jobs.md)。当前 artifact 存在 10 MiB、50,000 行和 256 KiB 单行上限，扩大容量前需要对象存储 Adapter。
+- 审计日志配置 `DATABASE_URL` 后读取 PostgreSQL `audit_logs`。可靠写入器提供有界重试、降级状态、关键事件本地恢复队列和健康信息；页面仍只读，且不会展示恢复队列中的事件正文。
+- 运维页的定时任务来自真实代码注册和 PostgreSQL 状态，不允许在线编辑任务代码。当前基线的 `stale` 只做观察告警和人工处置提示，不会自动终止或重试。
+
+## 后续工作与验证边界
+
+- 按实际资源处理器逐一扩展后台批量任务；当前只支持字典，不能把字典接口伪装为其它实体能力。
+- 当前自动化测试覆盖 Vue 组件、Router、同源 HTTP 客户端和 Server API，但未使用真实浏览器验证 Cookie、反向代理 TLS、跨 Origin 或多实例负载均衡。跨 Origin 部署前必须先设计 Origin 白名单、CSRF Token 和 Cookie Domain。
+- 客户 License 文件安装串行化和时间回拨高水位当前是单进程状态；多副本 Web/Server 部署不能在未增加单写者或跨进程协调前共享写入同一路径。

package/template/docs/product/built-in-roles.md

@@ -0,0 +1,26 @@
+# 平台内置角色基线
+
+## 首次安装
+
+Starter 首次安装提供四个稳定角色。角色 ID 和 code 是升级契约，不随显示名称改变：
+
+| ID                        | code                 | 名称       | 默认数据范围 | 默认定位                            |
+| ------------------------- | -------------------- | ---------- | ------------ | ----------------------------------- |
+| `role_super_admin`        | `super-admin`        | 超级管理员 | 全部         | 平台全部能力与导航                  |
+| `role_department_manager` | `department-manager` | 部门负责人 | 部门及下级   | 用户、部门只读和个人常用能力        |
+| `role_user`               | `user`               | 普通用户   | 仅本人       | 个人设置、通知、搜索和 License 状态 |
+| `role_developer`          | `developer`          | 开发运维   | 全部         | 开发、运维与升级恢复控制面          |
+
+初始 `admin` 用户归属 `role_super_admin` 和 `dept_platform`。从旧版本升级时会补入超级管理员角色和缺失部门，但保留已有角色归属。
+
+## 升级同步
+
+运行时以 Manifest 当前权限和导航注册补充内置角色缺失项，不删除客户已经追加的自定义权限或菜单。`super-admin` 补齐全部注册能力；`developer` 补齐标准能力，但不会因为自动同步获得标记为 `sensitive-disclosure` 的明文查看权限或 `governed-export` 的治理导出权限。这两类高风险能力必须显式授权，已经由客户显式授予的权限在重复同步时保留。部门负责人和普通用户只补齐各自的最小基线。角色名称、数据范围和已有自定义授权不会在每次启动时被覆盖。
+
+数据库 migration `0016_seed_platform_roles.sql` 幂等登记稳定角色，并升级已存在的 `user_dev_admin`。实际 Manifest 权限集合由启动同步写入，避免在 SQL migration 中复制一份会随模块演进而漂移的 Key 列表。
+
+## 安全边界
+
+当前 `dataScope` 和 `departmentIds` 已持久化，但 Repository 查询级的数据范围 Guard 仍是产品缺口。为避免默认角色越权写入，部门负责人基线暂不授予 `system.user.manage` 或 `system.department.manage`。在部门及下级查询约束和越权测试完成前，不应通过 seed 扩大该角色的写权限；管理员仍可按部署需求显式配置自定义角色。
+
+用户敏感字段策略将 `system.user.read`、`system.user.reveal` 和 `system.user.export` 分为三类能力。普通读取只能取得服务端脱敏结果；明文查看与治理导出即使由超级管理员执行，也必须重新授权并写入关键审计。客户端提交的角色 code、权限数组或展示模式不是授权来源。

package/template/drizzle.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  dialect: "postgresql",
+  schema: "./packages/database/src/schema/index.ts",
+  out: "./packages/database/drizzle",
+  casing: "snake_case",
+  migrations: {
+    table: "__drizzle_migrations",
+    schema: "drizzle",
+  },
+  dbCredentials: {
+    url:
+      process.env.DATABASE_URL || "postgresql://localhost:5432/windy",
+  },
+});

package/template/examples/inventory-item.crud.json

@@ -0,0 +1,55 @@
+{
+  "schemaVersion": 1,
+  "module": {
+    "name": "inventory",
+    "label": "库存管理",
+    "description": "库存物料独立业务模块。",
+    "version": "0.1.0"
+  },
+  "entity": {
+    "name": "InventoryItem",
+    "pluralName": "InventoryItems",
+    "label": "库存物料",
+    "table": "inventory_items",
+    "resource": "item",
+    "route": "/api/inventory/items",
+    "featureKey": "inventory.item",
+    "featureLabel": "库存物料管理",
+    "allowedLicenseVersions": ["standard", "advanced"],
+    "fields": [
+      {
+        "name": "code",
+        "column": "code",
+        "label": "物料编码",
+        "type": "string",
+        "maxLength": 80,
+        "required": true,
+        "unique": true,
+        "searchable": true
+      },
+      {
+        "name": "name",
+        "column": "name",
+        "label": "物料名称",
+        "type": "string",
+        "maxLength": 120,
+        "required": true,
+        "searchable": true
+      },
+      {
+        "name": "quantity",
+        "column": "quantity",
+        "label": "库存数量",
+        "type": "integer",
+        "required": true
+      },
+      {
+        "name": "available",
+        "column": "available",
+        "label": "是否可用",
+        "type": "boolean",
+        "required": true
+      }
+    ]
+  }
+}

package/template/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "windy-platform-template",
+  "version": "0.1.0",
+  "private": true,
+  "license": "UNLICENSED",
+  "type": "module",
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
+  "scripts": {
+    "prepare": "husky",
+    "dev": "bun run --cwd apps/web dev",
+    "dev:web": "bun run --cwd apps/web dev",
+    "dev:server": "bun run --cwd apps/server dev",
+    "dev:license": "bun run --cwd apps/license dev",
+    "dev:signing": "bun run --cwd apps/signing-service dev",
+    "generate:crud": "bun run packages/crud-generator/src/cli.ts",
+    "create:windy": "bun run packages/create-windy/src/cli.ts",
+    "test:create-windy": "bun run packages/create-windy/src/regression.ts",
+    "build": "bun run --cwd apps/web build",
+    "build:license": "bun run --cwd apps/license build:web",
+    "db:generate": "drizzle-kit generate --config drizzle.config.ts",
+    "db:migrate": "drizzle-kit migrate --config drizzle.config.ts",
+    "test:db:auth": "bun run scripts/auth-postgres-regression.ts",
+    "test:db:data-scope": "bun run scripts/data-scope-postgres-regression.ts",
+    "test:db:governance": "bun run scripts/governance-postgres-regression.ts",
+    "test:db:legacy-license": "bun run scripts/legacy-license-migration-regression.ts",
+    "test:db:license-bootstrap": "bun run scripts/license-bootstrap-postgres-regression.ts",
+    "test:db:migrations": "bun run scripts/database-migration-regression.ts",
+    "test:db:config": "bun run scripts/module-configuration-postgres-regression.ts",
+    "test:redis:health": "bun run scripts/redis-health-regression.ts",
+    "test:vault:signing": "bun run scripts/vault-signing-regression.ts",
+    "test:docker:license-signing": "bun run scripts/license-signing-compose-regression.ts",
+    "test:ops:recovery": "bun run scripts/production-recovery-regression.ts",
+    "test:ops:amd64": "bun run scripts/linux-amd64-container-regression.ts",
+    "ops:db": "bun run scripts/production-database.ts",
+    "ops:release": "bun run scripts/production-release.ts",
+    "test:release:evidence": "bun run scripts/release-evidence.ts",
+    "typecheck": "bun run --cwd apps/web typecheck && bun run --cwd apps/server typecheck && bun run --cwd apps/license typecheck && bun run --cwd apps/signing-service typecheck && bun run --cwd packages/license-sdk typecheck && bun run --cwd packages/storage typecheck && bun run --cwd packages/database typecheck && bun run --cwd packages/crud-generator typecheck && bun run --cwd packages/create-windy typecheck",
+    "lint": "oxlint .",
+    "format": "oxfmt",
+    "test": "bun test --path-ignore-patterns='packages/create-windy/template/**' && bun run --cwd apps/web test"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/pg": "^8.20.0",
+    "drizzle-kit": "^0.31.10",
+    "husky": "^9.1.7",
+    "oxfmt": "^0.59.0",
+    "oxlint": "^1.74.0",
+    "typescript": "5.9.3"
+  },
+  "dependencies": {}
+}