feat: Add guides matricole schema and router

[BIA3IA]

Introduce a new schema and router for guides matricole.

[coderabbitai]

Walkthrough

Changes

The PR adds the web_guides_matricole table and Drizzle metadata, implements tRPC queries and mutations for PDF guides, adds blob deletion, and registers the module in the web schema and router.

Guides matricole

Layer / File(s)	Summary
Guide storage schema drizzle/0015_equal_the_spike.sql, drizzle/meta/..., src/db/schema/web/guides_matricole.ts	Adds guide metadata, unique versions, audit references, timestamps, migration SQL, and Drizzle synchronization metadata.
Guide query and mutation procedures src/routers/web/guides_matricole.ts, src/azure/blob.ts	Provides ordered listing, latest-guide retrieval, PDF upload and insertion, duplicate-version handling, and deletion of guide records and associated blobs.
Web schema and router composition src/db/schema/web/index.ts, src/routers/web/index.ts	Exports the table through the web schema and exposes the guide procedures through webRouter.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant guides_matricole_router
  participant PostgreSQL
  participant BlobStorage
  Client->>guides_matricole_router: Submit guide FormData
  guides_matricole_router->>PostgreSQL: Check version
  guides_matricole_router->>BlobStorage: Upload PDF
  BlobStorage-->>guides_matricole_router: Return file URL
  guides_matricole_router->>PostgreSQL: Insert guide metadata
  PostgreSQL-->>Client: Return inserted guide

Loading

Possibly related PRs

• PoliNetworkOrg/backend#35: Extends the same web schema and router composition for another web module.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change by adding the new guides matricole schema and router.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

src/routers/web/guides_matricole.ts (1)

38-49: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add output schemas to mutations.

addGuide returns either { error: "DUPLICATE_VERSION" } or the full inserted row; deleteGuide returns { error: "NOT_FOUND" } or { error: null }. Neither has an .output() schema, so clients lack type safety and the return shapes are inconsistent. Additionally, the raw insert exposes internal columns (created_by_id, modified_by_id, timestamps) to the client.

Also applies to: 72-84

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/routers/web/guides_matricole.ts` around lines 38 - 49, Define explicit
.output() schemas for addGuide and deleteGuide covering every success and error
branch, then align their return values with those schemas; have addGuide map the
inserted row to a client-safe shape that excludes internal columns such as
created_by_id, modified_by_id, and timestamps, and preserve the documented
DUPLICATE_VERSION, NOT_FOUND, and null-error responses.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/routers/web/guides_matricole.ts`:
- Around line 44-46: Remove createdBy from the client-controlled schema in
guideFormSchema.extend and derive it exclusively from the authenticated session
when constructing the guide record; update the related handler and validation
flow to use the session user identity rather than request FormData.
- Around line 53-56: Fix the TOCTOU race in the duplicate version handling of
the guide creation flow: remove reliance on the pre-insert check in the relevant
handler and catch the unique-constraint error from the INSERT, returning {
error: "DUPLICATE_VERSION" } and cleaning up the uploaded blob when it occurs.
Alternatively, make the duplicate check and insert atomic with a transaction,
ensuring constraint failures never surface as unhandled errors.
- Around line 38-49: Replace publicProcedure for addGuide and deleteGuide with
the project’s authenticated/admin-only procedure. Remove createdBy from the
input schema and derive it from the authenticated user context inside the
mutation handlers, using the existing auth/context symbols and preserving the
validated form fields.
- Around line 78-83: Update the deleteGuide mutation to delete the associated
Azure blob using the deleted row’s stored file value before or alongside
removing the database record. Add or use a blob-deletion helper in
src/azure/blob.ts, and invoke it from deleteGuide with the appropriate blob
identifier, while preserving the NOT_FOUND response when no row exists.

---

Nitpick comments:
In `@src/routers/web/guides_matricole.ts`:
- Around line 38-49: Define explicit .output() schemas for addGuide and
deleteGuide covering every success and error branch, then align their return
values with those schemas; have addGuide map the inserted row to a client-safe
shape that excludes internal columns such as created_by_id, modified_by_id, and
timestamps, and preserve the documented DUPLICATE_VERSION, NOT_FOUND, and
null-error responses.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e86ad082-50bb-4abf-8869-43eb1b904fc4

📥 Commits

Reviewing files that changed from the base of the PR and between 7a1fda9 and 06912af.

📒 Files selected for processing (7)

• drizzle/0015_equal_the_spike.sql
• drizzle/meta/0015_snapshot.json
• drizzle/meta/_journal.json
• src/db/schema/web/guides_matricole.ts
• src/db/schema/web/index.ts
• src/routers/web/guides_matricole.ts
• src/routers/web/index.ts

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/azure/blob.ts`:
- Around line 31-38: Wrap the body of deleteBlob in a try-catch, including URL
parsing, client creation, and deleteIfExists. Log the caught error with the blob
URL and relevant context, then return without rethrowing so deleteGuide can
complete successfully after the database row is removed.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 87d54c5d-422d-45b8-8516-de49e6632765

📥 Commits

Reviewing files that changed from the base of the PR and between 06912af and 8f5fa33.

📒 Files selected for processing (2)

• src/azure/blob.ts
• src/routers/web/guides_matricole.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/routers/web/guides_matricole.ts