railwaysystem/docs/development/dms-r3/00_source_and_scope.md

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（技术选型与管理决策一页纸总结）