feat: ship OA drafts/badges, role dual-track, and test-env deploy tooling.

Add approval instance drafts with menu badges, dual-track user/role read model and role bound names, form-designer outline docs, and bare-metal test deploy scripts. Ignore local test-server credential file.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed 2026-08-06 13:58:47 +08:00
1 parent 7af53fc344
commit de22678c87
56 files changed
+11861 -6082

No files matched your search

@@ -0,0 +1,29 @@
# 角色列表:有效用户与关联职位
**日期:** 2026-08-05
**状态:** 已确认
## 目标
角色管理列表增强可读性:角色名称可点开查看;展示有效拥有该角色的用户,以及关联该角色的职位。
## 列表展示
| 列 | 行为 |
|----|------|
| 角色名称 | 主色 link,点击打开现有查看弹窗 |
| 拥有用户 | 有效拥有(直接绑定 ∪ 职位继承),`、` 分隔,多则换行;空为 `—` |
| 关联职位 | `sys_post_role` 关联且启用未删的职位名,同上 |
## API enrichment
`GET /web/admin/role-management` 每条角色附加:
- `boundUserNames: string[]` — 有效用户显示名(`nick_name` 优先,否则 `user_no`),去重保序
- `boundPostNames: string[]` — 关联启用职位名,去重保序
有效用户语义与 `get_effective_role_ids` 一致:角色启用;直接 `sys_user_role`;或经启用职位 `sys_post_role` + `sys_user_post`。用户 `del_flag=0`。租户隔离与列表一致。批量查询,禁止 N+1。
## 非目标
不改查看弹窗结构、角色增删改、菜单/数据权限配置 UI。
@@ -0,0 +1,41 @@
# 用户角色双轨读模型(方案 B)
**日期:** 2026-08-05
**状态:** 已确认,按此实现
**前置:** [2026-08-02-post-role-permission-design.md](./2026-08-02-post-role-permission-design.md)
## 决策
| 项 | 结论 |
|----|------|
| 权限模型 | 长期双轨:直接绑定 ∪ 职位继承(运行时并集,已落地) |
| 用户管理写入 UI | **不提供**直接绑角色;日常仅配职位 |
| 直接绑定运维 | API / 脚本 / 库表,或专用授权模块(如质检金额查看) |
| 用户详情读模型 | 区分直接 / 职位继承 / 有效三层,便于审计 |
## 字段约定(用户详情)
| 字段 | 含义 |
|------|------|
| `roleIds` | 仅 `sys_user_role` 直接绑定(写路径 / 运维) |
| `postInheritedRoleIds` | 经启用职位继承的启用角色 ID |
| `effectiveRoleIds` | 有效角色 ID = 启用直接 ∪ 职位继承(与 `get_effective_role_ids` 一致) |
| `effectiveRoleNames` | 有效角色名称(去重保序) |
| `postIds` | 用户职位(不变) |
## 写入规则
- 用户新增/编辑 UI **不提交** `roleIds`。
- `update_user` 关联替换:**仅当请求体显式带 `roleIds` / `postIds` 时替换对应一侧**;只改职位不得清空直接角色。
- 菜单权限、数据权限、登录门禁继续走有效角色并集;本变更不改运行时语义。
## 前端
- 查看弹窗:展示有效角色,并只读附「直接绑定」「职位继承」。
- 新增/编辑:仅职位多选,无角色写入控件。
## 非目标
- 恢复用户页直接绑角色 UI
- 角色页反向关联职位
- 专用授权模块(如 `qc_material_amount_auth`)改为职位继承
@@ -0,0 +1,123 @@
# OA 发起审批草稿箱 Design
| 项 | 内容 |
|----|------|
| 日期 | 2026-08-06 |
| 状态 | 已定稿(UI 以 `docs/demos/oa-approval-draft-box-demo.html` 为准) |
| 范围 | 发起审批「暂存草稿」+ 侧栏「草稿箱」列表(再编辑 / 保存 / 提交 / 删除) |
## 背景
现状「发起审批」弹窗仅有「取消」「提交」,填到一半关闭即丢失。客户要求可暂存草稿,并在「发起审批」下方增加「草稿箱」菜单集中管理。
现有 `oa_app_version.status=draft` 仅为**模板设计草稿**,与本需求的**发起人填写草稿**无关,不得混用。
## 目标与非目标
**目标**
- 发起弹窗可「暂存草稿」,不进入审批流、不产生待办。
- 侧栏「草稿箱」列出当前用户草稿;支持编辑、再次保存、提交审批、删除与批量删除。
- 草稿仅本人可见(租户内 + 发起人 = 当前用户)。
**非目标**
- 不与「我发起的」实例混排;草稿不是 `oa_instance`。
- 不做跨用户共享草稿、不做审批人代填。
- 不做自动定时暂存(仅显式点击「暂存草稿 / 保存草稿」)。
- 不改造小程序端(本期仅 web-admin)。
## 方案对比与结论
| 方案 | 做法 | 优点 | 缺点 |
|------|------|------|------|
| A(推荐) | 独立表 `oa_instance_draft` | 与引擎解耦;「我发起的」无需过滤 draft;语义清晰 | 多一张表与一套 CRUD |
| B | `oa_instance.status=draft` | 少表 | 引擎/列表/关联审批处处要排除;误发起风险高 |
| C | 仅浏览器 localStorage | 无后端 | 换设备丢失;无法做菜单级权限与审计 |
**选定 A。** 提交时调用现有 `start_instance`,成功后软删对应草稿。
## 数据模型
表名:`oa_instance_draft`
| 字段 | 说明 |
|------|------|
| `id` | VARCHAR(64) PK,UUID |
| `app_id` | 审批应用 ID |
| `app_version_id` | 暂存时锁定的已发布版本(提交时优先用最新已发布版,见下) |
| `title` | 可选标题(可由应用名或表单字段推导,可空) |
| `form_data_json` | 表单数据 JSON |
| `initiator_select_json` | 发起人自选 `{nodeId:[userId,...]}` |
| `initiator_dept_id` | 发起部门(与发起接口一致) |
| `owner_user_id` | 草稿所属人(= 创建人) |
| 公共字段 | `tenant_no` … `del_flag`(遵循 database-conventions) |
约束与行为:
- 同一用户对同一 `app_id` **允许多条**草稿(与 Demo 列表一致)。
- 列表默认 `create_time DESC` 不适用时,用 **`update_time DESC`**(最近保存优先)。
- 删除:软删 `del_flag=1`。
- **暂存不做完整必填校验**;**提交**走与正式发起相同的校验。
### 版本策略
- 暂存:写入当时「最新已发布」`app_version_id`。
- 编辑打开:用该草稿的 `app_id` 取**当前最新已发布**模板渲染;`form_data` / `initiator_select` 按 field 名回填(字段已删则忽略多余键)。
- 若应用已无已发布版本:编辑/提交时提示「该审批单已下架或未发布」,禁止提交,允许删除草稿。
## API(`/api/admin/oa-approval`)
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/drafts` | 当前用户草稿分页;query:`keyword`(流程名)、`groupId`、`updateTimeFrom`/`updateTimeTo`、`page`/`pageSize` |
| GET | `/drafts/{id}` | 草稿详情(含 formData、initiatorSelect、app 基础信息) |
| POST | `/drafts` | 新建草稿(`appId` + formData + initiatorSelect + initiatorDeptId + title?) |
| PUT | `/drafts/{id}` | 更新草稿(仅 owner) |
| DELETE | `/drafts/{id}` | 软删单条 |
| POST | `/drafts/batch-delete` | body: `{ ids: string[] }` 批量软删 |
| POST | `/drafts/{id}/submit` | 校验 + `start_instance`;成功后软删草稿;返回实例信息 |
权限:均需登录管理端用户;读写仅限 `owner_user_id == 当前用户` 且同 `tenant_no`。菜单码:`oa:drafts`(列表/读写统一挂此码,与 `oa:start` 同级授权习惯)。
## 前端
### 菜单与路由
- 侧栏顺序:… → 发起审批 → **草稿箱** → 待办中心 → …
- 路由:`/#/system-manage/oa-approval/drafts`,组件 `web-admin/src/views/oa-approval/drafts/index.vue`
- 前端路由模块 `sqxp.ts` 与库表 `sys_menu`(SQL 脚本)同步增加菜单项。
### 发起页 `start/index.vue`
- 弹窗底栏:**取消** | **暂存草稿** | **提交**(主色仅「提交」)。
- 「暂存草稿」:调用 POST/PUT drafts;成功提示「已存入草稿箱」并关弹窗(或保持打开——**关弹窗**,与 Demo 心智一致)。
- 若路由带 `draftId`(从草稿箱「编辑」跳入):打开对应模板并回填,暂存走 PUT。
### 草稿箱页(对齐「我发起的」列表模式)
列:序号、流程名称、模板版本、最近保存、状态(Tag「草稿」`warning`)、操作(编辑 / 提交审批 / 删除)。
- **编辑**:`router.push` 到发起页并带 `draftId`(或本页弹窗复用发起表单——**推荐跳转发页 + query**,少复制逻辑;若发起页已是弹窗模式,则在草稿箱页复用同一套 dialog 逻辑亦可。实现择一:**草稿箱页内嵌与 start 相同的发起弹窗**,避免整页跳转丢上下文)。
- **提交审批**:调用 `POST /drafts/{id}/submit`;若校验失败,打开编辑弹窗并展示错误。
- **删除 / 批量删除**:二次确认后调用删除接口。
筛选:流程名称、保存时间范围、模板分组(与 Demo 一致)。
## 错误处理
- 非 owner / 已删:404 或 403,文案「草稿不存在或无权访问」。
- 提交时应用不可用:400 + 明确文案。
- 批量删除:跳过无权 id,返回成功数(或全部失败则报错)——采用 **全部校验通过再删**,任一无权则整批失败。
## 测试要点
- 暂存后草稿箱可见;他人不可见。
- 更新草稿只改本人记录。
- 提交成功产生 `oa_instance` 且草稿软删;「我发起的」出现新实例。
- 暂存不产生 `oa_task`。
- 无发布版本时禁止提交。
## UI 权威
`docs/demos/oa-approval-draft-box-demo.html`;视觉遵循 Fresh Mint / `docs/web-admin-ui-spec-fresh-mint.md`。
@@ -0,0 +1,38 @@
# OA「草稿箱 / 待办中心」菜单角标 Design
| 项 | 内容 |
|----|------|
| 日期 | 2026-08-06 |
| 状态 | 已定稿(用户确认:对齐抄送角标,0 隐藏) |
| 范围 | 侧栏「草稿箱」「待办中心」数量角标 |
## 背景
「抄送我的」已落地未读角标。产品要求「草稿箱」「待办中心」同样展示数量统计。
## 目标
- 侧栏 `oa:drafts`:当前用户未删除草稿总数;0 隐藏。
- 侧栏 `oa:pending`:当前用户待审批任务数(`task_type=approval` + `status=pending`);0 隐藏。
- 样式与刷新机制复用现有 `oa-menu-badge`(与抄送一致:`99+`、路由守卫刷新、业务操作后 `refreshOaMenuBadges()`)。
## 非目标
- 不改列表页筛选语义;角标为无筛选全量计数。
- 不改造小程序。
## API
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/drafts/count` | `{ count }`;须注册在 `/drafts/{draft_id}` 之前 |
| GET | `/tasks/pending/count` | `{ count }` |
约束:租户隔离 + 归属当前用户;`del_flag=0`。
## 前端
- 扩展 `OA_MENU_CODE_DRAFTS` / `OA_MENU_CODE_PENDING`;`resolveOaMenuBadgeCode` 识别 drafts/pending。
- `refreshOaMenuBadges` 按可见菜单并行拉取(含既有 cc)。
- 草稿箱增删/提交、发起页存草稿/提交、待办相关审批动作、`onActivated` 刷新角标。
- 退出登录时 `clearBadges`(补齐既有遗漏)。
@@ -0,0 +1,35 @@
# OA 表单设计器画布描边优化(方案 E)
**日期:** 2026-08-06
**状态:** 已确认
**范围:** `web-admin` OA 审批设计器「表单设计」Tab(`oa-fc-host` iframe)
## 背景
`@form-create/designer` 为每个画布组件包一层 `_fd-drag-tool`,默认常驻蓝色虚线 `outline`。嵌套布局时多层虚线叠加,影响操作与阅读。对比 Demo(`docs/demos/oa-form-designer-outline-styles.html`)后选定 **方案 E**。
## 目标行为
| 对象 | 识别 | 默认 | 悬停 | 选中 |
|------|------|------|------|------|
| 叶子字段 | `._fd-drag-tool` 且内部无子 `._fd-drag-tool` | 无描边 | 浅绿实线 | Mint 实线 `#10b981` |
| 布局容器 | `._fd-drag-tool:has(._fd-drag-tool)` | 极淡虚线 | 略加深 | Mint 实线 `#10b981` |
## 方案
- **仅 CSS 覆盖**,落在 `web-admin/src/oa-fc-host/App.vue` 的 `<style>`。
- 容器识别用 `:has()`;空布局暂按叶子处理,拖入子项后自动变为淡虚线容器。
- 将库内残留的选中框 / 拖拽按钮默认蓝 `#2E73FF` 统一为 Mint。
- **不做:** 预览态、左侧组件列表、运行时开关、改 node_modules。
## 验收
1. 打开审批设计器 →「表单设计」。
2. 拖入普通输入:默认无虚线;悬停有浅框;点击选中为实线。
3. 拖入栅格/布局并放入字段:外层常驻极淡虚线,内层字段默认无框。
4. 操作按钮背景为主色绿,无默认蓝。
## 参考
- Demo:`docs/demos/oa-form-designer-outline-styles.html`(方案 E)
- 库样式:`@form-create/designer` → `DragTool.vue`(`outline: 1px dashed var(--fc-tool-border-color)`)
@@ -0,0 +1,180 @@
# 测试环境裸机部署设计(101.35.245.122)
> 日期:2026-08-06
> 状态:已确认设计,待写实现计划
> 范围:在测试机部署 web-admin + backend;**不使用 Docker**;中间件复用开发环境已有实例
---
## 1. 背景与目标
在测试机 `101.35.245.122` 的 `/root/zkxw` 部署一套可外网访问的测试环境:
- 前端:本机 `pnpm build:test` 后 rsync 静态产物;Nginx 对外 **10001**
- 后端:源码 rsync 到机器,用 `start-test.sh` 监听 **127.0.0.1:10002**
- 中间件:与本机开发一致,连接 `47.99.164.66` 上的 MySQL / Redis / MinIO(含库名等)
- **不**在测试机用 Docker 跑应用或中间件
成功标准:
- 浏览器打开 `http://101.35.245.122:10001` 可使用管理端
- `/api` 经 Nginx 反代到本机后端,健康检查与登录可用
- 外网无法直连 `10002`;附件走 MinIO 直连地址
---
## 2. 架构与流量
```text
浏览器
└─ http://101.35.245.122:10001
└─ Nginx(测试机,需新装)
├─ / → /root/zkxw/web-admin/dist
├─ /api/* → http://127.0.0.1:10002
└─ (不反代 MinIO)
后端(start-test.sh)
HOST=127.0.0.1 PORT=10002
.env.test 中间件 ≈ 本机 backend/.env
→ MySQL 47.99.164.66:3306 / zkxw-sc
→ Redis 47.99.164.66:16379 DB=8
→ MinIO 47.99.164.66:20004 bucket=zkxw
浏览器附件
└─ 直连 http://47.99.164.66:20004/zkxw/...
```
约束:
- 云安全组 / 防火墙仅放行 **TCP 10001**
- 后端绑定 `127.0.0.1`,不对公网暴露 10002
- 前端 `VITE_API_URL=/api`;`VITE_MINIO_BASE_URL=http://47.99.164.66:20004/zkxw`
---
## 3. 服务器目录
```text
/root/zkxw/
├── web-admin/
│ └── dist/ # 本机 build:test 产物
├── backend/
│ ├── app/
│ ├── requirements.txt
│ ├── start-test.sh
│ ├── .env.test # 敏感,勿提交 git
│ ├── .venv/ # 服务器用 Python 3.12.3 创建
│ ├── backend-test.pid
│ └── logs/
└── nginx/
└── zkxw-test-10001.conf # 仓库维护的 site 片段,部署到系统 nginx
```
rsync 排除:`venv/`、`.venv/`、`__pycache__/`、`*.pyc`、`logs/`、`graphify-out/`;`.env*` 默认不覆盖,首次单独 scp。
---
## 4. 机装依赖(实测前提)
| 组件 | 状态 | 动作 |
|------|------|------|
| Python | 已装 **3.12.3** | 用 `python3.12 -m venv .venv`,无需再装 Python |
| Nginx | **未安装** | 按 OS 安装、开机自启、加载 10001 site |
| Docker | 已装但本方案不用 | 不启动 zkxw compose 应用栈 |
实现阶段须探测发行版(apt / yum / dnf)后写入准确安装命令。
---
## 5. 配置
### 5.1 backend `.env.test`
- 中间件字段与本机 `backend/.env` 对齐(同一 MySQL 库名、Redis DB、MinIO endpoint/bucket/密钥)
- `API_ENCRYPT_*` 与 `web-admin/.env.test` 一致
- 启动覆盖:`HOST=127.0.0.1 PORT=10002`(脚本默认曾为 `0.0.0.0:8112`)
### 5.2 web-admin `.env.test`
- 保持 `VITE_API_URL=/api`、`VITE_MINIO_BASE_URL=http://47.99.164.66:20004/zkxw`
- 文档注释中的访问入口改为 `http://101.35.245.122:10001`
### 5.3 Nginx
- `listen 10001`
- `root /root/zkxw/web-admin/dist`;SPA `try_files`
- `location ^~ /api/` → `http://127.0.0.1:10002`(保留 URI)
- `location = /health` → `http://127.0.0.1:10002/health`(验收固定入口)
- **不**配置 MinIO 反代
---
## 6. 发版流程(方案:本机打包 + rsync)
### 6.1 首次
1. SSH 安装 Nginx,创建目录,放置 site,`nginx -t && reload`
2. rsync backend 源码;`python3.12 -m venv .venv`;`pip install -r requirements.txt`
3. scp `.env.test`;`HOST=127.0.0.1 PORT=10002 ./start-test.sh start`
4. 本机 `pnpm build:test`;rsync `dist/` 到服务器
5. 安全组放行 10001;按 §7 验收
### 6.2 日常
```bash
# 前端
cd web-admin && pnpm build:test
rsync -avz --delete dist/ root@101.35.245.122:/root/zkxw/web-admin/dist/
# 后端
rsync -avz --exclude .venv --exclude venv --exclude '__pycache__' --exclude logs \
backend/ root@101.35.245.122:/root/zkxw/backend/
ssh root@101.35.245.122 \
'cd /root/zkxw/backend && HOST=127.0.0.1 PORT=10002 ./start-test.sh restart'
```
---
## 7. 验收
| 检查 | 期望 |
|------|------|
| `curl -s -o /dev/null -w '%{http_code}' http://101.35.245.122:10001/` | 200 |
| `curl -s http://101.35.245.122:10001/health` | 后端健康检查成功 |
| SSH 上 `curl -s http://127.0.0.1:10002/health` | 成功 |
| 外网直连 `http://101.35.245.122:10002/health` | 失败(超时/拒绝) |
| 登录与附件预览 | 可用(MinIO 公网可达) |
---
## 8. 风险与回滚
| 风险 | 缓解 |
|------|------|
| 与开发共用库 `zkxw-sc`,测试写库影响开发数据 | 已知接受(选型 A);后续若需隔离再开独立库 |
| 测试机访问不到中间件端口 | 部署前从测试机 `curl`/连通性探测 3306、16379、20004 |
| 浏览器访问不到 MinIO | 确认 `47.99.164.66:20004` 对使用方网络开放 |
| 误提交密钥 / 机器密码 | `.env.test` 与账号文件不进 git |
回滚:前端保留上一版 `dist` 备份再覆盖;后端停服务或回退代码后 `restart`。
---
## 9. 仓库交付物(实现阶段)
- 本设计文档(本文件)
- Nginx site 示例:建议 `测试环境部署/zkxw-test-10001.conf`(或更新现有 nginx 说明)
- 更新 `测试环境部署/README.md`:新 IP、端口 10001/10002、无 Docker、Python 3.12、安装 Nginx 步骤
- 视需要微调 `web-admin/.env.test` 注释中的入口地址
- **不**把 `测试环境机器的账号密码`、真实 `.env.test` 提交入库
---
## 10. 明确不在范围
- Docker Compose / 应用镜像部署
- 在测试机新建 MySQL / Redis / MinIO
- 服务器上安装 Node 并执行 `pnpm build`
- 将后端 10002 对公网开放
- Nginx 反代 MinIO