invoicehn 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 633195e813e47b48266e5c5dd70026b7fb22f3a3c839d53a9c79e37cb4861cd9
-  data.tar.gz: 4970c4b593fb55f38ee90819b063444664bb07e0a00bc8b039f0e1b4d6c340c3
+  metadata.gz: 97a71a1ec9c4f50865c877824d8e0383eadd0586aafb647e01bc3d42cc160a7c
+  data.tar.gz: 5f2c1498b2ed86ab1845473badf845aae69ec3061de66c4e9328855e7d6e97ae
 SHA512:
-  metadata.gz: fbcecd6f82d560df0dd182e1cd0d57439a3c2c4f4de2cf5ac2980e838ad2746831d5775d54c894a2e474113f67ed7096610cb1f1a184aa2a0512851deab6fb40
-  data.tar.gz: 52a36d88796c7699fd29d193df20a16fb85651da782963bdd243e38557b6a73221478ce25b711083fdea4fa19d3535cfbfbe4d53090670d387dba70435f20a9d
+  metadata.gz: 94039271cdd437cc609cada52de779c80aa55259f7f58cfd6d6247d34832002df9a07f4443c3cdf3ba6d9c2e46824628e9ccb5a9e917acdcdcf87a569ade6f0d
+  data.tar.gz: 3d96cadbcd9ddbd4463a904e44e134cb8649303de6f1aaa7d09d8f00288879828ab5a33427f89083c18afcc660c2a7cc62bec75d25990a39765bed5bbb72ac6b

data/CHANGELOG.md

@@ -5,6 +5,118 @@ Este proyecto sigue [Versionado Semántico](https://semver.org/lang/es/).
 
 ## [Sin publicar]
 
+## [0.2.0] — 2026-10-10
+
+Notas de Crédito y de Débito, la tabla de códigos reformada, y correcciones
+que una aplicación anfitriona con su propia base de datos necesita. Las líneas
+citadas son de `doc/fuentes/acuerdo_481_2017_consolidado.txt` (texto
+consolidado) y `doc/fuentes/acuerdo_609_2017_gaceta_34457_ocr.txt`.
+
+### Corregido
+
+- **Códigos de tipo de documento (Art. 10 num. 7 lit. c y sus pares).** La 0.1.0
+  traía la tabla del texto original de 2017. El Art. 1 del Acuerdo 609-2017
+  (*La Gaceta* 34,457) reescribió el literal c) de los Arts. 15, 17, 20, 23, 25,
+  27, 29 y 33 (OCR del 609, líneas 209, 231, 273, 320, 359, 378, 404 y 438). La
+  tabla vigente: 01 Factura (l. 626), 04 Recibo por Honorarios Profesionales
+  (l. 1039, no reformado), 05 Comprobante de Retención (l. 1750), 06 Nota de
+  Crédito (l. 1345), 07 Nota de Débito (l. 1438), 08 Guía de Remisión (l. 1535),
+  09 Ticket (l. 969), 10 Factura Prevalorada (l. 889), 11 Boleta de Compra
+  (l. 1122), 12 Constancia de Donación (l. 1259). 02 y 03 quedan sin asignar y se
+  rechazan.
+- **Correlativo trabado.** Si el libro contable fallaba después de guardar el
+  documento, el documento quedaba en el store y el contador no avanzaba: toda
+  emisión posterior de ese identificador fallaba con `ImmutableDocument`. Ahora
+  el documento se borra si el asiento falla, dentro del bloque de `allocate`.
+- **Anulación trabada.** Si el libro contable rechazaba el asiento de
+  `:anulacion`, el store quedaba con la forma ANULADA sin asiento, y reintentar
+  fallaba con «ya está anulada». Ahora `Issuance#annul` vuelve a guardar la
+  forma emitida (borra la anulada y guarda la original) si el asiento falla.
+- **Fechas en servidores UTC.** Honduras es UTC-6; `Date.today` en un servidor UTC
+  estampaba la fecha de mañana desde las 18:00. Todas las fechas por defecto
+  salen de un reloj configurable (ver *Añadido*).
+- **`invoicehn check` / `Issuance#health`** informaba "listo" con una
+  autorización de rango agotado y documentos restantes negativos.
+  `JsonStore#active_authorization` con `next_sequence:` ya no recurre a una
+  autorización que no cubre ese número, y `remaining` nunca es negativo.
+
+### Añadido
+
+- **Nota de Crédito (tipo 06, Arts. 25-26, l. 1300-1391) y Nota de Débito
+  (tipo 07, Arts. 27-28, l. 1393-1496).** `Invoice` acepta `reference:`
+  (`Invoicehn::DocumentReference` con CAI, correlativo y fecha de emisión del
+  comprobante, Arts. 26 y 28 num. 3) y `motivo:` (num. 4); el tipo lo declara
+  el correlativo. `Issuance#issue` acepta `reference:` y `motivo:`, y hay
+  atajos `issue_credit_note` / `issue_debit_note`. Cada identificador lleva su
+  propio contador y su propia autorización (Art. 59, l. 2259).
+- **Reglas del validador para las notas**: referencia obligatoria; la de la NC
+  debe ser un Comprobante Fiscal (Art. 4 num. 32 y Art. 6) y la de la ND puede
+  ser "el Comprobante Fiscal o el documento" (Art. 28 num. 3 lit. b); motivo
+  obligatorio; nombre y RTN del adquirente (num. 1-2, sin alternativa de
+  CONSUMIDOR FINAL); moneda nacional (Art. 26 num. 9, Art. 28 num. 8); la
+  referencia no puede ser posterior a la nota. Las reglas propias de la
+  Factura (umbral de L 10,000.00, aviso de ventas mixtas, documentos del
+  exonerado del Art. 10 num. 8, moneda extranjera del Art. 11) se aplican sólo
+  a la Factura. No se encontró en las fuentes un monto máximo para las notas y
+  no se impone ninguno.
+- **Renderers Text y PDF**: título "NOTA DE CRÉDITO" / "NOTA DE DÉBITO" (Arts. 25
+  y 27 num. 2), bloque del documento de referencia y motivo, leyenda "Copia:
+  Obligado Tributario" (Arts. 25 y 27 num. 7) y, en la NC, campos en blanco para
+  nombre, identidad y firma de quien la recibe (Art. 26 num. 7).
+- **Reloj configurable**: `Invoicehn.configure { |c| c.today = -> { Date.current } }`
+  e `Invoicehn.today`. Por defecto `Date.today`, como antes. Una prueba recorre
+  `lib/` y falla si alguien vuelve a leer `Date.today` directamente.
+- **Contrato del store/sequence/ledger** documentado en el README, con
+  `require "invoicehn/testing"` (verificaciones que lanzan
+  `Invoicehn::Testing::ContractError`), `require "invoicehn/test_support/contracts"`
+  (módulos de minitest `StoreContract`, `SequenceContract`, `LedgerContract`,
+  `IssuanceContract`) y `require "invoicehn/test_support/memory"` (adaptadores
+  en memoria de referencia).
+- `Correlative::COMPROBANTES_FISCALES` (Art. 6) y `DOCUMENTOS_COMPLEMENTARIOS`
+  (Art. 7); `Correlative#credit_note?`, `#debit_note?`, `#note?`,
+  `#comprobante_fiscal?`; `Invoice#document_type`, `#document_name`,
+  `#factura?`, `#credit_note?`, `#debit_note?`, `#note?`.
+- `invoicehn issue -f` acepta `reference` y `motivo` en el JSON.
+- Pruebas del PDF leyéndolo de vuelta con `pdf-reader` (dependencia sólo de
+  desarrollo).
+
+### Cambiado — revisar al actualizar
+
+- **El store debe responder a `delete_document(document)`** (y `Issuance` usa
+  ahora `exists?`). Un store propio escrito para la 0.1.0 debe agregarlos.
+- `Issuance.new` ya no construye `Config` cuando se le inyectan store, sequence
+  y ledger: no toca `~/.invoicehn`.
+- **Autorizaciones registradas con la tabla vieja**: una autorización con
+  código 02 o 03 ya no se carga; una con 07 u 08 cambia de significado (07 es
+  ahora Nota de Débito, 08 Guía de Remisión). La 0.1.0 sólo emitía 01, así que
+  sólo afecta autorizaciones registradas y no usadas; revise
+  `authorizations.json`.
+- La exportación CSV agrega al final las columnas `tipo`,
+  `documento_referencia` y `motivo`; el JSON del documento agrega
+  `document_type` (y `reference`/`motivo` en las notas); el libro JSONL agrega
+  `document_type` y `reference`.
+- Mensajes: "no existe el documento …" en lugar de "no existe la factura …".
+
+### Pendiente de criterio (no resuelto por las fuentes)
+
+- Los Arts. 26 y 28 exigen RTN del adquirente sin alternativa: la gema rechaza
+  notas a consumidores finales sin RTN. Si el SAR admite otra práctica, es una
+  decisión del obligado tributario.
+- El Art. 17 conserva la frase "El Ticket tendrá como código 03" (l. 988)
+  aunque el 609-2017 reformó su num. 4 a "09=Ticket"; la tabla sigue el
+  numeral reformado.
+- Las notas se rechazan en moneda extranjera: el permiso del párrafo final del
+  Art. 11 habla sólo de "facturas" y los Arts. 26 num. 9 y 28 num. 8 piden la
+  Moneda Nacional Lempira. Una factura en dólares se ajustaría con una nota en
+  lempiras.
+- La referencia de la Nota de Crédito debe ser un Comprobante Fiscal del Art. 6
+  (01, 04, 09, 10, 11, 12), no sólo una Factura; la de la Nota de Débito acepta
+  cualquier tipo reconocido por el "o el documento" del Art. 28 num. 3 lit. b.
+- Ningún artículo (4 num. 31-32, 25-28) fija un monto máximo para las notas.
+- `Issuance#annul` todavía guarda la forma anulada antes del asiento contable:
+  si el libro falla, el documento queda anulado sin asiento. Queda para una
+  versión siguiente.
+
 ## [0.1.0] — 2026-08-28
 
 Primera versión. Emisión de Facturas (Comprobante Fiscal tipo 01) conforme al
@@ -55,5 +167,6 @@ Reglamento del Régimen de Facturación, Acuerdo 481-2017 y sus reformas
 - La leyenda "La factura es beneficio de todos, exíjala" no está exigida por
   ninguna norma; se admite como texto opcional.
 
-[Sin publicar]: https://github.com/JorgePadilla/invoicehn/compare/v0.1.0...HEAD
+[Sin publicar]: https://github.com/JorgePadilla/invoicehn/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/JorgePadilla/invoicehn/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/JorgePadilla/invoicehn/releases/tag/v0.1.0

data/README.md

@@ -5,7 +5,8 @@
 
 Facturación para Honduras conforme al **Reglamento del Régimen de Facturación,
 Otros Documentos Fiscales y Registro Fiscal de Imprentas** (Acuerdo No. 481-2017
-y sus reformas). Biblioteca Ruby más una interfaz de terminal.
+y sus reformas). Emite **Facturas** (tipo 01), **Notas de Crédito** (tipo 06) y
+**Notas de Débito** (tipo 07). Biblioteca Ruby más una interfaz de terminal.
 
 ```
 invoicehn setup      # datos del emisor (Art. 10 num. 1)
@@ -22,7 +23,8 @@ Esto es lo primero que debe quedar claro, porque el software sólo cubre una mit
 de lo que la ley exige.
 
 **Cubre el contenido del documento.** Todos los campos que exigen los Artículos
-10 (requisitos del formato) y 11 (requisitos al momento de la emisión): el
+10 (requisitos del formato) y 11 (requisitos al momento de la emisión) para la
+Factura, y los Artículos 25-26 y 27-28 para las Notas de Crédito y de Débito: el
 correlativo de 16 dígitos, el control del CAI, del rango autorizado y de la fecha
 límite de emisión, la discriminación del ISV por tarifa, los descuentos, el total
 en números y letras, y el redondeo estatutario.
@@ -88,6 +90,10 @@ invoicehn auth add --cai "ABCD12-345678-9ABCDE-F01234-567890-AB" \
   --limit "2027-06-30"
 ```
 
+El tercer grupo del correlativo es el **tipo de documento**, según la tabla
+vigente tras el Acuerdo 609-2017 (ver *Los códigos de tipo de documento* más
+abajo): `01` Factura, `06` Nota de Crédito, `07` Nota de Débito.
+
 Un mismo identificador acumula autorizaciones con el tiempo: cuando un rango se
 agota y el SAR concede otro que continúa la numeración, se registra el nuevo sin
 borrar el anterior. El asignador elige la autorización vigente que cubra el
@@ -125,6 +131,39 @@ O desde un archivo, para integrarlo con otro sistema:
 invoicehn issue -f venta.json
 ```
 
+### Notas de Crédito y de Débito desde un archivo
+
+Cada tipo de documento lleva su propio identificador, su propio contador y su
+propia autorización del SAR (Art. 59: *"La autorización será por punto de
+emisión y por tipo de documento"*). Registre primero el CAI de las notas:
+
+```
+invoicehn auth add --cai "..." --from "000-001-06-00000001" \
+  --to "000-001-06-00000500" --limit "2027-06-30"
+```
+
+El archivo es el de una venta más `reference` (el correlativo de la factura a
+la que se aplica) y `motivo`:
+
+```json
+{
+  "customer": { "kind": "taxpayer", "name": "Distribuidora del Norte, S.A.",
+                "rtn": "05019005123456" },
+  "items": [{ "description": "Devolución: cemento gris bolsa 42.5 kg",
+              "quantity": 2, "unit_price": "235.00", "treatment": "gravado_15" }],
+  "reference": "000-001-01-00000001",
+  "motivo": "Devolución de 2 bolsas dañadas"
+}
+```
+
+```
+invoicehn issue -f nota.json --identifier 000-001-06   # Nota de Crédito
+invoicehn issue -f nota.json --identifier 000-001-07   # Nota de Débito
+```
+
+Si la factura se emitió fuera de esta instalación, `reference` puede ser un
+objeto con sus tres datos: `{"correlative": "...", "cai": "...", "issue_date": "AAAA-MM-DD"}`.
+
 ### 4. Consultar, anular, exportar
 
 ```
@@ -196,6 +235,76 @@ issuance = Invoicehn::Issuance.new
 factura = issuance.issue(customer: cliente, line_items: lineas)
 ```
 
+### Notas de Crédito y de Débito
+
+```ruby
+# Nota de Crédito (tipo 06) — devoluciones, descuentos posteriores, anulación
+# de operaciones (Art. 4 num. 32).
+nc = issuance.issue_credit_note(
+  reference: "000-001-01-00000042",           # factura en el store: CAI y fecha se copian
+  motivo: "Devolución de 2 bolsas dañadas",   # Art. 26 num. 4
+  customer: cliente,                          # con RTN: Art. 26 num. 1-2
+  line_items: lineas_devueltas
+)
+
+# Nota de Débito (tipo 07) — ajustes a cargo del adquirente (Art. 4 num. 31).
+nd = issuance.issue_debit_note(
+  reference: Invoicehn::DocumentReference.new( # documento emitido fuera del store
+    correlative: "000-001-01-00009999",
+    cai: "ABCD12-345678-9ABCDE-F01234-567890-AB",
+    issue_date: Date.new(2026, 9, 1)
+  ),
+  motivo: "Flete adicional",
+  customer: cliente,
+  line_items: lineas
+)
+```
+
+Las firmas exactas:
+
+```ruby
+Invoicehn::Issuance#issue(customer:, line_items:, identifier: "000-001-01",
+                          currency: "HNL", exchange_rate: nil, notes: nil,
+                          issue_date: Invoicehn.today, reference: nil, motivo: nil)
+Invoicehn::Issuance#issue_credit_note(reference:, motivo:, customer:, line_items:,
+                                      identifier: "000-001-06", **opciones_de_issue)
+Invoicehn::Issuance#issue_debit_note(reference:, motivo:, customer:, line_items:,
+                                     identifier: "000-001-07", **opciones_de_issue)
+Invoicehn::Issuance#annul(correlative, reason:, on: Invoicehn.today)  # Factura o nota
+Invoicehn::DocumentReference.new(correlative:, cai:, issue_date:)
+```
+
+El **tipo de documento lo decide el identificador**: `NNN-NNN-01` Factura,
+`NNN-NNN-06` Nota de Crédito, `NNN-NNN-07` Nota de Débito. `issue` con un
+identificador `-06`/`-07` y `reference:`/`motivo:` es equivalente a los dos
+atajos. `reference:` acepta:
+
+- un correlativo (`String` o `Correlative`) de un documento que el store tiene:
+  se busca y se copian su CAI y su fecha de emisión;
+- un `DocumentReference` con los tres datos (Arts. 26 y 28 num. 3), para un
+  documento emitido fuera del store. Si el store sí lo tiene, los datos se
+  cotejan y una discrepancia se rechaza.
+
+Cuando el original está en el store, además se rechaza la nota si el original
+está ANULADO o si su adquirente tiene otro RTN. Esas dos verificaciones son de
+coherencia, no texto del Reglamento.
+
+### El reloj: la fecha de Honduras, no la del servidor
+
+Honduras está en UTC-6 todo el año. Un servidor en UTC que leyera `Date.today`
+estamparía, desde las 18:00 de Tegucigalpa, la fecha de **mañana** como fecha de
+emisión, y daría por vencida una autorización horas antes de su fecha límite
+(Art. 62). Todas las fechas por defecto de la gema (emisión, anulación,
+validación, `health`, vigencia de la autorización) salen de `Invoicehn.today`:
+
+```ruby
+# config/initializers/invoicehn.rb, con config.time_zone = "America/Tegucigalpa"
+Invoicehn.configure { |c| c.today = -> { Date.current } }
+```
+
+Sin configurar, el reloj es `Date.today` (la zona del proceso), como en la
+0.1.0. El reloj debe devolver un `Date`; un `Time` o un `DateTime` se rechazan.
+
 ---
 
 ## Decisiones que conviene conocer
@@ -255,13 +364,61 @@ RTN reales. Se valida longitud y dígitos, nada más.
 El asignador se lleva por la terna (establecimiento, punto de emisión, tipo de
 documento) — el *identificador del documento* del Art. 10 num. 7 — y trabaja bajo
 un candado exclusivo de archivo, de modo que dos procesos simultáneos no pueden
-repetir ni omitir un número. La asignación y el guardado ocurren dentro del mismo
-candado: si el guardado falla, el correlativo no se consume.
+repetir ni omitir un número. La asignación, el guardado y el asiento contable
+ocurren dentro del mismo candado y son todo o nada: si el guardado falla, el
+correlativo no se consume; si el libro contable rechaza el asiento, el documento
+recién guardado se borra antes de que avance el contador. (La 0.1.0 dejaba el
+documento en disco y el contador atrás, y toda emisión posterior fallaba.)
 
 Un documento emitido es inmutable. La única corrección es la anulación
 (Art. 41), que marca el registro con la leyenda **ANULADA** y **conserva el
 correlativo consumido**.
 
+### Los códigos de tipo de documento son los reformados
+
+El Acuerdo 609-2017 (*La Gaceta* 34,457) reescribió el literal c) de los
+artículos de cada documento. La tabla vigente, según el texto consolidado:
+
+| Código | Documento | Artículo |
+|---|---|---|
+| 01 | Factura | 10 num. 7 lit. c |
+| 04 | Recibo por Honorarios Profesionales | 18 num. 7 lit. c (no reformado) |
+| 05 | Comprobante de Retención | 33 num. 5 lit. c |
+| 06 | **Nota de Crédito** | 25 num. 5 lit. c |
+| 07 | **Nota de Débito** | 27 num. 5 lit. c |
+| 08 | Guía de Remisión | 29 num. 4 lit. c |
+| 09 | Ticket | 17 num. 4 lit. a |
+| 10 | Factura Prevalorada | 15 num. 6 lit. c |
+| 11 | Boleta de Compra | 20 num. 5 lit. c |
+| 12 | Constancia de Donación | 23 num. 7 lit. c |
+
+El texto original de 2017 numeraba distinto (02 Prevalorada, 03 Ticket, 07 Nota
+de Crédito, 08 Nota de Débito, 10 Retención...). La 0.1.0 traía esa tabla; la
+0.2.0 la corrige. 02 y 03 quedaron sin asignar y se rechazan. La gema **emite**
+01, 06 y 07; los demás códigos se reconocen (para validar referencias) pero no
+se emiten.
+
+### Las notas exigen el RTN del adquirente y se emiten en lempiras
+
+Los Arts. 26 y 28 num. 1-2 piden *"Nombres y Apellidos, Razón o Denominación
+Social del adquirente"* y *"Número de Registro Tributario Nacional (RTN) del
+adquirente"*. A diferencia del Art. 11 num. 2 para la Factura, no ofrecen la
+alternativa de CONSUMIDOR FINAL: una nota a un adquirente sin RTN se rechaza.
+
+Los Arts. 26 num. 9 y 28 num. 8 piden la *"Denominación literal de la Moneda
+Nacional Lempira o símbolo (L)"*. El permiso de emitir en *"otra denominación
+monetaria"* con la tasa de cambio está en el párrafo final del Art. 11 y habla
+sólo de *facturas*; los artículos de las notas no tienen ese párrafo. Una nota
+en otra moneda se rechaza.
+
+La Nota de Crédito debe aplicarse a un **Comprobante Fiscal** (Art. 4 num. 32,
+Art. 26 num. 3 lit. b; la lista está en el Art. 6). La Nota de Débito admite
+*"el Comprobante Fiscal o el documento"* (Art. 28 num. 3 lit. b). Ninguno de
+los artículos fija un monto máximo para la nota, y la gema no inventa uno.
+
+La Nota de Crédito imprime en blanco los campos de quien la recibe (nombres,
+identidad y firma, Art. 26 num. 7), que se llenan a mano al entregarla.
+
 ### La fecha de emisión es la del sistema
 
 No hay bandera para retrofechar. El Art. 43 obliga a custodiar los documentos en
@@ -296,10 +453,10 @@ Cada fila corresponde a pruebas automatizadas.
 | Artículo | Requisito | Implementado en |
 |---|---|---|
 | 10 num. 1 | Datos de identificación del emisor | `Issuer` |
-| 10 num. 2 | Denominación "Factura" | `Renderers::Text` |
+| 10 num. 2 | Denominación "Factura" | `Renderers::Text`, `Renderers::Pdf` |
 | 10 num. 3-5 | CAI, fecha límite y rango vigentes | `Authorization` |
 | 10 num. 6 | Destino de los ejemplares | `Renderers::Text` |
-| 10 num. 7 | Correlativo de 16 dígitos | `Correlative` |
+| 10 num. 7 | Correlativo de 16 dígitos; códigos reformados por el 609-2017 | `Correlative` |
 | 10 num. 8 | Datos del adquirente exonerado | `Customer::Exonerado` |
 | 10 num. 10 | Descuentos y rebajas (formato) | `Renderers::Text` |
 | 11 num. 1 | Requisitos para crédito fiscal | `Compliance::Validator` |
@@ -310,6 +467,13 @@ Cada fila corresponde a pruebas automatizadas.
 | 11 num. 3 | Crédito fiscal sólo por ventas gravadas | `TaxSummary#credito_fiscal_base` |
 | 11 párrafo final | Tasa de cambio a la fecha de emisión | `ExchangeRate` |
 | 12 | Exportaciones con tasa cero | `TaxTreatment::GRAVADO_0` |
+| 25 num. 2, 7 / 27 num. 2, 7 | "Nota de Crédito" / "Nota de Débito"; destino de los ejemplares | `Renderers::Text`, `Renderers::Pdf` |
+| 25 num. 5 / 27 num. 5 | Códigos 06 y 07, serie propia | `Correlative`, `Sequence` |
+| 26 num. 1-2 / 28 num. 1-2 | Nombre y RTN del adquirente | `Compliance::Validator` |
+| 26 num. 3 / 28 num. 3 | CAI, correlativo y fecha del comprobante | `DocumentReference` |
+| 26 num. 4 / 28 num. 4 | Motivo de la emisión | `Invoice#motivo` |
+| 26 num. 7 | Datos y firma de quien recibe la NC | `Renderers::Text`, `Renderers::Pdf` |
+| 26 num. 9 / 28 num. 8 | Moneda Nacional Lempira | `Compliance::Validator` |
 | 41 | Leyenda ANULADA; correlativo conservado | `Invoice#annul` |
 | 42 | Aviso de autorizaciones vencidas sin usar | `invoicehn check` |
 | 43 | Custodia cronológica | `Storage::JsonStore` |
@@ -356,6 +520,95 @@ Invoicehn::Issuance.new(
 
 ---
 
+## Integración con la aplicación anfitriona: store, sequence y ledger
+
+`Invoicehn::Issuance.new(store:, sequence:, ledger:)` acepta cualquier objeto
+que responda a los métodos de abajo (*duck typing*); la gema no depende de
+Rails ni de ActiveRecord. Cuando se inyectan los tres, `Issuance` no toca el
+sistema de archivos: no construye `Config` ni lee `~/.invoicehn`.
+
+### store
+
+| Método | Contrato |
+|---|---|
+| `issuer` → `Issuer` o `nil` | El emisor con los siete datos del Art. 10 num. 1. |
+| `authorizations_for(identifier)` → `Array<Authorization>` | Todas las autorizaciones de ese `NNN-NNN-TT`, vencidas incluidas. |
+| `active_authorization(identifier, next_sequence:, on:)` → `Authorization` o `nil` | Una autorización no vencida en `on` cuyo rango **cubra** `next_sequence` (la de menor inicio si hay varias). `nil` si ninguna lo cubre; no devolver una agotada. Con `next_sequence: nil`, la vigente de menor inicio. |
+| `save_document(document)` → `document` | Guarda el documento (`document.to_h` es su forma serializable). Si ya existe y el nuevo **no** está anulado, lanza `Invoicehn::ImmutableDocument`; la forma anulada reemplaza a la emitida (Art. 41). |
+| `delete_document(document)` → `document` | Borra el documento. `Issuance` lo llama **sólo** para deshacer una emisión cuyo asiento contable falló (dentro del bloque de `allocate`) o una anulación cuyo asiento falló (borra la forma ANULADA y vuelve a guardar la emitida). |
+| `find(correlative)` → `Invoice` | El documento con ese correlativo (`String` o `Correlative`); `Invoicehn::DocumentNotFound` si no existe. `find(c).to_h` debe ser igual a lo guardado, incluidos `reference` y `motivo` de las notas. |
+| `exists?(correlative)` → `Boolean` | |
+
+La CLI usa además `save_issuer`, `authorizations`, `add_authorization`, `all(from:, to:)`, `settings` y `save_settings`; una aplicación que no use la CLI no los necesita.
+
+### sequence
+
+| Método | Contrato |
+|---|---|
+| `allocate(identifier) { \|correlative\| ... }` → valor del bloque | Calcula el siguiente correlativo, lo entrega al bloque **bajo candado** (en Postgres: `SELECT ... FOR UPDATE` dentro de una transacción) y avanza el contador **sólo si el bloque termina sin excepción**. Si el bloque lanza, el contador queda igual y la excepción se propaga. |
+| `peek(identifier)` → `Correlative` | El próximo correlativo, sin consumirlo. |
+| `issued_count(identifier)` → `Integer` | La última secuencia consumida (0 si ninguna). |
+
+Cada identificador (`000-001-01`, `000-001-06`, `000-001-07`...) es una serie
+independiente que empieza en 00000001.
+
+### ledger
+
+| Método | Contrato |
+|---|---|
+| `record(document, event:)` → cualquier cosa | Asienta la emisión (`event: :emision`) o la anulación (`event: :anulacion`). Si lanza, `Issuance` borra el documento recién guardado y el correlativo no se consume. |
+
+`entries(from:, to:)` sólo lo usa la exportación de la CLI. `Ledger::Multi`
+reparte a varios libros, pero no puede deshacer el asiento de uno si el
+siguiente falla: un libro transaccional debería participar en la transacción
+de la aplicación.
+
+Si la aplicación envuelve la emisión en una transacción de base de datos
+(recomendado), cualquier fallo revierte también el contador y el documento.
+
+### Verificar los adaptadores
+
+```ruby
+require "invoicehn/test_support/contracts"
+
+class InvoicehnStoreContractTest < ActiveSupport::TestCase
+  include Invoicehn::TestSupport::StoreContract
+  # Un store con emisor completo y autorización vigente para 000-001-01
+  # (y, opcionalmente, para 000-001-06 para probar las notas).
+  def contract_store = Facturacion::InvoicehnStore.new
+end
+
+class InvoicehnSequenceContractTest < ActiveSupport::TestCase
+  include Invoicehn::TestSupport::SequenceContract
+  def contract_sequence = Facturacion::InvoicehnSequence.new
+end
+
+class InvoicehnLedgerContractTest < ActiveSupport::TestCase
+  include Invoicehn::TestSupport::LedgerContract
+  def contract_ledger = Facturacion::InvoicehnLedger.new
+end
+
+class InvoicehnIssuanceContractTest < ActiveSupport::TestCase
+  include Invoicehn::TestSupport::IssuanceContract   # emite una factura real
+  def contract_store = Facturacion::InvoicehnStore.new
+  def contract_sequence = Facturacion::InvoicehnSequence.new
+  def contract_ledger = Facturacion::InvoicehnLedger.new
+end
+```
+
+`IssuanceContract` emite primero con un libro que rechaza el asiento y verifica
+que no quede documento ni avance el contador; luego emite de verdad y verifica
+que `find` devuelva lo emitido. Fuera de minitest, las mismas verificaciones
+están en `require "invoicehn/testing"` (`Invoicehn::Testing.assert_store_contract`,
+`assert_sequence_contract`, `assert_ledger_contract`, `assert_issuance_round_trip`),
+que lanzan `Invoicehn::Testing::ContractError`. `invoicehn/test_support/memory`
+trae adaptadores en memoria: la implementación completa más corta del contrato,
+útil como modelo.
+
+La CLI (`thor`, `tty-prompt`) y el PDF (`prawn`) no se cargan con
+`require "invoicehn"`: una aplicación Rails los instala como dependencias de la
+gema, pero no los carga si no los usa.
+
 ## Almacenamiento
 
 Por defecto en `~/.invoicehn` (configurable con `INVOICEHN_HOME` o `--data-dir`):
@@ -384,6 +637,10 @@ Textos primarios, por número de *La Gaceta*:
 | 34,457 | Acuerdo 609-2017 (primera reforma) |
 | 34,792 | Acuerdo 725-2018 (segunda reforma — agrega los descuentos) |
 | 34,811 | Acuerdo 817-2018 (tercera reforma) |
+
+El Acuerdo 609-2017 es el que cambió los códigos de tipo de documento; las
+notas siguen los Arts. 25-28 del texto consolidado
+(`doc/fuentes/acuerdo_481_2017_consolidado.txt`, líneas 1300-1497).
 | 33,316 | Decreto 278-2013 (tasas del ISV) |
 
 Más la Ley del Impuesto Sobre Ventas (Decreto-Ley 24, Arts. 3 y 9) y el Código

data/lib/invoicehn/authorization.rb

@@ -47,9 +47,9 @@ module Invoicehn
     # perderán su validez y no podrán ser utilizados cuando se haya vencido el
     # plazo de tiempo autorizado." The fecha límite is the last day on which a
     # document may be issued, so it is still usable on that date itself.
-    def expired?(on = Date.today) = on > @limit_date
+    def expired?(on = Invoicehn.today) = on > @limit_date
 
-    def days_remaining(from = Date.today) = (@limit_date - from).to_i
+    def days_remaining(from = Invoicehn.today) = (@limit_date - from).to_i
 
     def covers?(correlative)
       correlative = Correlative.parse(correlative.to_s)
@@ -62,13 +62,13 @@ module Invoicehn
     def capacity = @range_end.sequence - @range_start.sequence + 1
 
     # Whether this authorization can still be used to issue the given number.
-    def usable?(correlative, on: Date.today)
+    def usable?(correlative, on: Invoicehn.today)
       !expired?(on) && covers?(correlative)
     end
 
     # Raises with the specific reason, so the caller can report which of the two
     # conditions failed rather than a generic refusal.
-    def assert_usable!(correlative, on: Date.today)
+    def assert_usable!(correlative, on: Invoicehn.today)
       if expired?(on)
         raise AuthorizationExpired,
               "la fecha límite de emisión (#{@limit_date}) ya venció; " \

data/lib/invoicehn/cli/builder.rb

@@ -21,10 +21,23 @@ module Invoicehn
           line_items: Array(data["items"] || data["line_items"]).map { |i| build_line(i, currency) },
           currency: currency,
           exchange_rate: build_rate(data["exchange_rate"], currency),
-          notes: data["notes"]
+          notes: data["notes"],
+          # Notes only (identifier NNN-NNN-06 or -07): the correlative of a
+          # document in the store, or {correlative, cai, issue_date} for one
+          # issued elsewhere — Arts. 26 and 28 num. 3 and 4.
+          reference: build_reference(data["reference"]),
+          motivo: data["motivo"]
         )
       end
 
+      def build_reference(value)
+        case value
+        when nil, "" then nil
+        when Hash then DocumentReference.from_h(value)
+        else value.to_s
+        end
+      end
+
       def build_customer(data)
         kind = (data["kind"] || data["tipo"] || "consumidor_final").to_s
 
@@ -63,7 +76,7 @@ module Invoicehn
         return nil if data.nil?
         return ExchangeRate.from_h(data) if data.is_a?(Hash)
 
-        ExchangeRate.new(rate: to_decimal(data), date: Date.today, currency: currency)
+        ExchangeRate.new(rate: to_decimal(data), date: Invoicehn.today, currency: currency)
       end
 
       private

data/lib/invoicehn/cli/wizard.rb

@@ -203,7 +203,7 @@ module Invoicehn
       def ask_exchange_rate(currency)
         ExchangeRate.new(
           rate: ask(Locale.t("invoice.exchange_rate")),
-          date: Date.today,
+          date: Invoicehn.today,
           currency: currency,
           source: @prompt.ask(Locale.t("invoice.exchange_source"),
                               default: ExchangeRate::DEFAULT_SOURCE)