# 脚手架当前能力与待联调事项

本文面向采用公司四个新通平台脚手架的新项目。依据 2026 年 10 月 21 日本地检出的四仓 README、`AGENTS.md`、包清单及目录记录；仅说明当时可见的代码与待联调事项，未验证四仓共同运行、生产配置或部署结果。开始实施前重新核对目标仓库当前版本和项目负责人给出的需求；本文不能替代仓库内规则。

## 四个仓库各管什么

| 仓库 | 当前技术与职责 | 构建与交付形态 |
| --- | --- | --- |
| `xt-platform-java` | Java 17、Spring Boot、MyBatis-Plus、MySQL、Redis；提供身份、权限、租户、基础设施和业务 API 的服务端基础。 | Maven 多模块；`xt-platform-server` 产出可运行 JAR。 |
| `xt-platform-admin` | Vue 3、Vite、TypeScript、Element Plus；独立管理端，已有登录、系统和基础设施页面。 | `pnpm run build:prod` 产出 `dist-prod` 静态文件；服务器需支持 SPA 路由回退。 |
| `xt-platform-web` | Nuxt 4、Vue 3、TypeScript；面向电脑和手机浏览器的前台。 | `pnpm build` 产出服务端渲染应用；生产需要 Node 进程运行 `.output/server/index.mjs`。 |
| `xt-platform-uniApp` | uni-app、Vue 3、TypeScript；面向 H5、微信小程序与 App 的前台。 | 按目标平台分别构建；微信和 App 还需对应工具、应用标识及发布环境。 |

四仓是既定的起步材料，但不能据此认定每个新项目都已需要四个对外入口或四份立即上线的产物。先写清本次要交付的用户端、管理端、服务端功能和发布范围，再在对应仓库实施。不要另建一套平行后台、请求层或业务服务；也不要为了“用满四仓”给尚无需求的端补占位功能。

## 开工顺序

1. 在每个涉及的仓库先读根目录 `README.md`、`AGENTS.md`、相关 `docs/` 和按任务需要的 `.agents/skills/`。依赖版本、命令、目录、接口前缀与验证要求以目标仓库当前文件为准。仓库内 Skill 用来约束该仓库的具体操作；本站提供可更新的横向参考，不代替它。
2. 明确首个真实用户任务和数据归属：哪个端发起操作，后端哪个业务模块负责授权、规则和写入，持久化与失败结果是什么。按一条端到端链路交付，避免只做可点击的前端样例。
3. 联调前核对 API 契约：路径与网关前缀、请求和响应字段、分页、登录态、租户、角色/数据权限、错误码、上传及跨域/同源策略。管理端默认使用 `/admin-api`；前台和小程序的实际接口及认证方式须与后端确认，不能从演示请求层推断已打通。
4. 按环境填写配置并验证真实连接。前端公开变量和构建产物不能放密钥；测试、生产的域名、数据库、Redis、对象存储和认证上下文应分别核对。数据库初始化脚本只能用于明确的新建隔离库，不能在存量库直接运行。
5. 各仓运行其当前要求的检查，再用同一环境走通用户操作、后台管理和服务端持久化。向研发交付时列出四仓版本、构建产物、配置项、数据库变更、启动顺序、已通过的链路和未验证的发布条件。

## 当前脚手架尚未替项目完成的事

- `xt-platform-web` 的 catalog 是假数据契约示例，页面不会自动请求后端；登录、支付和真实业务仍需实现。它没有默认 `/api` 代理，`NUXT_PUBLIC_API_BASE` 当前留空。部署时还需提供 Node SSR 运行环境，不能把它当作纯静态站点上传。
- `xt-platform-uniApp` 当前没有真实后端连接，首页不发请求；先配置目标环境的 API 地址，再验证 H5、微信或 App 实际需要的平台能力。其 README 给出的 `pnpm check` 覆盖 lint、类型、请求回归及 H5/微信构建，不等于 App 已在设备上验收。
- `xt-platform-admin` 虽有管理基础页面，实际 API 地址、租户和验证码等开关仍需与后端环境对齐；默认本地地址及模板示例不能直接当生产配置。前端菜单或按钮隐藏不代替服务端权限检查。
- `xt-platform-java` 保留多项平台能力，但不包含新项目的业务领域；业务代码应放进所属模块。其初始化 SQL 含 `DROP`，只能针对获准的新建隔离库使用。短信和邮件目前基于 Spring 事件与 `@Async`，不能仅凭“异步”宣称可靠投递，也不需要为模板额外部署消息队列。

## 最小交付核对

| 核对项 | 应提供的证据 |
| --- | --- |
| 真实业务链路 | 目标端调用真实 API；后端完成授权、业务处理和持久化；成功、失败和无权限路径可观察。 |
| 四仓契约 | 实际接口前缀、认证方式、租户/权限、字段和错误处理一致；涉及的端都用同一后端事实来源。 |
| 可部署性 | 各仓锁定版本和构建命令可复现；JAR、管理端静态文件、Nuxt Node 服务及所需移动平台产物分别有明确运行环境。 |
| 数据与配置 | 数据库变更可审阅且有执行步骤；测试/生产隔离；公开前端配置不含密钥；初始化脚本不误用。 |
| 性能 | 选出首屏、列表或关键提交等实际任务，在约定数据量和网络下测量请求数、等待时间及资源体积；针对异常做局部修正并复测。 |

构建通过、页面能打开或目录里有某项能力，都不足以证明跨仓联调和生产可用。性能目标值由当前产品和数据规模确定，方法见[性能研发规范](../performance/performance-principles.md)；项目本地约定与本站通用建议的关系见[使用指南](../../guide/usage/how-to-use-this-library.md)。

## 来源与有效边界

本次核对的 Git 修订分别为：`xt-platform-java` `a1af75c`（2026-10-15）、`xt-platform-admin` `9fe89d3`（2026-10-15）、`xt-platform-web` `15ceacf`（2026-10-17）、`xt-platform-uniApp` `0cd584c`（2026-10-19）。事实来源为四仓根目录 README、`AGENTS.md`、构建配置和相关开发文档。仓库后续更新、环境配置及产品需求可能改变这些结论，实施时须重新核对。本文没有验证构建或跨仓联调，也不包含内部地址、账号或凭据。