Initial Dever 0.0.1

skills/references/development.md

@@ -0,0 +1,57 @@
+# 开发指引
+
+## 开始项目
+
+```sh
+dever new my_app
+dever check my_app
+dever test my_app
+dever run my_app -- hello.greeting.greet '{"name":"Dever"}'
+```
+
+目标目录须不存在，父目录须存在。模板带源码、测试、配置和说明；替换演示功能时同步替换相应用例。
+
+## 项目组织
+
+源码使用 `.dever`。每个领域放 README、主题 doc 和自动 link.md，结构见 [文档写法](documentation.md)。业务角色按需要创建：
+
+| 角色 | 职责 |
+| --- | --- |
+| App | 公开能力和业务编排，跨领域只调用目标 App |
+| Domain | 本领域内部规则 |
+| Model | 数据结构、查询和迁移，只由本领域 App 操作 |
+| API | HTTP/CMD 绑定和自动 REST |
+| Port / Adapter | 外部操作声明及实现 |
+| Job | 绑定本领域 App 的持久任务 |
+
+函数用 ASCII lowerCamelCase，字段、局部值和目录用 snake_case，类型用 UpperCamelCase。不建 common/shared/utils/helper/base/service 目录。
+
+同一职责的函数放在同一文件，也可按主题写入 `app/publish.dever`。App/Domain/Port/Adapter/Job 的主文件与目录二选一；Model/API 可共存。只有 API 主题目录可递归并影响 URL。
+
+## 实现
+
+- 先读相关领域 README、主题、调用图和源码。可用 `dever inspect . --symbol component.domain.function --depth 2` 查询上下游，不默认读取全项目索引。
+- 普通 CRUD 使用 Model 和 REST，有额外业务规则再写 App。复用标准库和组件，不为每次调用套 helper、repository 或转发层。
+- 外部输入在入口验证；内部不重复检查已确定的类型。权限、归属和可变状态仍由所属逻辑检查。
+- 错误按声明传播，不用默认成功、空集合或测试数据掩盖失败。不为假想情况加兜底、重试或备用实现。
+- Model Text 默认去首尾空白；raw 保留原文，lower/upper 转换大小写。不要在业务代码重复清洗。
+- 环境配置放 `config/setting.json`，身份和归属取可信上下文。业务程序不从环境变量读取配置，真实凭据不提交。
+- 只实现当前需求，不写无调用方的扩展。Dever 源码不写说明注释；必要解释放主题 doc，句子要具体，不填“操作参数”等空话。
+
+项目不设置 `dever.version`；编译器跟随开发环境，依赖由 `dever.lock` 锁定。
+
+## 修改后检查
+
+```sh
+dever fmt . --check
+dever check .
+dever test . --filter component.domain.case
+dever inspect . --links
+dever inspect . --links --check
+```
+
+测试使用 assert/assertEq。用例主题转为 lowerCamelCase 入口，例如 `account_login.dever` 对应 `accountLogin() ()`。每例默认 60 秒，可用 `--timeout-ms` 调整；无匹配用例会报错。
+
+Port 用每例独立 fake，Model 使用临时 SQLite，不连接部署数据库。check 也检查配置、接口基线及生产入口可达性；测试调用不能代替生产调用。重复实现和业务合理性仍需审查。
+
+修改实现时同步受影响的主题说明、测试和调用图。已有 `dever.api` 不直接覆盖；接口变更先用 `dever api . --output <新文件>` 导出并审查。报告实际结果及未测范围，删除本次废弃内容，保留无关修改。