Confusion with Product field priorities and read/write statuses

[monsieurtanuki]

Describe the bug
When you save a product

• some product fields seem to have priority over others (e.g. productNameInLanguages being more important than productName)
• some product fields seem to be computed from other fields and cannot be set directly (e.g. ingredientsTags computed from ingredientsText)

The problem is not that such priority rules exist, the problem is that they are not explicitly available.

To Reproduce
I wrote a test code; as comments the values you get after the save+get operation:

const String barcode = '7340011364184';
final Product product = Product(
  barcode: barcode,
  // will be [en:product-categories-test-3, en:product-categories-test-4]
  categoriesTags: [
    'en:product-categories-test-1',
    'en:product-categories-test-2'
  ],
  // will be Product categories test 3,Product categories test 4
  categories: 'Product categories test 3,Product categories test 4',
  // will be null
  categoriesTagsInLanguages: {
    OpenFoodFactsLanguage.ENGLISH: [
      'Product categories test 5',
      'Product categories test 6',
    ],
  },
  // will be Product labels test 1,Product labels test 2
  labels: 'Product labels test 1,Product labels test 2',
  // will be [en:product-labels-test-1, en:product-labels-test-2]
  labelsTags: [
    'en:product-labels-test-3',
    'en:product-labels-test-4',
  ],
  // will be null
  labelsTagsInLanguages: {
    OpenFoodFactsLanguage.ENGLISH: [
      'Product labels test 5',
      'Product labels test 6',
    ],
  },
  // will be Italy,Japan
  countries: 'Italy,Japan',
  // will be [en:italy, en:japan]
  countriesTags: [
    'en:france',
    'en:portugal',
  ],
  // will be null
  countriesTagsInLanguages: {
    OpenFoodFactsLanguage.ENGLISH: [
      'Cyprus',
      'Hungary',
    ],
  },
  // will be Toto2
  productName: 'Toto1',
  // will be {OpenFoodFactsLanguage.ENGLISH: Toto2}
  productNameInLanguages: {OpenFoodFactsLanguage.ENGLISH: 'Toto2'},
  // will be beer,lemonade
  ingredientsText: 'sugar,milk',
  // will be {OpenFoodFactsLanguage.ENGLISH: beer,lemonade}
  ingredientsTextInLanguages: {
    OpenFoodFactsLanguage.ENGLISH: 'beer,lemonade',
  },
  // will be [en:beer, en:alcohol, en:lemonade]
  ingredientsTags: ['en:flour', 'en:water'],
  // will be null
  ingredientsTagsInLanguages: {
    OpenFoodFactsLanguage.ENGLISH: ['en:butter', 'en:cinnamon'],
  },
);

Status status = await OpenFoodAPIClient.saveProduct(
  TestConstants.TEST_USER,
  product,
);

expect(status.status, 1);
expect(status.statusVerbose, 'fields saved');

ProductQueryConfiguration configurations = ProductQueryConfiguration(
  barcode,
  language: OpenFoodFactsLanguage.ENGLISH,
);
ProductResult result = await OpenFoodAPIClient.getProduct(
  configurations,
  user: TestConstants.TEST_USER,
);

[monsieurtanuki]

Beyond the priority issue but still regarding product fields:

• there are no comments on Product fields (neither on ProductFields), which is sad
• some fields work in read mode, but not in write mode (e.g. serving_quantity from Fix: Added missing product fields to ProductField enum #331 (comment)) - that should be dealt with: either fixed (all fields work ok read/write) or with added warnings (those fields work ok in read mode, those work ok in write mode).

[M123-dev]

I don't think there is a really good way to solve this. Comments are a good idea in any case. If we have a documentation with all fields, this should be included there as well, otherwise we could consider throwing an error in the write methods if fields that can't be written are not null. This however would probably lead to an unpleasant developer expierence.

[monsieurtanuki]

I don't think there is a really good way to solve this.

Beyond the comments, we could create two enums that extend ProductField: ProductFieldRead and ProductFieldWrite, and accept only ProductFieldRead for read actions and ProductFieldWrite for write actions.
But first, good comments.