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

**日期:** 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 | 确认 |