Merge remote-tracking branch 'origin/main' into feat/member-group-hierarchy

hub/src/database/README.md

@@ -72,22 +72,56 @@ allowDevLoginBypass = (NODE_ENV !== "production") && HUB_DEV_LOGIN_BYPASS 为真
 
 | 文件 | 职责 |
 |------|------|
-| `plugin.ts` | 模块对外入口，`hub.ts` 调 `registerDatabasePlugin()`；先挂 concrete 路由再挂 SPA |
-| `routes/databaseRoutes.ts` | 后端 JSON / redirect 路由（`/database/config`、`/database/dev-login`），**数据端点加在这里** |
-| `static.ts` | `registerDatabaseSpa`：托管 `database-admin/build` 的 SPA + `/database/*` fallback |
+| `plugin.ts` | 模块对外入口，`hub.ts` 调 `registerDatabasePlugin()` |
+| `routes/databaseRoutes.ts` | 登录页/dashboard + 各子路由装配点 |
+| `routes/filelibRoutes.ts` | 文件库 树/授权/搜索 API |
+| `routes/fileRoutes.ts` | 文件库 文件内容/导出 API |
+| `routes/libraryPage.ts` | `/database/library` 文件库浏览页 |
+| `filelib/` | 文件库领域层(见下) |
 
 新增一类**数据**端点时：要么直接往 `databaseRoutes.ts` 加 `app.get("/database/...")`，
 要么新建 `routes/xxxRoutes.ts` 并在 `databaseRoutes.ts` 里 `registerXxxRoutes(app, {...})`
-注册一次。**页面**则加在 `database-admin/src/routes/` 下（SvelteKit 路由）。
+注册一次。
 
-## SPA 构建与托管
+## 文件库(filelib/)
 
-- 前端在 `hub/database-admin/`，`npm run build`（或 hub 根的 `npm run database:build`）
-  产出到 `database-admin/build/`。hub 的 `npm run build` 会把两个 SPA 一起带出来。
-- `static.ts` 默认从 `../../database-admin/build` 读产物；可用 `CPH_DATABASE_UI_DIR`
-  覆盖。产物缺失时降级：只 warn，不挂 SPA，`/database/config` 与 `/database/dev-login` 仍可用。
-- 本地开发：hub 根 `npm run database:dev` 起 Vite，它把 `/api`、`/auth`、`/database`
-  代理到 `127.0.0.1:8788`。
+独立文件库模块,语义由仓库根《文件库-接口契约.md》(C/D 编号)与
+`.omo/文件库-开工计划.md`(D11–D19)锚定。**与 hub 自己的 Folder/Project
+(ADR-0021 explorer)是两套体系,不复用。**
+
+| 文件 | 职责 |
+|------|------|
+| `filelib/model.ts` | 角色秩(MANAGE>EDIT>VIEW)、D14 命名规则、FileLibError |
+| `filelib/permission.ts` | 纯权限 reducer(取最高/不降权/祖先继承/D11 冻结),不碰 IO |
+| `filelib/treeService.ts` | 树增删改查;每个写操作同事务落审计 |
+| `filelib/grantService.ts` | 授权管理 + 契约 8.1 矩阵强制 + force_adjust |
+| `filelib/fileService.ts` | 文件路径安全 + 版本化读写(先 git 后审计的顺序铁律) |
+| `filelib/exportService.ts` | 导出 job 状态机(D10 异步)+ ExportAdapter port |
+| `filelib/versionStore.ts` | 契约 C1 port + 内存实现(版本团队 npm 包到位后替换) |
+| `filelib/groupResolver.ts` | 契约 C2 port + Team 过渡实现 |
+| `filelib/groupResolverHttp.ts` | C2 HTTP 实现(HUB_GROUP_SERVICE_URL 启用;失败 → 503) |
+| `filelib/audit.ts` | 审计动作词表(C3 §6.3)+ 同事务写入 |
+| `filelib/guards.ts` | session → FileLibActor;网站管理员 = org OWNER/ADMIN(D19) |
+| `filelib/routeShared.ts` | 路由共享件(依赖装配/错误映射/请求体校验) |
+
+环境变量:
+
+- `HUB_FILELIB_STORAGE_ROOT` — 项目 git 仓库根目录(默认 `./.filelib-repos`)
+- `HUB_GROUP_SERVICE_URL` — Group 团队服务地址(C2);未配置时读 hub Team(扁平)
+
+> ⚠️ 开发期注意:当前 VersionStore 是**进程内存**实现,**服务重启后仓库全失**,
+> 此前创建的项目再访问文件会报 `repo_not_found`(需重建项目)。版本团队的
+> 持久化 git 包到位后此问题消失。
+
+关键语义速查:
+
+- **D8**:无权限 → 404(不泄露存在性);越权 → 403;Group 服务故障 → 503
+- **D11**:creator 不可变 + 自动 MANAGE;独立权限关闭时项目级非创建者 grant 冻结
+- **D12**:move = 本节点 MANAGE + 目标父 EDIT+,事务 + pg 咨询锁
+- **D15**:删除只打标本节点,"任一祖先已删"即整支不可见
+- **8.1**:MANAGE 仅创建者可授/收;creator grant 不可动
+- **审计**:一切写操作在业务事务内写 AuditEntry(同事务,失败即回滚);
+  文件内容写先 versionStore.commit 再审计(宁多版本,不造假审计)
 
 ## 约定（与 admin 面一致）