把步骤、配方、清单与运行手册当成同一套内部手册结构

你是 Codex。请在 Cloudflare 上构建一个名为“社内マニュアル魔法 / Internal Manual Spell”的 production-shaped prototype。

你的任务不是写概念页。你的任务是实现一个真正可运行的 internal manual system prototype，把 business procedures、recipes、operating instructions、cautions、prerequisites、revision history 当成同一套 unified manual structure。

以高自主、非交互方式执行。
不要提出澄清问题。
自行做出合理假设，并以清晰代码、注释、类型安全、输入校验与可部署性完成端到端实现。

Project goal

构建一个可复用的 internal manual system，用于 operational procedures、recipes、SOPs、checklists、workstation instructions、service flows、cleaning routines、opening / closing tasks 等内部运营文档。

系统必须支持:
1. structured manual content
2. step-by-step procedure rendering
3. recipe-style and operation-style document types
4. role-based access control
5. revision awareness
6. search
7. operation flow / reading order
8. recent updates visibility
9. staff-only portal capability
10. admin metadata and revision inspection
11. print-friendly and mobile-friendly reading
12. content sync from repository-based source files

Core product concept

把 procedures、recipes、operations 当成同一个父 manual structure。

系统必须让人容易理解:
- 做什么
- 按什么顺序做
- 需要哪些 tools 或 materials
- 有哪些 cautions
- 谁应该阅读
- 当前版本是什么
- 最近改了什么

这不只是 general knowledge base。
它是一套 structured internal manual foundation，其中 operational sequence、required items、warnings、version control 都是 first-class。

在代码注释与命名中可使用以下 framing:
- Procedure Familiar = 结构化 steps、prerequisites、tools、materials、cautions、checks
- Access Familiar = 控制谁能读什么
- Revision Familiar = 保留 version flow，避免旧 instructions 无声滞留

架构还必须为未来接入这些扩展做好准备:
- training portals
- onboarding flows
- sign-off / read acknowledgement flows
- restricted departmental manuals
- policy distribution
- incident response runbooks

Non-goals for this prototype

不要做 full CMS。
不要做 collaborative rich-text editor。
不要做 full HR training compliance tracking。
不要做 e-signature workflows。
不要把 video hosting 设为 required dependency。
不要把权限模型复杂化到 practical staff / admin model with role-aware filtering 之外。

Fixed stack

除非绝对不可能，否则严格使用以下 stack:
- Frontend: Astro + TypeScript
- Interactive UI where needed: minimal React islands
- Content source: repository 内的 Markdown or MDX files
- Backend / API: Cloudflare Pages Functions 或 Cloudflare Workers，选择最简单的 Cloudflare-native route
- Database: Cloudflare D1
- Auth: Cloudflare Access compatible staff gate
- Search: 针对 metadata 与 step text 的 lightweight server-side search index
- Validation: Zod
- Testing: Vitest at minimum
- Styling: clean CSS，content-first，不需要 UI library

Architecture

使用如下 repository layout:
- apps/web = Astro frontend 与 admin UI
- content/manuals = Markdown or MDX source files
- packages/shared = shared types、validation schemas、content parsing、search、access logic、revision logic

如果你选择更简单的结构，也必须清楚分开:
- manual source content
- content sync and parsing
- metadata / revision logic
- access control
- search
- frontend rendering
- admin inspection views

Functional requirements

1. Structured manual types

至少支持这些 manual content types:
- procedure
- recipe
- checklist
- runbook
- troubleshooting

每个 manual document 至少支持以下 metadata:
- title
- slug
- summary
- manual type
- section
- chapter optional
- visibility
- status
- version label
- tags
- audience label optional
- estimated time optional
- prerequisites optional
- tools optional
- materials or ingredients optional
- related documents optional
- reading order optional
- operation flow key optional
- updated at timestamp

2. Step-based procedure structure

每个 manual 必须支持清晰的 structured steps。

每个 step 支持:
- step number
- title optional
- instruction text
- duration minutes optional
- caution text optional
- quality check or success condition optional
- note optional

这种结构必须在 UI 中清楚呈现。
不要把 procedures 降级成不成结构的大段文本。

3. Recipe and operation structure

recipe-style manuals 应能展示:
- ingredients or materials
- quantity text
- yield or batch note optional
- preparation notes
- ordered steps

operation-style manuals 应能展示:
- prerequisites
- tools
- opening / closing or execution sequence
- checkpoints
- failure or troubleshooting notes

4. Role-based access control

实现适合 internal manuals 的 access control。

至少支持:
- staff
- manager
- admin

如有必要也可支持 public 或 authenticated，但默认前提是 internal staff documentation。

access control 必须作用于:
- page rendering
- API responses
- search results
- navigation lists
- update feeds

不要把受保护文档的 metadata 泄露给未授权用户。

5. Revision and update model

实现 revision-aware structure。

每个 manual 必须支持:
- one canonical current version
- revision metadata
- updated_at timestamp
- changelog summary optional
- revision history in D1

在 prototype 中:
- manual source 存在 Markdown or MDX
- metadata 与 revision records 存在 D1
- UI 展示 last updated 与 version
- 提供 recent updates feed

不需要 in-browser editor，但内容维护流程必须真实且清晰。

6. Search

实现针对 accessible manual content 的 working search。

search 必须支持:
- title
- summary
- tags
- section
- manual type
- step text
- caution text where practical

search results 必须:
- 遵守 access control
- 链接到 manual pages
- 展示 manual type 与 updated date
- 如可行，支持按 type 或 section 过滤

7. Operation flow / ordered navigation

实现 operation flow 或 ordered manual sequence capability。

至少要有:
- manuals can belong to an operation flow
- manuals can have sequence numbers inside a flow
- UI can show previous and next manual
- UI can show “start here” for a flow

至少创建一个 example operation flow，例如:
- Opening Shift Flow
或
- Daily Kitchen Prep Flow

8. Manual page experience

每个 manual page 必须清楚展示:
- title
- summary
- manual type
- version
- last updated
- section or chapter
- audience or visibility label where appropriate
- prerequisites
- tools or ingredients where appropriate
- numbered steps
- cautions
- related manuals
- previous / next links when part of a flow

同时支持:
- print-friendly layout
- compact mobile reading
- optional checklist mode with local state only

Checklist mode 可以只用 client-side local state，不需要 server persistence。

9. Recent updates visibility

实现 updates feed，显示:
- recently changed manuals
- version label
- update date
- changelog summary where available

这样可以防止旧 instructions 在无感中长期残留。

10. Admin / staff inspection view

构建一个 staff-only admin area，用于:
- list manuals
- filter by type, visibility, section, status
- inspect manual metadata
- inspect step structure
- inspect revision history
- inspect recent update events
- inspect operation flow structure
- trigger content sync manually

不要把它过度做成 CMS。保持 operational 与 readable。

11. Content sync from repository

实现 content sync flow，能够:
- 从 content directory 读取 Markdown or MDX files
- 用 Zod 校验 frontmatter 与 step structure
- 向 D1 插入或更新 metadata
- 当 source content 改变时创建新的 revision records
- 刷新 search index data

sync 必须 deterministic 且有文档说明。

12. Future readiness

架构必须允许未来支持:
- read acknowledgement
- departmental targeting
- media attachments
- import from external source repositories
- scheduled sync jobs
- richer identity provider integration

你现在不需要全部实现，但结构不能阻碍这些能力。

Data model

至少在 D1 schema 中实现这些 tables:

manual_documents
- id
- slug
- title
- summary
- manual_type
- section_key
- chapter_key nullable
- visibility
- status
- version_label
- audience_label nullable
- source_path
- tags_json
- prerequisites_json nullable
- tools_json nullable
- materials_json nullable
- yield_text nullable
- estimated_minutes nullable
- reading_order nullable
- operation_flow_key nullable
- current_revision_id nullable
- created_at
- updated_at

manual_steps
- id
- manual_document_id
- step_number
- title nullable
- instruction_markdown
- duration_minutes nullable
- caution_text nullable
- quality_check_text nullable
- note_text nullable
- created_at
- updated_at

manual_revisions
- id
- manual_document_id
- revision_number
- version_label
- source_hash
- changelog_summary nullable
- rendered_excerpt nullable
- created_at
- created_by nullable

operation_flows
- id
- flow_key
- title
- description
- visibility
- created_at
- updated_at

operation_flow_items
- id
- operation_flow_id
- manual_document_id
- sequence_number
- created_at

update_events
- id
- manual_document_id
- revision_id
- event_type
- payload_json
- created_at

search_index 只有在明显提升实现 practicality 时才添加。
不要把 first prototype 无谓地膨胀。

Content source model

将 manual source 保存为带 frontmatter 的 Markdown or MDX files。

frontmatter 至少支持:
- title
- slug
- summary
- manualType
- section
- chapter
- visibility
- status
- version
- updatedAt
- tags
- audience
- estimatedMinutes
- prerequisites
- tools
- materials
- yieldText
- operationFlow
- flowOrder
- changelogSummary

source file 还必须支持 structured step data。
选择最简单但仍然 robust 的方式，例如:
- YAML frontmatter with a steps array of objects
或
- MDX components for steps

用 Zod 校验 content model。

Security

实现安全实践:
- 用 Zod 校验所有 content metadata
- 校验所有 API input
- 用明确的 auth middleware stub 保护 staff / admin routes
- 不要通过 search、navigation、update feeds 暴露 protected manuals
- sanitize search input
- 返回有用但不过度泄露的 error messages

API design

实现大致如下的 JSON endpoints:

User-facing:
GET /api/manuals/navigation
GET /api/manuals/search?q=...
GET /api/manuals/:slug
GET /api/manuals/updates
GET /api/flows
GET /api/flows/:flowKey

Admin:
GET /api/admin/manuals
GET /api/admin/manuals/:slug
GET /api/admin/revisions/:slug
GET /api/admin/flows
GET /api/admin/access-summary
GET /api/admin/update-events
POST /api/admin/sync-content

命名可以调整，但这些能力必须保留。

Frontend pages

至少构建这些 pages:
- / = concise landing page
- /manuals = manual home
- /manuals/section/[section] = section page
- /manuals/[slug] = manual detail page
- /flows/[flowKey] = operation flow page
- /search = search page
- /updates = recent updates page
- /admin = admin summary page
- /admin/manuals/[slug] = admin manual detail page

UX requirements

UI 必须:
- clean
- responsive
- content-first
- 在 mobile 上也高度可读
- 能在 kitchens、shops、clinics、offices、back rooms 的 tablet 上使用
- 在真实操作中保持 calm and legible

manual pages 应针对实际工作优化:
- large readable step numbering
- clearly separated cautions
- clearly separated tools / materials
- minimal decorative clutter
- fast access to next / previous related procedure
- print-friendly layout
- good heading hierarchy

search 要让一线 staff 用起来足够快且实用。

Copy 可为 bilingual-ready，但 prototype 若只做 English 也可接受，只要 strings centralized。
如果不拖慢开发，也可以支持 Japanese labels。

Seed / demo content

至少 seed 5 个 manual documents，覆盖 2 个以上 sections。

示例:
- Opening Shift Checklist
- Closing Shift Checklist
- Espresso Recipe Card
- Surface Sanitization Procedure
- POS Refund Operation
- Emergency Contact Runbook

还需 seed:
- at least 1 operation flow
- at least 1 recent update event
- mixed visibility examples such as staff and manager
- at least 1 troubleshooting-style document

Developer experience

提供:
- clear README
- local setup instructions
- D1 migration instructions
- content authoring instructions
- content sync instructions
- Wrangler configuration
- sample .dev.vars or environment variable documentation
- scripts for dev, test, build, sync, and deploy

Environment variables

至少定义并记录:
- BASE_URL
- DEFAULT_TIMEZONE
- ACCESS_MODE
- STAFF_SHARED_SECRET
- CONTENT_SYNC_ON_START
- SEARCH_INDEX_MODE

如未来 identity integration 需要，可加入:
- ACCESS_AUDIENCE
- ACCESS_TEAM_DOMAIN
- GOOGLE_CLIENT_ID
- GOOGLE_CLIENT_SECRET

但 prototype 必须在无 external providers 的情况下可运行。

Implementation guidance

优先保证 structure、access control、revision awareness、step rendering 的正确性，而不是视觉花哨。
content model 要让非工程维护者也能理解。
search 与 access filtering 必须是 server-authoritative。
domain logic 应放在 reusable modules，而不是埋在 route handlers 中。
不要用 fake static JSON 取代作为主流程核心的 content sync、search、access logic。

Tests

至少添加这些 tests:
- frontmatter validation
- step structure validation
- content sync behavior
- revision creation / update logic
- access filtering
- search filtering
- operation flow ordering
- protected content exclusion from unauthorized results
- recent updates feed logic

Acceptance criteria

当且仅当以下都成立时，prototype 才算 complete:
1. Staff can browse a manual home
2. Staff can open structured manual pages
3. Manual pages render ordered steps, cautions, and tools / materials correctly
4. Search works across accessible manuals
5. Protected manuals are hidden from unauthorized users
6. Metadata and revision records are stored in D1
7. Recent updates feed works
8. Operation flow navigation works with previous / next behavior
9. Admin can inspect metadata and revision history
10. Content source is Markdown or MDX driven
11. Content sync is functional and documented
12. The codebase is deployable to Cloudflare with documented steps
13. Tests run successfully

Output expectations

输出完整 codebase，而不是 snippets。

同时包括:
- D1 schema and migrations
- seed / demo manual content
- content sync logic
- README
- no placeholder skeletons for core flows
- no fake access / search logic in the main flow

Tone and naming

代码内部可以使用 practical English naming。
在 README 与 landing page 中描述系统为:
“社内マニュアル魔法 / Internal Manual Spell”

landing page 应体现:
- business procedures、recipes、operations handled in one structured manual foundation
- order、cautions、tools、materials、current-version awareness treated as one operational reference flow
- can later branch into staff portals、onboarding manuals、restricted departmental manuals、runbooks

Landing page content guideline

用以下 ideas 组织 concise landing sections:
- What spell it is
- What it can do
- Why it is useful
- Spell structure
- Familiars
- Grimoires
- Reproduction conditions
- Verification status

不要把 landing page 只做成 decorative。actual working manual portal 必须存在并被链接。

Final instruction

把它作为 future internal manual portals、operational recipe systems、structured procedure repositories 的 reusable parent spell 来实现。
优先追求 extensibility、clarity、operational realism、maintainability、auditability，而不是 hype。
交付一个真正可运行的 Cloudflare-native prototype。

Execution constraints:
- 不要停在 planning、scaffolding、summarizing
- 不要用 fake static JSON 取代 content sync、search、access filtering、revision logic
- 保持 access filtering server-authoritative
- 不要跳过 D1 migrations
- 不要跳过 seed / manual content
- 不要跳过 tests
- 不要再问已经给出的 requirements
- 如果出现 tradeoff，选择仍能完整满足 acceptance criteria 的最简单路径
- 尽量减少 preamble 与 status chatter
- 完成后简要总结 architecture、routes、environment variables、content model、local run / deploy steps

Implementation priority order:
1. content model and D1 schema
2. content parsing and sync pipeline
3. access filtering and search logic
4. manual page rendering
5. operation flow navigation
6. seeded demo manuals
7. admin inspection views
8. tests
9. README and deploy instructions