mirror of
https://github.com/hpd840321/starRiverProperty.git
synced 2026-06-10 00:40:30 +08:00
hpd840321
7b2bd307f1
- backend/: 13 Maven modules (cw-elevator-application, cloudwalk-cloud, intelligent-cwoscomponent, ninca-crk, etc.) - frontend/: 4 Vue projects (elevator-front, cwos-portal, alarm-front, front_acs) + decompiled + scripts - scripts/: build, test-env, tools (Docker Compose, service templates, API parity) - docs/: AGENTS.md, superpowers specs, architecture docs - .gitignore: standard Java/Maven exclusions Moved from legacy maven-*/ root layout to backend/ organized structure.
253 lines
10 KiB
Markdown
253 lines
10 KiB
Markdown
# 目录结构重组设计 — 星河湾星中星
|
||
|
||
**日期:** 2026-05-07
|
||
**状态:** 设计稿 v1
|
||
|
||
---
|
||
|
||
## 1. 背景与目标
|
||
|
||
星河湾星中星是 CloudWalk（云从科技）电梯/门禁/安防/人脸识别系统的单体仓库。当前顶层目录结构存在以下问题：
|
||
|
||
- **职责混淆：** `源码/` 中混合了 Maven 项目、运行时部署包、nginx 配置、反编译代码、frontend 运行时 + 备份
|
||
- **命名不一致：** 混用中文/英文、小写/下划线/连词符、`maven-` 前缀冗余、`01-` 数字前缀无意义
|
||
- **目录重复：** `源码/frontend/` 与 `星中心/frontend/` 内容高度重叠；`源码/cw-elevator-application-V1.0.0.20211103/` 与 `星中心/` 下同名
|
||
- **自嵌套：** `源码/源码/` 指向自身
|
||
- **备份混乱：** 15+ 个 `.bakYYYYMMDD` 目录与活跃目录混合，难以区分
|
||
|
||
**设计原则：**
|
||
|
||
1. **单一职责** — 每个顶层目录只放一种类型的内容
|
||
2. **零删除** — 所有历史/遗留文件集中移至 `archive/`，不做任何删除
|
||
3. **命名规范** — 小写 kebab-case、去除冗余前缀、统一版本/备份格式
|
||
4. **最小中断** — 保持开发/部署工作流不受影响
|
||
|
||
---
|
||
|
||
## 2. 命名规范
|
||
|
||
所有新路径遵循以下规则：
|
||
|
||
| 规则 | 旧示例 | 新示例 |
|
||
|------|--------|--------|
|
||
| 目录名统一小写+连词符 | `data_backup/` | `data-backups/` |
|
||
| 去除 `maven-` 前缀 | `maven-cw-elevator-application/` | `cw-elevator-application/` |
|
||
| 去除 `01-` / `_01-` 数字前缀 | `cwos_manager_01-cwos_manager/` | `cwos-manager/` |
|
||
| 版本号规范 | `V1.0.0.20211103` | `v1.0.0`（内部保留完整日期） |
|
||
| 备份标记规范 | `front_acs.bak20231018/` | → `archive/frontend-backups/`（集中存放） |
|
||
|
||
---
|
||
|
||
## 3. 顶层目录结构
|
||
|
||
```text
|
||
星河湾星中星/
|
||
├── source/ # 源码（仅活跃开发代码）
|
||
├── runtime/ # 运行时部署（生产/预发镜像）
|
||
├── packages/ # 部署压缩包（tar.gz）
|
||
├── scripts/ # 统一脚本入口
|
||
├── docs/ # 文档中心
|
||
├── data-backups/ # 数据库备份
|
||
├── archive/ # 【新增】历史/遗留/参考内容
|
||
├── artifacts/ # 构建产物/证据
|
||
├── nginx/ # Nginx 配置
|
||
└── logs/ # 运行日志
|
||
```
|
||
|
||
### 3.1 映射关系
|
||
|
||
| 当前路径 | 新路径 | 类型 |
|
||
|---------|--------|------|
|
||
| `源码/` | → 拆分 | 源码、nginx、artifacts、反编译各自归位 |
|
||
| `星中心/` | `runtime/` | 运行时部署 |
|
||
| `部署包/` | `packages/` | 部署压缩包 |
|
||
| `data_backup/` | `data-backups/` | 数据库备份 |
|
||
| `反1/` | `archive/decompiled-sources/` | 归档 |
|
||
| `cn/` | `archive/miscellaneous/` | 归档 |
|
||
| `media/` | `archive/miscellaneous/` | 归档 |
|
||
| `源码/源码/` | `archive/miscellaneous/` | 归档 |
|
||
| — | `archive/frontend-backups/` | **新增**，收纳所有 `.bak` 前端备份 |
|
||
| `scripts/` (顶层) | `scripts/deploy/` | 合并到统一脚本目录 |
|
||
| `源码/scripts/` | `scripts/` (主目录) | 合入不同子目录 |
|
||
|
||
---
|
||
|
||
## 4. 各目录内部设计
|
||
|
||
### 4.1 `source/backend/` — 后端 Maven 项目
|
||
|
||
去除 `maven-` 前缀，保持原始目录内部结构不变：
|
||
|
||
| 原名 | 新名 |
|
||
|------|------|
|
||
| `maven-cloudwalk-cloud/` | `cloudwalk-cloud/` |
|
||
| `maven-cloudwalk-device-manager/` | `cloudwalk-device-manager/` |
|
||
| `maven-cloudwalk-device-sdk/` | `cloudwalk-device-sdk/` |
|
||
| `maven-cloudwalk-intelligent-davinci-manager/` | `intelligent-davinci-manager/` |
|
||
| `maven-cloudwalk-legacy-public/` | `cloudwalk-legacy-public/` |
|
||
| `maven-cw-elevator-application/` | `cw-elevator-application/` |
|
||
| `maven-cwos-common-aks/` | `cwos-common-aks/` |
|
||
| `maven-cwos-device-authentication/` | `cwos-device-authentication/` |
|
||
| `maven-cwos-resource/` | `cwos-resource/` |
|
||
| `maven-intelligent-cwoscomponent/` | `intelligent-cwoscomponent/` |
|
||
| `maven-ninca-common-component-organization/` | `ninca-common-component-organization/` |
|
||
| `maven-ninca-crk-from-lib/` | `ninca-crk-from-lib/` |
|
||
| `maven-ninca-qk-alarm/` | `ninca-qk-alarm/` |
|
||
**移出 `source/`:**
|
||
- `cw-elevator-application-V1.0.0.20211103/` → `runtime/elevator-v1/`
|
||
|
||
### 4.2 `source/frontend/` — 前端源码
|
||
|
||
| 原名 | 新名 |
|
||
|------|------|
|
||
| `frontend-source/projects/` | `projects/` (alarm-front, cwos-portal, elevator-front, front-acs) |
|
||
| `frontend-source/decompiled/` | `decompiled/` |
|
||
| `frontend-source/scripts/` | `scripts/` |
|
||
|
||
### 4.3 `runtime/` — 运行时部署
|
||
|
||
去除 `_01-` 数字前缀和冗余版本后缀，改用简洁的服务名：
|
||
|
||
| 原名 | 新名 |
|
||
|------|------|
|
||
| `cw-elevator-application-V1.0.0.20211103/` | `elevator-v1/` |
|
||
| `cwos_manager_01-cwos_manager/` | `cwos-manager/` |
|
||
| `cwos_system_api_01-cwos_system_api/` | `cwos-system-api/` |
|
||
| `ninca_crk_std_01-ninca_crk_std_backend/` | `ninca-crk-std/` |
|
||
| `ninca_qk_alarm_app_01-ninca_qk_alarm_app/` | `ninca-qk-alarm/` |
|
||
| `ninca-crk-std-backend-V2.9.1_20210630/` | `ninca-crk-std-lib/` |
|
||
|
||
**前端运行时合并（`runtime/frontend/`）：**
|
||
- 从 `源码/frontend/` 和 `星中心/frontend/` 中提取**非 `.bak`** 的活跃前端目录
|
||
- 重复的以前者（`源码/frontend/`）为准
|
||
- 所有 `.bak` 目录 → `archive/frontend-backups/`
|
||
|
||
### 4.4 `packages/` — 部署压缩包
|
||
|
||
保持现有结构，仅移除 `01-` 文件名前缀：
|
||
|
||
| 原名 | 新名 |
|
||
|------|------|
|
||
| `cwos_manager_01-cwos_manager.tar.gz` | `cwos-manager.tar.gz` |
|
||
| `ninca_common_component_organization_01-...` | `ninca-common-component-organization-...` |
|
||
| （同理应用于所有 13 个 tar.gz） | |
|
||
|
||
**内部目录规范化：**
|
||
- `releases/` — 保留
|
||
- `components/` — 整理展开的组件目录
|
||
|
||
### 4.5 `scripts/` — 统一脚本目录
|
||
|
||
```text
|
||
scripts/
|
||
├── build/ # 构建/发布/格式化相关
|
||
│ ├── release-cw-elevator-application.sh
|
||
│ ├── format_maven_formatter_all.sh
|
||
│ ├── check_maven_formatter_validate.sh
|
||
│ ├── build_elevator.sh (new)
|
||
│ └── *.sh
|
||
├── deploy/ # 部署/启停相关
|
||
│ ├── start_ninca.sh (from top-level scripts/)
|
||
│ └── *.sh
|
||
├── test-env/ # 测试环境搭建（从 源码/scripts/test-env/ 整体迁移）
|
||
│ ├── docker-compose.infra.yml
|
||
│ ├── setup.sh
|
||
│ ├── start-all.sh / stop-all.sh
|
||
│ ├── health-check.sh
|
||
│ └── ...
|
||
├── tools/ # 分析/对拍/校验工具
|
||
│ ├── check_elevator_fatjar_lib_parity.sh
|
||
│ ├── compare_jar_to_sources.py
|
||
│ ├── decompile_ninca_crk_lib_modules.py
|
||
│ ├── run_full_elevator_api_suite.sh
|
||
│ ├── run_v1v2_parity_automated.sh
|
||
│ ├── verify_frontend_runtime.py
|
||
│ ├── verify_v1_v2_config_load_order.sh
|
||
│ └── ...
|
||
```
|
||
|
||
### 4.6 `archive/` — 历史/参考/遗留
|
||
|
||
```text
|
||
archive/
|
||
├── decompiled-sources/ # (from 反1/ — 22 个 .src.zip)
|
||
├── frontend-backups/ # (所有 .bak* 前端备份目录)
|
||
│ ├── front_acs.bak20231012/
|
||
│ ├── front_acs.bak20231018/
|
||
│ ├── ...
|
||
│ └── *.tar.gz (旧前端归档)
|
||
└── miscellaneous/ # (其他杂项)
|
||
├── cn/ # (from 顶层 cn/)
|
||
├── media/ # (from 顶层 media/)
|
||
├── source-self-ref/ # (from 源码/源码/ 自嵌套目录)
|
||
├── visitor-noauth-verify-v20260430.zip # (源码/ 根部的 zip)
|
||
└── elevator-app.log # (源码/ 根部的日志文件)
|
||
```
|
||
|
||
### 4.7 其他目录
|
||
|
||
| 当前路径 | 新路径 | 说明 |
|
||
|---------|--------|------|
|
||
| `源码/artifacts/` | `artifacts/` | 构建产物/证据（与源码分离） |
|
||
| `源码/nginx-r1.0425/` | `nginx/` | Nginx 配置（与源码分离） |
|
||
| `源码/docs/` | `docs/` | 文档中心（统一位置） |
|
||
| `源码/dev-support/` | `docs/dev-support/` | 开发支持文档 |
|
||
| `logs/` | `logs/` | 保持不变 |
|
||
| `源码/.sisyphus/` | `.sisyphus/` | 保持不变（在 source/ 内的工具配置） |
|
||
| `源码/.gitignore` | (保持) | |
|
||
| `源码/AGENTS.md` | (保持) | 更新路径引用 |
|
||
| `源码/.editorconfig` | (保持) | |
|
||
|
||
---
|
||
|
||
## 5. 影响与注意事项
|
||
|
||
### 5.1 路径依赖影响
|
||
|
||
以下内容可能引用了旧路径，重组后需更新：
|
||
|
||
1. **`源码/AGENTS.md`** — 文档中引用了顶层目录结构，需更新
|
||
2. **`scripts/test-env/` 下的脚本** — 可能引用了 `../maven-cw-elevator-application/` 等路径
|
||
3. **`源码/maven-cw-elevator-application/scripts/`** — 构建脚本中可能硬编码了路径
|
||
4. **`maven-cw-elevator-application/tools/`** — Python 测试脚本中的路径引用
|
||
5. **`source/frontend/scripts/`** — 前端构建工具的路径配置
|
||
6. **Docker Compose 文件** — `scripts/test-env/docker-compose.infra.yml` 中的挂载卷路径
|
||
|
||
### 5.2 执行策略
|
||
|
||
1. 使用 `git mv` 执行移动（保留 git 历史）
|
||
2. 先移动、再更新引用、最后验证
|
||
3. 每个顶层目录分批执行，每批完成后运行验证
|
||
4. 备份文件不做任何修改，整体迁移
|
||
|
||
### 5.3 不处理的范围
|
||
|
||
以下内容保持原样，不做重组：
|
||
- `.git/` — git 仓库元数据
|
||
- `.gitignore` — 配置
|
||
- `源码/.sisyphus/` — Sisyphus AI 工具配置
|
||
- 各 Maven 项目的 `target/` 目录 — 构建产物
|
||
|
||
---
|
||
|
||
## 6. 执行计划（概要）
|
||
|
||
| 阶段 | 内容 | 预估操作数 |
|
||
|------|------|-----------|
|
||
| 1 | 创建 archive/ 及子目录 | ~10 `mkdir` |
|
||
| 2 | 迁移 反1/ → archive/decompiled-sources/ | 1 `git mv` |
|
||
| 3 | 迁移 cn/, media/ → archive/miscellaneous/ | 2 `git mv` |
|
||
| 4 | 迁移 源码/源码/ → archive/miscellaneous/ | 1 `git mv` |
|
||
| 5 | 迁移源码/frontend/ .bak 目录 → archive/frontend-backups/ | ~15 `git mv` |
|
||
| 6 | 创建 runtime/, 从 星中心/ 迁移并重命名 | ~8 `git mv` |
|
||
| 7 | 创建 source/backend/, 从 源码/ 迁移 Maven 项目并重命名 | ~14 `git mv` |
|
||
| 8 | 创建 source/frontend/, 从 源码/frontend-source/ 迁移 | 1 `git mv` |
|
||
| 9 | 迁移 源码/frontend/（非 .bak）→ runtime/frontend/ | ~15 `git mv` |
|
||
| 10 | 迁移 源码/nginx-r1.0425/ → nginx/ | 1 `git mv` |
|
||
| 11 | 迁移 源码/artifacts/ → artifacts/ | 1 `git mv` |
|
||
| 12 | 合并 scripts/ 目录 | ~5 `git mv` |
|
||
| 13 | 清理 源码/ 残余 | 验证 |
|
||
| 14 | 更新 AGENTS.md 中的路径引用 | 1 次编辑 |
|
||
| 15 | 更新 test-env 脚本中的路径引用 | 逐一检查 |
|
||
| 16 | final: 验证 + git status | 确认 |
|