gly-hub/ai-dandelion/technical-doc-builder

Technical Doc Builder

Purpose

Turn an applied product document into an implementation-ready technical design. Make all interaction, data, action, and file contracts explicit so code generation can implement without inventing the product. Stop before writing code or generated app files.

Authority Scope

This skill is only authorized to create or update the technical draft document specified by draft 文件.

Allowed:

• Read the applied product document from documents/product/applied/product-doc.md.
• Read generated-app-builder reference files such as references/structure.md and references/style-guide.md from that skill when generated-app-builder is injected.
• Write exactly one file: generated_apps/<app-id>/documents/technical/draft/technical-doc.md, or the exact draft 文件 path from the prompt.

Forbidden:

• Do not modify product documents under documents/product/.
• Do not modify generated app code, frontend files, backend files, manifest.json, backend.wasm, or platform source code.
• Do not run build commands, regenerate WASM, edit config, edit proto files, or call backend APIs.
• Do not perform code repair even if the user asks in the technical conversation. Instead, describe the technical requirement and leave implementation to the generated-app/code generation session.
• Do not change applied technical docs directly; only the draft file may be written.

If a user request in the technical conversation asks for product scope changes, send it back to the product step. If it asks for code changes, capture the requirement in the technical contract only when appropriate, but do not edit code.

Func-Operation Prompt Contract

The frontend sends a short prompt like:

使用 `technical-doc-builder` 技能。
功能名称：...
产品文档（applied）：generated_apps/<app-id>/documents/product/applied/product-doc.md
draft 文件：generated_apps/<app-id>/documents/technical/draft/technical-doc.md

When you see this shape:

1. Read the applied product document from the given path first.
2. Use TaskCreate and TaskUpdate to plan and execute the current request. The final task must be the technical-document completion action.
3. Read generated-app-builder references/structure.md and references/style-guide.md when available; align the technical contract with both.
4. Before writing the document, decide whether implementation-critical facts are missing. If missing facts would change data models, actions, layout, validation, or generated-app contracts, use AskUserQuestion instead of writing the draft.
5. Draft the technical document strictly from the product doc and generated-app contracts; do not expand scope.
6. Write the full document to the exact draft 文件 path only after the implementation contract is clear enough (overwrite if exists).
7. Reply with 1-3 sentence summary only; do not paste the full document in chat.
8. Only after the complete draft is written, call submit_technical_document_draft with a concise summary. Never call it while waiting for clarification, blocked, or before the file is complete.
9. Never emit XML tags, bracketed completion markers, or text status tags in chat or in the document.

Document Storage

generated_apps/<app-id>/documents/technical/draft/technical-doc.md
generated_apps/<app-id>/documents/technical/applied/technical-doc.md

Hard Rules

• Read applied product doc before drafting.
• Read generated-app-builder structure and style references before drafting when they exist.
• No final code, generated files, or migration scripts.
• Sections 2, 4, and 8-16 must be concrete enough that generated-app-builder can implement without redesigning layout, structure, data models, action names, frontend states, visual style, or observability.
• Overwrite draft with the latest complete document; never append partial content.
• Do not produce generic architecture prose. Every page, component, action, state, and table must map to the requested feature.
• Do not design a generated page that only renders document summaries, AI output, API notes, or implementation plans.
• If the repository has doc/func-operation/interaction-design.md, follow its layout and workflow conventions for usage/design mode, preview behavior, recovery actions, and user-facing terminology.
• Use the standard generated-app style guide when planning frontend layout. If available, refer to generated-app-builder references/style-guide.md for visual tokens, component sizes, scoped CSS, and responsive behavior.
• Use one stable action naming scheme across Section 4, Section 10, Section 11, and Section 12. Do not mix names such as createBook, book_create, and create for the same operation.
• Define a concrete WASM logging contract in Section 16 for every backend action. It must identify the diagnostic markers, severity, permitted fields, and sensitive-field redaction needed for incident investigation.
• Do not leave placeholders such as <business>, <entity>, 待生成, 根据情况, or TODO in the final technical document.
• Do not write unresolved questions, "待确认问题", assumptions needing confirmation, or implementation TBDs into the final technical document. Clarify first, then produce a complete implementation contract.

Quality Bar

A good technical doc must let the next agent implement the app by following contracts rather than making product decisions. It must specify:

• Exact page layout and regions.
• Frontend component/module responsibilities.
• User actions, request payloads, response shapes, and state updates.
• Which actions are button-permission-controlled versus read-only defaults.
• Business data models, relations, and named query capabilities.
• Validation and error handling.
• Empty/loading/success/failure UI states.
• Standard visual style and CSS module responsibilities.
• Acceptance checks for the generated app.

Generated-App Handoff Contract

The technical document is the direct handoff to generated-app-builder. It must include a complete mapping across these layers:

If non-critical details are absent, choose a conservative default and state the chosen behavior directly in the relevant section. If any row cannot be filled without changing scope or implementation contracts, ask the user before writing the draft. Do not leave implementation-critical gaps in Sections 8-16.

Required Structure

1. 模块拆分
2. 页面与组件设计
3. 数据模型
4. API 设计
5. 状态流转与校验规则
6. 异常与空状态处理
7. 实施步骤
8. 代码目录与文件清单（对接 generated-app-builder）
9. Manifest 与表结构约定
10. 后端 Action 清单
11. 前端模块拆分
12. 前端交互流程与状态合同
13. 样式规范与视觉一致性
14. 验收与自检清单
15. App Skill 契约
16. 可观测性与 WASM 日志

Prefer actionable detail over abstract advice.

Required Output Template

Use this section shape in the generated technical document. The content can be concise, but each table must be complete enough for code generation.

# <功能名称> 技术设计
 
## 1. 模块拆分
## 2. 页面与组件设计
## 3. 数据模型
## 4. API 设计
## 5. 状态流转与校验规则
## 6. 异常与空状态处理
## 7. 实施步骤
## 8. 代码目录与文件清单（对接 generated-app-builder）
## 9. Manifest 与表结构约定
## 10. 后端 Action 清单
## 11. 前端模块拆分
## 12. 前端交互流程与状态合同
## 13. 样式规范与视觉一致性
## 14. 验收与自检清单
## 15. App Skill 契约
## 16. 可观测性与 WASM 日志

Do not add a "待确认问题" section. If the document would need that section, stop and ask the user before writing the draft.

Section 1: 模块拆分

Split by runtime responsibility:

• Frontend UI modules.
• Frontend API/state modules.
• Backend action handlers.
• Data model and validation helpers.

Do not write broad layered architecture unless each module maps to files in Section 8.

Recommended table:

Every file listed here must also appear in Section 8.

Section 2: 页面与组件设计

For every page or region, include:

• Layout: table/list/card/form/modal/detail/filter bar/action bar.
• Visible fields and field order.
• Primary and secondary buttons.
• Event behavior for each button.
• Responsive behavior for narrow screens.
• Loading, empty, error, and success states.

Use a concrete layout sketch:

顶部操作栏：搜索 / 筛选 / 新建
主体：记录表格
右侧或弹窗：新建/编辑表单
底部：分页或统计

Required table:

Rules:

• The first screen must show the main working view and primary action.
• List each modal or detail panel as its own component.
• Name buttons exactly as they should appear in the UI.
• Every 触发 action must exist in Section 4 and Section 10.

Section 3: 数据模型

Define logical entities before backend actions. Include field purpose, validation, and UI usage.

Example:

Required table:

Rules:

• Use business names here, not physical table names.
• Include enum/status values and their display labels.
• Include whether fields appear in list, detail, form, filters, or badges.
• Keep fields compatible with manifest dataModels in Section 9.

Section 4: API 设计

Every API action must include:

• Action name string.
• Request shape.
• Response shape.
• Frontend caller.
• Backend handler.
• State update after success.
• Error handling shown to the user.

Use one envelope consistently:

{ "action": "create", "data": { "...": "..." } }

Backend responses should use:

{ "success": true, "data": {}, "error": "" }

or, for lists:

{ "success": true, "rows": [], "total": 0, "error": "" }

Required table:

权限模式 must be one of:

• button_controlled: must be written into manifest.actions, requires context.can(action) for button display, and requires backend button permission validation.
• read_default: must not be written into manifest.actions; UI controls remain visible by default and backend falls back to menu-level access only.

Action naming rules:

• Use lower snake/camel-free simple names unless a domain prefix is needed: list, detail, create, update, delete, change_status.
• For multi-entity apps, prefix by entity: student_list, class_list, department_list.

Permission rules:

• Any action that changes business state must be button_controlled.
• Read actions such as *_list, *_detail, *_query, *_search, *_page, *_stats must be read_default unless the product doc explicitly says otherwise.
• frontend/api.js, backend dispatch action names, and manifest.actions must use exactly the same action keys.
• manifest.actions must be documented and generated as a JSON string array only, for example ["class_create", "class_update"]; do not place label/mode objects into manifest.actions.
• Use exactly the same string in frontend API wrappers and backend dispatch.
• Do not use Chinese action strings.

Response rules:

• List actions return rows and total.
• Detail/create/update/status actions return data.
• Delete/archive actions return { "success": true } or updated data.
• Failures return success: false and a user-readable error.