Files
zkxw/docs/superpowers/specs/2026-07-27-oa-dept-select-design.md
T
zlwuandCursor 19c97d148f docs(oa): add department select control design and mockup
Capture the approved OA form designer dept control contract (multi/single,
{id,name} path snapshot, mobile full-screen picker) and a Fresh Mint HTML demo.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-27 18:17:38 +08:00

203 lines
7.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# OA「部门选择」控件设计文档
**日期:** 2026-07-27
**范围:** `web-admin` 审批设计器步骤 2(表单设计)+ 发起/详情运行时;`backend` 发布白名单已有 `dept`,补齐值形态校验与打印
**状态:** 已评审待实现
---
## 1. 背景与目标
OA 审批「2 表单设计」需提供可拖拽的 **部门** 控件,供发起人选择本租户组织树(`sys_dept`),与钉钉式「部门」及既有规格 `docs/superpowers/specs/2026-07-14-oa-approval-dingtalk-design.md` §4.5 / §4.6 对齐。
当前发布字典已允许 `type: "dept"`,但设计器与运行时尚未落地自定义控件。
### 1.1 产品结论(已确认)
| 项 | 结论 |
|----|------|
| 选择能力 | 默认可多选;设计器属性可改为仅单选 |
| 存值 | 单选 `{ id, name }`;多选同结构数组 |
| `name` | **全路径快照**(分隔符 ` / `) |
| 可选范围 | **任意层级**均可选(非仅末级) |
| 实现路径 | 自定义 `type=dept`(对齐关联审批四层扩展);PC 用 `el-tree-select` |
| 移动兼容 | 窄屏禁止仅依赖宽屏下拉;须全屏/半屏选择器;Schema/`form_data` 双端同一份 |
### 1.2 非目标
- 行业通讯录部门
- 用本控件结果改写审批人解析(仍用发起人部门 / `oa_role` 等既有策略)
- 本期实现小程序页面(但契约与交互必须可映射)
- 本控件「参与流程条件分支」(对象/多选不便进比较器;需要时二期单开)
---
## 2. 架构
对齐 FormCreate / FcDesigner **四层扩展**(与「关联审批单」同路径):
| 层 | 内容 |
|----|------|
| Runtime | `OaDeptSelect.vue`:`v-model` 为对象或对象数组 |
| FormCreate 组件注册 | `formCreate.component('dept', …)` |
| DragRule | `menu: 'main'`;`name/label` 为部门;`props.multiple` 默认 `true` |
| 双侧注册 | 主应用(发起/详情)+ `oa-fc-host`(设计器 iframe)均调用 `setupOaDeptSelect` |
数据源:现有 `fetchDeptTree()`(本租户组织树),不另造 API。
```
[设计器 DragRule] → form_schema_json.type = "dept"
↓
[OaDeptSelect] ← fetchDeptTree
↓
form_data[field] = { id, name } | { id, name }[]
↓
[后端发起校验] → 详情 / 打印优先展示 name 快照
```
---
## 3. Schema 与属性
### 3.1 规则形态(示例)
```json
{
"type": "dept",
"field": "Fxxxx",
"title": "所属部门",
"info": "",
"$required": false,
"props": {
"multiple": true,
"max": null
}
}
```
### 3.2 设计器可配属性
| 属性 | 说明 |
|------|------|
| 标题 / 提示信息 / 必填 | 与现有控件一致 |
| 允许多选 | Switch,**默认 `true`**;`false` 时仅单选 |
| 最大可选数 | 可选;仅多选时生效;不填则不限制 |
树下拉节点文案:**本级名称**;选中后输入框 / 发起页 / 详情 / 打印:**全路径**(与 `tree-path` 约定一致)。
---
## 4. `form_data` 契约(锁定)
```ts
type DeptValueItem = {
id: string // sys_dept.id
name: string // 提交时全路径快照,如 "中科兴皖 / 研发中心 / 前端组"
}
// 单选(props.multiple === false)
type DeptFormValueSingle = DeptValueItem | null
// 多选(props.multiple === true,默认)
type DeptFormValueMulti = DeptValueItem[]
```
约束:
- `id`、`name` 均为非空字符串。
- **禁止**写入 DOM、组件实例、仅本级名却标注为全路径、或与 `multiple` 不一致的标量/对象混用。
- 组织改名/调整后,历史实例 **SHALL** 仍展示提交时的 `name` 快照;不强制按 `id` 重算路径。
- 后端 **SHALL NOT** 强制校验 `id` 仍存在于当前组织树(允许已删/历史部门快照可读)。
本决定更新钉钉规格 §4.6 值类型表中「部门」一行的歧义:发布锁定为 **`{ id, name }` / 数组**,不再使用裸 `string` deptId。
---
## 5. 运行时交互
### 5.1 PC(视口宽度 ≥ 768)
- 使用 `el-tree-select`(或等价树选)。
- `multiple` 跟随 `props.multiple`。
- 触发条/标签展示全路径;多选以 chip 展示,可删除单条。
### 5.2 窄屏 / 设计器手机预览(宽度 &lt; 768)
对齐双端规格:「部门/省市区 → 移动端 **全屏或半屏选择器**,禁止依赖宽屏下拉才能选完」。
- 表单项为触发条(展示已选全路径或占位「请选择部门」)。
- 点击后打开 **抽屉或全屏面板**:搜索 + 组织树 +(多选)勾选 + 取消/确定。
- 未点「确定」前不写回 `v-model`。
- 与 PC 共用同一 `v-model` 形态,仅交互壳不同。
### 5.3 只读
详情 / 审批页:仅展示路径文案(单选一个 `name`;多选多个 `name` 用中文顿号「、」拼接),不可打开选择器。
### 5.4 条件分支
`dept` **不**注册「参与流程条件分支」开关;`CONDITION_ELIGIBLE_TYPES` **不**包含 `dept`。
---
## 6. 校验
### 6.1 前端
- 必填:单选无值或 `null`;多选空数组 → 拦截提示。
- 多选且配置了 `max`:达到上限不可再选并提示。
- 窄屏面板未确认不算变更。
### 6.2 后端(发起 / 再次提交)
- 按 schema 遍历 `type === "dept"`。
- 单选:非必填允许缺省/`null`;否则须为 `{ id, name }`。
- 多选:须为数组;每项为 `{ id, name }`;必填则 `length >= 1`;有 `max` 则 `length <= max`。
- 发布:`ALLOWED_CONTROL_TYPES` 已含 `dept`,保持即可。
---
## 7. 打印与详情
- 单选:输出 `name`。
- 多选:多个 `name` 用中文顿号「、」拼接。
- **SHALL NOT** 将对象 JSON 原样打印到纸面。
- 实现落点:`oa-approval-print`(及详情只读渲染)对 `type === "dept"` 特判。
---
## 8. 主要改动面
| 区域 | 文件(预期) |
|------|----------------|
| Runtime | `web-admin/src/components/oa-approval/OaDeptSelect.vue` |
| DragRule | `web-admin/src/utils/oa-dept-select-rule.ts` |
| 注册 | `web-admin/src/utils/oa-form-create-dept.ts`;`oa-fc-host/main.ts`;主应用 form-create 注册点 |
| 打印 | `web-admin/src/utils/oa-approval-print.ts` |
| 后端校验 | `backend/app/services/oa_publish.py` 或发起校验模块中的 form_data 校验 |
| Demo(可选) | `docs/mockups/oa-dept-select-demo.html` 与实现对齐 |
---
## 9. 验收标准
1. 「2 表单设计」左侧组件库出现「部门」,可拖入画布;属性可关闭多选。
2. PC:树选可用;设计器切换手机预览(或窄视口)时可用半屏/全屏选完,不必依赖宽屏下拉。
3. 提交后 `form_data` 形态符合 §4;组织改名后旧实例仍显示快照路径。
4. 含 `dept` 的应用可发布;未知 `type` 仍拒绝。
5. 无该控件的旧应用行为不变。
6. 详情与打印展示人类可读路径,不出现原始 JSON。
---
## 10. 测试建议
- 单元:`form_data` 形态校验(单选/多选/必填/max)。
- 手工:设计器拖入 → 发起多选/单选 → 详情/打印;窄屏或手机预览走完选择;改部门名称后回看历史单。
---
## 11. 开放问题
无。若二期要做「部门字段参与条件分支」或小程序原生页,另开变更,不修改本节契约。