# 开发指引

## 开始项目

```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 <新文件>` 导出并审查。报告实际结果及未测范围，删除本次废弃内容，保留无关修改。