create-windy 0.2.34 → 0.3.0

package/template/docs/platform/notifications.md

@@ -2,32 +2,88 @@
 
 ## 产品行为
 
-通知管理页 `/system/notifications` 提供广播发布与历史管理。当前一条通知发布后，会进入所有同时具备 `system.notification.read` 权限且 `system.notification` Feature 可用的用户收件箱。Header 点击通知后打开完整正文，并为当前用户写入跨设备共享的已读回执。
+通知管理页 `/system/notifications` 提供广播或定向发布、定时发布、已发布公告修改、不可变版本历史、外部投递状态与归档管理，不是普通用户收件箱。能否修改只取决于当前 Actor 是否通过角色获得独立的 `system.notification.update` 权限；管理页访问、发布、历史查询和归档继续使用 `system.notification.manage`。普通 `system.notification.read` 用户可以在收件箱阅读、筛选、标记已读、维护个人收藏，并设置邮件、短信与分类偏好。
 
-管理页通过页头的“发布新通知”按钮打开发布对话框，避免让常驻表单挤占历史列表。发布过程必须显式提交、点击取消或关闭按钮；点击遮罩层不会误关对话框和丢失已填写内容。对话框遵循全局布局约束：设置适合表单的最小高度且不超过当前屏幕，只有 Body 区域滚动，标题与底部操作始终可见。发布成功后对话框自动关闭并清空表单。
+普通用户收件箱由 `GET /api/notifications` 提供服务端分页与筛选：
+
+- `page`、`pageSize` 保持原有契约，默认每页 10 条、上限 100 条；
+- `q` 在标题、摘要、正文和分类中做不区分大小写的关键词匹配；
+- `category` 按分类精确筛选；
+- `read=read|unread` 筛选当前用户的已读或未读通知；
+- `favorite=true|false` 筛选当前用户的收藏或未收藏通知。
+
+筛选条件使用 AND 组合。服务端先按当前 Actor 的用户 ID、角色和所属部门确定可见通知；部门受众可选择递归包含子部门。用户、角色和部门范围按“或”合并，全部留空时广播。列表查询与总数查询复用同一组条件，`total` 表示筛选后的可见总数，分页不会退化为客户端全量加载。
+
+管理页通过页头的“发布新通知”按钮打开发布对话框。管理员从服务端受控目录选择用户、角色或部门，可选择是否包含子部门、未来发布时间和外部渠道；API 不接受邮箱或手机号等任意投递地址。发布、偏好和编辑对话框都执行未保存保护：关闭、路由离开和浏览器刷新不会静默丢失输入，保存失败时留在原编辑态。
 
 管理列表与用户收件箱共享平台分页契约：默认每页 10 条，服务端上限 100；管理页允许输入范围内任意正整数页大小，并按跨页连续序号展示通知。已发布通知的刷新操作固定在列表右上角，仅显示刷新图标，通过立即出现的组件库 Tooltip 和 `aria-label` 提供名称；加载期间图标旋转且按钮不可重复提交。
 
-通知管理页的人工发布范围仍是全体授权用户，不能通过普通发布 API 伪造定向受众。平台业务端口可以创建受控的用户或角色通知，并携带通用 `TargetRef` 业务目标；当前仅最小审批工作流接入。业务通知使用稳定 `sourceKey` 去重，收件箱查询和已读写入都按当前 Actor 的用户 ID 与角色集合执行最终可见性校验。
+管理员编辑标题、摘要、正文或分类后，服务端在同一事务中更新当前公告并追加新版本；客户端不能指定版本号、修改人或修改时间。内容完全相同时返回 `changed: false`，不会增加版本或重复写审计。并发修改通过行锁串行化，版本号从当前值单调递增。归档后的公告不再允许修改，但仍可分页查看全部历史。编辑对话框存在未保存内容时，关闭、切换路由、刷新或关闭标签页都会触发确认保护。
+
+平台业务端口仍可创建携带通用 `TargetRef` 的用户或角色通知；当前最小审批工作流使用稳定 `sourceKey` 去重。无论人工还是业务发布，收件箱查询、已读和收藏写入都会按当前 Actor 重新执行最终可见性校验。
 
-组织范围、管理端定向/定时发布、用户偏好、策略化合并，以及邮件、短信、企业微信等渠道 Adapter 仍属于 P1，不在现有广播管理页或审批接入中伪装支持。
+站内通知始终保留，个人偏好只控制外部渠道。外部投递的确定顺序固定为：强制类别优先，其次类别退订，最后取“发布者请求渠道”与“用户启用渠道”的交集；未保存偏好时普通类别默认不向外部发送。当前默认把“安全”作为强制类别，但仍不会增加发布者未请求的渠道。收藏与已读不参与渠道策略。
+
+邮件渠道使用 Server 组合根注入的标准 SMTP Adapter，唯一配置来源是类型化 `platformConfig.mail`；`MAIL_SMTP_URL` 仍是 env-only Secret，不进入普通 API、页面、审计或 outbox。短信只定义类型化 `NotificationChannelAdapter` Port：平台不知道供应商报文时不猜格式，未注入 Adapter 的短信投递会明确进入 `dead / CHANNEL_NOT_CONFIGURED`，业务项目可在组合根注入供应商实现。
 
 ## 生命周期与数据
 
-- `platform_notifications` 保存标题、摘要、正文、分类、发布时间和审计字段；业务端口还可写入可选 TargetRef、用户/角色受众和唯一 source key。
+- `platform_notifications` 保存内容、状态、计划/实际发布时间、用户/角色/部门受众、是否包含子部门、请求渠道和审计字段；业务端口还可写入 TargetRef 与唯一 source key。
+- `platform_notifications.revision` 保存当前版本号；`notification_revisions` 以“通知 ID + 版本号”为复合主键保存每次完整内容快照、修改时间与修改人。发布即形成 v1，历史只追加不覆盖。
 - `notification_reads` 以“通知 ID + 用户 ID”为复合主键保存已读时间，重复点击幂等。
-- 管理操作使用归档而不是物理删除。归档后通知立即退出用户收件箱，但通知历史、操作者信息和既有已读回执继续保留。
+- `notification_favorites` 以“通知 ID + 用户 ID”为复合主键保存收藏时间。收藏与已读是两份独立回执：收藏不会自动已读，阅读或取消收藏也不会改写另一份状态。
+- `notification_preferences` 按用户保存启用的外部渠道和退订分类；客户端不能修改其他用户的偏好。
+- `notification_delivery_outbox` 按“通知 + 用户 + 渠道”唯一保存持久投递。Worker 使用 `FOR UPDATE SKIP LOCKED`、lease token、过期租约回收和有界指数退避；成功进入 `delivered`，不可重试、地址缺失或超过上限进入 `dead`。outbox 只保存用户 ID 和通知内容，不保存 SMTP Secret，也不接受客户端地址快照。
+- 管理操作使用归档而不是物理删除。归档后通知立即退出用户收件箱，但通知历史、操作者信息和既有已读、收藏回执继续保留。
 - 无数据库时仅允许开发态内存 Repository；生产部署必须配置 `DATABASE_URL` 并执行迁移。
 
+## 收藏 API 与安全边界
+
+- `PUT /api/notifications/:id/favorite` 把当前用户状态设为收藏；
+- `DELETE /api/notifications/:id/favorite` 把当前用户状态设为未收藏；
+- 两个命令都幂等，响应中的 `changed` 只在本次请求真实改变状态时为 `true`；
+- Repository 在写入或删除个人回执前必须重新校验通知仍为已发布状态且对当前 Actor 可见；
+- 收藏记录始终使用 Guard 解析出的 Actor ID，客户端不能指定用户 ID；
+- 未知、已归档或对 Actor 不可见的通知统一返回 `404`，避免通过猜测通知 ID 探测受众；
+- 快速重复收藏只允许一个插入成功，快速重复取消收藏最多删除一次。
+
+## 定向、偏好与投递 API
+
+- `GET /api/system/notifications/audience-options` 返回当前启用的用户、角色和部门最小投影，要求 `system.notification.manage`；
+- `POST /api/system/notifications` 可提交受众、`includeChildDepartments`、`scheduledFor` 与 `deliveryChannels`；未来时间创建 `scheduled` 通知，调度器到期后以条件更新激活，重复 tick 不会重复发布或投递；
+- `GET/PUT /api/notifications/preferences` 只读取或更新当前 Actor 偏好，要求 `system.notification.read`；
+- `GET /api/system/notifications/:id/deliveries` 查询外部投递状态，要求 `system.notification.manage`；
+- `system.notification.dispatch` 每 5 秒发布到期通知并领取 outbox。投递时再次从受控用户目录解析当前邮箱或手机号，停用用户或缺失地址不会被发送。
+
+## 修改与历史 API
+
+- `PUT /api/system/notifications/:id` 修改仍处于已发布状态的公告，正文结构与发布接口兼容，响应为 `{ notification, changed }`；
+- `GET /api/system/notifications/:id/revisions?page=1&pageSize=10` 按版本号倒序返回不可变历史、修改人和 ISO 8601 修改时间，并返回筛选前该公告的历史总数；
+- 修改接口要求 `system.notification.update`，历史接口要求 `system.notification.manage`；两者都要求 `system.notification` Feature，缺少对应角色权限时返回 `403`；
+- 未知公告返回 `404`；归档公告的修改也返回 `404`，避免暴露额外生命周期细节，历史查询仍可用；
+- 修改输入只接受标题、摘要、正文和分类，沿用发布接口的必填与长度限制；Actor、时间和版本号全部由服务端生成。
+
 ## Feature、RBAC 与审计
 
 能力基础 Key 为 `system.notification`：
 
-- 用户收件箱和已读接口要求 `system.notification.read`；
-- 后台列表、发布和归档要求 `system.notification.manage`；
+- 用户收件箱、已读和个人收藏接口要求 `system.notification.read`；
+- 修改要求独立的 `system.notification.update`；后台列表、发布、历史查询和归档要求 `system.notification.manage`，两项权限可以分别赋予角色；
 - 菜单、Router、Header、Server API 都引用 Manifest 中的同一 Feature / Permission Key；
 - Feature 或权限不可用时 Header 隐藏且不发请求，Server 仍执行最终 Guard；
-- 普通管理发布只接受广播字段；受众和 TargetRef 只由经过组合根注入的业务端口生成，猜测通知 ID 不能绕过已读可见性检查；
-- 发布记录 `notification.publish`，首次阅读记录 `notification.read`，归档记录 `notification.archive`；重复已读不重复制造审计事件。
+- 管理端受众只接受受控目录 ID/角色 code，不接受外部地址；猜测通知 ID 不能绕过已读或收藏可见性检查；
+- 立即发布记录 `notification.publish`，定时创建记录 `notification.schedule`，偏好更新记录 `notification.preference.update`；修改、阅读、收藏和归档沿用既有审计动作。审计 metadata 不记录地址、正文或 SMTP Secret。
+
+发布、修改和归档使用关键审计写入策略。普通已读与收藏使用常规审计，避免审计存储短暂降级时阻止用户消费通知。
+
+## 升级与迁移
+
+个人收藏由 migration `0035_material_nightshade.sql` 引入，公告版本由 `0036_hesitant_speed.sql` 引入。`0038_uneven_wasp.sql` 新增定时/多受众/渠道字段、用户偏好和持久 outbox；旧通知默认保持立即发布、广播且不请求外部渠道。升级平台或通过 Windy 生命周期更新下游项目后：
+
+1. 先审阅生成边界与 `windy update --dry-run` 结果，不手工覆盖 Windy-managed 文件；
+2. 在切换新版 Server 前按生产发布流程备份数据库；
+3. 使用生产唯一入口 `DATABASE_URL=... bun run db:migrate` 应用最新 migration；
+4. 运行 `bun run test:db:migrations` 可验证 fresh migration 与重复执行幂等；
+5. migration 成功后再发布应用。旧客户端仍可只传 `page/pageSize`，无需同步上线筛选、收藏、修改或历史调用；旧公告首次修改会从已回填的 v1 继续递增。
 
-发布和归档使用关键审计写入策略。普通已读使用常规审计，避免审计存储短暂降级时阻止用户阅读正文。
+真实 PostgreSQL 回归可执行 `bun run scripts/notification-postgres-regression.ts`，覆盖 fresh migration、组织子树可见性、偏好持久化、outbox lease 防伪与重建 Repository 后的投递状态。

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

@@ -4,7 +4,7 @@
 
 Windy V1 采用单组织、单租户的企业私有化模型。canonical schema 保留 RuoYi-Vue 兼容导入所需的部门树、用户主部门和角色自定义部门范围，但新模块不得直接依赖旧 `sys_dept` 或其它 `sys_*` 表。
 
-- `departments.parent_id` 表示上级部门，空值为根部门；
+- `departments.parent_id` 表示上级部门，只有平台根组织为空；
 - `users.department_id` 表示用户唯一主部门；
 - `roles.data_scope` 和 `roles.department_ids` 表示角色数据范围策略；
 - 岗位、兼职部门和多组织成员关系属于后续独立模型，不复用 `department_id` 暗中表达。
@@ -20,7 +20,21 @@ Windy V1 采用单组织、单租户的企业私有化模型。canonical schema
 - `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.department.create` 与既有 `system.department.read/manage` 使用同一能力基础 Key `system.department`，接口继续经过 `system.rbac` Feature Guard，并写入 `crud.create` 审计事件。没有创建或管理权限时，表单只显示部门选择，不渲染快捷入口。
+
+## 组织树强不变量
+
+Windy V1 只允许一个未删除根组织。`0037_absent_nick_fury.sql` 通过 PostgreSQL partial unique index 约束根节点数量，并用 check constraint 拒绝直接把部门设为自身上级；Service 在写入前继续覆盖数据库无法表达的整棵树规则：
+
+- 新部门必须选择一个启用上级，不能通过通用或快捷 API 创建第二个根；
+- 根组织不能移动、停用或删除；
+- 部门不能移动到自身或任意下级，异常旧树的遍历使用 visited set 有界终止；
+- 角色 `custom` 数据范围至少选择一个启用部门，未知或停用部门返回 `INVALID_ROLE_DEPARTMENT_SCOPE`；
+- 部门仍有直接下级、未删除用户或角色自定义部门范围时，普通停用和删除返回 `DEPARTMENT_MIGRATION_REQUIRED`，响应包含三类引用计数。
+
+管理端处置部门使用 `POST /api/system/departments/:id/transition`。请求明确给出 `disable` 或 `delete` 以及启用的迁移目标；Server 会拒绝当前节点和其下级作为目标，然后把直接下级的 `parentId`、用户主部门和角色 `departmentIds` 一起迁移，再完成停用或软删除。操作写入 `organization.department.transition` 审计事件，元数据只记录动作、目标 ID 和迁移计数。
+
+用户、角色和部门写操作共享同一个组织 mutation coordinator。无数据库开发模式使用进程内串行；PostgreSQL 使用固定 advisory transaction lock，因此多个 Server 实例的互相移动、用户归属写入和部门处置也按同一事实顺序判定。`bun run test:db:organization` 在 PostgreSQL 17 覆盖唯一根约束、双实例循环竞态和用户归属竞态；`bun run test:db:data-scope` 继续验证组织树调整后数据范围查询不漂移。
 
 ## 权限边界
 
@@ -28,4 +42,4 @@ Windy V1 采用单组织、单租户的企业私有化模型。canonical schema
 
 当前用户资源已接入类型化数据访问上下文。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`，不能从当前后代解析能力推导为已经完成。
+详细接入契约见 [数据访问范围](./data-access-control.md)。没有明确 `ownerId` / `departmentId` 归属的资源不会自动套用部门范围。ORG-02 只覆盖单组织、用户唯一主部门和角色自定义部门范围；岗位、兼职部门与多组织成员关系仍是明确的后续模型，不在本轮暗中扩展。

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

@@ -8,6 +8,7 @@ Server 端已提供系统基础模块 Repository API，用于打通权限、查
 默认无数据库时使用内存 Repository；配置 `DATABASE_URL` 后，系统资源 CRUD 会切换为 Drizzle Repository，并把用户、角色、部门、菜单、字典和功能开关持久化到 PostgreSQL。
 
 <!-- @windy-module system.license begin -->
+
 选择离线 License 模块时，原型 License 兼容记录也会持久化到 PostgreSQL。
 <!-- @windy-module system.license end -->
 
@@ -19,9 +20,13 @@ Server 端已提供系统基础模块 Repository API，用于打通权限、查
 - `menus`：菜单。
 - `dictionaries`：字典。
 - `features`：功能开关。
+
 <!-- @windy-module system.license begin -->
+
 - `licenses`：License 记录。
+
 <!-- @windy-module system.license end -->
+
 - `audit-logs`：审计日志查询。
 
 ## 路由
@@ -34,6 +39,7 @@ GET    /api/system/:resource/export
 GET    /api/system/:resource/:id
 POST   /api/system/:resource
 POST   /api/system/departments/quick
+POST   /api/system/departments/:id/transition
 POST   /api/system/:resource/import
 PUT    /api/system/:resource/:id
 DELETE /api/system/:resource/:id
@@ -68,12 +74,17 @@ GET    /api/system/audit-logs
 
 - 读操作：`system.<resource>.read`。
 - 用户表单快捷创建部门：`system.department.create`；既有通用部门创建仍要求 `system.department.manage`。
+- 部门迁移后停用或删除：`system.department.manage`；接口绑定 `system.rbac` Feature 并记录 `organization.department.transition`。
 - 写操作：`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)。
@@ -86,12 +97,17 @@ GET    /api/system/audit-logs
 - 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 字典页默认使用后台工作流。其它实体尚未注册批量处理器。
+- 用户、角色和部门禁止通用 JSON 导入，避免绕过账号、数据范围和组织树强不变量；部门备份导出仍可用于现场核查。
 
 ## 已完成补强与后续边界
 

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

@@ -9,7 +9,7 @@ Web 端已从单页静态首页推进为带真实会话的 Router 应用壳：
 - 侧边栏菜单可点击跳转，并按当前路由高亮。
 - 顶部面包屑读取 route meta 标题。
 - 顶部账号菜单展示当前 Actor 并提供服务端退出；401 会全局清理会话并返回登录页。
-- 顶部通知入口读取服务端通知收件箱，可打开正文并跨设备保存当前用户已读回执；无 `system.notification.read` 权限或 Feature 关闭时不显示入口，也不会请求通知 API。
+- 顶部通知入口读取服务端通知收件箱，可打开正文并跨设备保存当前用户已读与个人收藏回执；无 `system.notification.read` 权限或 Feature 关闭时不显示入口，也不会请求通知 API。后台通知管理页负责发布、修改、查看不可变历史和归档，普通用户不能修改公告。
 
 ## 页面范围
 
@@ -59,8 +59,12 @@ POST   /api/system/bulk-data/dictionaries/import
 POST   /api/system/bulk-data/dictionaries/export
 GET    /api/notifications
 POST   /api/notifications/:id/read
+PUT    /api/notifications/:id/favorite
+DELETE /api/notifications/:id/favorite
 GET    /api/system/notifications
 POST   /api/system/notifications
+PUT    /api/system/notifications/:id
+GET    /api/system/notifications/:id/revisions
 DELETE /api/system/notifications/:id
 ```
 
@@ -84,7 +88,7 @@ VITE_DEV_ADMIN_TOKEN=<显式开发 Token>
 - Feature 开关成功修改会写入 `feature.update`，可在审计日志页通过“功能开关变更”直接查看。
 - 系统资源表和字典后台任务表加载时保留表头与列宽，并显示带 `animate-pulse` 的骨架行；加载失败和空数据仍使用各自独立状态。
 - 全局水印与业务页面范围默认开启。管理员在“全局设置”中维护总开关、低/中/高密度，并勾选用户名、姓名、手机号、邮箱或最多 80 个字符的自定义内容；保存写入审计并立即成为所有用户的只读策略。客户端按旋转文本包围盒自动计算平铺尺寸与安全间距，长内容和高密度模式也不会相互重叠。用户应用端不提供开关，也不使用 localStorage。`system.watermark` Feature 控制最终生效态，管理区另需 `system.watermark.read/manage` 权限。水印使用专用审计顶层覆盖 Sidebar、Drawer、Overlay 和 Modal，同时保持 `pointer-events-none`。服务端只向当前用户自己的会话响应补充这些身份字段。
-- 站内通知由 PostgreSQL `platform_notifications` 和 `notification_reads` 持久化；管理人员可在 `/system/notifications` 广播发布和归档，用户从 Header 收件箱阅读正文并幂等写入已读回执。归档是生命周期操作，不物理删除通知或回执。当前发布范围是全体有阅读权限的用户，尚未提供组织、角色、用户定向和外部渠道投递。
+- 站内通知由 PostgreSQL `platform_notifications`、`notification_revisions`、`notification_reads` 和 `notification_favorites` 持久化；管理人员可在 `/system/notifications` 广播发布、修改、查看版本历史和归档，用户从 Header 收件箱阅读正文并幂等写入相互独立的已读、收藏回执。修改会生成带服务端时间和 Actor 的完整不可变快照，无内容变化不增加版本。普通用户 API 支持关键词、分类、已读和收藏的服务端组合筛选，列表与 `total` 使用同一可见性范围。归档是生命周期操作，不物理删除通知、版本或回执。
 - 字典页已切换为后台 NDJSON 导入导出，展示本人任务状态、进度、重试和终态文件下载；其它系统资源仍保留小数据同步 JSON 入口。详细契约见 [批量导入导出后台任务](./bulk-data-jobs.md)。当前 artifact 存在 10 MiB、50,000 行和 256 KiB 单行上限，扩大容量前需要对象存储 Adapter。
 - 审计日志配置 `DATABASE_URL` 后读取 PostgreSQL `audit_logs`。可靠写入器提供有界重试、降级状态、关键事件本地恢复队列和健康信息；页面仍只读，且不会展示恢复队列中的事件正文。
 - 运维页的定时任务来自真实代码注册和 PostgreSQL 状态，不允许在线编辑任务代码。当前基线的 `stale` 只做观察告警和人工处置提示，不会自动终止或重试。

package/template/package.json

@@ -16,6 +16,8 @@
     "dev:web": "bun run --cwd apps/web dev",
     "dev:server": "bun run --cwd apps/server dev",
     "dev:agent": "docker compose --profile agent up --build",
+    "dev:adk-web": "docker compose --profile agent-debug up --build adk-web-debug",
+    "dev:search": "OPENSEARCH_URL=http://opensearch:9200 docker compose --profile search up --build",
     "dev:license": "bun run --cwd apps/license dev",
     "dev:license:docker": "docker compose --profile license up license",
     "dev:signing": "bun run --cwd apps/signing-service dev",
@@ -28,6 +30,8 @@
     "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:organization": "bun run scripts/organization-postgres-regression.ts",
+    "test:db:notification": "bun run scripts/notification-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",

package/template/packages/config/index.test.ts

@@ -29,6 +29,51 @@ test("平台 Redis 与 RuoYi 旧 Redis 使用独立 SecretResolver 配置", () =
   );
 });
 
+test("平台设置提供类型化默认值并校验 IANA 时区", () => {
+  const config = loadPlatformConfig({});
+
+  expect(config.security).toMatchObject({
+    sessionTtlSeconds: 28_800,
+    passwordMinLength: 12,
+    passwordMaxLength: 128,
+  });
+  expect(config.storage).toEqual({
+    bulkDataMaxByteSize: 512 * 1024 * 1024,
+    brandingLogoMaxByteSize: 5 * 1024 * 1024,
+  });
+  expect(config.mail).toMatchObject({
+    enabled: false,
+    port: 587,
+    secure: false,
+  });
+  expect(config.regional.timeZone).toBe("Asia/Shanghai");
+  expect(() =>
+    loadPlatformConfig({ REGIONAL_TIME_ZONE: "Invalid/Timezone" }),
+  ).toThrow(
+    expect.objectContaining<Partial<ConfigLoadError>>({
+      code: "CONFIG_INVALID_VALUE",
+      fieldPath: "regional.timeZone",
+    }),
+  );
+  expect(() =>
+    loadPlatformConfig({
+      PASSWORD_MIN_LENGTH: "64",
+      PASSWORD_MAX_LENGTH: "32",
+    }),
+  ).toThrow(
+    expect.objectContaining<Partial<ConfigLoadError>>({
+      code: "CONFIG_INVALID_VALUE",
+      fieldPath: "security.passwordMinLength",
+    }),
+  );
+  expect(() => loadPlatformConfig({ MAIL_ENABLED: "true" })).toThrow(
+    expect.objectContaining<Partial<ConfigLoadError>>({
+      code: "CONFIG_INVALID_VALUE",
+      fieldPath: "mail.fromAddress",
+    }),
+  );
+});
+
 test("strict loader 对 unknown 与错误类型 fail-fast 且不回显输入值", () => {
   expect(() => loadPlatformConfig({ PLATFORM_ENABLE_AII: "true" })).toThrow(
     expect.objectContaining<Partial<ConfigLoadError>>({

package/template/packages/config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/config",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/config/src/platform.ts

@@ -34,7 +34,23 @@ export interface PlatformConfig {
     sessionCookieName: string;
     sessionTtlSeconds: number;
     passwordHash: "argon2id";
+    passwordMinLength: number;
+    passwordMaxLength: number;
   };
+  storage: {
+    bulkDataMaxByteSize: number;
+    brandingLogoMaxByteSize: number;
+  };
+  mail: {
+    enabled: boolean;
+    host: string;
+    port: number;
+    secure: boolean;
+    fromAddress: string;
+    connectTimeoutMs: number;
+    smtpUrl?: string;
+  };
+  regional: { timeZone: string };
   license: {
     enabled: boolean;
     publicKeyId?: string;
@@ -60,56 +76,111 @@ export interface ProjectConfig {
   modules: string[];
 }
 
-const platformSchema: z.ZodType<PlatformConfig> = z.strictObject({
-  name: z.string().trim().min(1).max(120),
-  logoUrl: z.string().trim().url().optional(),
-  enableAI: z.boolean(),
-  database: z.strictObject({
-    dialect: z.enum(["postgresql", "mysql", "dm", "kingbase"]),
-    url: z.string().trim().min(1).optional(),
-    legacyRuoYiMysqlUrl: z.string().trim().min(1).optional(),
-    legacyRuoYiRedisUrl: z.string().trim().min(1).optional(),
-  }),
-  cache: z.strictObject({
-    redisUrl: z.string().trim().min(1).optional(),
-    healthTimeoutMs: z.number().int().min(50).max(10_000),
-  }),
-  security: z.strictObject({
-    sessionCookieName: z.string().trim().min(1).max(120),
-    sessionTtlSeconds: z.number().int().min(60).max(2_592_000),
-    passwordHash: z.literal("argon2id"),
-  }),
-  license: z.strictObject({
-    enabled: z.boolean(),
-    publicKeyId: z.string().trim().min(1).optional(),
-    publicKey: z.string().trim().min(1).optional(),
-    machineCode: z.string().trim().min(1).optional(),
-    versions: z
-      .unknown()
-      .transform((value, context) => {
-        try {
-          return parseLicenseCatalog(value);
-        } catch (error) {
-          context.addIssue({
-            code: "custom",
-            message: error instanceof Error ? error.message : "版本目录无效",
-          });
-          return z.NEVER;
-        }
-      })
-      .optional(),
-  }),
-  audit: z.strictObject({
-    enabled: z.boolean(),
-    redactFields: z.array(z.string().min(1)).min(1),
-  }),
-  compatibility: z.strictObject({
-    ruoyiVue: z.strictObject({
+const platformSchema: z.ZodType<PlatformConfig> = z
+  .strictObject({
+    name: z.string().trim().min(1).max(120),
+    logoUrl: z.string().trim().url().optional(),
+    enableAI: z.boolean(),
+    database: z.strictObject({
+      dialect: z.enum(["postgresql", "mysql", "dm", "kingbase"]),
+      url: z.string().trim().min(1).optional(),
+      legacyRuoYiMysqlUrl: z.string().trim().min(1).optional(),
+      legacyRuoYiRedisUrl: z.string().trim().min(1).optional(),
+    }),
+    cache: z.strictObject({
+      redisUrl: z.string().trim().min(1).optional(),
+      healthTimeoutMs: z.number().int().min(50).max(10_000),
+    }),
+    security: z.strictObject({
+      sessionCookieName: z.string().trim().min(1).max(120),
+      sessionTtlSeconds: z.number().int().min(60).max(2_592_000),
+      passwordHash: z.literal("argon2id"),
+      passwordMinLength: z.number().int().min(8).max(128),
+      passwordMaxLength: z.number().int().min(12).max(512),
+    }),
+    storage: z.strictObject({
+      bulkDataMaxByteSize: z
+        .number()
+        .int()
+        .min(1024)
+        .max(10 * 1024 ** 3),
+      brandingLogoMaxByteSize: z
+        .number()
+        .int()
+        .min(1024)
+        .max(50 * 1024 ** 2),
+    }),
+    mail: z.strictObject({
       enabled: z.boolean(),
-      runtimeReadonly: z.boolean(),
+      host: z.string().trim().max(253),
+      port: z.number().int().min(1).max(65_535),
+      secure: z.boolean(),
+      fromAddress: z.string().trim().max(320),
+      connectTimeoutMs: z.number().int().min(100).max(120_000),
+      smtpUrl: z.string().trim().min(1).optional(),
     }),
-  }),
-});
+    regional: z.strictObject({
+      timeZone: z
+        .string()
+        .trim()
+        .min(1)
+        .max(100)
+        .refine(isSupportedTimeZone, "时区必须是有效的 IANA 时区"),
+    }),
+    license: z.strictObject({
+      enabled: z.boolean(),
+      publicKeyId: z.string().trim().min(1).optional(),
+      publicKey: z.string().trim().min(1).optional(),
+      machineCode: z.string().trim().min(1).optional(),
+      versions: z
+        .unknown()
+        .transform((value, context) => {
+          try {
+            return parseLicenseCatalog(value);
+          } catch (error) {
+            context.addIssue({
+              code: "custom",
+              message: error instanceof Error ? error.message : "版本目录无效",
+            });
+            return z.NEVER;
+          }
+        })
+        .optional(),
+    }),
+    audit: z.strictObject({
+      enabled: z.boolean(),
+      redactFields: z.array(z.string().min(1)).min(1),
+    }),
+    compatibility: z.strictObject({
+      ruoyiVue: z.strictObject({
+        enabled: z.boolean(),
+        runtimeReadonly: z.boolean(),
+      }),
+    }),
+  })
+  .superRefine((config, context) => {
+    if (config.security.passwordMinLength > config.security.passwordMaxLength) {
+      context.addIssue({
+        code: "custom",
+        path: ["security", "passwordMinLength"],
+        message: "密码最小长度不能大于最大长度",
+      });
+    }
+    if (config.mail.enabled && !config.mail.fromAddress) {
+      context.addIssue({
+        code: "custom",
+        path: ["mail", "fromAddress"],
+        message: "启用邮件传输时必须配置发件地址",
+      });
+    }
+    if (config.mail.enabled && !config.mail.smtpUrl && !config.mail.host) {
+      context.addIssue({
+        code: "custom",
+        path: ["mail", "host"],
+        message: "启用邮件传输时必须配置 SMTP URL 或主机",
+      });
+    }
+  });
 
 export const platformConfigDefinition = defineModuleConfig<PlatformConfig>({
   key: "platform.runtime",
@@ -118,9 +189,13 @@ export const platformConfigDefinition = defineModuleConfig<PlatformConfig>({
   ownedEnvironmentPrefixes: [
     "PLATFORM_",
     "DATABASE_",
+    "PASSWORD_",
     "REDIS_",
     "RUOYI_",
     "SESSION_",
+    "STORAGE_",
+    "MAIL_",
+    "REGIONAL_",
     "AUDIT_",
   ],
   ownedEnvironmentKeys: [
@@ -153,6 +228,43 @@ export const platformConfigDefinition = defineModuleConfig<PlatformConfig>({
       strictInteger,
     ),
     value("PLATFORM_PASSWORD_HASH", "security.passwordHash", "argon2id"),
+    value(
+      "PASSWORD_MIN_LENGTH",
+      "security.passwordMinLength",
+      12,
+      strictInteger,
+    ),
+    value(
+      "PASSWORD_MAX_LENGTH",
+      "security.passwordMaxLength",
+      128,
+      strictInteger,
+    ),
+    value(
+      "STORAGE_BULK_DATA_MAX_BYTE_SIZE",
+      "storage.bulkDataMaxByteSize",
+      512 * 1024 * 1024,
+      strictInteger,
+    ),
+    value(
+      "STORAGE_BRANDING_LOGO_MAX_BYTE_SIZE",
+      "storage.brandingLogoMaxByteSize",
+      5 * 1024 * 1024,
+      strictInteger,
+    ),
+    value("MAIL_ENABLED", "mail.enabled", false, strictBoolean),
+    value("MAIL_HOST", "mail.host", ""),
+    value("MAIL_PORT", "mail.port", 587, strictInteger),
+    value("MAIL_SECURE", "mail.secure", false, strictBoolean),
+    value("MAIL_FROM_ADDRESS", "mail.fromAddress", ""),
+    value(
+      "MAIL_CONNECT_TIMEOUT_MS",
+      "mail.connectTimeoutMs",
+      10_000,
+      strictInteger,
+    ),
+    secret("MAIL_SMTP_URL", "mail.smtpUrl"),
+    value("REGIONAL_TIME_ZONE", "regional.timeZone", "Asia/Shanghai"),
     value("LICENSE_ENABLED", "license.enabled", true, strictBoolean),
     value("LICENSE_PUBLIC_KEY_ID", "license.publicKeyId"),
     value("LICENSE_PUBLIC_KEY", "license.publicKey"),
@@ -210,3 +322,12 @@ function value(
 function secret(key: string, path: string) {
   return { key, path, secret: { provider: "env" as const } };
 }
+
+function isSupportedTimeZone(value: string): boolean {
+  try {
+    new Intl.DateTimeFormat("zh-CN", { timeZone: value });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/template/packages/database/drizzle/0035_material_nightshade.sql

@@ -0,0 +1,10 @@
+CREATE TABLE "notification_favorites" (
+	"notification_id" varchar(64) NOT NULL,
+	"user_id" varchar(64) NOT NULL,
+	"favorited_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "notification_favorites_notification_id_user_id_pk" PRIMARY KEY("notification_id","user_id")
+);
+--> statement-breakpoint
+ALTER TABLE "notification_favorites" ADD CONSTRAINT "notification_favorites_notification_id_platform_notifications_id_fk" FOREIGN KEY ("notification_id") REFERENCES "public"."platform_notifications"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "notification_favorites" ADD CONSTRAINT "notification_favorites_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "idx_notification_favorites_user" ON "notification_favorites" USING btree ("user_id","favorited_at");

package/template/packages/database/drizzle/0036_hesitant_speed.sql

@@ -0,0 +1,35 @@
+CREATE TABLE "notification_revisions" (
+	"notification_id" varchar(64) NOT NULL,
+	"revision" integer NOT NULL,
+	"title" varchar(120) NOT NULL,
+	"summary" varchar(240) NOT NULL,
+	"content" text NOT NULL,
+	"category" varchar(40) NOT NULL,
+	"edited_at" timestamp with time zone NOT NULL,
+	"edited_by" varchar(64) NOT NULL,
+	CONSTRAINT "notification_revisions_notification_id_revision_pk" PRIMARY KEY("notification_id","revision")
+);
+--> statement-breakpoint
+ALTER TABLE "platform_notifications" ADD COLUMN "revision" integer DEFAULT 1 NOT NULL;--> statement-breakpoint
+ALTER TABLE "notification_revisions" ADD CONSTRAINT "notification_revisions_notification_id_platform_notifications_id_fk" FOREIGN KEY ("notification_id") REFERENCES "public"."platform_notifications"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "idx_notification_revisions_time" ON "notification_revisions" USING btree ("notification_id","edited_at");--> statement-breakpoint
+INSERT INTO "notification_revisions" (
+	"notification_id",
+	"revision",
+	"title",
+	"summary",
+	"content",
+	"category",
+	"edited_at",
+	"edited_by"
+)
+SELECT
+	"id",
+	1,
+	"title",
+	"summary",
+	"content",
+	"category",
+	"published_at",
+	"created_by"
+FROM "platform_notifications";

package/template/packages/database/drizzle/0037_absent_nick_fury.sql

@@ -0,0 +1,2 @@
+CREATE UNIQUE INDEX "uk_departments_single_root" ON "departments" USING btree (((1))) WHERE "departments"."parent_id" is null and "departments"."deleted_at" is null;--> statement-breakpoint
+ALTER TABLE "departments" ADD CONSTRAINT "departments_parent_not_self" CHECK ("departments"."parent_id" is null or "departments"."parent_id" <> "departments"."id");