migrate-to-elinsa-stack

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrar para o Stack Elinsa

迁移至Elinsa技术栈

Principio

原则

Trate o projeto original como fonte de comportamento, nao como stack a preservar. A migracao deve reconstruir o produto no padrao Elinsa: Next.js App Router, UI shadcn/Tailwind, Better Auth, Drizzle/PostgreSQL, Biome e entrega revisavel pela TI.

Normalmente a equipe setorial nao tera acesso ao repositorio do site. Nesse caso, prepare um projeto Next.js migrado, versionado no GitHub, alinhado aos contratos desta skill, para revisao e aprovacao da TI antes da integracao final.

将原始项目视为行为逻辑的来源，而非需要保留的技术栈。迁移需按照Elinsa标准重构产品：采用Next.js App Router、shadcn/Tailwind UI、Better Auth、Drizzle/PostgreSQL、Biome，并交付给IT部门审核。

通常业务部门无法访问网站仓库。这种情况下，请先准备好迁移后的Next.js项目，在GitHub上进行版本控制，符合本技能的规范要求，提交给IT部门审核批准后再进行最终集成。

Fontes de Verdade

权威参考来源

Use esta ordem:

Repositorio oficial, quando acessivel: https://github.com/elinsa-do-brasil/site
Checkout local do site, quando existir.
```
references/elinsa-stack-contract.md
```
como baseline quando o repo Elinsa nao estiver acessivel.

Quando tiver acesso ao repo Elinsa, confira

package.json

components.json

app/globals.css

components/frontend-shell.tsx

, rotas irmas em

app/(frontend)

e componentes existentes antes de decidir arquitetura, UI ou versoes. As versoes do repo atual vencem o baseline desta skill. Se o repo pedir algo mais novo que Node 26+, Next 16+ ou Tailwind 4+, siga o repo.

Antes de usar APIs ou convencoes Next.js, consulte

node_modules/next/dist/docs/

no projeto em uso. Priorize os docs de estrutura, layouts/pages, Server/Client Components, metadata e Route Handlers.

请遵循以下优先级：

官方仓库（若可访问）：https://github.com/elinsa-do-brasil/site
本地检出的网站项目（若存在）
当Elinsa仓库不可访问时，以
```
references/elinsa-stack-contract.md
```
作为基准

若可访问Elinsa仓库，请在决定架构、UI或版本前，先查看

package.json

、

components.json

、

app/globals.css

、

components/frontend-shell.tsx

、

app/(frontend)

下的同级路由及现有组件。当前仓库的版本优先级高于本技能的基准要求。若仓库要求使用比Node 26+、Next 16+或Tailwind 4+更新的版本，请遵循仓库要求。

在使用Next.js的API或规范前，请查阅当前项目中的

node_modules/next/dist/docs/

。优先参考结构、布局/页面、Server/Client Components、元数据及Route Handlers相关文档。

Workflow

工作流程

Siga esta sequencia:

Inventarie o projeto original: telas, rotas, fluxos, dados, auth, dependencias, assets, tecnologia e estado de versionamento.
Se nao houver Git/GitHub confiavel ou o app vier de ZIP/Lovable/no-code, leia
```
references/setup-versioning.md
```
e crie o repositorio antes de refatorar.
Leia o contrato de stack em
```
references/elinsa-stack-contract.md
```
.
Use a decision tree abaixo para escolher superficie, persistencia, auth e referencias adicionais.
Escreva um plano curto: rota final sugerida, arquivos a criar/editar, dependencias a remover, dados/auth a migrar e validacoes.
Migre uma tela funcional primeiro. Nao comece por landing page explicativa.
Substitua auth legado por Better Auth e persistencia legado por Drizzle/PostgreSQL quando o projeto tiver usuarios, permissoes ou banco.
Recrie formularios com shadcn Field, React Hook Form, Zod e resolver.
Valide Git, pnpm, Biome, build e fluxos manuais.
Prepare README, branch/PR GitHub, checklist e evidencias para revisao da TI.

请遵循以下步骤：

盘点原始项目：页面、路由、流程、数据、认证、依赖项、资源、技术栈及版本控制状态。
若无可信赖的Git/GitHub，或项目来自ZIP/Lovable/no-code，请先阅读
```
references/setup-versioning.md
```
并创建仓库后再进行重构。
阅读
```
references/elinsa-stack-contract.md
```
中的技术栈规范。
使用下方的决策树选择界面层、持久化方案、认证方式及其他参考资料。
撰写简短计划：建议的最终路由、需创建/编辑的文件、需移除的依赖项、需迁移的数据/认证逻辑及验证项。
先迁移一个可运行的功能页面，不要从说明性的着陆页开始。
若项目包含用户、权限或数据库，请将遗留认证系统替换为Better Auth，将遗留持久化方案替换为Drizzle/PostgreSQL。
使用shadcn Field、React Hook Form、Zod及解析器重新构建表单。
验证Git、pnpm、Biome、构建流程及手动操作流程。
准备README文档、GitHub分支/PR、检查清单及相关证据，提交给IT部门审核。

Decision Tree

决策树

Sem Git, sem GitHub, ZIP, pasta local ou Lovable: carregue
```
references/setup-versioning.md
```
antes de editar codigo.
Sem acesso ao repo Elinsa: carregue
```
references/elinsa-stack-contract.md
```
e copie os contratos base.
Sistema operacional interno, como almoxarifado, pedidos, cadastros, aprovacoes ou consultas: use Drizzle/PostgreSQL, Better Auth e paginas operacionais. Nao adicione Payload/Fumadocs por padrao.
Conteudo gerenciavel, vagas, imprensa ou documentacao do site: considere Payload/Fumadocs somente se o dominio pedir ou se a TI aprovar.

Rota publica institucional: planeje

app/(frontend)/(publico)/<rota>/page.tsx

Portal interno: planeje
```
app/(frontend)/portal/<rota>/page.tsx
```
e respeite o shell existente.
Conta, login ou configuracoes de usuario: planeje
```
app/(frontend)/(conta)/<rota>/page.tsx
```
.
Mutacoes chamadas pela propria UI React: prefira Server Actions co-localizadas ao fluxo ou modulo de dominio. Use Route Handlers apenas quando houver webhook, upload/download protegido, integracao externa, cliente nao React, callback de auth ou necessidade explicita de endpoint HTTP.
Formulario migrado: carregue
```
references/forms.md
```
.
UI, layout, tokens, shadcn ou responsividade: carregue
```
references/ui-patterns.md
```
.
Auth, permissoes, banco, emails ou integracoes: carregue
```
references/auth-and-data.md
```
.
Entrega, validacao, aceite ou antipadroes: carregue
```
references/delivery-checklist.md
```
.

无Git、无GitHub、来自ZIP/本地文件夹或Lovable：在编辑代码前先查看
```
references/setup-versioning.md
```
。
无法访问Elinsa仓库：查看
```
references/elinsa-stack-contract.md
```
并复制基础规范。
内部运营系统（如库存、订单、注册、审批或查询系统）：使用Drizzle/PostgreSQL、Better Auth及运营页面。默认不要添加Payload/Fumadocs。
可管理内容、职位招聘、新闻或网站文档：仅在业务领域要求或IT部门批准时，才考虑使用Payload/Fumadocs。

公共机构路由：规划为

app/(frontend)/(publico)/<rota>/page.tsx

。

内部门户：规划为
```
app/(frontend)/portal/<rota>/page.tsx
```
并遵循现有壳组件规范。
用户账户、登录或设置：规划为
```
app/(frontend)/(conta)/<rota>/page.tsx
```
。
React UI自身调用的变更操作：优先使用与流程或领域模块共存的Server Actions。仅当存在webhook、受保护的上传/下载、外部集成、非React客户端、认证回调或明确需要HTTP端点时，才使用Route Handlers。
迁移表单：查看
```
references/forms.md
```
。
UI、布局、令牌、shadcn或响应式设计：查看
```
references/ui-patterns.md
```
。
认证、权限、数据库、邮件或集成：查看
```
references/auth-and-data.md
```
。
交付、验证、验收或反模式：查看
```
references/delivery-checklist.md
```
。

Referencias Sob Demanda

按需参考资料

Leia apenas o que a tarefa pedir:

```
references/setup-versioning.md
```
: instalacao de Git/Node/pnpm, Lovable/ZIP, commit inicial, GitHub e branch de migracao.

references/elinsa-stack-contract.md

: baseline de package/runtime,

components.json

biome.json

app/globals.css

```
references/migration-process.md
```
: inventario, traducao de tecnologias antigas, escolha de superficie, extracao tecnica e assets.
```
references/ui-patterns.md
```
: shadcn, Tailwind v4, tokens, acessibilidade e composicao visual Elinsa.
```
references/forms.md
```
: formularios com shadcn Field, React Hook Form, Zod, resolver e validacao server-side.
```
references/auth-and-data.md
```
: Better Auth, Drizzle/PostgreSQL, permissoes, Payload/Fumadocs, Resend e segredos.
```
references/delivery-checklist.md
```
: validacao, README, PR para TI, criterios de aceite e antipadroes.

Use skills complementares apenas quando o dominio exigir:

next-best-practices

shadcn

drizzle-best-practices

better-auth-best-practices

payload

resend

webapp-testing

仅阅读任务所需的内容：

```
references/setup-versioning.md
```
：Git/Node/pnpm安装、Lovable/ZIP处理、初始提交、GitHub及迁移分支创建。

references/elinsa-stack-contract.md

：包/运行时基准、

components.json

、

biome.json

及

app/globals.css

规范。

```
references/migration-process.md
```
：项目盘点、旧技术栈转换、界面层选择、技术提取及资源处理。
```
references/ui-patterns.md
```
：shadcn、Tailwind v4、令牌、可访问性及Elinsa视觉组合规范。
```
references/forms.md
```
：使用shadcn Field、React Hook Form、Zod、解析器及服务端验证构建表单。
```
references/auth-and-data.md
```
：Better Auth、Drizzle/PostgreSQL、权限、Payload/Fumadocs、Resend及密钥管理。
```
references/delivery-checklist.md
```
：验证、README文档、提交给IT部门的PR、验收标准及反模式。

仅当业务领域需要时，才使用补充技能：

next-best-practices

、

shadcn

、

drizzle-best-practices

、

better-auth-best-practices

、

payload

、

resend

或

webapp-testing

。

Contratos Duros

硬性规范

Versione o original antes da migracao quando nao houver historico confiavel.
Entregue repositorio GitHub privado, branch ou pull request. ZIP, pasta solta, deploy ou link do Lovable nao bastam.
Use pnpm como unico package manager.
Use Node 26+, Next.js 16+, React 19+, Tailwind 4+, Biome, shadcn/radix, Better Auth e Drizzle/PostgreSQL como baseline minimo quando o repo Elinsa nao estiver acessivel.
Prefira Server Actions para mutacoes acopladas a UI. Nao crie uma malha de
```
app/api/*
```
para CRUD interno sem necessidade real.
Versione alteracoes de banco com migrations Drizzle commitadas em
```
lib/db/migrations
```
ou no caminho usado pelo repo. Nao altere schema manualmente no banco como estado final.
Quando o repo Elinsa estiver acessivel, use as versoes e configuracoes dele como fonte primaria.
Nao mantenha PHP, WordPress, Vue, Angular, React Router, Firebase Auth, JWT caseiro ou outro runtime legado como dependencia de producao.
Nao comite
```
.env
```
, tokens, credenciais, dumps sensiveis ou arquivos pessoais.

当无可信赖的历史记录时，需在迁移前对原始项目进行版本控制。
交付私有GitHub仓库、分支或拉取请求。仅提供ZIP、零散文件夹、部署链接或Lovable链接是不够的。
仅使用pnpm作为包管理器。
当Elinsa仓库不可访问时，需以Node 26+、Next.js 16+、React 19+、Tailwind 4+、Biome、shadcn/radix、Better Auth及Drizzle/PostgreSQL作为最低基准。
优先使用Server Actions处理与UI耦合的变更操作。若无实际需求，请勿为内部CRUD创建大量
```
app/api/*
```
接口。
使用Drizzle迁移对数据库变更进行版本控制，并提交至
```
lib/db/migrations
```
或仓库使用的对应路径。请勿手动修改数据库 schema 作为最终状态。
若可访问Elinsa仓库，请将其版本及配置作为主要参考来源。
请勿保留PHP、WordPress、Vue、Angular、React Router、Firebase Auth、自定义JWT或其他遗留运行时作为生产依赖。
请勿提交
```
.env
```
、令牌、凭证、敏感数据转储或个人文件。

Saida Esperada

预期输出

Ao final da resposta ou execucao, entregue:

O que foi inventariado e qual superficie Elinsa foi escolhida.
Quais referencias desta skill foram usadas.
Link ou estado do repositorio/branch/PR GitHub, quando aplicavel.
Mudancas principais de stack, UI, auth, dados e formularios.
Comandos de validacao executados e resultados.
Pendencias claras para a TI revisar ou integrar.

在响应或执行完成时，请交付：

盘点内容及选择的Elinsa技术栈层面。
本技能中使用的参考资料。
GitHub仓库/分支/PR的链接或状态（若适用）。
技术栈、UI、认证、数据及表单的主要变更。
执行的验证命令及结果。
需IT部门审核或集成的明确待办事项。