shanxia2.0/doclib/需求说明.md

山峡化工简单文档库

当前方案（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。文档库新增配置：

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 标志。