# 山峡化工简单文档库

## 当前方案（2026-10-26）

文档库已接入现有门户 `/doclib/enter`，侧栏点击直接进入门户内页面。采用 **P04 左树右表**，参考 `web-admin/src/views/system/user/index.vue`，视觉遵循 Fresh Mint。

- 左侧同屏展示“我的文档”“分享给我”，下挂文件夹；超级管理员另有“全部文档”。右侧统一列表、搜索、分页。
- 所有登录用户可创建自己的文件夹/子文件夹、上传文件。文件夹支持重命名；仅允许创建人或超级管理员删除空目录。
- 文件默认私有。上传人或超级管理员可选择同租户有效人员分享，接收人能查看详情和下载。清空分享人员即撤回。
- 上传人或超级管理员可删除文件（支持批量、全部验证后才操作）；接收人不能删除或修改分享。删除写入 `del_flag=1`，保留对象和历史。
- 租户强制隔离，超级管理员也仅管理当前租户。目录路径可见不等于目录内全部文件共享。文档按明确人员 ACL 管理，普通部门/角色范围不会扩大私人文档可见性。
- 支持多选逐个立即上传；默认单文件 100 MB。私有 MinIO 桶保存文件，下载每次通过门户认证和 ACL 校验，不对外发送永久对象地址。
- 仅文件管理、详情和下载；不含在线 Office 编辑、版本管理、审批。

## 开发与部署

1. 执行增量 SQL `docs/sql/20261026_simple_doclib.sql`。新增 `biz_doclib_folder`、`biz_doclib_file`、`biz_doclib_share` 三表，MySQL 5.7 / utf8mb4；不更改旧 Cloudreve 库。
2. 使用已有 `MINIO_ENDPOINT`、`MINIO_ACCESS_KEY`、`MINIO_SECRET_KEY`、`MINIO_SECURE`。文档库新增配置：

```dotenv
DOCLIB_MINIO_BUCKET=shanxia-doclib-private
DOCLIB_MAX_UPLOAD_BYTES=104857600
```

3. 私有桶必须与普通附件 `MINIO_BUCKET` 不同，且不得有公开策略。首次使用会创建缺失的桶；检测到策略或访问异常会拒绝存储操作。运行账号需具有此专用桶的创建/检查策略/读写/清理未登记上传权限。
4. 重启后端并发布前端构建。`doclib_router` 沿用原先在 `app/api/__init__.py` 和 `app/main.py` 的注册。
5. 上传接口 `/api/web/doclib/upload` 为 multipart 专用，沿用 Bearer 认证和审计；不参与 JSON 加密。请求体接收阶段最多接受文件限额加 64 KiB 表单开销（包括无 Content-Length 请求）。上传/下载正文不缓存进审计日志。
6. 其他接口仍经过现有 JSON 加密、认证和日志；下载为 `application/octet-stream` 附件，`Cache-Control: no-store`。代理层也应允许业务需要的 100 MB 上传。

本次已对开发 `.env` 所连数据库执行增量 SQL（已确认与 `.env.production` 不同），并创建、验证专用私有桶；本机 8000 后端已重载。**未对生产环境执行迁移或部署。**

## 验证记录

- 后端文档库、上传边界、加密/审计与既有数据权限测试：28 项通过。
- 前端模型/API 契约：7 项通过；定向 Prettier、ESLint、Stylelint 通过。
- 浏览器回归：门户内导航、树切换、目录选择、接收人权限、分享、上传锁定与失败处理、下载删除、搜索/重试/响应布局通过（隔离上下文与模拟 API）。
- 真实开发 MySQL 5.7 + MinIO 联调：上传/读取一致、匿名读取403、旧快照并发分享撤回通过；验收记录已软删除。
- `pnpm build` 成功（现有大块体积警告）；全量 `vue-tsc` 仍有工作区既有错误，新文档库文件无诊断。
- 仓库未找到规范提及的 `scripts/check_field_consistency.py`，已人工核对后端序列化、请求schema、TypeScript和表单字段；元信息、上传人、存储key均不可由客户端覆盖。

## 旧文档库

Cloudreve/OnlyOffice 的旧文件和服务保留。门户不再依赖旧 SSO，但兼容接口仍在。旧文件迁移、停用服务以及历史对象回收应单独安排，不在本次实施中执行。

---

## 历史方案（留档，不再作为当前实施要求）


### 目标

在本仓库 `doclib/` 中，基于 Cloudreve 社区版与 OnlyOffice 文档社区版，做一套供内部查阅、下载和在线修改共享资料的文档库。门户已登录用户可从侧栏「文档库」进入，并按门户用户一一对应到 Cloudreve 账号。

### 范围

| 项 | 决定 |
|---|---|
| 文件库 | Cloudreve 社区版 4.19.1（GPL-3.0），源码在 `doclib/upstream/cloudreve` |
| 在线编辑 | OnlyOffice 文档社区版 10.0.0（AGPL-3.0），用官方社区版镜像，通过 WOPI 接到 Cloudreve |
| 账号 | 门户每个用户对应一个文档库账号（邮箱 `p.{门户用户名}@sso.shanxia.local`，用户名需唯一）。分享、共享权限仍在 Cloudreve 里设置。测试管理员 `test@shanxia.local` 只用于对接，不是门户用户 |
| 数据 | 测试库 MySQL 上的独立库 `cloudreve`，不写入 `shanxia2.0` |
| 门户进入 | 所有已登录角色在侧栏「文档库」打开。门户签发 60 秒一次性票据，文档库页面换成本人的 Cloudreve 会话 |

### 品牌

Cloudreve 对外界面改为山峡化工文档库：

- 站点名、登录页标题：山峡化工文档库
- Logo：沿用门户 `web-admin/public/logo.gif`
- 去掉登录页「Powered by Cloudreve」和界面里的 Cloudreve 产品名

OnlyOffice 编辑器窗口保留其自有标识。社区版协议要求保留 ONLYOFFICE 标志，去标志属于付费开发者版，本期不改编辑器本体。

### 在线编辑

用户只打开文档库。点开 docx、xlsx、pptx、pdf 时，由 OnlyOffice 在浏览器里打开和保存，文件仍存在 Cloudreve。

两边容器要能互相访问：Cloudreve 的站点地址必须能被 OnlyOffice 容器访问，否则打开文件会下载失败。

### 验收

1. 浏览器打开文档库，登录页是山峡化工文档库，看不到 Cloudreve 产品名和 Powered by。
2. 测试账号能登录并看到文件列表。
3. 新建或上传一份 docx，能在浏览器里打开编辑器并保存。
4. 编辑器区域仍显示 OnlyOffice 标识。
5. 门户任意角色登录后打开「文档库」，不再输入文档库密码；同一门户用户再次进入仍是同一个文档库账号，不同门户用户对应不同账号。

### 本机运行

- 文档库：http://127.0.0.1:5212 ，测试账号 `test@shanxia.local` / `Test123456`
- 站点地址固定为 `http://127.0.0.1:5212`。OnlyOffice 按这个地址回读、回写文件；改成 `localhost` 时，容器会解析到 IPv6 并拒绝访问。
- 两个容器重启后，执行 `doclib/scripts/office-bridge.sh`，恢复 127.0.0.1 互相转发。
- 改过 Cloudreve 前端后，在 `doclib/upstream/cloudreve/assets` 执行构建，把 `build` 整目录覆盖到 Cloudreve 数据目录的 `statics`，再重启 Cloudreve 容器，并重新执行上面的转发脚本。

已在浏览器核对：登录页为山峡化工文档库，底部是山峡化工标识；测试文档能在编辑器中打开，保存后的正文能再次打开；编辑器仍保留 ONLYOFFICE 标志。