本项目采用 MIT License，允许个人和企业使用、修改、分发、闭源集成、售卖及提供收费 SaaS；使用或分发时须保留版权声明和许可文本。

AI WorkMate 是一个面向企业协同场景的 AI 助手与 OA 工作台平台。项目采用两个独立 Vite SPA、一个 Spring Boot 模块化单体，以及 PostgreSQL/pgvector、Redis、MinIO 等基础设施，当前已覆盖认证、动态权限、审批、人事、行政资产、知识库、流式 AI 对话和受控 Agent 执行链路。

打开 Archify 交互式系统架构图 · 查看架构图规格 · 查看视觉检查报告

核心边界如下：

• frontend-main：营销官网，独立运行于 3000。
• frontend-oa：企业 OA 工作台，独立运行于 3001，根路径 / 跳转到 /oa。
• backend：Java 17 + Spring Boot 3 模块化单体，统一提供 REST、SSE、认证、领域服务、RAG 和 Agent 任务能力。
• Agent Runtime：Planner 与 Worker 不能直接调用工具处理器；所有 Agent 工具执行必须经过进程内 ToolGateway.execute(stepId, workerLease)。
• PostgreSQL + pgvector：承载业务数据、RBAC、会话、知识向量、Agent 任务快照与审计；Schema 由 Flyway 独占管理。
• Redis：用于登录保护、验证码、缓存及运行时辅助能力。
• MinIO：保存聊天附件、员工档案、印章文件、头像和壁纸等对象。
• OCR：PaddleOCR + PyMuPDF 可选服务，用于图片和扫描版 PDF 文字提取。

• 密码登录、邮箱验证码登录、注册、重置密码、图形验证码和登录失败保护。
• Spring Security + JWT 无状态鉴权；除认证与系统健康接口外，业务 API 默认要求认证。
• 后端根据认证用户实时解析角色、权限、数据范围和租户，不依赖前端隐藏按钮保证安全。
• 动态菜单由 GET /api/navigation 返回；权限后台支持角色、成员、组织、权限和动态路由配置。
• 中文与英文国际化，两个前端共享 workmeta-locale，后端错误消息按 Accept-Language 返回。

• 驾驶舱、待办、通知、考勤打卡、补卡、异常、统计和考勤设置。
• 通用审批的草稿、提交、撤回、重新发起、转交、抄送、加签、催办和审批时间线。
• 审批表单、流程和规则配置，并在申请时冻结定义快照。
• 人事组织、员工档案、附件和入转调离流程。
• 资产领用、归还、调拨、维修、盘点和报废。
• 会议室预约与冲突检测、访客预约与到访生命周期、印章申请与实际用印归还。
• 动态菜单、访问页签、主题、壁纸、个人资料和服务端用户设置。
• Ant Design 业务组件、ECharts 图表和响应式中后台布局。

• 独立 /oa/ai-workspace 页面，包含会话列表、消息区、附件、引用和流式输入体验。
• 对话与消息服务端持久化，SSE 流式回复，认证用户只能访问自己的资源。
• 文档上传、解析、分块、向量化、pgvector 检索和 PostgreSQL 全文检索。
• 可配置本地或 OpenAI 兼容 Embedding 服务，以及可选 Rerank 服务。
• 图片和扫描版 PDF 可通过可选 OCR 服务提取文字；能力不可用时返回真实错误，不伪造成功。

• 持久化任务、步骤、事件、租约 Worker、幂等、取消、恢复、保留清理和 SSE 进度。
• 当前代码登记 152 个工具：50 个只读、102 个受控写，覆盖审批、人事、资产、会议、访客、用印、财务、知识库、设置和平台观测。登记数量不代表运行启用或验收数量，详见全页面工具交付清单。
• 每个任务最多一个写步骤，并按风险要求确认；新增通用申请、费用原子提交工具默认保持关闭，需独立验收与发布。
• Tool Gateway 重新校验任务快照、租户、用户、实时权限、Worker 租约、attempt、哈希、确认、预算、Kill Switch 和审计。
• 工具 Handler 只能通过固定注册表分派；领域 Service 再次校验租户、所有权、权限和业务状态。
• SQL、代码执行、文件系统、任意 URL、权限修改、删除、批量操作、敏感导出、外部消息和后台自治属于永久禁止能力。
• Agent 与写工具默认关闭；数据库策略只能进一步收紧能力，不能绕过代码安全上限。

当前问题与剩余验收见 OA 与 Agent 问题基线；本轮按用户要求停止扩展，收尾情况见 工作树提交记录。R3–R4 验收记录保留对应历史提交的结果，不能代替本轮验收。安全设计详见 Phase 2 Agent 安全边界、Tool Gateway 架构 和 Agent 任务引擎。

ai-workmate/
├─ frontend-main/                  # 营销官网独立 Vite SPA，端口 3000
├─ frontend-oa/                     # OA 工作台独立 Vite SPA，端口 3001，base=/oa/
├─ backend/                       # Spring Boot 模块化单体，端口 8080
│  └─ src/main/
│     ├─ java/com/aiworkmate/
│     │  ├─ config/               # Security、AI、存储与框架配置
│     │  ├─ controller/           # REST/SSE 协议入口
│     │  ├─ service/              # 领域服务接口与实现
│     │  ├─ mapper/               # MyBatis-Plus 数据访问
│     │  ├─ entity/               # 数据库实体
│     │  ├─ dto/                  # API 请求/响应契约
│     │  ├─ security/             # JWT 与认证上下文
│     │  └─ agent/                # Planner、任务引擎、Gateway、Registry、Worker、Handler
│     └─ resources/
│        ├─ application.yml
│        └─ db/migration/         # Flyway 版本化迁移，唯一 Schema 入口
├─ docker/ocr-service/            # 可选 OCR 服务源码
├─ docs/                          # 架构、规则、路线图、交付报告与 Skills
├─ scripts/                       # 部署、数据库验收、OCR 与 Iconfont 工具
├─ docker-compose.yml             # 基础设施、后端、两个前端和可选 OCR
├─ start.bat                      # Windows 本地多服务启动器
├─ .env.example                   # 本地开发配置模板
└─ .env.docker.example            # Docker 部署配置模板

目录名 frontend-main 和 frontend-oa 是当前仓库的既有名称。旧 frontend 边界已废弃，不要重新合并两个前端。

• Java 17
• Maven 3.9+
• Node.js 20+ 与 npm
• Docker Desktop 或兼容的 Docker Compose 环境
• PostgreSQL 16 + pgvector、Redis 7、MinIO（推荐直接使用 Compose）
• 64 位 Python 3.10/3.11（仅本地安装 OCR 时需要）

PowerShell：

Copy-Item .env.example .env

Bash：

cp .env.example .env

至少检查并替换：

• DB_PASSWORD
• JWT_SECRET（至少 32 字节随机值）
• AI_API_KEY
• MINIO_ACCESS_KEY / MINIO_SECRET_KEY
• 邮箱登录需要的 SMTP_*
• 知识库需要的 EMBEDDING_*；默认 local 模式要求本地 Embedding 服务运行于 127.0.0.1:18080

不要提交 .env、.env.docker、真实账号、Token、API Key 或生产连接串。

docker compose up -d postgres redis minio

后端启动时会自动执行 backend/src/main/resources/db/migration 中的 Flyway 迁移，无需手工执行 init.sql。

cd backend
mvn spring-boot:run

分别打开两个终端：

cd frontend-main
npm install
npm run dev

cd frontend-oa
npm install
npm run dev

访问 http://localhost:3000 或直接打开 http://localhost:3001/oa/。

首次完成两个前端的 npm install，并确保 PostgreSQL、Redis、MinIO 已启动后，可运行：

.\start.bat

启动器会检查 Java、Maven、npm 和 Windows Terminal，释放 8080、3000、3001 端口，然后分别打开后端、官网和 OA 标签页；如已安装 OCR，也会启动 8686 服务。

Copy-Item .env.docker.example .env.docker
docker compose --env-file .env.docker up -d --build

必须显式传入 --env-file .env.docker，否则 Compose 不会读取该文件中的构建期变量，例如 VITE_OA_URL。

默认启动 PostgreSQL、Redis、MinIO、后端、营销官网和 OA。启用可选 OCR：

docker compose --env-file .env.docker --profile ocr up -d --build

部署形态支持：

• 分端口：主站 3000，OA 3001/oa/。
• 同域名反向代理：设置 VITE_OA_URL=/oa/，由外部 Nginx 将 /oa/ 转发到 OA 容器。
• 独立 OA 域名：将 VITE_OA_URL 设置为完整 OA 地址。

生产部署前必须替换模板中的所有密钥和占位值，并启用 HTTPS；AUTH_COOKIE_SECURE 应设置为 true。

OCR 用于图片与扫描版 PDF 的聊天和知识库文本提取。未启用时主链路仍可运行，但相关识别请求会明确返回能力不可用。

Windows 本地安装：

.\start.bat --install-ocr

Docker 启用方式见上一节。OCR 主要配置：

• OCR_ENABLED
• OCR_BASE_URL
• OCR_API_KEY
• OCR_USE_GPU
• OCR_MAX_PAGES
• OCR_TIMEOUT_MS
• OCR_MIN_CONFIDENCE

更多说明见 OCR 聊天处理链路。

Agent 的安全默认值是全部关闭：

AGENT_ENABLED=false
AGENT_PLANNING_ENABLED=false
AGENT_EXECUTION_ENABLED=false
AGENT_WRITE_TOOLS_ENABLED=false

本地验收 Phase 2A 时，可以在受控环境中开启前三项，但还必须在 agent_tenant_policy 中显式启用目标租户。环境变量不能覆盖租户策略、Registry、实时权限、风险等级、确认或永久禁止清单。

AGENT_WRITE_TOOLS_ENABLED 属于 Phase 2B 全局发布门。即使设置为 true，写工具仍需租户写策略、工具策略、实时权限和一次性确认全部通过；未经独立人工批准不得在生产启用。

• Flyway 是部署环境 Schema 的唯一入口，迁移位于 backend/src/main/resources/db/migration。
• V1–V4 是已发布基线，文件名和内容不得修改。
• 新迁移使用 VYYYYMMDDHHMM__description.sql，以分钟粒度递增。
• 已执行迁移禁止重命名、删除或修改 checksum；修正结构必须新增更高版本的前向迁移。
• 迁移保持幂等，不在脚本中手写 BEGIN / COMMIT。
• backend/src/main/resources/db/init.sql 只作为历史手工初始化和 CI 参考，不再自动执行。

真实 PostgreSQL 验证入口：

.\scripts\verify-p1-postgres.ps1 `
  -DatabaseUrl 'jdbc:postgresql://localhost:5432/ai_workmate_dev' `
  -DatabaseUsername 'postgres' `
  -DatabasePassword '<password>'

营销官网：

cd frontend-main
npm install
npm run lint
npm run build

OA 工作台：

cd frontend-oa
npm install
npm run lint
npm run test
npm run build

后端：

cd backend
mvn test

涉及数据库、权限、SSE、Agent Gateway 或写工具的改动，还必须运行相应真实 PostgreSQL、安全失败路径和架构边界测试。没有可用 Java 17、Maven、Docker 或外部模型环境时，应明确记录未执行项，不能把跳过描述为通过。

完整说明以 .env.example、.env.docker.example 和 application.yml 为准。

• 系统架构图
• 企业认证架构
• AI Chat Workspace
• Embedding 与 pgvector
• OCR 聊天处理链路
• Agent Tool Gateway
• Agent 持久任务引擎

• 工程规范
• 前端规范
• 后端规范
• Agent 规范
• 国际化规范
• Git 与提交规范
• 仓库 Agent 入口规范

• AI、Embedding、Rerank、SMTP、MinIO 和 OCR 是否可用取决于服务端配置与外部服务状态；健康检查“已配置”不等于真实外部推理成功。
• OA 仍有较大的前端 chunk，构建可能输出体积警告；后续需要继续做路由级拆包。
• OCR、Rerank 和 SMTP 是可选能力；未配置时对应功能不可用，但不得回退为伪造成功。
• Phase 2A/2B 的自动化发布门通过不等于生产授权；Agent 总开关、租户策略和写工具发布门必须独立审批。
• 文件元数据存放在 PostgreSQL，对象存放在 MinIO；数据库回滚不会自动恢复或删除对象文件。

• 项目许可证为 MIT License，不附加非商用、禁止售卖或禁止收费 SaaS 的限制。
• 软件按原样提供，不提供任何明示或默示担保；具体权利、条件及责任限制以许可证正文为准。
• 本次变更不撤销历史版本已经授予的 Apache-2.0 许可。对于仍受原许可约束的历史代码或贡献，须继续遵守其原有义务；原许可副本保留于 LICENSES/Apache-2.0.txt。
• 第三方依赖、代码和素材仍适用各自的许可证及版权声明，不因项目许可证变更而自动改为 MIT。

• 修改项目前先阅读 AGENTS.md 及对应 docs/rules、docs/skills。
• 前后端接口变更必须同步更新 DTO、TypeScript 类型、调用方、国际化资源和文档。
• 不提交密钥、真实账号、生产连接串、数据库转储或用户隐私数据。
• 安全、鉴权、数据一致性、流式体验和失败路径优先于视觉效果。
• 新能力必须提供本地验证方式；无法验证时必须说明环境限制。