pessimistcamellia/proto-note

Capa de anotación de cambios en prototipos (proto-note)

Superpone sobre prototipos HTML de una sola página una «guía de cambios para la perspectiva de desarrollo»: panel lateral fijo oscuro de anotaciones (casillas de módulo + tarjetas de anotación) ↔ anclajes numerados en la página + líneas de conexión en canvas; localización bidireccional al pasar el ratón o hacer clic; las tarjetas de anotación incluyen enlaces profundos SDD.

Instalación y directorio

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

# O dentro del proyecto
git clone https://github.com/pessimistcamellia/proto-note.git .cursor/skills/proto-note

También se puede copiar todo el directorio a la ruta anterior. Estructura del directorio:

proto-note/
├── SKILL.md
├── assets/diff-annotator.js      # Motor de anotación (se incrusta en línea en el prototipo, no modificar la lógica)
├── references/changeset-schema.md
├── docs/screenshots/             # Capturas de pantalla del README
└── scripts/deploy_github.sh      # Despliegue alternativo en GitHub Pages

Dependencias del entorno

Capacidad	Herramienta	Si falta
Pila tecnológica / localización de código fuente	codewiki MCP (o equivalente para búsqueda de código)	Usar URL en línea + repositorio fuente + DOM del navegador para reconstruir
Enlace profundo SDD	lark-cli (Feishu)	Rellenar manualmente la URL del documento y el blockId del capítulo; si no es Feishu, enlazar al ancla del capítulo correspondiente
Calibración a nivel de píxel	DevTools del navegador / chrome-devtools MCP	Abrir manualmente la página en línea para comparar
Despliegue	Alojamiento estático en intranet (prioritario)	GitHub Pages personal (deploy_github.sh, requiere autorización gh)

Si el equipo tiene otro skill de normas de frontend (como lista blanca de selección de librerías, uso de componentes), leerlo según sea necesario antes de la creación; si no, basarse en el código fuente del repositorio de destino y la documentación del equipo.

Plan por defecto: librería de componentes y prioridad de publicación

Ejecutar en orden de prioridad; solo pasar al siguiente nivel si el anterior no está disponible; el último nivel es el plan de respaldo por defecto:

1. Librería de componentes / normas (prioritario) : usar la librería de componentes real que utiliza el sistema en línea de destino y las normas de componentes (comparar con el código fuente / DOM / skill de normas del equipo), prohibido cambiar de librería sin justificación.
2. Dirección de publicación (prioritario) : si existe un alojamiento estático en la intranet (o una dirección de intranet acordada por el equipo), publicar allí preferentemente.
3. Plan de respaldo por defecto : si no se puede obtener la librería de componentes / normas real, o no se puede usar debido a permisos, red, intranet inaccesible, etc. → los componentes se pueden elegir según un plan general (manteniendo el prototipo HTML interactivo de una sola página); publicar en el repositorio personal de GitHub del usuario (Pages) . Antes del despliegue, confirmar la autorización gh; si no está autorizado, comunicarse con el usuario primero; prohibido enviar a un repositorio privado sin consentimiento.

Reglas de producto

1. Tres niveles de cambio + tipo : página / módulo / campo; tipos: nuevo, texto, enumeración/dimensión, lógica, flujo, eliminación; prohibido etiquetar genéricamente como «nuevo».
2. Oculto por defecto, casilla de módulo : al abrir, no mostrar anotaciones; marcar por page::module; el estado se guarda en localStorage. La clave faltante de un módulo nuevo por defecto es true (visible) , prohibido heredar la ocultación con un interruptor que haya estado apagado; el estado sucio se limpia actualizando la versión LS_KEY.
3. Solo vincular SDD, no mostrar PRD : las tarjetas de anotación usan URL del documento SDD#blockId.
4. Información concisa : el panel de anotaciones no tiene número de versión / línea base / instrucciones de uso; desc solo escribe la conclusión.
5. Toda acción debe ser efectiva : al marcar un módulo, se cambia la vista + desplazamiento + localización con pulso.
6. Estado de revisión solo en el panel de anotaciones : los estados normal / vacío / error, etc., se colocan en demoControls; las pestañas de negocio real permanecen en la página de negocio.
7. Las ramas de entrada deben dar ejemplos reproducibles : examples deben coincidir con los fixtures; prohibido usar valores ficticios de marcador de posición.
8. El panel de anotaciones no bloquea el contenido : no comprime el diseño de negocio; usa un spacer para extender scrollWidth, desplazamiento horizontal para ver todo el lado derecho. Prohibido solo añadir padding-right:360px al body o modificar el ancho raíz de negocio.
9. Librería de componentes y normas: priorizar la versión real en línea : si se puede restaurar, debe restaurarse (ver el primer nivel del «Plan por defecto»). El mismo nombre de librería de componentes no equivale a restauración: la estructura esquelética, columnas/ancho de columnas, columnas congeladas, estructura de celdas, diseño de columna de acciones, nombres de clase personalizados y estilos clave deben compararse con el DOM / código fuente en línea; antes de la entrega, comparar capturas de pantalla pantalla por pantalla. Solo cuando no sea posible obtener la librería de componentes / normas real, se permite el plan de respaldo con componentes genéricos.
10. Publicar primero en intranet, luego en GitHub personal : si hay dirección de intranet, usarla primero; si no está disponible, publicar en GitHub Pages personal (ver el segundo y tercer nivel del «Plan por defecto»).
11. «Antes» = estado actual en línea : para algo nuevo, escribir «No existe esta página / módulo / función / campo»; prohibido escribir como diferencia respecto a la versión anterior del demo; no dejar de marcar puntos nuevos en línea.
12. Sin destino UI, sin línea de conexión : para flujos/cadenas puramente de proceso, target: null, sin ancla; la tarjeta se coloca en «Flujos y cadenas · No visible en la página» y al final de los cambios.
13. Cambios dentro de ventanas emergentes : al hacer clic en la tarjeta de anotación, debe pasar por DIFF_HOOKS.locate para abrir la ventana emergente y luego conectar la línea; el ancla / línea debe tener un z-index superior al de la ventana emergente (el motor usa el rango 9000).
14. Las ventanas emergentes se desplazan con el scroll horizontal y vertical de la página : cuando el panel de anotaciones está abierto, el contenedor de la ventana emergente se traslada con (-scrollX,-scrollY) (el motor ya lo maneja); prohibido bloquear el scroll para evitarlo.
15. Los objetos descargables deben tener el formato real : las plantillas/recibos deben tener el mismo formato y estructura que los de negocio real (por ejemplo, si tiene dos hojas, debe ser un .xlsx real), prohibido usar CSV para suplantar.
16. Crear por separado para cada extremo y vincularlos : backoffice, frontend C, etc., se dividen en HTML por límite de sistema; un menú unificado etiqueta «Extremo · Página»; si hay datos entre páginas, simular escritura/lectura/inicio/parada/excepción.
17. Las tarjetas de anotación deben poder saltar a SDD : si hay SDD, cada cambio (o punto funcional) debe configurar sdd.section + blockId, la tarjeta renderiza un enlace profundo; al hacer clic, debe abrir el capítulo correspondiente, no solo escribir el nombre del capítulo.

Normas de capa de visualización (ya integradas en el motor, no revertir)

• Panel derecho de anotaciones: azul marino oscuro, ancho 360px, plegable a un icono flotante de entrada.
• Desplazamiento horizontal: usar document.body.scrollWidth para medir el ancho de negocio (el spacer es absolute, no entra en ese valor); no ocultar el spacer antes de medir. Restaurar el scroll con behavior:"instant" para evitar conflictos con scroll-behavior:smooth.
• Anclajes: coordenadas del documento position:absolute, fijados en la esquina superior izquierda del destino; prohibido fixed + seguimiento por fotogramas; ocultar con elementFromPoint si hay solapamiento.
• Líneas de conexión: normalmente sin líneas; al pasar el ratón o fijar, dibujar solo una línea; el estado fijo tiene prioridad sobre el estado hover; el punto de inicio toma el rect en tiempo real.
• Tarjeta de anotación: número + título + tipo·nivel + conclusión + antes/después + SDD; puede contener examples.
• Área de demostración: control segmentado en la parte superior del panel de anotaciones → DIFF_HOOKS.setDemoState.

Restauración de la pila tecnológica (Paso 0)

Ejecutar según el «Plan por defecto»: si se puede restaurar, restaurar; si no, registrar el motivo y luego usar el plan de respaldo de selección libre.

1. Si el usuario no proporciona URL en línea → recordarle primero; si aún así no la proporciona, buscar el sistema/ruta/código fuente por cuenta propia.
2. Usar codewiki (o búsqueda de código fuente) para confirmar: framework, librería de componentes, ruta → archivo de página, fragmentos de plantilla clave; si es necesario, verificar la frescura del índice y calibrar con el DOM en línea.
3. Prioritariamente usar la librería de componentes y normas reales del repositorio de destino; los nuevos controles deben seguir el tipo/tamaño/disposición existente en esa página. El mismo nombre de librería de componentes no equivale a restauración: la estructura esquelética, columnas/ancho de columnas, columnas congeladas, estructura de celdas, diseño de columna de acciones, nombres de clase personalizados deben compararse con el DOM / código fuente en línea.
4. Si existe un skill de normas del equipo, seguirlo; si no, basarse en el repositorio de destino y la documentación.
5. Si la inspección a nivel de píxel o la búsqueda son insuficientes: abrir la página en línea para capturar el método de montaje, nombres de clase de componentes, ancho de columnas de tabla / columnas congeladas, estructura de columna de acciones, estilos calculados personalizados.
6. El resultado sigue siendo un HTML de una sola página; si es posible, importar el mismo framework/librería de componentes mediante CDN. Si no se puede restaurar toda la página, usar libremente una librería de componentes común para completar el prototipo interactivo e indicar en la nota de entrega «Razón por la que no se restauró».
7. Publicar : si hay una dirección estática de intranet, subir allí primero; de lo contrario, después de obtener la autorización de GitHub del usuario, usar deploy_github.sh para publicar en su repositorio personal.

Errores comunes : no establecer un min-width demasiado ancho en el contenedor externo que ahogue la tabla (perdería el scroll horizontal interno y las columnas fixed); la barra superior del menú unificado debe usar position:fixed para evitar que se rompa al hacer scroll horizontal en páginas anchas.

Múltiples páginas / múltiples extremos y vinculación de datos

1. Primero, crear una matriz: extremo/sistema → página → estados clave → datos ascendentes/descendentes; diferentes pilas tecnológicas se separan en archivos, no se fusionan forzosamente.
2. Menú unificado: nombrado como «Extremo · Página», resaltar la página actual; el menú no lleva anotaciones de cambios.
3. Desplegar en el mismo origen y directorio para garantizar la compartición de localStorage.
4. Clave de estado compartido: proto-note:<requirement-slug>:state:v1; después de leer/escribir, disparar eventos en la misma página; en pestañas cruzadas, escuchar storage.
5. La URL solo lleva el ID de negocio; el contenido real está en el estado compartido. Si no es el mismo origen, priorizar cambiar al mismo origen; de lo contrario, usar postMessage y verificar el origin.
6. Incluir fixture integrado + «Restablecer datos de demostración»; los estados ascendentes/descendentes y las excepciones deben ser reproducibles.

Flujo de trabajo

0. Paso 0: Restauración de la pila tecnológica.
1. Del PRD extraer la lista de cambios, la matriz extremo/página, las ramas de entrada y las relaciones de datos entre páginas → ver references/changeset-schema.md.
2. Obtener el blockId de SDD e insertarlo en cada sdd.
3. Crear prototipos por extremo; para múltiples extremos, configurar menú y estado compartido, y verificar la vinculación.
4. Integrar la capa de anotación:
   • Añadir data-diff-page al contenedor; completar id en los puntos de destino; implementar DIFF_HOOKS.locate / setDemoState.
   • Mover las pestañas de revisión a meta.demoControls.
   • Escribir las ramas en examples (coincidiendo con los fixtures).
   • Antes de </body>, incrustar en línea DIFF_CHANGESET y luego copiar el archivo más reciente completo assets/diff-annotator.js (no reutilizar copias obsoletas).
5. Despliegue y autocomprobación:

   • Priorizar intranet : si hay alojamiento estático en la intranet, subir allí; si la clave del objeto no se sobrescribe, usar una nueva ruta (como -v2), tomando como referencia la URL devuelta + md5.

   • Plan de respaldo GitHub Pages : cuando la intranet no esté disponible, publicar en el repositorio personal. Primero ejecutar gh auth status; si no hay permisos, comunicarse y completar gh auth login; prohibido enviar a un repositorio privado sin autorización:

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

Lista de autocomprobación

• Cuando se puede restaurar, se ha usado la librería de componentes / normas real en línea; cuando no se puede restaurar, se ha indicado el motivo y se ha usado el plan de respaldo de selección libre
• La publicación prioriza la intranet; cuando la intranet no está disponible, se ha publicado en GitHub personal después de la autorización
• Se ha comparado pantalla por pantalla con la versión en línea (si hay página en línea: ancho de columna, columnas congeladas, columna de acciones, paginación, barra superior)
• Inicialmente sin anclajes / líneas de conexión; módulos sin marcar; los módulos nuevos son visibles por defecto para visitantes antiguos
• Al marcar un módulo, solo se muestran las tarjetas / anclajes / líneas correspondientes, y se localiza automáticamente; los cambios dentro de ventanas emergentes se abren automáticamente y la línea está por encima de la ventana emergente
• El desplazamiento no provoca deriva de los anclajes; normalmente sin líneas; al fijar/pasar el ratón, solo una línea; el estado fijo no es reemplazado por el hover
• Con el panel de anotaciones abierto, se puede desplazar horizontalmente para ver todo el lado derecho; la posición horizontal no retrocede por actualizaciones del DOM; las ventanas emergentes se desplazan con el scroll horizontal y vertical de la página subyacente
• target:null sin ancla, las tarjetas en «Flujos y cadenas» y al final; «Antes» es siempre el estado actual en línea, sin omisiones de marcado
• Los enlaces profundos SDD en las tarjetas de anotación se abren y localizan en el capítulo correspondiente
• El estado de demostración solo en el panel de anotaciones; examples son reproducibles; los objetos descargables tienen el formato correcto
• El menú de múltiples extremos es accesible; la lectura/escritura/actualización/pestaña cruzada/restablecimiento entre prototipos es coherente
• Al plegar el panel de anotaciones, queda limpio; la interacción de negocio no se ve afectada

Referencias

• README.md de este repositorio (capturas de pantalla, Live demo, descripción del plan por defecto)
• Live demo: https://pessimistcamellia.github.io/non-ecommerce-thirdparty-order-prototype/admin-upload.html