huangping/starRiverProperty
1
0
Fork 0
mirror of https://github.com/hpd840321/starRiverProperty.git synced 2026-06-09 16:30:29 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
203005aafb10292e85dfc69e5d34fb5c3d7416fa
starRiverProperty/docs/superpowers/specs/2026-05-07-directory-restructure-design.md
T
hpd840321 7b2bd307f1 Initial commit: reorganized source tree 
- 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.
2026-05-09 09:56:45 +08:00

10 KiB
Raw Blame History

目录结构重组设计 — 星河湾星中星

日期: 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. 顶层目录结构

星河湾星中星/
├── 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/ — 统一脚本目录

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/ — 历史/参考/遗留

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 确认
Reference in New Issue View Git Blame Copy Permalink