Add project management guide

docs/user-guide/advanced-settings/manage-project/README.md

@@ -0,0 +1,9 @@
+# 管理项目
+
+当企业需要在开发、测试和生产等多套环境之间交付 TapData 配置时，可以通过项目管理能力将同一业务目标下的任务、API 及其依赖连接组织为项目，并结合 GitHub 与自动化流水线完成版本化管理和跨环境部署。
+
+本专题包含功能介绍、部署架构设计、流水线搭建和项目发布操作，帮助您从规划到落地逐步完成项目管理能力的建设与使用；如仅通过导出 ZIP 文件并在目标环境手动导入配置，可直接阅读[创建项目并部署](deploy-project.md)。
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />

docs/user-guide/advanced-settings/manage-project/deploy-project.md

@@ -0,0 +1,171 @@
+# 创建项目并部署
+
+工程师在完成 TapData 连接和任务配置后，可通过本文的步骤将配置打包为项目、导出并部署到目标环境，支持通过 GitHub Actions 自动触发部署或手动触发部署。
+
+:::tip
+本文同时介绍自动化部署和手动导入导出两种使用方式。如果您计划通过 GitHub 和 GitHub Actions 实现自动化流转，可结合阅读[搭建自动化部署流水线](setup-pipeline.md)；如果当前仅需手动导入导出，继续阅读本文并参考文末的“附：手动导入配置”即可。
+:::
+
+## 场景说明
+
+本文以一个典型的数据集成场景为例，团队需要将 Oracle 源库的数据实时同步至 Doris 数据仓库，构建实时数仓链路。该团队已在开发环境完成了宽表同步任务和对外 API 的配置验证。现在需要将这套配置迁移到测试环境进行验证，最终发布到生产环境。
+
+以下步骤将完整演示从创建项目、导出配置，到自动部署、手动发布的全流程。
+
+:::tip
+为保障各环境的任务配置可通过连接名称引用数据源，推荐各环境的连接名称保持一致，部署时系统根据连接名从 GitHub Secrets 匹配并注入该环境的真实地址和密码。
+:::
+
+## 步骤一：创建项目并选择资源
+
+将本团队的任务和 API 打包为一个项目，作为后续导出和部署的基本单元。
+
+1. [登录 TapData 管理平台](../../log-in.md)，在左侧导航栏选择**高级设置 → 项目管理**。
+2. 点击左侧面板顶部的 **+** 新建项目，填写项目名称（本例填入 `dw-pipeline`，建议与 GitHub 租户仓库名保持一致）。
+3. 在中间面板通过标签切换查看**复制任务**、**开发任务**或 **API**，勾选 `CRM_TO_DW`、`ORDER_TO_DW` 和 `customer-api`，点击**添加已选 →** 移入右侧已选列表。
+
+   ![创建项目并选择资源](../../../images/create_project.png)
+
+   :::tip
+   选择任务或 API 时，系统会自动识别并包含其所依赖的数据连接（本例中会自动带入 `oracle-source` 和 `doris-target`），无需手动添加。
+   :::
+4. 点击**保存**，完成项目创建。
+
+## 步骤二：关联 Git 仓库
+
+将项目与 GitHub 租户仓库关联，后续导出时配置文件可直接推送到仓库并创建 PR，无需手动下载上传。
+
+1. 点击页面右上角的 **Git 配置**。
+2. 在弹出的对话框中填写 GitHub 租户仓库的 URL 和 Personal Access Token。
+
+   ![配置 Git 仓库](../../../images/git_config.png)
+3. 点击**保存**。
+
+:::tip
+如暂不集成 GitHub，可跳过此步骤，直接进入[步骤三](#步骤三导出配置)，选择手动下载文件的方式导入。
+:::
+
+## 步骤三：导出配置
+
+将当前开发环境的项目配置导出，提交到 GitHub 仓库，为后续各环境的部署做准备。
+
+1. 在项目管理页面，点击右上角**导出**，在弹出的导出对话框中，左侧选择要导出的项目。
+2. 在右侧选择**导出类型**：
+
+   ![导出项目](../../../images/export_project.png)
+   - **Git 导出**（已关联 Git 仓库时可用）：配置文件直接推送到 GitHub 仓库并创建 PR。填写以下信息：
+     | 字段    | 说明                                 |
+     | ----- | ---------------------------------- |
+     | 分支名   | 系统自动生成，以 `feat_` 开头，包含当前时间戳，也可手动修改 |
+     | PR 标题 | 简要描述本次变更内容，便于 Review 时识别           |
+     | PR 描述 | 详细说明变更原因和影响范围（可选）                  |
+   - **文件导出**：将配置打包为压缩包文件下载到本地，适用于未配置 Git 集成的场景，后续通过手动导入完成部署（见[附：手动导入](#附手动导入配置)）。
+3. 在资源列表中确认本次导出的任务和 API，确认无误后点击**确认导出**，完成提交。
+
+   :::tip
+   导出时连接信息默认脱敏，数据库密码等敏感字段不会写入配置文件。如目标环境导入后需要任务重新全量同步（如新增源表、变更主键），在此处开启**重跑**；常规变更保持默认（不重跑），任务从上次断点继续，对业务影响最小。
+   :::
+
+<details>
+<summary>导出文件结构说明</summary>
+
+导出的配置以目录形式组织（Git 导出时即为仓库中的文件夹，文件导出时打包为 tar 文件），结构如下：
+
+```
+{项目名}_tapdata_export/
+├── GroupInfo.json          # 项目元数据：项目名称、关联 Git 仓库、资源清单
+├── Connection/             # 连接配置（自动包含所有任务和 API 依赖的连接）
+│   ├── {id}_Connection_Config.json    # 连接参数（账号密码等敏感字段已脱敏）
+│   └── {id}_Connection_Metadata.json # 连接的表结构元数据
+├── Task/                   # 任务配置
+│   ├── {id}_MigrateTask.json          # 复制任务
+│   └── {id}_SyncTask.json             # 开发任务
+├── API/                    # API 配置
+│   ├── {id}_Module.json               # API 定义（路径、字段、查询逻辑）
+│   └── MetadataDefinition.json
+└── User/                   # 用户与角色信息（用于目标环境还原操作人身份）
+    ├── Users.json
+    ├── Roles.json
+    ├── RoleMappings.json
+    └── UserIdEmailMap.json
+```
+
+**说明：**
+
+- **连接数量**：Connection 目录下的连接由系统根据任务和 API 的依赖关系自动识别并导出，无需手动选择。
+- **敏感信息脱敏**：连接的账号、密码等凭据字段在导出时自动清空。如采用自动化部署时，系统会从 GitHub Secrets 中获取该环境的真实凭据注入；采用手动导入时，则需手动更新连接信息。
+- **用户数据**：User 目录包含操作人的账号和角色信息，用于在目标环境建立对应的用户上下文；密码以哈希形式存储，不含明文。
+
+</details>
+
+## 步骤四：合并 PR，自动部署到开发环境
+
+本步骤在 GitHub 侧完成，验证配置文件是否能成功导入开发环境。
+
+1. 进入 GitHub 租户仓库，打开刚创建的 Pull Request，Review 配置文件内容无误后点击 **Merge**。
+2. PR 合并触发 GitHub Actions `TapData Deploy` Workflow，自动将配置部署到开发环境。
+3. 部署完成后，登录开发环境 TapData 管理平台，确认 `CRM_TO_DW`、`ORDER_TO_DW` 任务和 `customer-api` 已正确导入，连接测试通过。
+
+## 步骤五：创建 Tag，自动部署到测试环境
+
+开发环境验证通过后，手动打一个 Git Tag，触发测试环境的自动部署。
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+Tag 推送后，GitHub Actions 自动触发测试环境的部署流程。部署完成后，在测试环境完成业务验证（功能正确性、数据量、同步延迟等），确认无问题后进入下一步。
+
+## 步骤六：手动触发，发布到生产环境
+
+测试验证通过后，手动触发生产部署，指定与测试相同的 Tag，确保生产和测试环境部署的是同一版本配置。
+
+1. 进入 GitHub 租户仓库 → **Actions** → 选择 `TapData Deploy`。
+2. 点击 **Run workflow**，**Branch** 选择 Tag 名（如 `v1.0.0`），**Target environment** 选择 `prod`。
+3. 点击 **Run workflow**，经过 `deploy` 审批门后执行部署。
+4. 部署完成后，登录生产环境验证任务状态和 API 可用性，确认无误后正式上线。
+
+## 回滚
+
+若生产部署后发现问题，可立即回滚到上一个稳定版本：
+
+1. 进入 GitHub 租户仓库 → **Actions** → 选择 `TapData Rollback`。
+2. 点击 **Run workflow**，填写目标环境（如 `prod`）和要回滚到的 Tag（如 `v0.9.0`）。
+3. 回滚流程自动停止当前任务、清理现有配置，并从目标 Tag 重新导入。
+4. 完成后登录目标环境验证，确认无误后手动启动任务。
+
+回滚只影响指定的目标环境，其他环境不受干扰。
+
+## 常见问题
+
+**Q：项目导入的规则是什么？**
+
+无论是自动部署还是手动导入，目标环境中已有的连接、任务和 API 会被更新，如果不存在则会自动创建。另外，如采用手动导入，连接凭据不会自动注入，导入后需要您在目标环境中手动补全或调整。
+
+**Q：提示 `Could not find reusable workflow`？**
+
+- 检查 Worker 仓库可见性是否为 `Internal`。
+- 检查租户仓库 Workflow 中的 Worker 仓库路径是否已替换为真实值。
+
+**Q：部署成功了，但数据库密码没有注入成功？**
+
+- 检查连接凭据是否配置在对应 Environment 的 Secrets / Variables 中，而不是仓库级 Secrets 中。
+- 检查变量名称是否与 TapData 中的连接名称严格对应。
+
+**Q：执行导入脚本时报错？**
+
+- 检查 `{ENV}_TAPDATA_ACCESS_CODE` 是否配置正确且仍然有效。
+- 查看 GitHub Actions 执行日志中 TapData API 返回的具体错误信息，再进一步定位问题。
+
+
+## 附录：手动导入配置
+
+适用于未配置 GitHub 集成，或需要直接在目标环境导入某个版本配置的场景。
+
+1. 在**高级设置 → 导出/导入**页面，点击**导入**。
+2. 上传从开发环境导出的压缩包文件。
+3. 选择冲突处理策略（跳过 / 更新已存在的配置）。
+4. 点击**开始导入**，系统校验文件格式，并显示导入预览（涉及哪些连接、任务、API）。
+5. 确认无误后执行导入，查看导入结果（成功 / 失败明细）。
+6. 导入完成后，登录目标环境 TapData 管理平台，补充或调整连接的真实地址、账号和密码等信息，然后确认数据库连接、任务状态和 API 可用性，确认无误后正式启动任务。

docs/user-guide/advanced-settings/manage-project/introduction.md

@@ -0,0 +1,51 @@
+# 功能概述
+
+项目管理功能帮助数据集成团队将 TapData 环境中的连接、任务、API 等配置资源打包为可版本化的交付单元，结合 GitHub 自动化流水线，在开发、测试、生产等多套环境之间实现快速部署与配置追溯，替代人工手动迁移。
+
+## 背景介绍
+
+在实际项目中，企业通常需要同时维护多套 TapData 环境，并为每套环境准备对应的源库、目标库或服务端点，例如开发、测试、性能验证和生产环境。
+
+当数据集成业务逐步走向稳定运行，团队通常会面临一个共同的挑战：如何将经过测试验证的配置，安全、准确地迁移到下一个环境，最终发布到生产环境？
+
+在没有自动化流程的情况下，通常需要在测试环境配置好任务和 API 后，工程师登录生产环境，逐一手动创建连接、任务和 API。一旦任务或连接数量增多，漏配某个依赖连接、配错参数的概率就会显著上升，而这类问题往往在生产故障发生后才被发现。更为棘手的是缺少过程审计，即谁改了什么、什么时候改的，很难通过有效的记录追踪。
+
+为此，TapData 推出了项目管理与自动化部署能力，将上述过程标准化、自动化，让配置像代码一样实现版本控制、审计追溯与一键发布。
+
+<details>
+
+<summary>什么是项目</summary>
+
+在 TapData 中，**项目（Project）** 是将同一业务目标下的任务、API 及其依赖连接组织在一起，用于统一管理、导出、部署和版本追溯的基本单元。
+
+通过项目，原本分散的资源可以按业务场景归组，在多环境之间作为完整整体打包迁移，降低遗漏依赖配置的风险，并按项目粒度管理导出结果和变更历史。
+
+</details>
+
+## 整体工作链路
+
+![整体工作链路](../../../images/cicd_config_deployment_flow.png)
+
+当 TapData 数据集成链路有新的需求，开发人员在源环境中完成任务、API 和连接等资源的配置与验证，并通过项目化打包能力将配置导出，提交到 GitHub 仓库进行版本管理。
+
+当需要发布至下一个环境时，GitHub Actions 流水线会自动触发部署流程，选择或判定目标环境，例如测试环境、性能验证环境或生产环境，并从对应的 Environment Secrets 中加载该环境的数据源连接信息，如数据库连接字符串、账密等。
+
+随后，流水线将配置导入目标环境并运行，同时执行健康检查和结果通知。整个过程无需工程师逐一登录各环境手动配置，实现配置版本化、凭据隔离和多环境自动化部署。
+
+## 核心能力
+
+- **项目化快速打包**：将任务、API、连接等资源聚合为项目统一管理，自动包含所有依赖项，确保整体迁移完整一致。
+- **配置即代码易于审计**：配置托管至 GitHub，每次变更均有 Git 记录，支持随时审计、对比差异及一键回滚。
+- **自动化分钟级发布**：结合 GitHub Actions 实现跨环境自动化部署，支持条件触发与人工审批，内置健康检查与通知。
+- **跨环境配置/凭据复用**：同一份配置可在多环境复用。真实连接凭据在部署时根据环境自动注入，无需修改任务逻辑。
+- **隔离敏感信息提升安全性**：导出时自动脱敏，密码等凭据不入代码库，通过 GitHub Secrets 或 Excel 模板独立管理与动态注入。
+- **平滑切换与快速回滚**：支持先部署至备用环境，验证通过后无感知切换流量；遇错可秒级回滚，保障高可用。
+
+## 适用场景
+
+项目管理与自动化部署能力特别适用于以下业务场景：
+
+- **多套环境的自动化部署**：当企业存在开发、测试、生产等多套独立环境，且需要将数据集成配置在各环境中快速、准确地同步时，可通过项目打包和自动化流水线实现一键部署，确保各环境配置严格一致。
+- **大规模团队协同开发**：当多名工程师共同维护大量数据集成任务时，配置极易发生冲突或被误改。引入项目管理后，所有变更均可接入 Git 工作流，通过 Pull Request 进行团队审查，让变更过程可见、可控。
+- **强安全合规与操作审计**：适用于对变更留痕和信息安全有严格要求的企业规范。Git 原生提供完整的变更时间线和操作人审计记录；同时实现配置与凭据分离，数据库密码等敏感信息不再明文流转，而是通过 Secrets 动态安全注入。
+- **核心业务高可用升级**：针对要求“零停机”发布的关键线上业务，支持在独立的备用环境中充分验证新版配置，再平滑切换业务流量；一旦发现异常，可通过指定历史版本实现秒级快速回滚，最大程度降低生产故障风险。