mirror of
https://github.com/Sea-Haven-Industries/afterhours-shift-manager.git
synced 2026-09-30 21:53:11 +00:00
Update README for merged architecture and new features
This commit is contained in:
Adam Moussa
parent
debac9f8a7
commit
1f2237f442
1 changed files with 54 additions and 39 deletions
93
README.md
93
README.md
|
|
@ -1,10 +1,12 @@
|
|||
# After-Hours Shift Manager
|
||||
|
||||
Slack bot for managing after-hours on-call shifts at Sea Haven Industries. Employees can pick up, drop, and swap shifts directly from Slack. Changes automatically update 3CX ring group 800 routing.
|
||||
Slack bot for managing after-hours on-call shifts at Sea Haven Industries. Employees can pick up, drop, and swap shifts directly from Slack. Changes automatically update 3CX ring group routing via the integrated ring scheduler.
|
||||
|
||||
## How It Works
|
||||
|
||||
A recurring weekly schedule assigns employees to after-hours phone duty (5pm-8am). Any unassigned day shows as **Available** in Slack with a pickup button. When someone picks up or drops a shift for today, the 3CX phone system is updated immediately. Future changes take effect when the 3CX scheduler runs at 8am.
|
||||
A recurring weekly schedule assigns employees to after-hours phone duty. Weekend shifts are split into Day (8am-5pm) and Night (5pm-8am). Any unassigned shift shows as **Available** in Slack with a pickup button. When someone picks up or drops a shift for today, the 3CX ring group is updated immediately. Future changes take effect when the ring scheduler runs at 8am daily and 5pm on weekends.
|
||||
|
||||
The weekly schedule post is updated live when shifts change, and the previous week's post is automatically deleted when the new one goes out.
|
||||
|
||||
## Slack Commands
|
||||
|
||||
|
|
@ -23,15 +25,49 @@ A recurring weekly schedule assigns employees to after-hours phone duty (5pm-8am
|
|||
| `/oncall rate <ext> <amount>` | Set a per-person shift rate |
|
||||
| `/oncall help` | Show help |
|
||||
|
||||
### Admin Commands
|
||||
|
||||
Available to users listed in `admin_users` in the CONFIG record:
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `/oncall admin override <date> <ext>` | Assign a shift to an extension |
|
||||
| `/oncall admin open <date>` | Mark a shift as open |
|
||||
| `/oncall admin clear <date>` | Remove override (revert to weekly) |
|
||||
| `/oncall admin roster add <ext> <name>` | Add an employee to the roster |
|
||||
| `/oncall admin roster remove <ext>` | Remove an employee |
|
||||
| `/oncall admin roster rename <ext> <name>` | Rename an employee |
|
||||
|
||||
Dates accept: `today`, `tomorrow`, `monday`-`sunday`, `4/5`, `2026-04-05`
|
||||
|
||||
## Architecture
|
||||
|
||||
- **Runtime**: Python 3.12 on AWS Lambda (via API Gateway)
|
||||
- **Runtime**: Python 3.12 on AWS Lambda (arm64)
|
||||
- **Data**: DynamoDB single-table (`afterhours-shifts`)
|
||||
- **IaC**: AWS SAM (`template.yaml`)
|
||||
- **IaC**: AWS SAM (`template.yaml`) with shared Lambda Layer
|
||||
- **Slack**: Slack Bolt framework with `/oncall` slash command
|
||||
- **3CX Integration**: Invokes the `3cx-ring-group-scheduler` Lambda for same-day changes; the scheduler reads DynamoDB for future dates
|
||||
- **3CX Integration**: Ring group routing updated directly via 3CX RingGroup XAPI
|
||||
- **Secrets**: AWS Secrets Manager (`afterhours-shift-manager/*`)
|
||||
|
||||
### Lambda Functions
|
||||
|
||||
| Function | Trigger | Purpose |
|
||||
|---|---|---|
|
||||
| `afterhours-shift-manager` | API Gateway (POST /slack/events) | Slack bot — handles `/oncall` commands and interactive buttons |
|
||||
| `afterhours-weekly-post` | EventBridge (Monday 7am ET) | Posts weekly schedule to Slack, sends pay report email |
|
||||
| `afterhours-roster-sync` | EventBridge (daily 6am ET) | Syncs employee roster from 3CX |
|
||||
| `afterhours-ring-scheduler` | EventBridge (daily 8am ET + weekend 5pm ET) | Updates 3CX ring group routing based on who's on shift |
|
||||
|
||||
### Project Layout
|
||||
|
||||
```
|
||||
src/
|
||||
slack-bot/ Slack Bolt Lambda (handler + app)
|
||||
weekly-post/ Monday schedule + pay post
|
||||
roster-sync/ Daily 3CX roster sync
|
||||
ring-scheduler/ 3CX ring group routing updates
|
||||
shared/ Lambda Layer (schedule, blocks, 3CX client, secrets)
|
||||
```
|
||||
|
||||
### DynamoDB Schema
|
||||
|
||||
|
|
@ -42,12 +78,23 @@ Single table with `PK` / `SK` keys:
|
|||
| `ROSTER` | `<extension>` | Employee: name, extension, slack_user_id |
|
||||
| `WEEKLY` | `<DayName>` | Default weekly schedule: extension, name |
|
||||
| `OVERRIDE` | `<YYYY-MM-DD>` | Date override from pickup/drop (or `OPEN`) |
|
||||
| `SCHEDULE_POST` | `<channel_id>` | Current schedule message timestamp |
|
||||
| `PAY` | `<YYYY-MM-DD>` | Weekly pay record (Monday date key) |
|
||||
| `CONFIG` | `CONFIG` | Settings: shift_rate, fallback_extension |
|
||||
| `CONFIG` | `CONFIG` | Settings: shift_rate, fallback_extension, admin_users |
|
||||
|
||||
### Secrets Manager
|
||||
|
||||
| Secret | Description |
|
||||
|---|---|
|
||||
| `afterhours-shift-manager/slack-bot-token` | Slack bot OAuth token (`xoxb-...`) |
|
||||
| `afterhours-shift-manager/slack-signing-secret` | Slack app signing secret |
|
||||
| `afterhours-shift-manager/3cx-domain` | 3CX FQDN (e.g. `company.3cx.us`) |
|
||||
| `afterhours-shift-manager/3cx-client-id` | 3CX OAuth2 client ID |
|
||||
| `afterhours-shift-manager/3cx-client-secret` | 3CX OAuth2 client secret |
|
||||
|
||||
## Deployment
|
||||
|
||||
Merges to `main` are automatically deployed via **CodePipeline + CodeBuild**. The pipeline stack (`afterhours-shift-manager-pipeline`) watches the GitHub repo and runs `sam build && sam package` then deploys via CloudFormation changeset.
|
||||
Merges to `main` are automatically deployed via **GitHub Actions** using reusable SAM workflows from the Sea Haven org.
|
||||
|
||||
For manual deploys:
|
||||
|
||||
|
|
@ -57,35 +104,3 @@ sam deploy
|
|||
```
|
||||
|
||||
See [SETUP.md](SETUP.md) for full deployment and Slack app creation instructions.
|
||||
|
||||
### Version Bumps
|
||||
|
||||
A GitHub Actions workflow runs daily at 6pm ET, collects all PRs merged since the last version tag, creates a semver patch bump (e.g. v1.6.0 → v1.6.1), updates the Slack changelog canvas, and posts a summary to the team channel. Minor bumps can be triggered manually via `workflow_dispatch`.
|
||||
|
||||
### SSM Parameters
|
||||
|
||||
| Parameter | Description |
|
||||
|---|---|
|
||||
| `/afterhours-shift-manager/slack-bot-token` | Slack bot OAuth token (`xoxb-...`) |
|
||||
| `/afterhours-shift-manager/slack-signing-secret` | Slack app signing secret |
|
||||
| `/afterhours-shift-manager/channel-id` | Slack channel ID for notifications |
|
||||
|
||||
## Weekly Auto-Post
|
||||
|
||||
Every Monday at 7am ET, the bot posts the week's schedule to the configured channel with pickup buttons for any available shifts.
|
||||
|
||||
## Pay Report Email
|
||||
|
||||
A weekly Bonus Pay Summary email is sent via SES to payroll@seahaven.com with a table showing each employee's name, rate, and total pay for the week.
|
||||
|
||||
### Lambda Functions
|
||||
|
||||
| Function | Trigger | Purpose |
|
||||
|---|---|---|
|
||||
| `afterhours-shift-manager` | API Gateway (POST /slack/events) | Slack bot — handles `/oncall` commands and interactive buttons |
|
||||
| `afterhours-weekly-post` | EventBridge (Monday 7am ET) | Posts weekly schedule to Slack, sends pay report email |
|
||||
| `afterhours-roster-sync` | EventBridge (daily 6am ET) | Syncs employee roster from 3CX |
|
||||
|
||||
## Related
|
||||
|
||||
- [3cx-ring-scheduler](https://github.com/Sea-Haven-Industries/3cx-ring-scheduler) — the Lambda that updates 3CX ring group routing daily
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue