# 工程结构

一个用 `acdev new my-app --backend` 建出来的工程:

```text
my-app/
├── acde.config.jsonc    应用的配置: id、名字、图标、入口、能力
├── package.json
├── index.html           入口页面
├── src/main.js
├── src/i18n.js         选语言, 填上界面文字
├── src/locales/         每种语言一张文字表: en.js、zh.js
├── server.ts            后端 (可选)
├── public/              原样复制的静态文件 (可选)
└── .acde/               构建产物, 不进 git
```

## 界面语言

`html` 和 `desktop` 模板不把界面文字写在标记里, 而是放在 `src/locales/` 下每种语言一张的表里 (`en.js`、`zh.js`, 各自 `export default { key: 'text' }`). `src/i18n.js` 只用平台自带的能力, 不依赖库:

- `locale` 按 `navigator.language` 选: 有这个标签的表就用它 (`zh-TW.js`), 否则用它的基础语言 (`zh`, 经 `Intl.Locale`), 再否则用 `en`. 表里没有的 key 回落到英文的文字.
- `t(key, values)` 返回填好 `{name}` 占位符的文字.
- `translate()` 把 `<html lang>` 设成 `locale`, 并给每个带 `data-i18n="key"` 属性的元素填上文字; 在那之前 `index.html` 带的是 `lang="en"`.

要加一种语言, 加一个和 `en.js` 有同样 key 的 `src/locales/<tag>.js`, 再在 `i18n.js` 里导入它. 日期和数字用 `Intl` 和 `locale` 来格式化 (`new Intl.DateTimeFormat(locale)`). 框架模板保留各自脚手架写出来的界面.

## 配置和清单

- **`acde.config.jsonc`** 是你写的配置, 只在构建时读. `"type"` 是 `"app"` (一个窗口应用) 或 `"desktop"` (一个桌面).
- **清单** 是构建产物 `.acde/` 里 `package.json` 的 `acde` 字段. `.acde/` 这个目录就是一个**包**: 运行时跑的东西. 运行时只认清单.

`acdev build` 把前者变成后者. 绝大多数时候你只需要关心配置; 清单的格式见 [包清单](https://docs.dopame.ai/zh/reference/manifest.md).

没有 `acde.config.jsonc` 的目录也能构建:

- `package.json` 的 `acde` 字段里有 `apps` 的, 当作**手写的包**, 原样使用 (只检查);
- 否则当作默认应用: 入口 `index.html`, id 由 `package.json` 的 `name` 得出, 显示名取 `displayName` 或 `productName`.

## 构建出来的包

应用 `my-app` 构建后:

```text
.acde/
├── package.json         清单
├── web/                 网页, 在运行时里的地址是 /app/my-app/
└── backend/
    ├── server.js        打包好的后端
    ├── package.json     {"type": "module"}
    └── acde-listen.js   把后端的 listen 换成 unix socket 的 preload
```

桌面工程是 `desktop/` (地址 `/desktop/<id>/`)、`services/<名字>.js`, 以及自带应用的 `apps/<id>/{web,backend}`.

## JS 运行时和包管理器

工程跑在 Bun 还是 Node.js 上, 由包管理器决定: `bun` → Bun; `npm` / `pnpm` / `yarn` → Node.js. 已有的工程按 lockfile 判断, 再看 `package.json` 的 `packageManager` 字段; 两样都没有时, 工程跑在 acdev 自己跑的那个 JS 运行时上. `acdev new` 会写上 `packageManager`.

Node.js 上 acdev 用工程自己的 Vite 打包 (所以自带模板在 npm / pnpm / yarn 下会带上 `vite` 开发依赖); Bun 上用 `Bun.build`. 两边的打包规则相同.

## SDK

工程的开发依赖里有一个 `@dopame/acde-api`, 是这一版 acdev 自带的 SDK, 写的是它在这台机器上的路径 (`file:...`; SDK 不在 npm 上, 装了 acdev 的地方工程就装得上). `acdev new` 会装上它. 升级 acdev 之后, 工程的 SDK 比较旧时 `acdev check` 和 `acdev dev` 会说出来; `acdev sdk update` 把它升到这一版 acdev 配对的版本. 它提供:

- 所有 `acde:` 模块和清单的 TypeScript 类型 (只有声明: SDK 里没有 JavaScript)

在 JS 文件里引用类型:

```js
/// <reference types="@dopame/acde-api/app" />
```

TypeScript 工程在 `tsconfig.json` 的 `compilerOptions.types` 里加 `"@dopame/acde-api/app"`. 桌面的页面改用 `@dopame/acde-api/shell`, 它再加上只有桌面才拿得到的模块; `@dopame/acde-api` 声明全部.
