mirror of
https://github.com/tiennm99/miti99bot.git
synced 2026-04-17 15:20:58 +00:00
85 lines
2.9 KiB
Markdown
85 lines
2.9 KiB
Markdown
# Phase 06 — Docs
|
|
|
|
**Priority:** P1 (last)
|
|
**Status:** Complete
|
|
**Depends on:** All prior phases (✓ complete)
|
|
|
|
## Overview
|
|
|
|
Document D1 + Cron usage for module authors. Update existing architecture + module-authoring docs. Update `CLAUDE.md` module contract snippet.
|
|
|
|
## Deliverables
|
|
|
|
### Create
|
|
|
|
- `docs/using-d1.md` — how to add a D1-backed feature to a module
|
|
- When to choose D1 vs KV (query patterns, relational needs, scans)
|
|
- Writing migrations (`src/modules/<name>/migrations/NNNN_name.sql`)
|
|
- `sql.prepare/run/all/first/batch` API reference
|
|
- Table naming convention (`{module}_{table}`)
|
|
- Accessing `sql` from `init` and command handlers
|
|
- Testing with Miniflare D1 (`tests/fakes/fake-d1.js`)
|
|
- Running migrations: `npm run db:migrate`
|
|
|
|
- `docs/using-cron.md` — how to add a scheduled job to a module
|
|
- Declaring `crons: [{ schedule, name, handler }]`
|
|
- Cron expression syntax + Cloudflare limits
|
|
- Registering schedule in `wrangler.toml` `[triggers] crons`
|
|
- Handler signature `(event, { db, sql, env })`
|
|
- Local testing: `curl "http://localhost:8787/__scheduled?cron=0+17+*+*+*"`
|
|
- Error isolation (one handler fail ≠ others fail)
|
|
- Execution time limits
|
|
|
|
### Update
|
|
|
|
- `docs/adding-a-module.md` — add sections:
|
|
- Optional `crons[]` field
|
|
- Optional `init({ sql })` for D1
|
|
- Migration file placement
|
|
- Link to `using-d1.md` + `using-cron.md`
|
|
|
|
- `docs/architecture.md` — add:
|
|
- `scheduled()` flow diagram alongside existing fetch flow
|
|
- D1 store layer in storage section
|
|
- Migration runner role in deploy
|
|
|
|
- `docs/codebase-summary.md` — reflect new `src/db/cf-sql-store.js`, `src/modules/cron-dispatcher.js`, `src/types.js`
|
|
|
|
- `docs/code-standards.md` — JSDoc expectations (when to add, ESLint rules enforced)
|
|
|
|
- `CLAUDE.md` (project) — update module contract code block:
|
|
|
|
```js
|
|
{
|
|
name: "mymod",
|
|
init: async ({ db, sql, env }) => { ... },
|
|
commands: [ /* ... */ ],
|
|
crons: [{ schedule: "0 1 * * *", name: "daily", handler: async (event, { sql }) => { ... } }],
|
|
}
|
|
```
|
|
|
|
- `CLAUDE.md` — add D1/cron bullets in "Commands" (npm run db:migrate)
|
|
|
|
- `README.md` — light touch: mention D1 + cron in "Why" bullets + update architecture snapshot tree
|
|
|
|
### Plan Output Docs
|
|
|
|
- Update `plans/260415-1010-d1-cron-infra/plan.md` — mark all phases Complete
|
|
|
|
## Todo List
|
|
|
|
- [x] Draft `docs/using-d1.md`
|
|
- [x] Draft `docs/using-cron.md`
|
|
- [x] Update `docs/adding-a-module.md`
|
|
- [x] Update `docs/architecture.md`
|
|
- [x] Update `docs/codebase-summary.md`
|
|
- [x] Update `docs/code-standards.md`
|
|
- [x] Update project `CLAUDE.md`
|
|
- [x] Update `README.md`
|
|
- [x] Mark plan phases complete
|
|
|
|
## Success Criteria
|
|
|
|
- A dev unfamiliar with Cloudflare Workers can follow `using-d1.md` + `using-cron.md` to add a persistent scheduled feature without reading framework internals.
|
|
- Internal docs reflect shipped state (no stale references to KV-only).
|