# 四仓脚手架：选仓、拉取与新项目开发

给产品同事的新项目操作指南：从哪里找脚手架、没权限找谁、代码放在哪里、怎样交给 AI 开发，以及怎样交到研发手里上线。

公司新项目沿用四仓的固定技术栈。本指南依据 2026 年 10 月 21 日检出的四仓 README、`AGENTS.md` 和团队确认的权限处理方式整理；具体启动命令、分支与部署方式以目标项目当前约定为准。

## 先记住三个位置

| 位置 | 是什么 | 你要做什么 |
| --- | --- | --- |
| 脚手架源仓库 | 公司 Codeup 的 `Base/xt-platform-*` 四个仓库，共用的工程起点 | 从下面的地址查看、拉取。**没有权限就找对应开发。** |
| 你电脑上的项目目录 | 从脚手架拉下来的本地代码，Agent 在这里修改和运行 | 将四个仓库放在同一项目父目录下，分别保留各自的 Git 仓库。 |
| 新项目仓库 | 公司 Codeup 中为这个产品新建的四个目标仓库 | 由对应开发确认所属代码组、地址和分支；之后把本地改动推到这里。 |

`git clone` 是把源代码拉到电脑；`origin` 是本地代码接下来同步的远端地址；`git push` 才会把提交传到远端。**拉下脚手架后，要先把 `origin` 换成新项目仓库。**

## 现场演示：用“活动报名”走一遍

示例范围：用户在浏览器报名，运营在管理端审核，用户能查到结果。它用于说明操作顺序，不表示已经创建或上线了一个活动产品。

| 步骤 | 屏幕上实际展示什么 | 完成时应看到什么 |
| --- | --- | --- |
| 1. 找入口 | 打开本指南，点击下方四个源仓库链接 | 能看到代码文件与 README。 |
| 2. 拿权限 | 确认公司账号、仓库读取及新仓库写入权限 | 网页能看、SSH 能拉；缺权限就找对应开发。 |
| 3. 确认场景 | 说明活动报名的用户端、管理端、账号与数据需求 | 首期使用 Java + Web + admin，uni-app 暂不开发和发布。 |
| 4. 建新仓库 | 打开对应开发指定的新项目代码组和四个目标仓库 | 有四个真实目标地址、默认分支和协作成员。 |
| 5. 初始化 | 拉取四仓、更换各自远端、首次推送 | 本地远端和 Codeup 页面都指向新项目。 |
| 6. 交给 Agent | 提供需求、项目目录、规范地址，先启动现有工程 | 基线能构建、能运行，Agent 列出真实缺口。 |
| 7. 做通流程 | 用户提交 → 后台审核 → 用户查询 | 真实接口保存，刷新和重新登录后结果仍在。 |
| 8. 交付上线 | 查看提交、测试地址、验收记录和发布版本 | 研发能按记录发布，产品在目标环境走完同一流程。 |

现场开始前先与对应开发准备好演示账号、新项目仓库和测试环境。依赖安装、构建、发布可以展示事先真实执行留下的结果，说明哪些步骤现场操作、哪些已提前完成；不把示例地址、模拟数据或本地运行当作已上线。

## 1. 找到脚手架，确认访问权限

打开下方仓库网页，用已加入公司云效组织的账号登录。**没有权限就找对应开发开通**，同时说明你要做的产品、需要的仓库和使用目的。无需申请源仓库写入权限来开发自己的产品。

可以复制这段发给对应开发：

```text
我要用四仓脚手架开发【产品名称】，首期场景是【用户端、管理端、核心流程】。
我的云效账号是【账号】，当前无法访问【仓库链接 / 错误现象】。
请帮我开通脚手架读取与克隆权限，并确认新项目所属代码组、四个目标仓库地址、默认分支，以及我的开发分支推送权限。
```

| 现象 | 下一步 |
| --- | --- |
| 仓库网页无权限或找不到 | 核对账号和公司组织，把完整链接交给对应开发确认仓库权限。 |
| 网页可看，但 SSH 拉取失败 | 按官方说明配置本机 SSH **公钥**到同一个云效账号；仍失败请对应开发核对克隆权限。SSH 公钥配置不会自动授予仓库权限。 |
| 可以拉取，不能推到新项目 | 让对应开发核对新项目成员权限、远端地址和目标分支规则；受保护分支按项目流程提交合并请求。 |
| 无法创建新项目仓库 | 请对应开发在确定的代码组下创建，再把四个地址交给你。 |

操作参考：[Codeup 配置 SSH 密钥](https://help.aliyun.com/zh/yunxiao/user-guide/configure-ssh-key)、[代码组与代码库权限](https://help.aliyun.com/zh/yunxiao/user-guide/platform-permission-settings/)。

## 2. 按场景确定首期开发哪些仓库

四个脚手架分别复制为新项目的四个仓库；“选择”指根据本次需求决定先修改、验证和交付哪些仓库，不是重新选技术栈。

| 需求落点 | 对应仓库 | 同时检查 |
| --- | --- | --- |
| API、身份权限、业务规则、数据库 | `xt-platform-java` | 哪些前端要调用新接口，以及数据变更如何交付。 |
| 运营/管理页面 | `xt-platform-admin` | Java 的 `/admin-api` 契约、菜单和服务端权限。 |
| 电脑或手机浏览器的用户前台 | `xt-platform-web` | Java 提供的用户端 API、认证方式和 Nuxt SSR 部署。 |
| H5、微信小程序或 App 前台 | `xt-platform-uniApp` | Java API、平台登录与对应平台构建。 |

例如新增“用户提交申请、运营审核”：Java 负责申请状态、权限和数据；Web 或 uni-app 实现用户提交，admin 实现审核。若首期没有 App 页面，仍可保留 uni-app 新项目仓库，但不做无需求的页面或发布。实际需求先于仓库数量；不要把业务逻辑分别写在多个前端。

## 四个脚手架源仓库地址

网页地址用于查看代码，SSH 地址用于 `git clone`。这些是脚手架**源仓库**，新项目应另建自己的四个目标仓库，并将各本地仓库的 `origin` 改到对应目标地址。

| 仓库 | 网页地址 | SSH 地址 |
| --- | --- | --- |
| `xt-platform-java` | [查看后端仓库](https://codeup.aliyun.com/696a12a07a1ed8d3da00f471/Base/xt-platform-java) | `git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-java.git` |
| `xt-platform-admin` | [查看管理端仓库](https://codeup.aliyun.com/696a12a07a1ed8d3da00f471/Base/xt-platform-admin) | `git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-admin.git` |
| `xt-platform-web` | [查看浏览器前台仓库](https://codeup.aliyun.com/696a12a07a1ed8d3da00f471/Base/xt-platform-web) | `git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-web.git` |
| `xt-platform-uniApp` | [查看多端前台仓库](https://codeup.aliyun.com/696a12a07a1ed8d3da00f471/Base/xt-platform-uniApp) | `git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-uniApp.git` |

## 3. 先确定新项目仓库放在哪里

新项目继续放在**公司 Codeup 中，由对应开发确认的项目代码组**。`Base` 中上面的四个地址用于取脚手架；自己的产品代码放到新项目目标仓库。代码组没有在本指南中统一指定，不要从示例猜一个真实位置。

有创建权限时，在对应开发确认的位置新建四个空仓库；无创建权限时请对应开发代建。按当前项目命名规则填写名称与成员。复制已有脚手架历史时，目标仓库先不初始化 README 或其他文件，避免出现两套初始历史。平台操作见 [Codeup 快速入门](https://help.aliyun.com/zh/yunxiao/user-guide/novice-guide-1/)。

在项目 README 中记录下面这张表。`event-*` 只是活动报名示例名，实际网页和 SSH 地址必须从新建仓库页面复制。

| 脚手架来源 | 新项目仓库示例名 | 开发前要填齐 |
| --- | --- | --- |
| `xt-platform-java` | `event-java` | 网页地址、SSH 地址、默认分支 |
| `xt-platform-admin` | `event-admin` | 网页地址、SSH 地址、默认分支 |
| `xt-platform-web` | `event-web` | 网页地址、SSH 地址、默认分支 |
| `xt-platform-uniApp` | `event-uniApp` | 网页地址、SSH 地址、默认分支 |

这张表是之后找代码和交接给研发的入口。四个远端准备齐全，开发和部署只覆盖首期实际需要的端。

## 4. 拉取四个脚手架到本地

在新项目的本地父目录执行。以下为脚手架的 SSH 源地址；`your-project` 是示例目录名，执行前换成实际名称，且该目录应为空或不存在。不要把脚手架仓库直接当新项目的远端长期使用。

```sh
mkdir your-project
cd your-project
git clone git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-java.git
git clone git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-admin.git
git clone git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-web.git
git clone git@codeup.aliyun.com:696a12a07a1ed8d3da00f471/Base/xt-platform-uniApp.git
```

四个目录是四个独立 Git 仓库。首次打开时分别运行 `git status -sb`、`git log -1 --oneline`、`git remote -v`，确认所处分支、修订和源地址。脚手架当前默认分支并不相同；不能假定四仓都是 `main`。不要在本地复用同一套 Node/pnpm 版本：各仓版本按当前 README 和锁文件准备。

## 5. 把远端改为新项目仓库，再首次推送

先由项目负责人确定四个**新项目仓库**的地址、默认分支和访问权限。目标通常是四个对应的空仓库；不要把四份代码推到同一 Git 仓库，也不要改写脚手架源仓库。进入每个本地目录，把 `origin` 改为对应的新地址：

```sh
cd xt-platform-java
git remote set-url origin 'git@codeup.aliyun.com:组织/项目/新项目-java.git'
git remote -v
git status -sb
```

对 `xt-platform-admin`、`xt-platform-web`、`xt-platform-uniApp` 分别重复，替换为各自的新项目仓库地址。示例中的“组织/项目/新项目”必须换成真实地址；`git remote -v` 的 fetch 和 push 地址都应指向该仓库。`set-url` 只修改本地 Git 远端，不会推送代码，也不会修改脚手架源仓库。若想保留源地址供以后比较，可先记录在项目文档中；后续更新应先审阅差异，不能无条件合并脚手架的新提交。

只有确认目标仓库为空、分支策略明确且已获得推送授权后，才执行首次推送。若目标仓库已有提交，先核对其历史和默认分支，不能用 `--force` 覆盖。下面仅适用于对应开发已确定新项目默认分支为 `main`，且本地不存在冲突的其他 `main` 分支时：

```sh
git branch -m main
git push -u origin main
git remote -v
git status -sb
```

这里把本地分支与新远端分支对齐；`main` 不是四个脚手架的统一默认分支。若项目用其他分支名，按约定替换。若默认分支受保护，由对应开发完成初始化，再按项目分支流程开发。之后打开新项目网页，确认四份代码分别出现且提交一致，并在平台确认默认分支。

## 6. 让 Agent 先读规则、启动工程，再开发

1. 分别阅读涉及仓库的 `README.md`、根目录 `AGENTS.md`、相关开发文档和按任务需要的 `.agents/skills/`。仓库本地规则优先于本站概述。
2. 按[固定技术栈](technology-selections.md)保留原有框架、构建工具和请求层；仅在需求涉及的仓库增加业务代码。后端先明确规则、权限和数据，再对接页面；不要把前端演示数据视作后端已实现。
3. 按各仓锁文件安装与验证。Java 以 Maven 构建；admin、web、uni-app 各有自己的 Node/pnpm 基线。具体命令取当前仓库 README，不复制其他仓库的版本和脚本。
4. 联调真实 API，核对前后端接口、身份/租户、失败状态与持久化结果。管理端是静态 SPA；Web 是需要 Node 运行的 Nuxt SSR；uni-app 按目标平台验证。跨仓边界见[四仓项目蓝图](project-blueprint.md)。
5. 交付时记录四个新项目仓库地址与修订、实际涉及的端、构建结果、配置需求、数据库变更、联调证据及未验证的平台或环境。没有完成联调时如实说明。

脚手架的阶段性能力和缺口见[脚手架当前能力与待联调事项](four-repository-starters.md)。

把实际信息填进下面的提示，再交给能访问项目目录的 Agent：

```text
我要开发【产品名称】，项目父目录是【本机绝对路径】。
四个新项目仓库地址与默认分支见【项目 README / 地址表】。
先阅读 https://docs.tzxys.cn/llms.txt 和四仓起步指南：
https://docs.tzxys.cn/content/engineering/scaffolds/four-repository-start.md
再读取各仓 README.md、AGENTS.md、现有实现及与任务相关的规范。

固定使用四仓现有技术栈。先检查四个 origin 都指向新项目，按各仓要求启动并记录构建结果。
首期是浏览器活动报名：用户登录提交报名，运营审核，用户查询结果。
涉及 Java、Web、admin；uni-app 本期不开发、不发布。
先说明账号来源、数据归属、接口、配置依赖和缺口，再实现这一条真实流程。
从真实接口保存，补齐权限、加载、空态、失败与重复提交处理。
完成后给出改动仓库、提交、运行方法、验证结果和待研发协助的事项。
环境地址和授权信息缺失时列出需要对应开发提供的内容，不自行编造。
```

产品同事负责确认流程和结果，对应开发提供账号接入、接口、环境与部署边界，Agent 按这些信息执行。脚手架能启动只是基线；账号、业务接口和数据仍要按新产品接通。

## 7. 用真实流程验收第一轮结果

活动报名示例可以按下面顺序现场演示：

1. **用户提交**：用测试账号填写并提交一条报名。页面显示服务端返回的结果；失败时不能显示成功。
2. **后台查到**：进入新项目管理端，找到同一条报名，核对账号、活动和状态。
3. **运营处理**：有权限的运营账号审核报名；无权限账号不能执行该操作。
4. **用户读回**：用户页面刷新、退出并重新登录，仍能查询到审核结果；换另一账号不能看到别人的记录。
5. **异常与规模**：核对重复提交和接口失败提示；按预期数据量检查列表、图片与请求，不只用几条假数据验收。

保留测试环境、版本、操作结果和未通过项。本地完成后还要在目标测试环境再走一遍；涉及小程序或 App 的项目要补目标平台验证。

## 8. 交给研发、测试部署，再上线

产品在新项目仓库持续协作，交付入口应是**仓库与提交版本**。进入团队约定的审查和发布流程前，至少交齐：

| 交付项 | 要写清什么 |
| --- | --- |
| 代码与范围 | 四个新项目地址、分支与提交；本次涉及哪些端。 |
| 运行与配置 | 已验证的安装、构建和启动方法；所需环境变量名、账号和资源依赖。凭据按团队方式交接。 |
| 数据与内容 | 数据库变更、初始化数据、图片或音频如何导入目标环境。 |
| 验收 | 核心真实流程、权限与失败场景的结果，以及未通过项。 |
| 发布与恢复 | 目标环境、域名、发布负责人、本次版本、日志和回退方式。 |

对应开发检查代码和配置，按现有流程发布到测试环境；产品在测试地址走完上面的真实流程。确认首期范围通过后，由项目约定的负责人发布生产，再验证登录、提交、后台处理和结果读回，记录本次版本。

公司四仓的运行方式不同：Java 需要后端运行环境，admin 是静态站点，Web 是 Nuxt SSR 的 Node 服务，uni-app 按实际平台构建。一个前端页面能打开，不能代替其余服务、配置、数据和权限的交付。具体职责与边界见[四仓项目蓝图](project-blueprint.md)。