Merge pull request #4229 from LiteFarmOrg/LF-5360-generalize-the-tape-survey-flow-into-a-reusable-multi-survey-architecture

LF-5360 Generalize the tape survey flow into a reusable multi survey architecture

Author: kathyavini

packages/api/db/migration/20260625000000_generalize_survey_tables.js

@@ -0,0 +1,76 @@
+/*
+ *  Copyright 2026 LiteFarm.org
+ *  This file is part of LiteFarm.
+ *
+ *  LiteFarm is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  LiteFarm is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ *  GNU General Public License for more details, see <https://www.gnu.org/licenses/>.
+ */
+
+/**
+ * Generalizes the bespoke TAPE survey storage into a reusable, multi-survey model:
+ * - Renames `tape_survey` to `survey_response` and adds a `survey_key` column identifying which survey each row answers
+ * - Makes `survey_step` nullable, as it is TAPE-specific and not used by every survey
+ * - Repurposes the TAPE permissions to generic survey_response permissions (add/get/edit).
+ *
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+export const up = async function (knex) {
+  await knex.schema.renameTable('tape_survey', 'survey_response');
+
+  await knex.schema.alterTable('survey_response', function (table) {
+    table.string('survey_key').nullable();
+  });
+
+  // Every existing row is a TAPE response.
+  await knex('survey_response').update({ survey_key: 'tape' });
+  await knex.schema.alterTable('survey_response', function (table) {
+    table.string('survey_key').notNullable().alter();
+  });
+
+  await knex.schema.alterTable('survey_response', function (table) {
+    table.string('survey_step').nullable().alter();
+  });
+
+  // Repurpose the TAPE permissions (names only)
+  await knex('permissions')
+    .where({ permission_id: 185 })
+    .update({ name: 'add:survey_response', description: 'add survey_response' });
+  await knex('permissions')
+    .where({ permission_id: 186 })
+    .update({ name: 'get:survey_response', description: 'get survey_response' });
+  await knex('permissions')
+    .where({ permission_id: 187 })
+    .update({ name: 'edit:survey_response', description: 'edit survey_response' });
+};
+
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+export const down = async function (knex) {
+  await knex('permissions')
+    .where({ permission_id: 185 })
+    .update({ name: 'add:tape_survey', description: 'add tape_survey' });
+  await knex('permissions')
+    .where({ permission_id: 186 })
+    .update({ name: 'get:tape_survey', description: 'get tape_survey' });
+  await knex('permissions')
+    .where({ permission_id: 187 })
+    .update({ name: 'edit:tape_survey', description: 'edit tape_survey' });
+
+  await knex.schema.alterTable('survey_response', function (table) {
+    table.string('survey_step').notNullable().alter();
+  });
+  await knex.schema.alterTable('survey_response', function (table) {
+    table.dropColumn('survey_key');
+  });
+  await knex.schema.renameTable('survey_response', 'tape_survey');
+};

packages/api/src/controllers/surveyResponseController.ts

@@ -0,0 +1,149 @@
+/*
+ *  Copyright 2026 LiteFarm.org
+ *  This file is part of LiteFarm.
+ *
+ *  LiteFarm is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  LiteFarm is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ *  GNU General Public License for more details, see <https://www.gnu.org/licenses/>.
+ */
+
+import { Response } from 'express';
+import { LiteFarmRequest } from '../types.js';
+import SurveyResponseModel from '../models/surveyResponseModel.js';
+
+interface SurveyResponseData {
+  survey_version: string;
+  project_id: string;
+  survey_step?: string;
+  [key: string]: unknown;
+}
+
+interface CreateSurveyResponseReqBody {
+  survey_key: string;
+  survey_response: SurveyResponseData;
+}
+
+interface LatestSurveyResponseQuery {
+  survey_key?: string;
+}
+
+interface UpdateSurveyResponseParams {
+  submission_id: string;
+}
+
+interface UpdateSurveyResponseReqBody {
+  survey_response: SurveyResponseData;
+}
+
+type InsertableQuery = { insert: (data: Record<string, unknown>) => Promise<unknown> };
+
+const surveyResponseController = {
+  createSurveyResponse() {
+    return async (
+      req: LiteFarmRequest<unknown, unknown, unknown, CreateSurveyResponseReqBody>,
+      res: Response,
+    ) => {
+      try {
+        const { farm_id } = req.headers;
+        const user_id = req.auth?.user_id;
+        const { survey_key, survey_response } = req.body;
+        if (!survey_key) {
+          return res.status(400).json({ error: 'survey_key is required' });
+        }
+        const { survey_version, project_id, survey_step } = survey_response;
+
+        const insertQuery = SurveyResponseModel.query().context({
+          user_id,
+        }) as unknown as InsertableQuery;
+        await insertQuery.insert({
+          farm_id,
+          survey_key,
+          survey_response,
+          survey_version,
+          project_id,
+          survey_step,
+        });
+
+        return res.status(201).send();
+      } catch (error) {
+        console.error(error);
+        return res.status(500).json({ error });
+      }
+    };
+  },
+
+  getLatestSurveyResponse() {
+    return async (req: LiteFarmRequest<LatestSurveyResponseQuery>, res: Response) => {
+      try {
+        const { farm_id } = req.headers;
+        const { survey_key } = req.query;
+        if (!survey_key) {
+          return res.status(400).json({ error: 'survey_key is required' });
+        }
+        // Find the latest survey response of this kind for the farm
+        const result = await SurveyResponseModel.query()
+          .where({ farm_id, survey_key })
+          .orderBy('created_at', 'desc')
+          .first();
+        return res.status(200).send(result ?? null);
+      } catch (error) {
+        console.error(error);
+        return res.status(500).json({ error });
+      }
+    };
+  },
+
+  // Note: Not currently called from frontend
+  updateSurveyResponse() {
+    return async (
+      req: LiteFarmRequest<
+        unknown,
+        UpdateSurveyResponseParams,
+        unknown,
+        UpdateSurveyResponseReqBody
+      >,
+      res: Response,
+    ) => {
+      try {
+        const { farm_id } = req.headers;
+        const user_id = req.auth?.user_id;
+        const { submission_id } = req.params;
+        const { survey_response } = req.body;
+        const { survey_version, project_id, survey_step } = survey_response;
+
+        const existing = (await SurveyResponseModel.query().findOne({ submission_id })) as
+          | { survey_key: string }
+          | undefined;
+        if (!existing) {
+          return res.status(404).json({ error: 'Survey response not found' });
+        }
+
+        const insertQuery = SurveyResponseModel.query().context({
+          user_id,
+        }) as unknown as InsertableQuery;
+        await insertQuery.insert({
+          submission_id,
+          farm_id,
+          survey_key: existing.survey_key,
+          survey_response,
+          survey_version,
+          project_id,
+          survey_step,
+        });
+
+        return res.status(204).send();
+      } catch (error) {
+        console.error(error);
+        return res.status(500).json({ error });
+      }
+    };
+  },
+};
+
+export default surveyResponseController;

packages/api/src/controllers/tapeSurveyController.js

@@ -30,8 +30,7 @@ const entitiesGetters = {
   nomination_id: fromNomination,
   transplant_task: fromTransPlantTask,
   product_id: fromProductFarm,
-  tape_survey_id: fromTapeSurvey,
-  submission_id: fromTapeSurvey,
+  submission_id: fromSurveyResponse,
 };
 import userFarmModel from '../../models/userFarmModel.js';
 
@@ -285,8 +284,8 @@ function fromProductFarm(product_id, _next, farm_id) {
   return knex('product_farm').where({ product_id, farm_id }).first();
 }
 
-function fromTapeSurvey(submission_id) {
-  return knex('tape_survey').where({ submission_id }).first();
+function fromSurveyResponse(submission_id) {
+  return knex('survey_response').where({ submission_id }).first();
 }
 
 function sameFarm(object, farm) {

packages/api/src/middleware/acl/hasFarmAccess.js

@@ -15,9 +15,9 @@
 
 import BaseFormatModel from './baseFormatModel.js';
 
-class TapeSurveyModel extends BaseFormatModel {
+class SurveyResponseModel extends BaseFormatModel {
   static get tableName() {
-    return 'tape_survey';
+    return 'survey_response';
   }
 
   static get idColumn() {
@@ -27,14 +27,15 @@ class TapeSurveyModel extends BaseFormatModel {
   static get jsonSchema() {
     return {
       type: 'object',
-      required: ['farm_id', 'survey_version', 'project_id', 'survey_step', 'survey_response'],
+      required: ['farm_id', 'survey_key', 'survey_version', 'project_id', 'survey_response'],
       properties: {
         id: { type: 'integer' },
         submission_id: { type: 'string' },
         farm_id: { type: 'string' },
+        survey_key: { type: 'string' },
         survey_version: { type: 'string' },
         project_id: { type: 'string' },
-        survey_step: { type: 'string' },
+        survey_step: { type: ['string', 'null'] },
         survey_response: { type: 'object' },
         created_by_user_id: { type: 'string' },
         created_at: { type: 'string', format: 'date-time' },
@@ -54,4 +55,4 @@ class TapeSurveyModel extends BaseFormatModel {
   }
 }
 
-export default TapeSurveyModel;
+export default SurveyResponseModel;