# docM

**Repository Path**: zdyumath/doc-m

## Basic Information

- **Project Name**: docM
- **Description**: 文档管理工具，目标通用可集成平台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文档管理工具

企业级文档管理中台，面向 OA、MES、网报等业务系统提供统一的文件、目录、版本、权限、回收站、配额和审计能力。

当前累计产品版本为 `0.4.1`（阶段四补丁，正式 schema V30）。项目采用 Java 21 + Spring Boot + MyBatis + Flyway，前端采用 React 19 + Vite。它在同一套代码中累计包含阶段一文件核心、阶段二开放平台、阶段三存储/权限扩展和阶段四版本、分享、全文搜索、在线编辑、合规与运维能力；`0.4.1` 在 `0.4.0` 基线上补全 iframe 业务目录隔离及三种第三方接入形态的完整生命周期样例。阶段基线通过 Git 标签、产品版本、数据库迁移和测试报告追溯，不复制多套源码。真实 AWS/华为云、企业策略服务、跨主机、非 Chromium 浏览器和信创环境仍属于外部待验收范围，不能把本地协议及兼容测试表述为厂商认证。

## 快速开始

### 开发环境

Windows 在仓库根目录执行：

```powershell
.\scripts\dev-start.ps1
```

也可以双击 `scripts\dev-start.cmd`。启动后访问：

```text
http://127.0.0.1:5173/
```

开发服务监听 `0.0.0.0:5173`，Vite 将 `/api`、`/dl`、`/s/`（匿名分享接口）和 `/actuator` 代理到本机后端 `127.0.0.1:8080`，因此对外测试通常只需开放 5173。代理**保留浏览器的 Host**（`changeOrigin: false`）：分享链接和在线编辑回调 URL 都由后端从请求 Host 反推，改写 Host 会让生成的链接指向 8080——那里没有前端，链接打不开。开发测试账号为：

```text
用户名：admin
密码：admin123admin123
```

停止服务：

```powershell
.\scripts\dev-stop.ps1
```

详细说明见 [本地开发环境](./docs/03-开发/本地开发环境.md)。

### 绿色版

在仓库根目录构建 Windows 绿色版：

```bat
backend\package-green.bat
```

默认产物为 `backend\target\green\`，发布元数据为 `0.4.1 / phase 4 / V30`；阶段一至四原始基线由标签保留，不复制多套源码。构建机需要 JDK 21（含 `jlink`）、Maven 和 Node.js/npm；目标机不需要另装 Java、Node.js、Maven、数据库、Redis、IdP 或 MinIO。Windows 构建产物只能部署到匹配的操作系统和 CPU 架构；Linux 可使用目标机原生脚本或 Docker 构建入口。

将整个绿色版目录复制到目标机后运行 `start.cmd` 或 `start.ps1`。停止时双击 `stop.cmd`，或在命令行执行 `stop.ps1`；脚本会通知应用正常关闭并等待 H2 压实完成，不会直接强杀 Java 进程。`VERSION`、`版本信息.json`/`version-info.json` 和 `SHA256SUMS` 记录产品版本、提交、源码树状态、schema、平台/JRE 架构及全目录校验和；`compliance/` 包含 CycloneDX SBOM、第三方许可证清单和人工复核说明。首次启动会在 `data\initial-admin.txt` 写入管理员凭据。登录并修改密码后删除该文件。停服后可用 `docm-tool.cmd backup --output <文件.docmbak>` 生成数据库、对象、主密钥和配置的统一备份。

完整构建、运行、备份、端口、环境变量和浏览器要求见 [绿色版产品说明](./docs/07-用户与管理员手册/绿色版产品说明.md) 和 [绿色版部署说明](./docs/05-构建与发布/绿色版部署说明.md)；Linux systemd 见 [Linux 绿色版构建与 systemd 部署](./docs/05-构建与发布/Linux绿色版构建与systemd部署.md)。

## 已实现能力

| 领域 | 当前能力 |
|---|---|
| 租户 | 应用、空间、应用/空间隔离，默认应用和空间幂等初始化 |
| 文件 | 目录树、上传、分片上传、断点续传、下载、HTTP Range、复制、移动、改名、软删除 |
| 版本 | 历史版本、指定版本下载、回滚、版本保留数量清理 |
| 搜索与预览 | 名称/正文/综合搜索，内置 Lucene 与可插拔 Elasticsearch/OpenSearch；图片缩放、文本、Markdown、视频拖动和可选水印预览，文件页预览区可真全屏；**PDF 内置预览**（pdf.js 前端渲染，字体与 CMap 随包分发，离线可用，文件页与嵌入页共用）；**Office 文档在配置了在线编辑 Provider（OnlyOffice / Collabora）时以只读会话在预览区内打开**，未配置时降级为说明加下载 |
| 回收站 | 列表、搜索、还原、彻底删除、保留期清理、清空任务 |
| 权限 | 内置角色、空间成员、目录/文件权限和权限审计基础 |
| 管理端 | 应用、用户、空间、存储后端、存储路由、API Key、审计日志、Webhook 管理接口和正式页面 |
| 接入 | OpenAPI 契约、password 登录、标准 OAuth2 `client_credentials` 与旧 JSON 兼容入口、Bearer、API Key、Outbox/Webhook 基础、OA/MES 模拟客户端 |
| 下载体验 | 浏览器 IndexedDB 任务持久化、受控并发 Range 下载、失败续传、暂停、继续、重试、取消、视频原生播放器 |

## 数据库与存储概要

### 数据库

当前明确支持并测试：

- H2 文件数据库：正式/绿色版默认值；
- PostgreSQL 16：外置数据库，Flyway V1-V30 和核心 SQL 已做容器测试。

开发环境使用内存 H2，重启会重新初始化。切换 PostgreSQL 通过 `SPRING_DATASOURCE_URL`、`SPRING_DATASOURCE_USERNAME`、`SPRING_DATASOURCE_PASSWORD` 和可选的 `SPRING_DATASOURCE_DRIVER_CLASS_NAME` 配置完成。达梦/人大金仓已提供外置驱动、profile、schema 校验和真实库验收入口，但缺少本机授权环境，只能标记“适配入口完成、目标环境待验收”；MySQL、MariaDB、Oracle 和 SQL Server 当前未纳入。

### 文件存储

当前支持本地磁盘、MinIO、AWS S3/S3 兼容存储和华为云 OBS。多个存储后端可以同时存在，每个空间绑定一个默认写入后端；阶段三任务 3.4 已增加空间 > 应用 > 全局的写入路由，可按大小、MIME 和扩展名选择后端并预览命中结果。文件写入时固化 `blob.storage_backend_id`，读取时按该记录回到原后端；修改规则或空间默认后端只影响新写入，不会自动迁移旧文件。S3 已通过真实 MinIO S3 API 兼容测试，OBS 已通过本地协议模拟和共享 Provider 合约；真实 AWS、真实华为云 OBS 账号仍待外部验收。

跨后端迁移与安全下线见 [跨后端迁移运行手册](./docs/06-运维手册/跨后端迁移运行手册.md)。详细配置示例和切换注意事项见 [数据库与存储配置指南](./docs/07-用户与管理员手册/数据库与存储配置指南.md) 与 [存储路由配置指南](./docs/07-用户与管理员手册/存储路由配置指南.md)；厂商 IAM、CORS、SSE、生命周期和排障分别见 [AWS S3 存储配置指南](./docs/07-用户与管理员手册/AWS%20S3存储配置指南.md) 与 [华为云 OBS 存储配置指南](./docs/07-用户与管理员手册/华为云OBS存储配置指南.md)。

## 管理员与用户

绿色版/正式环境首次启动默认用户名为 `admin`。密码优先取 `DOCM_INITIAL_ADMIN_PASSWORD`，否则读取或生成 `data\initial-admin.txt`。密码只以 Argon2 哈希保存到数据库；管理员已经存在时，重新设置初始化环境变量不会重置密码。

用户日常操作见 [用户手册](./docs/07-用户与管理员手册/用户手册.md)，应用、空间、存储、权限、API Key、审计和 Webhook 操作见 [管理员手册](./docs/07-用户与管理员手册/管理员手册.md)。

阶段四 `4.0–4.12` 的原始发布基线为 `0.4.0/V29`；版本、分享、全文索引/搜索、在线编辑、信创适配入口、审计合规、统一 `backup/restore/verify/export-space` 离线工具，以及 OAuth 客户端和系统运维正式页面均已收口。`0.4.1/V30` 补充 iframe 的稳定业务目录上下文、附件型与完整工作台，以及 REST、SDK、iframe、Office 和原始 HTTP 的完整接入样例。H2/Local 破坏恢复、PostgreSQL 16 原生工具、真实 MinIO 对象核对、100 万/200 万元数据、1 万份混合语料、10 GiB 等价流和 Chromium 桌面/`390x844` 主流程已验证。目标厂商数据库/编辑器、Linux/ARM64/LoongArch、国产 OS/浏览器及真实云/国产存储仍待外部验收。

## 第三方系统接入

第三方系统可注册为 Application，推荐使用标准 `POST /api/v1/oauth/token` 的 OAuth2 `client_credentials` 获取带 scope 的 Bearer Token，也可为浏览器用户使用 authorization code + PKCE；旧 JSON `/api/v1/auth/token` 和带 scope 的 API Key 仍可调用 `/api/v1`。当前已具备租户隔离、权限收窄、审计、Outbox 和 HMAC Webhook 投递能力；仓库提供 REST 可视化模拟器、Java/Python/JavaScript 真实平台 SDK 示例和独立 iframe 宿主模拟器。

当前阶段二的本地工程收口已完成：OAuth2 authorization code + PKCE、OIDC discovery/JWKS/RSA `RS256/RS384/RS512` 与 EC `ES256/ES384/ES512`、UserInfo `sub`、state/nonce 和外部用户映射均已落地，并使用真实 Keycloak 完成互操作测试；统一 `Idempotency-Key` 支持持久化重放，三维限流支持本机和 Redis 跨实例两种模式。Webhook 已具备 SSRF 防护、保序、熔断、投递观测、数据库原子 claim，并在双 worker 的 240 事件压力测试中未发生重复回调或事件饿死；正式投递语义仍为至少一次，接收方必须按 eventId 去重。三语言 SDK 已通过统一 conformance、真实 DocM 示例和本地仓库发布预检；iframe 一次性受限会话、`/embed` 页面及四种 sandbox 预设已在 Chromium 实测。接入方应先阅读 [第三方接入指南](./docs/08-集成与SDK/第三方接入指南.md)。

三种接入示例入口：

- REST/OpenAPI：`samples/oa-mes-simulator/`
- Java/Python/JavaScript SDK：`samples/sdk-integration-simulator/`
- iframe + `postMessage`：`samples/iframe-host-simulator/`
- 阶段四原始 HTTP：`samples/phase4-http-examples/`

## 项目文档

全部文档的总目录在[文档索引](./docs/文档索引.md)——按读者 / 按类别 / 按阶段三张地图，`docs/` 下 111 份逐份列出，每份一句话。**本节只留入口，不在这里再维护一份逐份清单**：同一份清单存两处就会漂移，而漂的那一份往往是没人核的那份。

| 入口 | 什么时候用 |
|---|---|
| [文档索引](./docs/文档索引.md) | 找任何一份文档 |
| [文档体系说明](./docs/文档体系说明.md) | 文档怎么分类、新文档该放哪、重组前的旧路径怎么找回来 |
| [需求文档](./需求文档.md) | 产品范围、阶段边界、系统限制与验收目标 |
| [架构设计](./架构设计.md) | 数据模型、模块边界、存储抽象、权限与 API 设计 |
| [开发手册 00《导读》](./docs/03-开发/开发手册/00-导读.md) | 要独立读懂这套代码并继续开发：第 1 天 / 第 1 周 / 第 1 月三条路线，再按需读 01–11 章 |
| [本地开发环境](./docs/03-开发/本地开发环境.md) | 第 1 天第一步：装什么、怎么起前后端、端口与账号、日志在哪 |
| [编码与协作规范](./docs/03-开发/编码与协作规范.md) | 第 1 月固定动作第一步：分支与提交约定、评审两问、「改了什么 → 更新哪份文档」判据表 |
| [产品路线图与待办](./docs/01-需求与产品/产品路线图与待办.md) | 还没做完的事：外部验收项、仓库内待办、技术债与风险登记 |
| [CHANGELOG](./CHANGELOG.md) | 版本之间实际变了什么 |
| [测试策略总览](./docs/04-测试与质量/测试策略总览.md) | 测试怎么分层、当前规模、九道闸门各自判什么 |
| [发布流程手册](./docs/05-构建与发布/发布流程手册.md) | 发一个版本要动哪些文件、按什么顺序 |

用户、管理员、运维、接入方各自的阅读顺序在[文档索引](./docs/文档索引.md) §1。

原型位于 `prototype/`，是设计和契约来源，不是正式前端运行时。正式 React 前端位于 `frontend/`。

## 验证命令

前端、契约和生产构建：

```powershell
cd frontend
npm ci
npm run verify
```

后端全量测试：

```powershell
cd backend
mvn clean test
```

`clean` 不可省：`target/surefire-reports` 不会自我清理，而闸门 G6 读的正是这个目录——
只跑过一条用例之后，G6 会对着上一次的陈旧报告判通过（本仓库实测过，理由见
[开发手册 08《测试与质量实践》](./docs/03-开发/开发手册/08-测试与质量实践.md) §5.5）。
**首次克隆之后不要加 `-o`**：本地 Maven 仓库还是空的，离线模式会直接失败；依赖下全之后
再用 `mvn -o clean test` 跑得更快。

存储共享套件与 Linux 候选包：

```powershell
.\scripts\test-storage-provider.ps1 -WithDocker
.\scripts\build-linux-green.ps1
```

SDK 发布技术预检（不上传公共仓库）：

```powershell
.\sdk\publish-preflight.ps1 -PythonExecutable .\.dev\sdk-publish-venv\Scripts\python.exe
```

绿色版构建会自动运行前端 `verify`，后端打包使用 `-DskipTests`；发布前应单独执行后端全量测试。阶段一和阶段二测试报告分别保留对应基线的验证证据，升级兼容说明定义累计发行和回滚边界。

## 当前已知限制

当前仍然打开的限制、外部待验收项、技术债与风险登记，**统一在[产品路线图与待办](./docs/01-需求与产品/产品路线图与待办.md)**，本文不再另存一份。

> 此前同一条限制会同时出现在本文、四份阶段测试报告的「已知边界」、`阶段一路线图.md` 的挂账表和 CI 闸门负例台账的 triage 表里，五处各写各的。代价是真实的：本节上一版写的「冷启动约 11-15 秒」是 `0.1.0` 的口径，而 `0.4.1` 绿色包实测为 12.570 秒。

## 工程约定

参与开发和审查时请遵循 [CLAUDE.md](./CLAUDE.md)，并以实际代码、冻结的 `contract/openapi.yaml`、需求文档和架构设计共同作为依据。