新增门禁：验证真实接口契约并落地暂行访问策略
This commit is contained in:
wangzhibiao committed
1 parent
aa2e8a36de
commit
e367ec1fe3
17 files changed
+806
-9
No files matched your search
@@ -0,0 +1,119 @@
|
||||
# R.3 Provisional Business Policy V0 (临时业务策略规范 V0)
|
||||
|
||||
> **当前状态**：`STATUS = PROVISIONAL`
|
||||
> **确认要求**：`CUSTOMER_CONFIRMATION_REQUIRED = YES`
|
||||
> **基线标识**：`TEMPORARY BUSINESS DEFAULT (甲方确认后可无缝平滑替换)`
|
||||
> **版本与生效**：`PROVISIONAL_V0_20260916`
|
||||
> **覆盖范围**：沈阳房建公寓段职工培训管理系统 - DMS 智能门禁外拓业务策略
|
||||
|
||||
---
|
||||
|
||||
## 1. 策略背景与设计原则
|
||||
|
||||
在 R.3 阶段，外部 DMS 门禁系统已经完成 Adapter 架构抽象、状态机驱动对账以及契约容错设计。为确保沈阳房建公寓段学员日常管理与门禁下发能够在业务未定细节下有序推进，本项目制定一套**可继续赶进度的临时业务策略 (PROVISIONAL_V0)**。
|
||||
|
||||
核心设计原则：
|
||||
1. **策略集中化与配置化**：业务规则由 `AccessAuthorizationOrchestrator` 与专用策略类统一推导，严禁在 Controller 或前端界面中散落硬编码逻辑。
|
||||
2. **安全兜底与最小特权**：在未取得现场业务方最终签字前，采取最保守的安全防错策略（例如：多锁报错、一次性展示）。
|
||||
3. **高兼容可平滑升级**：为未来甲方确权后的新策略（如短信直发、学员端自提、差异化请假时段）预留可插拔扩展点。
|
||||
|
||||
---
|
||||
|
||||
## 2. 五大临时业务策略明细
|
||||
|
||||
### A. 学员请假门禁策略 (Leave Access Policy)
|
||||
|
||||
- **策略声明**：
|
||||
```
|
||||
LEAVE_ACCESS_POLICY = KEEP_ACCESS
|
||||
```
|
||||
- **策略细则**：
|
||||
1. **短期请假**：学员在培训期间发起并审批通过的短期日常请假（学籍状态为 `LEAVE (2)`），系统**不自动撤销**其宿舍门禁权限，保留其进出宿舍的通行权利。
|
||||
2. **培训终止/退宿**：当学员进入 `TERMINATED (3)`（退训）或 `COMPLETED (4)`（结训/离校/退宿）状态时，系统即刻触发门禁凭证撤权流程 (`REVOKE_REQUIRED`)，注销外部硬件钥匙。
|
||||
- **业务考量**：
|
||||
沈阳房建公寓段短期学员通常在请假期间仍有生活物资留置在宿舍内，频繁撤销及重新发放下发不仅容易引发硬件通信与轮询拥堵，还会导致学员回校后进门受阻。故一期默认保持通行权限。
|
||||
|
||||
---
|
||||
|
||||
### B. 调房授权策略 (Transfer Policy)
|
||||
|
||||
- **策略声明**：
|
||||
```
|
||||
TRANSFER_POLICY = GRANT_NEW_THEN_REVOKE_OLD
|
||||
```
|
||||
- **策略细则**：
|
||||
1. **先下发新房**：学员因床位调整换房时，系统首先针对新宿舍发起外部凭据下发流程 (`GRANT`)。
|
||||
2. **新房生效后再撤旧房**：仅当新房门禁凭证经轮询对账确认硬件已就绪 (`AUTH_STATUS = ACTIVE`) 后，系统才自动驱动注销旧宿舍的门禁权限。
|
||||
3. **新房失败保留旧房**：若新房因网络离线、主锁未配置或供应商超时导致下发失败，系统严格保留学员旧宿舍的门禁权限，坚决杜绝“新房进不去、旧房回不去”的挂起事故。
|
||||
|
||||
---
|
||||
|
||||
### C. 门锁选择策略 (Lock Selection Policy)
|
||||
|
||||
- **策略声明**：
|
||||
```
|
||||
LOCK_SELECTION_POLICY = PRIMARY_LOCK_ONLY
|
||||
```
|
||||
- **策略细则**：
|
||||
1. **唯一主锁原则**：系统通过 `train_external_resource_mapping` 建立宿舍与门锁的映射。一间宿舍默认仅向且必须向标记为 `is_primary = 1` 的唯一定义门锁下发凭据。
|
||||
2. **0 把主锁处理**：若该宿舍在外部映射中未配置主锁，对账决策标记为：
|
||||
```
|
||||
WAITING_FOR_CONFIGURATION ("Dorm has 0 primary lock configured; cannot grant access")
|
||||
```
|
||||
3. **多把主锁处理**：若该宿舍错误配置了 >1 把主锁，对账决策标记为：
|
||||
```
|
||||
CONFIGURATION_ERROR ("Dorm has N primary locks configured; configuration error")
|
||||
```
|
||||
系统拒绝盲目下发，提醒管理员前往设备映射台账进行纠错。
|
||||
|
||||
---
|
||||
|
||||
### D. 权限有效期策略 (Validity Window Policy)
|
||||
|
||||
- **策略声明**：
|
||||
```
|
||||
VALIDITY_POLICY = ACCOMMODATION_WINDOW
|
||||
```
|
||||
- **策略细则**：
|
||||
1. **首选住宿周期**：凭据有效期 `validStart` 与 `validUntil` 严格优先使用 `train_accommodation` 记录中的实际入住与退宿安排时间窗口。
|
||||
2. **缺省 Fallback 机制**：
|
||||
- 若当前住宿数据模型中尚未明确退宿时间：
|
||||
- `validStart` = 实际授权生效时间 / 住宿分配时间 (`assignedTime`)
|
||||
- `validUntil` = 开班计划结束时间 (`plan.endDate`)；若无计划时间，则 fallback 为 `validStart + 30 天`。
|
||||
3. **标识说明**：
|
||||
本策略为 `TEMPORARY BUSINESS DEFAULT`，待后续甲方对各班次作息与换届窗口提出明确规范后统一替换调整。
|
||||
|
||||
---
|
||||
|
||||
### E. 凭据交付策略 (Credential Delivery Policy)
|
||||
|
||||
- **策略声明**：
|
||||
```
|
||||
CREDENTIAL_DELIVERY_POLICY = ADMIN_ONE_TIME_DISPLAY
|
||||
```
|
||||
- **策略细则**：
|
||||
1. **管理员一次性展示 (ADMIN_ONE_TIME_DISPLAY)**：
|
||||
- 在门禁授权创建成功（Vendor Accepted）的当次接口响应中，仅向具有受控授权权限的管理员一次性展示随机生成的门禁密码（例如界面弹窗提示）。
|
||||
- 弹窗关闭或页面刷新后，系统**绝不提供二次回显**接口。
|
||||
2. **四重严苛安全防线**：
|
||||
- **严禁 DB 持久化** (`DB_PLAINTEXT_COUNT = 0`)：密码明文绝不写入 `train_dorm_auth`、`train_external_operation` 或任何本地数据库表。
|
||||
- **严禁日志打印** (`LOG_PLAINTEXT_EXPOSURE = 0`)：`ReconciliationResult.toString()`、底层 HTTP 客户端拦截器中均对敏感密码严格脱敏掩码。
|
||||
- **严禁历史记录暴露** (`HISTORY_PLAINTEXT_EXPOSURE = 0`)：外部异步操作日志与轮询记录实体绝无明文密码字段。
|
||||
- **严禁查询端点暴露** (`RETRIEVAL_ENDPOINT_COUNT = 0`)：所有列表、详情、对账 GET 接口一律无密码返回值。
|
||||
3. **未来演进路径**：
|
||||
- 短信网关通知 (`SMS_DIRECT_DELIVERY`)
|
||||
- 学员微信小程序/电子看板自提 (`STUDENT_SELF_SERVICE`)
|
||||
- 上述方式作为二期交付策略，本轮不开发。
|
||||
|
||||
---
|
||||
|
||||
## 3. 策略参数总览表
|
||||
|
||||
| 策略维度 | V0 临时规则值 | 是否允许硬编码散落 | 终态判定依据 | 变更确认方 |
|
||||
| :--- | :--- | :---: | :--- | :--- |
|
||||
| **请假处理** | `KEEP_ACCESS` | 严禁 | 学员非退训/结训均保持门禁有效 | 房建公寓段教学管理科 |
|
||||
| **调房处理** | `GRANT_NEW_THEN_REVOKE_OLD` | 严禁 | 新房 ACTIVE 后才触发旧房注销 | 系统可靠性强制约束 |
|
||||
| **门锁筛选** | `PRIMARY_LOCK_ONLY` | 严禁 | 映射表 `is_primary = 1` 且 count=1 | 物联网网络运维班组 |
|
||||
| **有效期计算** | `ACCOMMODATION_WINDOW` | 严禁 | 优先住宿窗口，Fallback 计划结束时间 | 房建公寓段教务处 |
|
||||
| **凭据交付** | `ADMIN_ONE_TIME_DISPLAY` | 严禁 | 管理员端一次性展示，DB/日志零留存 | 信息安全保密要求 |
|
||||
|
||||
Reference in new issue
Block a user