phoenix_kit_projects

# PhoenixKitProjects

A [PhoenixKit](https://github.com/BeamLabEU/phoenix_kit) plugin for **project + task management**: a reusable task library, projects that pull tasks in as assignments, per-project and per-template dependencies, schedule math with weekday/calendar awareness, and assignees sourced from [`phoenix_kit_staff`](https://github.com/BeamLabEU/phoenix_kit_staff).

## Features

- **Task library** — reusable tasks with description, estimated duration, default assignee ("template" is reserved for project templates)
- **Projects** — containers with `immediate` or `scheduled` start mode, completion auto-detection
- **Assignments** — task instances inside a project; editable independently of the template
- **Dependencies** — per-project ("A must finish before B") with multi-hop cycle detection
- **Default dependencies** — declared on the library task, auto-applied when both tasks are in the same project
- **Templates** — project templates cloned into real projects inside a single transaction
- **Polymorphic assignees** — team _or_ department _or_ person (at-most-one, enforced at DB + changeset layer)
- **Schedule math** — planned vs. projected end with velocity tracking; per-task `counts_weekends` override
- **Timeline & Calendar views** — every project has List/Timeline/Calendar tabs over one shared schedule walk (`ScheduleLayout`)
- **Quick-add** — "Add a task" under a project's task list opens the add-task sheet with the cursor in the title: Enter adds and closes, Shift+Enter adds and starts the next task on a fresh form, Esc closes; new tasks are one-off unless "Add to the task library" is ticked
- **Forms in a drawer** — on a project page every form (add/edit task, sub-project, edit project) opens as a right-hand sheet over the plan instead of a separate page; a save closes it and the plan updates, an edited form guards against a stray Esc/backdrop, and the same pages still answer at their own URLs for deep links
- **Overview & dashboards** — the landing page is the project list, the Overview (running projects, calendar, my tasks) is the last subtab, and the same pieces are available as widgets for `phoenix_kit_dashboards` boards
- **Assignee filters** — a Filters panel on both calendars: multi-person typeahead (DB-paged), Unassigned lens, personal-only and overdue-only refinements, with inherited team/department semantics (`Assignees`)
- **Dashboard widgets** — seven widgets for `phoenix_kit_dashboards` (board, workload, my tasks, deadlines, per-project status/schedule/tasks), duck-typed and crash-isolated
- **Mass-assignment guard** — `completed_by_uuid` / `completed_at` can only be set through the server-trusted `status_changeset/2`
- Real-time updates via `PhoenixKit.PubSub.Manager`
- Activity logging for every mutation
- Admin pages under `/admin/projects/*`

## Installation

Add to your parent PhoenixKit app's `mix.exs`:

```elixir
{:phoenix_kit_projects, "~> 0.21"},
# Optional — the people admin UI (assignee data works without it):
{:phoenix_kit_staff, "~> 0.1"}
```

(For local development inside the PhoenixKit workspace, use the path-dep form instead: `{:phoenix_kit_projects, path: "../phoenix_kit_projects"}`.)

`phoenix_kit_staff` is **optional** — the staff tables are created by core's migrations, and this module maps its own read-only shadow schemas over them for the polymorphic assignee; install staff for the people admin UI.

Also add the apps to `extra_applications` so `PhoenixKit.ModuleDiscovery` finds them (include `:phoenix_kit_staff` only if you installed it):

```elixir
def application do
  [extra_applications: [:logger, :phoenix_kit, :phoenix_kit_projects]]
end
```

Run `mix deps.get`, then toggle the module on from **Admin > Modules**.

## Database

Tables are created by the **V101** versioned migration inside `phoenix_kit` core. V101 depends on V100 (staff tables). Run via `mix phoenix_kit.install` / `mix phoenix_kit.update` in the parent app.

Tables created:

- `phoenix_kit_project_tasks` (reusable library)
- `phoenix_kit_project_task_dependencies` (template-level)
- `phoenix_kit_projects`
- `phoenix_kit_project_assignments` (with `CHECK` that at most one assignee is set)
- `phoenix_kit_project_dependencies` (per-project)

All tables use UUIDv7 primary keys.

## Public API

See `PhoenixKitProjects.Projects` — the single context module covers tasks, projects, templates, assignments, dependencies, and schedule/summary computation. Highlights:

```elixir
# Projects
Projects.list_projects/1          # :status, :include_templates
Projects.project_summaries/1      # batch query — no N+1
Projects.recompute_project_completion/1

# Tasks
Projects.list_tasks/0
Projects.create_task/1

# Assignments (form-facing vs. server-trusted split)
Projects.create_assignment/1
Projects.update_assignment_form/2    # safe: mass-assignment guard
Projects.update_assignment_status/2  # server-trusted: completion fields
Projects.complete_assignment/2
Projects.reopen_assignment/1

# Dependencies
Projects.add_dependency/2   # refuses cycles
Projects.dependencies_met?/1
Projects.available_dependencies/2

# Templates
Projects.list_templates/0
Projects.create_project_from_template/2  # atomic clone
```

## Development

See [`AGENTS.md`](AGENTS.md) for development conventions, test setup, and the pre-commit workflow.

## License

MIT