V3 S3 : correction des faits (fiche document + correct_facts)

Backend : CorrectFacts (editor+, validation Go -> 400 jamais 500),
op outbox correct_facts (full-replace jeu user), PATCH
/files/:id/facts (renvoie jeu complet). Tests service + sync + handlers.

Mobile (Room v20) : table resource_facts + FactsDao, FactsRepository
(sync remplace-en-bloc, correction optimiste + outbox atomique),
fiche « Ce qu'on a compris » sur le viewer (chips, suggéré grisé,
édition par type, reset auto), bouton viewer si processed, FR/EN.

Contrat docs/api-v1.md, V3.md (S1-S3 livrés, FTS -> v21).
This commit is contained in:
venture
2026-09-26 10:28:33 +02:00
parent 95b4cf79cf
commit ac8bd9acb4
45 changed files with 2554 additions and 15 deletions
+1
View File
@@ -18,6 +18,7 @@ var expectedRoutes = []string{
"GET /api/v1/files/:id",
"GET /api/v1/files/:id/ocr",
"GET /api/v1/files/:id/facts",
"PATCH /api/v1/files/:id/facts",
"GET /api/v1/files/:id/content",
"GET /api/v1/files/:id/shares",
"GET /api/v1/files/:id/links",
+85
View File
@@ -81,3 +81,88 @@ func TestFactsEndpoint(t *testing.T) {
rec, _ = doRequest(t, r, http.MethodGet, "/api/v1/files/"+emptyID+"/facts", tokenB, nil, "")
expectError(t, rec, http.StatusNotFound, "NOT_FOUND", "facts-foreign")
}
// TestCorrectFactsEndpoint : PATCH /files/:id/facts — remplace le jeu user
// (editor+ = owner ici), renvoie le jeu complet ; 400 sur corps invalide ;
// 404 si trashé/étranger.
func TestCorrectFactsEndpoint(t *testing.T) {
r, store, repo := setup(t)
device := repository.NewID()
token, userID := registerAndLogin(t, r, repo, testUserUsername(device, "fc"), "facts-test-password", device)
fileID := repository.NewID()
if err := repo.Resources.InsertFile(userID, fileID, "facture.pdf", "", 0, nil, nil); err != nil {
t.Fatalf("insert: %v", err)
}
extractSvc := service.NewExtract(repo)
if err := extractSvc.ProcessText(fileID, "EDF\nFacture n° F-1 du 01/02/2026\nTotal : 10,00 €\n"); err != nil {
t.Fatalf("extract: %v", err)
}
_ = store
patch := func(body string) (int, envelope) {
t.Helper()
rec, _ := doRequest(t, r, http.MethodPatch, "/api/v1/files/"+fileID+"/facts", token, []byte(body), "application/json")
var env envelope
if rec.Code == http.StatusOK {
if err := json.Unmarshal(rec.Body.Bytes(), &env); err != nil {
t.Fatalf("patch unmarshal: %v body=%s", err, rec.Body.String())
}
}
return rec.Code, env
}
// Correction : émetteur fixé par l'utilisateur.
code, env := patch(`{"facts":[{"factType":"issuer","valueText":"Vrai Fournisseur","confidence":1}]}`)
if code != http.StatusOK {
t.Fatalf("patch: attendu 200, got %d", code)
}
var facts []struct {
FactType string `json:"factType"`
ValueText string `json:"valueText"`
Origin string `json:"origin"`
}
if err := json.Unmarshal(env.Data, &facts); err != nil {
t.Fatalf("unmarshal: %v", err)
}
foundUser, foundAuto := false, false
for _, f := range facts {
if f.FactType == "issuer" && f.Origin == "user" && f.ValueText == "Vrai Fournisseur" {
foundUser = true
}
if f.Origin == "auto" {
foundAuto = true
}
}
if !foundUser || !foundAuto {
t.Fatalf("jeu après correction inattendu: %+v", facts)
}
// Corps invalides → 400.
for _, body := range []string{
`{}`,
`{"facts":[{"factType":"couleur","valueText":"bleu"}]}`,
`{"facts":[{"factType":"date","valueDate":"12/03/2026"}]}`,
`{"facts":[{"factType":"issuer"}]}`,
`not-json`,
} {
rec, _ := doRequest(t, r, http.MethodPatch, "/api/v1/files/"+fileID+"/facts", token, []byte(body), "application/json")
expectError(t, rec, http.StatusBadRequest, "INVALID_REQUEST", "facts-patch-400:"+body)
}
// Étranger (viewer simulé : partage + snapshot hors scope ici, un autre
// user sans grant suffit — CorrectFacts exige editor+) → 404.
deviceB := repository.NewID()
tokenB, _ := registerAndLogin(t, r, repo, testUserUsername(deviceB, "fd"), "facts-test-password", deviceB)
rec, _ := doRequest(t, r, http.MethodPatch, "/api/v1/files/"+fileID+"/facts", tokenB,
[]byte(`{"facts":[{"factType":"issuer","valueText":"X"}]}`), "application/json")
expectError(t, rec, http.StatusNotFound, "NOT_FOUND", "facts-patch-foreign")
// Trashé → 404.
if _, err := store.Trash(userID, fileID); err != nil {
t.Fatalf("trash: %v", err)
}
rec, _ = doRequest(t, r, http.MethodPatch, "/api/v1/files/"+fileID+"/facts", token,
[]byte(`{"facts":[{"factType":"issuer","valueText":"X"}]}`), "application/json")
expectError(t, rec, http.StatusNotFound, "NOT_FOUND", "facts-patch-trashed")
}
+48
View File
@@ -133,6 +133,54 @@ func FilesGetFacts(c *gin.Context) {
api.OK(c, facts)
}
// FilesCorrectFacts remplace le jeu `user` des faits (V3 S3) :
// PATCH /files/:id/facts `{ facts: [...] }` (full-replace, jamais de diff).
// Nécessite editor+ (comme update_metadata) ; viewer- → 404 NOT_FOUND.
// Corps invalide (type inconnu, date non ISO, fait sans valeur) → 400.
func FilesCorrectFacts(c *gin.Context) {
if Store == nil {
api.Error(c, http.StatusServiceUnavailable, "SERVICE_UNAVAILABLE", "backend not initialized")
return
}
userID := c.GetString(UserIDKey)
id := c.Param("id")
if !deviceIDPattern.MatchString(id) {
api.Error(c, http.StatusNotFound, "NOT_FOUND", "file not found")
return
}
var req struct {
Facts []service.FactDTO `json:"facts"`
}
if err := c.ShouldBindJSON(&req); err != nil {
api.Error(c, http.StatusBadRequest, "INVALID_REQUEST", "invalid JSON body (expected { facts: [...] })")
return
}
if req.Facts == nil {
api.Error(c, http.StatusBadRequest, "INVALID_REQUEST", "missing required field `facts`")
return
}
if len(req.Facts) > 100 {
api.Error(c, http.StatusBadRequest, "INVALID_REQUEST", "`facts` too long (max 100)")
return
}
if err := Store.CorrectFacts(userID, id, req.Facts); err != nil {
// Erreurs de validation (type/date/valeur) → 400 explicite, pas 500 :
// ce sont des fautes client, jamais des pannes (cf. FEEDBACK #8).
if errors.Is(err, service.ErrInvalidFact) {
api.Error(c, http.StatusBadRequest, "INVALID_REQUEST", err.Error())
return
}
writeError(c, err)
return
}
facts, err := Store.GetFacts(userID, id)
if err != nil {
writeError(c, err)
return
}
api.OK(c, facts)
}
// own ou shared) : GET /files/:id/content. Réponse binaire (Content-Type du
// fichier, Content-Disposition inline) — jamais d'enveloppe {data}. Supporte
// Range via http.ServeContent (Gin c.File). Sans bytes serveur (ressource
+1
View File
@@ -76,6 +76,7 @@ func setup(t *testing.T) (*gin.Engine, *service.Resources, *repository.Repositor
handlers.Auth = manager
handlers.Store = store
handlers.ResetDevicesRateLimit()
handlers.ResetLoginRateLimit()
gin.SetMode(gin.TestMode)
r := gin.New()
+1
View File
@@ -34,6 +34,7 @@ func RegisterRoutes(r *gin.Engine) {
protected.GET("/files/:id", FilesGet)
protected.GET("/files/:id/ocr", FilesGetOcr)
protected.GET("/files/:id/facts", FilesGetFacts)
protected.PATCH("/files/:id/facts", FilesCorrectFacts)
protected.GET("/files/:id/content", FilesContent)
protected.GET("/files/:id/shares", SharesList)
protected.GET("/files/:id/links", LinksList)
+33 -1
View File
@@ -93,7 +93,39 @@ func (r *Resources) ListFacts(resourceID string) ([]FactRow, error) {
return out, rows.Err()
}
// factNeedingExtract is a file with OCR text but no auto facts yet.
// CorrectFacts fully replaces the origin='user' set of a resource (S3 :
// correction en un tap — le client envoie le jeu corrigé complet, pas un
// diff). Auto facts are never touched. Empty params clears user corrections
// (back to pure auto).
func (r *Resources) CorrectFacts(resourceID string, params []FactParam) error {
tx, err := r.DB.Begin()
if err != nil {
return err
}
defer tx.Rollback() //nolint:errcheck — no-op after Commit.
if _, err := tx.Exec(
`DELETE FROM resource_facts WHERE resource_id = $1 AND origin = 'user'`,
resourceID,
); err != nil {
return err
}
for _, p := range params {
id, err := NewIDErr()
if err != nil {
return err
}
if _, err := tx.Exec(
`INSERT INTO resource_facts
(id, resource_id, fact_type, value_text, value_num, value_date, confidence, origin)
VALUES ($1, $2, $3, NULLIF($4, ''), $5, NULLIF($6, '')::date, $7, 'user')`,
id, resourceID, p.Type, p.ValueText, nullableFloat(p.ValueNum), derefStr(p.ValueDate), clamp01(p.Confidence),
); err != nil {
return err
}
}
return tx.Commit()
}
type factNeedingExtract struct {
ResourceID string
Text string
+73
View File
@@ -1,7 +1,9 @@
package service
import (
"fmt"
"log"
"time"
"github.com/kazier/backend/extract"
"github.com/kazier/backend/repository"
@@ -106,3 +108,74 @@ func (s *Resources) GetFacts(userID, resourceID string) ([]FactDTO, error) {
}
return out, nil
}
// validFactTypes mirrors the resource_facts CHECK (migration 000019).
// Validated in Go so violations map to INVALID_REQUEST, never 500.
var validFactTypes = map[string]bool{
"date": true, "due_date": true, "period": true, "amount": true,
"issuer": true, "reference": true, "doc_type": true,
}
// ErrInvalidFact marks client fact-validation failures (400 INVALID_REQUEST,
// never 500 — cf. FEEDBACK #8). Wrapped by validateFactParam.
var ErrInvalidFact = fmt.Errorf("invalid fact")
// CorrectFacts replaces the user's correction set on a resource (S3 :
// full-replace, not a diff). Requires editor+ like update_metadata
// (A8-style : viewer- ne peut pas corriger → NOT_FOUND halt, pas d'oracle).
// Absent/trashed/foreign → repository.ErrNotFound.
func (s *Resources) CorrectFacts(userID, resourceID string, facts []FactDTO) error {
access, err := s.Repository.Shares.EffectiveAccess(userID, resourceID)
if err != nil {
return err
}
if access.EffectiveRank < repository.AccessEditor {
return repository.ErrNotFound
}
params := make([]repository.FactParam, 0, len(facts))
for i, f := range facts {
p, err := validateFactParam(i, f)
if err != nil {
return err
}
params = append(params, p)
}
return s.Repository.Resources.CorrectFacts(resourceID, params)
}
func validateFactParam(i int, f FactDTO) (repository.FactParam, error) {
if !validFactTypes[f.FactType] {
return repository.FactParam{}, fmt.Errorf("facts[%d].factType invalide: %w", i, ErrInvalidFact)
}
if f.Confidence < 0 || f.Confidence > 1 {
return repository.FactParam{}, fmt.Errorf("facts[%d].confidence hors bornes [0,1]: %w", i, ErrInvalidFact)
}
var num *float64
if f.ValueNum != nil {
n := *f.ValueNum
num = &n
}
var dat *string
if f.ValueDate != "" {
if _, err := time.Parse("2006-01-02", f.ValueDate); err != nil {
return repository.FactParam{}, fmt.Errorf("facts[%d].valueDate doit être ISO YYYY-MM-DD: %w", i, ErrInvalidFact)
}
d := f.ValueDate
dat = &d
}
if f.ValueText == "" && num == nil && dat == nil {
return repository.FactParam{}, fmt.Errorf("facts[%d] sans valeur (valueText|valueNum|valueDate requis): %w", i, ErrInvalidFact)
}
conf := f.Confidence
if conf == 0 {
// Correction manuelle sans confiance explicite = affirmation.
conf = 1.0
}
return repository.FactParam{
Type: f.FactType,
ValueText: f.ValueText,
ValueNum: num,
ValueDate: dat,
Confidence: conf,
}, nil
}
+167
View File
@@ -1,6 +1,7 @@
package service
import (
"errors"
"testing"
"github.com/kazier/backend/repository"
@@ -194,3 +195,169 @@ func TestBackfill(t *testing.T) {
t.Fatalf("backfill 2 = %d, attendu 0", n)
}
}
func correctDTO(factType, valueText string) FactDTO {
return FactDTO{FactType: factType, ValueText: valueText, Confidence: 1.0}
}
func TestCorrectFactsReplacesUserSet(t *testing.T) {
s, ex := newExtractStore(t)
userID := mustCreateUser(t, s.Repository, "extract-correct")
fileID := repository.NewID()
if err := s.Repository.Resources.InsertFile(userID, fileID, "facture.pdf", "", 0, nil, nil); err != nil {
t.Fatalf("insert: %v", err)
}
if err := ex.ProcessText(fileID, extractCorpus); err != nil {
t.Fatalf("process: %v", err)
}
// Correction : l'émetteur auto est faux, l'utilisateur le fixe.
if err := s.CorrectFacts(userID, fileID, []FactDTO{correctDTO("issuer", "Vrai Fournisseur")}); err != nil {
t.Fatalf("correct: %v", err)
}
facts, err := s.GetFacts(userID, fileID)
if err != nil {
t.Fatalf("get facts: %v", err)
}
var userIssuer, autoIssuer int
for _, f := range facts {
if f.FactType == "issuer" && f.Origin == "user" && f.ValueText == "Vrai Fournisseur" {
userIssuer++
}
if f.FactType == "issuer" && f.Origin == "auto" {
autoIssuer++
}
}
if userIssuer != 1 {
t.Fatalf("correction user manquante: %+v", facts)
}
if autoIssuer == 0 {
t.Error("l'auto doit survivre à côté du user (les deux sont lus, user d'abord)")
}
// Deuxième correction (jeu vide) : efface les corrections, garde l'auto.
if err := s.CorrectFacts(userID, fileID, nil); err != nil {
t.Fatalf("clear corrections: %v", err)
}
facts, _ = s.GetFacts(userID, fileID)
for _, f := range facts {
if f.Origin == "user" {
t.Fatalf("corrections restantes: %+v", facts)
}
}
if len(facts) == 0 {
t.Fatal("l'auto doit survivre à l'effacement des corrections")
}
}
func TestCorrectFactsValidation(t *testing.T) {
s, _ := newExtractStore(t)
userID := mustCreateUser(t, s.Repository, "extract-correct-val")
fileID := repository.NewID()
if err := s.Repository.Resources.InsertFile(userID, fileID, "doc.pdf", "", 0, nil, nil); err != nil {
t.Fatalf("insert: %v", err)
}
num := 12.5
cases := []struct {
name string
facts []FactDTO
}{
{"type inconnu", []FactDTO{{FactType: "couleur", ValueText: "bleu"}}},
{"confiance hors bornes", []FactDTO{{FactType: "issuer", ValueText: "X", Confidence: 2}}},
{"date non ISO", []FactDTO{{FactType: "date", ValueDate: "12/03/2026"}}},
{"sans valeur", []FactDTO{{FactType: "issuer"}}},
}
for _, tc := range cases {
if err := s.CorrectFacts(userID, fileID, tc.facts); err == nil {
t.Errorf("%s : erreur attendue", tc.name)
} else if !errors.Is(err, ErrInvalidFact) {
t.Errorf("%s : attendu ErrInvalidFact, got %v", tc.name, err)
}
}
// Valides : date ISO + montant numérique.
if err := s.CorrectFacts(userID, fileID, []FactDTO{
{FactType: "due_date", ValueDate: "2026-04-12"},
{FactType: "amount", ValueNum: &num},
}); err != nil {
t.Fatalf("faits valides rejetés: %v", err)
}
}
func TestCorrectFactsScope(t *testing.T) {
s, _ := newExtractStore(t)
owner := mustCreateUser(t, s.Repository, "extract-corr-o")
viewer := mustCreateUser(t, s.Repository, "extract-corr-v")
fileID := repository.NewID()
if err := s.Repository.Resources.InsertFile(owner, fileID, "doc.pdf", "", 0, nil, nil); err != nil {
t.Fatalf("insert: %v", err)
}
// Étranger (même viewer via partage simulé plus bas) → NOT_FOUND.
if err := s.CorrectFacts(viewer, fileID, nil); err != repository.ErrNotFound {
t.Fatalf("étranger : attendu NOT_FOUND, got %v", err)
}
// Absent → NOT_FOUND (EffectiveAccess sur ressource inconnue).
if err := s.CorrectFacts(owner, repository.NewID(), []FactDTO{correctDTO("issuer", "X")}); err != repository.ErrNotFound {
t.Fatalf("absent : attendu NOT_FOUND, got %v", err)
}
}
func TestSyncOpCorrectFacts(t *testing.T) {
s, ex := newExtractStore(t)
userID := mustCreateUser(t, s.Repository, "extract-op")
other := mustCreateUser(t, s.Repository, "extract-op-x")
device := mustRegisterDevice(t, s.Repository, "c0000000000000000000000000000001")
fileID := repository.NewID()
if err := s.Repository.Resources.InsertFile(userID, fileID, "facture.pdf", "", 0, nil, nil); err != nil {
t.Fatalf("insert: %v", err)
}
if err := ex.ProcessText(fileID, extractCorpus); err != nil {
t.Fatalf("process: %v", err)
}
foreignID := repository.NewID()
if err := s.Repository.Resources.InsertFile(other, foreignID, "autre.pdf", "", 0, nil, nil); err != nil {
t.Fatalf("insert foreign: %v", err)
}
apply := func(resID string, facts []FactDTO) SyncResult {
t.Helper()
raw := map[string]any{"facts": facts}
res, err := s.ApplyBatch(userID, device, []SyncOperation{
syncOp(repository.NewID(), resID, OpCorrectFacts, "file", raw),
})
if err != nil {
t.Fatalf("apply: %v", err)
}
return res
}
if res := apply(fileID, []FactDTO{correctDTO("issuer", "Corrigé")}); res.Applied != 1 || res.Failed != nil {
t.Fatalf("correct op: %+v", res)
}
facts, _ := s.GetFacts(userID, fileID)
found := false
for _, f := range facts {
if f.FactType == "issuer" && f.Origin == "user" && f.ValueText == "Corrigé" {
found = true
}
}
if !found {
t.Fatalf("correction via op manquante: %+v", facts)
}
// Op étrangère → halt NOT_FOUND.
if res := apply(foreignID, []FactDTO{correctDTO("issuer", "X")}); res.Failed == nil || res.Failed.Code != "NOT_FOUND" {
t.Fatalf("correct autrui doit halter NOT_FOUND: %+v", res)
}
// Payload invalide → halt INVALID_REQUEST.
res, err := s.ApplyBatch(userID, device, []SyncOperation{
syncOp(repository.NewID(), fileID, OpCorrectFacts, "file", map[string]any{
"facts": []any{map[string]any{"factType": "couleur", "valueText": "bleu"}},
}),
})
if err != nil {
t.Fatalf("apply: %v", err)
}
if res.Failed == nil || res.Failed.Code != "INVALID_REQUEST" {
t.Fatalf("payload invalide doit halter INVALID_REQUEST: %+v", res)
}
}
+24 -1
View File
@@ -31,6 +31,8 @@ const (
OpTrashResource = "trash_resource"
OpRestoreResource = "restore_resource"
OpPurgeResource = "purge_resource"
// V3 corrections (S3) : remplace le jeu `user` des faits (editor+).
OpCorrectFacts = "correct_facts"
)
// SyncOperation is one outbox entry (shadow of mobile PendingOperationRow).
@@ -98,6 +100,10 @@ type reportBytesPayload struct {
HasBytes *bool `json:"hasBytes"`
}
type correctFactsPayload struct {
Facts []FactDTO `json:"facts"`
}
func classifySyncError(err error) (string, string) {
switch {
case errors.Is(err, repository.ErrNameConflict):
@@ -206,7 +212,8 @@ func validateSyncOp(op *SyncOperation) error {
switch op.Operation {
case OpCreateResource, OpUpdateMetadata, OpMoveResource, OpDeleteResource,
OpShare, OpRevokeShare, OpUpdateShare, OpCreateLink, OpRevokeLink,
OpReportBytes, OpTrashResource, OpRestoreResource, OpPurgeResource:
OpReportBytes, OpTrashResource, OpRestoreResource, OpPurgeResource,
OpCorrectFacts:
default:
return errors.New("unknown operation " + op.Operation)
}
@@ -400,6 +407,22 @@ func (s *Resources) applySyncOp(ownerID, deviceID string, op *SyncOperation) err
case OpReportBytes:
return s.applyReportBytesOp(ownerID, deviceID, resourceID, op)
case OpCorrectFacts:
// S3 : même garde que CorrectFacts (editor+, A8) — une ressource
// visible sans droit de mutation n'est pas corrigeable (NOT_FOUND,
// pas d'oracle). Le payload porte le jeu `user` complet
// (full-replace, jamais de diff).
var p correctFactsPayload
if err := json.Unmarshal(op.Payload, &p); err != nil {
return errors.New("invalid payload: " + err.Error())
}
for i, f := range p.Facts {
if _, err := validateFactParam(i, f); err != nil {
return err
}
}
return s.CorrectFacts(ownerID, resourceID, p.Facts)
default:
return errors.New("unknown operation " + op.Operation)
}