# R.3A DMS 门禁集成审计与设计基线：来源与范围定义

> **系统展示名称（暂定）**：沈阳房建公寓段学员管理系统
> **内部工程代号**：RailwaySystem
> **当前正式 Release HEAD**：`adcf930ea0a880e1faae36ff3d3e6539d0c0b8f9`
> **当前开发工作区 (Worktree)**：`/Users/wzb/Desktop/项目/RailwaySystem-worktrees/dms-r3`
> **当前分支**：`design/dms-r3`（基于 `origin/feat/cicd-pipeline`）
> **文档读取与审计日期**：2026-09-15
> **文档完整性状态**：`DOCUMENTATION_COMPLETENESS = PARTIAL`
> **真实 DMS 平台调用**：`DMS_LIVE_API_CALLED = NO`

---

## 1. 命名与工程纪律

1. **展示名称与工程代号隔离**：
   - 对外业务展示名称统一为：**沈阳房建公寓段学员管理系统**（暂定）。
   - 内部工程代号继续保持：`RailwaySystem`。
   - **绝对红线**：严禁因为展示名称变化而重命名 Git 仓库名、Java 包名 (`com.ruoyi.train.*`)、数据库名 (`training`)、Maven 模块名 (`ruoyi-train`, `ruoyi-admin` 等) 以及内部技术路径与文件结构。
2. **并行开发工作区分离**：
   - R.2 RBAC 权限重构当前在独立 Worktree 进行开发：`/Users/wzb/Desktop/项目/RailwaySystem-worktrees/rbac-r2`（分支 `feature/rbac-r2`）。
   - **纪律**：本集成审计任务严格在独立 Worktree `/Users/wzb/Desktop/项目/RailwaySystem-worktrees/dms-r3` 进行，严禁触碰 `rbac-r2` 目录，严禁修改 `feature/rbac-r2` 分支。
3. **只读审计与设计冻结红线**：
   - 本阶段为 **R.3A 审计与设计冻结阶段**，只做技术审计、架构设计、模型比选与任务拆分。
   - **严格禁止**：
     - 修改任何 Java 代码 (`*.java`)
     - 修改任何 Vue/前端代码 (`*.vue`, `*.js`)
     - 修改任何 SQL 脚本或执行 Migration
     - 对生产/测试 Kingbase 数据库执行任何写操作 (INSERT, UPDATE, DELETE, DDL)
     - 调用任何真实 DMS 登录接口或门锁操作接口
     - 使用官方文档中的示例凭据 (`appid`, `appsecret`, `token` 等)
     - 执行 `git commit`, `git push`, 部署操作

---

## 2. 文档来源与凭据安全红线

### 2.1 外部接口文档来源
- **文档地址**：`https://dms.dmsiot.com/V1/doc/restapi.html`
- **平台性质**：DMS 设备管理 / 智能门锁物联网平台 RESTful API 文档。
- **文档完整性定义**：`PARTIAL`（部分接口文档）。
- **来源纪律 (Source Discipline)**：
  - 严禁假设文档已覆盖 DMS 的全部能力。
  - 审计结论严格区分为四类置信度：
    - `DOCUMENTED`：官方文档中有明确的 HTTP 方法、路径、请求体和响应体说明。
    - `INFERRED`：基于文档上下文字段、枚举说明推导，但缺少独立端点描述。
    - `UNCONFIRMED`：仅在响应体或枚举中出现字段，未提供接口调用支持。
  - 官方文档中已明确定义二维码/手机钥匙接口（生成：`POST /rest/doorlock/qrcode/create`，注销：`POST /rest/qrcode/delete`），分类为 `DOCUMENTED`；但其载荷缺失与一期适用性仍为 `NEEDS_BUSINESS_CONFIRMATION`。严禁根据返回体中的其他无接口字段（如 `fingerprint: false`）脑补或声称系统已支持指纹等未定义接口。

### 2.2 示例凭据安全隔离红线
- 官方文档中出现的示例 `appid`、示例 `appsecret`、示例 `token`、示例手机号、密码、卡号等：
  - **仅作为文档语法结构与格式说明**。
  - **严禁**使用文档中任何示例凭据向 `dms.dmsiot.com` 发送任何网络请求（无论登录或业务测试）。
  - **严禁**将上述示例密钥提交到代码库或配置文件中。

---

## 3. 任务范围定义与交付清单

### 3.1 核心任务目标
1. 完整审计 DMS REST API 文档，建立全量 API 清单与参数/状态审计表。
2. 重新审计当前 RailwaySystem 真实代码库与 Kingbase 物理表（Dormitory, Accommodation, DormAuth）。
3. 建立 RailwaySystem 宿舍业务与 DMS 门锁平台之间的领域映射体系。
4. 设计厂商无关的门禁网关架构（DoorAccessGateway）与 DMS 专用适配器（DmsAdapter）。
5. 设计生产级 Token 生命周期管理机制与高并发防击穿策略。
6. 设计门禁授权生命周期状态机与异步 `operationId` 轮询调度器。
7. 设计重试、网络未知状态对账、退训撤权、调房换房补偿等可靠性机制。
8. 评估敏感数据保护方案（密码、卡号、Token 脱敏与加密）。
9. 明确一期试点接入范围与后续 R.3B 任务 WBS 拆分。

### 3.2 交付物清单
本审计任务仅在 `docs/development/dms-r3/` 目录下生成以下 15 个基线设计文档：
- `00_source_and_scope.md`（本文件：来源、范围与安全红线）
- `01_dms_api_inventory.md`（DMS API 全量资产清单与分级）
- `02_current_accommodation_audit.md`（本地住宿/宿舍/门禁模型真实代码与数据库审计）
- `03_domain_mapping.md`（业务领域模型映射与生命周期对应）
- `04_auth_and_token_strategy.md`（DMS 登录鉴权、Token 缓存与并发控制策略）
- `05_adapter_architecture.md`（集成适配器分层架构与厂商无关接口设计）
- `06_authorization_state_machine.md`（门锁授权生命周期状态机）
- `07_retry_idempotency_and_compensation.md`（重试机制、本地幂等与换房补偿设计）
- `08_security_and_audit.md`（凭据安全、日志脱敏与门禁审计轨迹）
- `09_database_mapping_proposal.md`（数据库表结构方案比选与模型演进建议）
- `10_api_and_ui_proposal.md`（内部管理接口与端到端 UI 交互原型方案）
- `11_testing_and_mock_plan.md`（WireMock 模拟测试与多并发可靠性测试计划）
- `12_implementation_task_breakdown.md`（R.3B 实施阶段 WBS 任务拆分）
- `13_open_questions.md`（供应商/业务/技术未决问题与阻塞项清单）
- `14_decision_summary.md`（技术选型与管理决策一页纸总结）