pessimistcamellia/proto-note

Camada de Anotação de Alterações de Protótipo (proto-note)

Sobreponha em protótipos HTML de página única um "Guia de Alterações para Desenvolvimento": barra lateral fixa escura (checkboxes de módulos + cartões de anotação) ↔ âncoras numeradas na página + linhas de conexão canvas; localização bidirecional ao passar o mouse/clicar; cartões de anotação com link profundo para SDD.

Instalação e Diretório

# Skill pessoal (recomendado)
git clone https://github.com/pessimistcamellia/proto-note.git ~/.cursor/skills/proto-note

# Ou dentro do projeto
git clone https://github.com/pessimistcamellia/proto-note.git .cursor/skills/proto-note

Também é possível copiar todo o diretório para o caminho acima. Estrutura de diretórios:

proto-note/
├── SKILL.md
├── assets/diff-annotator.js      # Motor de anotação (inline no protótipo, não altere a lógica)
├── references/changeset-schema.md
├── docs/screenshots/             # Imagens do README
└── scripts/deploy_github.sh      # Deploy alternativo no GitHub Pages

Dependências de Ambiente

Capacidade	Ferramenta	Quando ausente
Localização de stack técnica/código-fonte	codewiki MCP (ou equivalente de busca de código)	Usar URL online + repositório de código + DOM do navegador para reconstruir
Link profundo SDD	lark-cli (Feishu)	Preencher manualmente a URL do documento e o blockId da seção; se não for Feishu, linkar para a âncora da seção correspondente
Calibragem em nível de pixel	DevTools do navegador / chrome-devtools MCP	Abrir a página online manualmente para comparação
Deploy	Hospedagem estática interna (prioridade)	GitHub Pages pessoal (deploy_github.sh, requer autorização gh)

Se a equipe tiver outro skill de padrão de front-end (ex.: lista de permissões de escolha de bibliotecas, uso de componentes), leia-o conforme necessário antes da criação; caso contrário, baseie-se no código-fonte do repositório alvo e na documentação da equipe.

Plano Padrão: Biblioteca de Componentes e Prioridade de Publicação

Execute por ordem de prioridade; se o anterior não estiver disponível, vá para o próximo; o último é o fallback padrão:

1. Biblioteca de Componentes / Padrões (prioridade): Use a biblioteca de componentes e os padrões reais do sistema online alvo (comparando com o código-fonte / DOM / skill de padrões da equipe). É proibido trocar de biblioteca sem justificativa.
2. Endereço de publicação (prioridade): Se houver hospedagem estática interna existente (ou um endereço de intranet combinado pela equipe), publique primeiro na intranet.
3. Fallback padrão: Se não for possível obter a biblioteca de componentes/padrões reais, ou se não for possível usar devido a permissões, rede, intranet inacessível, etc. → Os componentes podem ser escolhidos livremente conforme um esquema genérico (mantendo-se um HTML interativo de página única); publique no repositório GitHub pessoal do usuário (Pages). Antes do deploy, confirme a autorização gh; se não autorizado, comunique-se com o usuário primeiro. É proibido fazer push para repositório privado sem consentimento.

Regras de Produto

1. Três níveis de alteração + tipo: Página / Módulo / Campo; os tipos distinguem-se entre novo, texto, enumerador/lógica, fluxo, exclusão. É proibido rotular genericamente como "novo".
2. Oculto por padrão, seleção por módulo: Não exibir anotações ao abrir; selecionar por page::module; o estado vai para localStorage. A ausência de chave em módulos novos é true (visível) por padrão. É proibido herdar o estado oculto de "já desligou algum interruptor"; estados sujos são limpos pela atualização da versão LS_KEY.
3. Apenas vinculado a SDD, não exibir PRD: Cartões de anotação usam URL do Documento SDD#blockId.
4. Informação concisa: Barra de anotações sem número de versão/linha de base/instruções de operação; desc apenas a conclusão.
5. Clicável deve ser efetivo: Ao marcar um módulo, a visualização muda + scroll + localização com pulso.
6. Estado de revisão apenas na barra de anotações: Estados normais/vazios/de erro, etc., vão em demoControls; as abas de negócio reais permanecem na página de negócio.
7. Ramos de entrada com exemplos reproduzíveis: examples consistentes com fixtures, é proibido usar valores falsos de placeholder.
8. Barra de anotações não obstrui conteúdo: Não comprimir o layout de negócio; usar spacer para estender scrollWidth, rolagem horizontal para ver totalmente o lado direito. É proibido apenas adicionar body padding-right ou alterar a largura raiz do negócio.
9. Biblioteca de componentes e padrões priorizam o online real: Se for possível reconstituir, deve-se reconstituir (veja o nível 1 do "Plano Padrão"). Mesma biblioteca de componentes não significa reconstituição — esqueleto, conjunto de colunas/largura de colunas, colunas congeladas, estrutura de células, layout da coluna de ações, nomes de classe personalizados e estilos chave devem ser comparados com o DOM/código-fonte online; comparar capturas de tela tela por tela antes da entrega. Somente quando não for possível obter a biblioteca de componentes/padrões reais, é permitido usar componentes genéricos como fallback.
10. Publicação prioriza intranet, senão GitHub pessoal: Se houver endereço de intranet, use-o primeiro; quando não disponível, publique no GitHub Pages pessoal (veja níveis 2–3 do "Plano Padrão").
11. "Antes" = estado atual online: Para itens novos, escreva "sem esta página/módulo/função/campo"; é proibido escrever como diferença em relação à versão anterior do demo; pontos novos online não podem ser omitidos.
12. Sem ponto de aterrissagem de UI, sem linha de conexão: Para fluxos/cadeias puros, target: null, sem âncora; o cartão vai em "Fluxos e Cadeias · Página não visível" e no final das alterações.
13. Alterações em pop-ups: Ao clicar no cartão de anotação, deve passar por DIFF_HOOKS.locate para abrir o pop-up e então conectar a linha; âncora/linha com z-index acima do pop-up (o motor usa segmento 9000).
14. Pop-ups rolam com a página horizontal e verticalmente: Quando a barra de anotações está aberta, o contêiner do pop-up translada com (-scrollX,-scrollY) (o motor já trata); é proibido travar o scroll para evitar.
15. Itens baixáveis com formato real: Modelos/recibos com o mesmo formato e estrutura do negócio real (ex.: se tiver duas planilhas, deve ser verdadeiro .xlsx). É proibido usar CSV para fingir.
16. Múltiplas pontas (frontends) criadas separadamente e interligadas: Back-office de operação, frontend para cliente, etc., separados por limite de sistema em HTMLs distintos; menu unificado com indicação "Ponta · Página"; se houver dados entre páginas, simular escrita/leitura/iniciar/parar/erros.
17. Cartões de anotação devem permitir navegação para SDD: Se houver SDD, cada alteração (ou ponto de funcionalidade) configura sdd.section + blockId, o cartão renderiza o link profundo; o clique deve abrir a seção correspondente, não apenas escrever o nome da seção.

Especificação da Camada de Exibição (Já embutida no motor, não reverter)

• Barra de anotações à direita: Azul marinho escuro, largura 360px, pode ser recolhida para um botão flutuante de entrada.
• Rolagem horizontal: Usar document.body.scrollWidth para medir a largura do negócio (spacer é absolute, não entra neste valor); não ocultar o spacer antes de medir. Restaurar rolagem com behavior:"instant" para evitar conflito com scroll-behavior:smooth.
• Âncoras: Coordenadas do documento position:absolute, fixadas no canto superior esquerdo do alvo; proibido fixed com rastreamento por frames; ocultar com elementFromPoint se houver sobreposição.
• Linhas de conexão: Sem linhas normalmente; ao passar o mouse/fixar, desenhar apenas uma linha; estado fixo tem prioridade sobre hover; ponto inicial usa o rect em tempo real.
• Cartões de anotação: Número + título + tipo·nível + conclusão + antes/depois + SDD; pode conter examples.
• Área de demonstração: Segmented control no topo da barra de anotações → DIFF_HOOKS.setDemoState.

Reconstituição da Stack Técnica (Passo 0)

Execute conforme o "Plano Padrão": se for possível reconstituir, reconstitua; caso contrário, registre o motivo e use o fallback de escolha livre.

1. Se o usuário não forneceu a URL online → avise primeiro; se ainda não houver, pesquise o sistema/rotas/código-fonte por conta própria.
2. Use codewiki (ou busca de código-fonte) para confirmar: framework, biblioteca de componentes, rotas → arquivos de página, trechos de template chave; se necessário, verifique a frescura do índice e calibre com o DOM online.
3. Prioritariamente use a biblioteca de componentes e padrões reais do repositório alvo; novos controles seguem o tipo/tamanho/arranjo existente na página. Mesma biblioteca de componentes não significa reconstituição — esqueleto, conjunto de colunas/largura de colunas, colunas congeladas, estrutura de células, layout da coluna de ações, nomes de classe personalizados devem ser comparados com o DOM/código-fonte online.
4. Se houver skill de padrões da equipe, siga-o; caso contrário, siga o repositório alvo e a documentação.
5. Se pixel-level ou pesquisa for insuficiente: Abra a página online para capturar o modo de montagem, nomes de classe dos componentes, largura de colunas da tabela/colunas congeladas, estrutura da coluna de ações, estilos computados personalizados.
6. O resultado ainda é um HTML de página única; se puder, importe o mesmo framework/biblioteca de componentes via CDN. Se não for possível reconstituir a página inteira, escolha livremente uma biblioteca de componentes comum para criar o protótipo interativo e indique no relatório de entrega "Motivo da não reconstituição".
7. Publicação: Se houver um endereço estático de intranet, faça upload prioritariamente; caso contrário, após obter autorização GitHub do usuário, use deploy_github.sh para publicar no repositório pessoal.

Armadilhas frequentes: Não defina min-width excessivo no contêiner externo que force a tabela a esticar (isso perde a rolagem interna e colunas fixed); use position:fixed na barra de menu unificada do topo para evitar que a barra quebre ao rolar horizontalmente em páginas largas.

Múltiplas Páginas / Múltiplas Pontas e Interligação de Dados

1. Primeiro, crie uma matriz: Ponta/Sistema → Página → Estado chave → Dados upstream/downstream; stacks técnicas diferentes em arquivos separados, não force a mesclagem.
2. Menu unificado: Nomear como "Ponta · Página", destacar a página atual; o menu não recebe anotações de alteração.
3. Implantar no mesmo diretório de mesma origem para garantir que localStorage seja compartilhado.
4. Chave de estado compartilhado: proto-note:<requirement-slug>:state:v1; após ler/escrever, disparar eventos na mesma página, ouvir storage entre abas.
5. URL leva apenas o ID de negócio; o corpo está no estado compartilhado. Se não for mesma origem, priorize alterar para mesma origem; caso contrário, use postMessage validando origin.
6. Fixtures embutidas + "Redefinir dados de demonstração"; estados upstream/downstream e erros reproduzíveis.

Fluxo de Trabalho

0. Passo 0: Reconstituição da stack técnica.
1. Extrair da PRD a lista de alterações, matriz de ponta/página, ramos de entrada e relações de dados entre páginas → veja references/changeset-schema.md.
2. Obter blockId do SDD, escrever em cada sdd.
3. Criar protótipos por ponta; múltiplas pontas com menu e estado compartilhado e verificar interligação.
4. Integrar a camada de anotação:
   • Adicionar data-diff-page ao contêiner; adicionar id aos pontos de aterrissagem; implementar DIFF_HOOKS.locate / setDemoState.
   • Migrar abas de revisão para meta.demoControls.
   • Escrever ramos em examples (consistentes com fixtures).
   • Antes de </body>, inline DIFF_CHANGESET e então copiar a versão mais recente de assets/diff-annotator.js (não usar cópia desatualizada).
5. Deploy e Auto-verificação:

   • Priorizar intranet: Se houver hospedagem estática interna existente, faça upload; se a chave do objeto não sobrescrever, use novo caminho (-v2 etc.), baseado na URL retornada + md5.

   • Fallback GitHub Pages: Quando intranet não disponível, publique no repositório pessoal. Primeiro gh auth status; se sem permissão, comunique-se e complete gh auth login. É proibido fazer push para repositório privado sem autorização:

     bash ~/.cursor/skills/proto-note/scripts/deploy_github.sh <slug> ./index.html
     

Lista de Auto-verificação

• Se possível reconstituir, já usou biblioteca de componentes/padrões reais online; se não, já registrou o motivo e usou fallback de escolha livre
• Publicação priorizou intranet; quando intranet não disponível, já autorizou e publicou no GitHub pessoal
• Comparou tela por tela com o online (se houver página online: largura de colunas, colunas congeladas, coluna de ações, paginação, barra de topo)
• Inicialmente sem âncoras/linhas; módulos não marcados; módulos novos visíveis por padrão para visitantes antigos
• Marcar módulo exibe apenas o cartão/âncora/linha correspondente, com localização automática; alterações em pop-ups abrem automaticamente a janela e a linha fica acima do pop-up
• Rolagem sem desvio de âncoras; sem linhas normalmente; apenas uma linha ao fixar/hover; estado fixo não é tomado pelo hover
• Com a barra de anotações aberta, é possível rolar horizontalmente para ver todo o lado direito; posição horizontal não é revertida por atualização do DOM; pop-up rola com a página subjacente horizontal e verticalmente
• target:null sem âncora, cartão em "Fluxos e Cadeias" e no final; "Antes" sempre estado atual online, sem omissões
• Link profundo SDD no cartão de anotação pode ser aberto e localizar a seção correspondente
• Estado de demonstração apenas na barra de anotações; exemplos reproduzíveis; itens baixáveis com formato correto
• Menu de múltiplas pontas acessível; leitura/escrita/atualização/entre abas/redefinição consistentes entre protótipos
• Ao recolher a barra de anotações, fica limpo; interações de negócio não são afetadas

Referência

• README.md deste repositório (capturas de tela, live demo, explicação do plano padrão)
• Live demo: https://pessimistcamellia.github.io/non-ecommerce-thirdparty-order-prototype/admin-upload.html