@wneng/create-keel 0.3.4 → 0.4.0

package/src/templates/docs-skeleton/files/governance-database.md

@@ -0,0 +1,150 @@
+---
+last-reviewed: 2026-05-16
+---
+
+# 数据库治理
+
+> 本文件统一回答："SQL / 索引 / 迁移 / 种子数据放哪个目录、与 `contracts/` 如何对齐"。
+>
+> 工具与命令的细节（哪个项目用 Knex / Flyway / Alembic / golang-migrate / ES applier）见各项目的 `server/db/README.md`，本文件不重复。
+>
+> 工具决策与 mongodb / sqlite 排除理由见 [`../02-系统方案与架构/adr-0005-database-conventions.md`](../02-系统方案与架构/adr-0005-database-conventions.md)。
+
+## 1. 五类 SQL 文件的归属
+
+数据库相关的产物分五类，每类只有一个合法位置：
+
+| 类型 | 例子 | 归属 | 与契约关系 |
+|---|---|---|---|
+| **schema migration**（DDL，版本化） | `V1__create_users.sql` / `0001_init.py` / `000001_init.up.sql` | `server/db/migrations/`（Java 走 `src/main/resources/db/migration/`） | 与 `contracts/openapi/` 中的字段对齐 |
+| **生产种子数据**（字典 / 码表） | 角色码表、状态枚举、错误码 lookup | `server/db/seeds/prod/`（Knex）/ 写入迁移文件（Flyway / Alembic / golang-migrate） | **真值在 `contracts/dictionaries/`**；当前手动同步 |
+| **开发种子数据**（fixture） | 样例用户、demo 商品、调试数据 | `server/db/seeds/dev/` | 与契约无关；不进生产 |
+| **存储过程 / 函数 / 视图 / 触发器** | `usp_calculate_amount.sql`、物化视图 | `server/db/procedures/` | 写入迁移文件，与代码同等对待 |
+| **运维脚本**（一次性） | 数据回填、重建索引、清理过期数据 | `scripts/db/<date>-<topic>.sql` | 与契约无关；不进生产迁移历史 |
+| **报表 / 分析 query**（BI 看板） | 仪表板背后的 SQL、临时调研 query | `docs/09-数据与埋点/`（启用 data 角色） | 与契约无关；与数据资产对齐 |
+
+> Elasticsearch 的"migration"指**幂等的 index-template apply**，不在上述 RDBMS 表里；其归属规则：JSON template 在 `server/db/index-templates/`（Java 走 `src/main/resources/index-templates/`），applier 脚本在 `server/db/`。详见各项目 `server/db/README.md`。
+
+## 2. 三类特殊场景
+
+### 2.1 跨 service 共享同一个 DB（微服务但 DB 没拆）
+
+DB schema 升格为契约：
+
+```
+contracts/schemas/db/
+├── README.md              # 谁是 schema 拥有者（"owner service"）
+├── ddl/                   # 真值；其他 service 视为 read-only
+│   ├── core_tables.sql
+│   └── views.sql
+└── CHANGELOG.md           # 改 schema 必须 bump SemVer
+server/apps/owner/db/migrations/   # 唯一执行迁移的 service
+server/apps/consumer/db/             # 不存 DDL，只存 ORM 映射
+```
+
+只有 owner service 的 PR 能改 `contracts/schemas/db/ddl/`；consumer service 改 → CI 拒（按 contracts/ 现有规则）。
+
+### 2.2 多租户 schema-per-tenant
+
+```
+server/db/migrations/
+├── shared/                # 公共 schema（账户、租户元数据）
+└── tenant/                # 应用到每个租户 schema 的迁移
+```
+
+文档说清楚"新租户 onboarding 要跑哪些 migrations"。
+
+### 2.3 多 database per service
+
+例如：postgres 主库 + elasticsearch 用作搜索。
+
+- 选第二个 fragment：手动从对应 `db-<backend>-<other>` 复制配置
+- 在 `server/db/README.md` 里说明双库各管什么
+- CI 起两个 service container
+
+scaffolder 0.4.0 不自动支持双库；用户合并两个 fragment 的内容。
+
+## 3. 与 `contracts/` 的同步规则
+
+### 3.1 字典数据 → 生产种子
+
+`contracts/dictionaries/enums.yaml` 是字典（角色 / 错误码 / 状态枚举）的真值。改字典的 PR 必须**同步**：
+
+- 加字典项 → 同 PR 在迁移文件中加 INSERT IGNORE / ON CONFLICT DO NOTHING
+- 改字典项的 name / description → 写新迁移更新对应行（不要改既有迁移）
+- 删字典项 → Tier 4，需 ADR
+
+> 当前是**手动同步**。自动派生（codegen）留给后续 `contract-derived-seeds` 特性。
+
+### 3.2 OpenAPI 字段 → DB 列
+
+OpenAPI 中的实体字段与 DB 表的列**应当**对齐（同名、同类型映射）。手动维护；governance-lint 不强制（语义 diff 太复杂）。
+
+### 3.3 AsyncAPI 事件 → ES index template
+
+`contracts/asyncapi/asyncapi.yaml` 中的事件 schema 与 `server/db/index-templates/` 中的 mapping **应当**对齐。当前手动同步。
+
+## 4. 改动分级（参见 `change-tiers.md`）
+
+| 改动 | Tier | 备注 |
+|---|---|---|
+| 新增 migration 加表 / 加字段 | 3 | 同 PR 改 `contracts/CHANGELOG.md`（如果字段进契约） |
+| 修改既有 migration 文件 | **不允许** | 写新 migration 代替；Flyway / Alembic / golang-migrate 都拒绝 |
+| 删字段 / 改类型（破坏性） | 4 | ADR + 详细设计 + 数据迁移预案 |
+| 改 dev seed | 1/2 | 不需要同步契约 |
+| 改 prod seed（字典数据） | 3 | 同 PR 改 `contracts/dictionaries/` |
+| 改 ES index-template 的 mapping | 4 | 破坏性 - 可能需要 reindex |
+| 改 ES index-template 的 priority / settings | 2 | 局部行为调整 |
+| 升级 Knex / Flyway / Alembic / golang-migrate / ES SDK | 2 | 同 PR 改 `tech-stack-server.md` 钉版本 |
+
+## 5. CI 行为
+
+每个 (backend, database) 组合的 CI 都跑 **migrate up + migrate down** smoke test：
+
+- RDBMS：`db-migrate-smoke` job 起 service container，跑 `npm run db:migrate && npm run db:rollback`（或对应工具命令）
+- ES：`db-es-template-apply` job 起 ES service container，跑 applier 脚本一次
+
+CI **不**校验：
+- schema 内容（用 DBA tool）
+- 与 `contracts/` 字段对齐（语义 diff 太复杂）
+- 数据回填脚本的正确性（一次性脚本不进 CI）
+
+## 6. 目录布局速查（非 multi-app 模式）
+
+```
+server/
+├── db/
+│   ├── README.md                      # 工具与命令（按 backend 不同）
+│   ├── migrations/                    # Knex / Alembic / golang-migrate 路径
+│   │   └── <ts/N>_<description>.<ext>
+│   ├── index-templates/               # ES applier 模式
+│   │   └── <ts>_<description>.json
+│   ├── seeds/
+│   │   ├── prod/                      # 字典数据；与 contracts/dictionaries 对齐
+│   │   └── dev/                       # 仅本地 / 测试
+│   └── apply-templates.{cjs,py,go}    # ES applier（按 backend）
+├── src/main/resources/db/migration/   # ← Java + Flyway 的迁移路径（与 server/db/ 分离）
+└── src/main/resources/index-templates/ # ← Java + ES applier 的 template 路径
+
+contracts/
+├── dictionaries/enums.yaml            # 字典真值（→ prod seed 派生）
+├── openapi/api.yaml                   # API 字段（→ DB 列对齐）
+└── asyncapi/asyncapi.yaml             # 事件 schema（→ ES mapping 对齐）
+
+scripts/db/                            # 一次性运维（数据回填等）
+└── 2026-05-backfill-tenants.sql
+
+ops/db/                                # DB 实例 / 权限 / 备份（IaC）
+└── grants/
+```
+
+## 7. multi-app 模式
+
+每个 `server/apps/<app>/` 自己一份 `db/`。共享 schema 时（多 app 同 DB）schema 真值进 `contracts/schemas/db/`，由 owner app 唯一执行迁移。完整规则与示例见 §2.1。
+
+## 8. 不在本特性范围内的（推到下次 spec）
+
+- mongodb 支持（详见 ADR-0005）
+- sqlite 支持（详见 ADR-0005）
+- contracts/dictionaries → seed migration 自动派生
+- web/mobile/miniapp 本地数据库（IndexedDB / SQLite / Realm）

package/src/templates/docs-skeleton/fragment.yaml

@@ -114,6 +114,12 @@ files:
   - from: files/governance-ai-access-modes.md
     to: docs/governance/ai-access-modes.md
     render: true
+  - from: files/governance-change-tiers.md
+    to: docs/governance/change-tiers.md
+    render: false
+  - from: files/governance-database.md
+    to: docs/governance/database.md
+    render: false
   - from: files/governance-checklists.md
     to: docs/governance/checklists.md
     render: true

package/src/templates/root-files/files/AGENTS.md

@@ -45,7 +45,9 @@
 | `.claude/`   | AI        | Claude Code slash-commands                           |
 <% } %>
 
-### 1.1 单应用 vs 多应用模式
+<% if (it.options.database !== 'none') { %>> **数据库相关产物**（已启用 `database=<%= it.options.database %>`）：`server/db/`（迁移、种子<% if (it.options.database === 'elasticsearch') { %>、ES index template<% } %>、运维脚本入口）的归属规则见 [`docs/governance/database.md`](docs/governance/database.md)。<% if (it.options.backend === 'java') { %> Java + <%= it.options.database === 'elasticsearch' ? 'spring-data-elasticsearch' : 'Flyway' %> 因 Spring Boot classpath 约定，<%= it.options.database === 'elasticsearch' ? 'index template' : '迁移' %>文件实际在 `server/src/main/resources/<%= it.options.database === 'elasticsearch' ? 'index-templates/' : 'db/migration/' %>`。<% } %>
+
+<% } %>### 1.1 单应用 vs 多应用模式
 
 每个执行环境目录（`server/` `web/` `mobile/` `miniapp/` `agent/`）默认处于**单应用模式**。需要容纳第二个应用时切换到**多应用模式**：
 
@@ -57,7 +59,7 @@
 
 ## 2. 不可协商原则
 
-- **Contract First**：契约定义优先于代码实现。
+- **Contract First**：契约定义优先于代码实现；变更触及契约时，**契约先冻结再写 code**（详见 §6 变更分级）。
 - 接口、事件、错误码、字典、状态机统一进入 `contracts/`，**禁止**在模块内部重复定义。
 - 由契约生成的 `generated/` 代码**禁止手改**；CI 校验"重新生成后 diff 为空"。
 - **禁止**提交 secret、私钥、真实 PII、真实用户数据。
@@ -93,6 +95,19 @@
 | 后端模块详细设计                          | `docs/04-后端详细设计/`                        |
 | 前端 / 客户端模块详细设计                 | `docs/05-前端客户端详细设计/`                  |
 <% if (it.options.integrations) { %>| 跨执行环境对接（已启用 `integrations`）   | `docs/06-集成对接/<consumer>-to-<producer>/`   |
+<% } else { %>| 跨执行环境对接（**未启用 `integrations`**，启用后位于此目录） | `docs/06-集成对接/`                            |
+<% } %><% if (it.options.roles && it.options.roles.includes('qa')) { %>| 测试计划 / 用例 / 缺陷库（已启用 qa 角色）| `docs/07-质量与测试/`                          |
+<% } else { %>| 测试计划 / 用例 / 缺陷库（**未启用 qa 角色**，启用后位于此目录） | `docs/07-质量与测试/`                          |
+<% } %><% if (it.options.roles && it.options.roles.includes('field')) { %>| 客户部署手册 / 上线作业书（已启用 field 角色，on-demand） | `docs/08-部署与现场实施/`              |
+<% } else { %>| 客户部署手册 / 上线作业书（**未启用 field 角色**） | `docs/08-部署与现场实施/`（启用后 on-demand）|
+<% } %><% if (it.options.roles && it.options.roles.includes('data')) { %>| 埋点契约 / 看板 / 数据资产（已启用 data 角色） | `docs/09-数据与埋点/`                       |
+<% } else { %>| 埋点契约 / 看板 / 数据资产（**未启用 data 角色**） | `docs/09-数据与埋点/`                          |
+<% } %><% if (it.options.roles && it.options.roles.includes('legal-security')) { %>| 合规清单 / PIA / 安全证据（已启用 legal-security 角色，on-demand） | `docs/10-合规与安全/` |
+<% } else { %>| 合规清单 / PIA / 安全证据（**未启用 legal-security 角色**） | `docs/10-合规与安全/`（启用后 on-demand） |
+<% } %><% if (it.options.roles && it.options.roles.includes('marketing')) { %>| 产品介绍 / 白皮书 / 案例（已启用 marketing 角色，on-demand） | `docs/11-市场与对外材料/`         |
+<% } else { %>| 产品介绍 / 白皮书 / 案例（**未启用 marketing 角色**） | `docs/11-市场与对外材料/`（启用后 on-demand） |
+<% } %><% if (it.options.roles && it.options.roles.includes('design')) { %>| 设计稿 / UI 规范（已启用 design 角色，on-demand） | `docs/design/`                                  |
+<% } else { %>| 设计稿 / UI 规范（**未启用 design 角色**） | `docs/design/`（启用后 on-demand）             |
 <% } %>| 治理细则（CI / 安全 / Git / 资产 / 等）   | `docs/governance/`（详见 §8）                  |
 | 架构图源、UI 稿、截图、设计稿             | `docs/assets/{diagrams,images,design}/`        |
 | 行业标准、厂商手册、法规、合规参考        | `docs/references/{standards,vendors,legal}/`   |
@@ -125,11 +140,28 @@
 - 完整规则 → [`docs/governance/integrations.md`](docs/governance/integrations.md)
 <% } %>
 
-## 6. 核心协作规则
+## 6. 核心协作规则（变更分级）
+
+变更分**六档**，文档与契约的"厚度"匹配影响面。完整判定决策树、反例、与 SemVer 关系 → [`docs/governance/change-tiers.md`](docs/governance/change-tiers.md)。
+
+| Tier | 典型 | 文档要求 | 契约动作 |
+|---|---|---|---|
+| 0 trivial | typo / 格式化 / patch 升级 / 补测试 | PR title + 1-2 行描述 | 不动 |
+| 1 bugfix | 修 NPE / SQL / UI 错位（无新行为） | PR 描述：重现 + 根因 + 修复 + 回归测试 | 不动 |
+| 2 small | 加按钮 / 排序 / 文案 / 配置项 | PR 描述（动机 + 方案 + 影响面） | 通常不动 |
+| 3 contract | 加 API / 字段 / 错误码 / 事件 / 状态 | 简短设计章节进 `docs/04` 或 `docs/05` | **必须**先冻结契约 + CHANGELOG |
+| 4 arch | 跨服务 / 鉴权变化 / 删字段 / breaking | PRD（如来自需求）→ ADR → 详细设计 → 契约 → code | **必须** ADR + 契约 + 迁移说明 |
+| 5 spike | 探索 / 方案未明 | `spike/*` 分支自由探索 | 合入 `main` 前补到对应 tier |
+
+**判定**：改 `contracts/` → 至少 Tier 3；改鉴权 / 跨服务 / 删字段 → Tier 4；纯局部 → 0/1/2；探索 → 5。
+
+**AI 引用义务**（按 tier 升级）：
+- Tier 0/1/2：PR 描述自身即方案记录，**不强制**引用契约或 ADR
+- Tier 3+：必须显式引用契约锚点（如 `contracts/openapi/api.yaml#/paths/~1users/post`）
+- Tier 4：必须引用 ADR / 详细设计文档
 
-- 先补契约和文档，再补实现。
-- AI 生成代码必须在 PR / commit 中显式引用契约锚点和设计文档。
-- `spike/*` 分支允许暂时跳过契约；合入 `main` 前必须补齐。
+其他：
+- `spike/*` 分支允许暂时跳过契约（即 Tier 5）；合入 `main` 前必须补齐到对应 tier
 - 完整 PR 模板与 CODEOWNERS → [`docs/governance/git-workflow.md`](docs/governance/git-workflow.md)
 - 契约 SemVer / CHANGELOG / 废弃流程 → [`contracts/README.md`](contracts/README.md)
 
@@ -146,7 +178,8 @@
 | `docs/assets/**` 或根 `.gitattributes` | `docs/governance/assets.md` |
 | `ops/**` 或 `deploy/**` | `docs/governance/deploy-ops.md`、`docs/governance/security.md` |
 | `tools/**` 或 `scripts/**` | `docs/governance/tools-scripts.md` |
-<% if (it.options.ci === 'gitee') { %>| `.gitee/**` | `docs/governance/ci.md`、`docs/governance/security.md` |
+<% if (it.options.database !== 'none') { %>| `server/db/**`（迁移 / 种子 / ES template / applier） | `docs/governance/database.md`、`contracts/dictionaries/`（如改字典 seed） |
+<% } %><% if (it.options.ci === 'gitee') { %>| `.gitee/**` | `docs/governance/ci.md`、`docs/governance/security.md` |
 <% } else { %>| `.github/**` | `docs/governance/ci.md`、`docs/governance/security.md` |
 <% } %>
 
@@ -174,6 +207,8 @@
 | 集成对接 | [`docs/governance/integrations.md`](docs/governance/integrations.md) |
 | ops / deploy 完整规则 | [`docs/governance/deploy-ops.md`](docs/governance/deploy-ops.md) |
 | tools / scripts 完整规则 | [`docs/governance/tools-scripts.md`](docs/governance/tools-scripts.md) |
+| 变更分级（六档 Tier） | [`docs/governance/change-tiers.md`](docs/governance/change-tiers.md) |
+| 数据库目录 / 迁移工具 / SQL 归属 | [`docs/governance/database.md`](docs/governance/database.md) |
 | 完整 checklist | [`docs/governance/checklists.md`](docs/governance/checklists.md) |
 | 治理细则索引 | [`docs/governance/README.md`](docs/governance/README.md) |
 

package/src/templates/server-node/files/_eslintrc.cjs

@@ -13,7 +13,11 @@ module.exports = {
   extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
   rules: {
     '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
-    '@typescript-eslint/no-explicit-any': 'warn',
+    // docs/03-工程规范与研发基础设施/coding-style-typescript.md forbids `any`.
+    // Use `unknown` + narrowing, or define the missing type. Escape hatch:
+    // a per-line `// eslint-disable-next-line @typescript-eslint/no-explicit-any`
+    // with a comment explaining why.
+    '@typescript-eslint/no-explicit-any': 'error',
     '@typescript-eslint/consistent-type-imports': 'warn',
   },
   ignorePatterns: ['dist', 'node_modules', 'generated'],

package/src/templates/server-python/files/README.md

@@ -1,4 +1,77 @@
 # server/
 
-Python backend for **<%= it.options.projectName %>**. Contract-first; see
-`contracts/openapi/api.yaml` for the authoritative API definition.
+Python backend for **<%= it.options.projectName %>**, built on **FastAPI**.
+
+> Contract First：路由 / 请求体 / 响应体应当与 [`../contracts/openapi/api.yaml`](../contracts/openapi/api.yaml) 对齐。新增端点的工作流见根 `AGENTS.md` §6（变更分级）+ `docs/governance/change-tiers.md`：端点新增 / 字段新增是 Tier 3，必须先冻结 contracts 再写实现。
+
+## 目录布局
+
+```
+server/
+├── pyproject.toml             # 依赖钉版本、ruff / mypy / pytest 配置
+├── app/
+│   ├── __init__.py            # re-export `app` 给 `python -m app`
+│   ├── main.py                # FastAPI 实例 + /healthz + CORS
+│   └── config.py              # pydantic-settings；从环境 / .env 读配置
+└── tests/
+    └── test_healthz.py        # ASGI smoke test
+```
+
+## 工具与版本
+
+| 项 | 值 |
+|---|---|
+| Python | 3.11+ |
+| Framework | FastAPI `0.115.5` |
+| ASGI server | uvicorn `0.32.0` |
+| Validation | pydantic `2.9.2` + pydantic-settings `2.6.1` |
+| Lint / format | ruff `0.6.8+` |
+| Type check | mypy `1.11.0+`（strict-ish） |
+| Test | pytest `8.3.0+` + pytest-asyncio + httpx |
+
+版本钉死见 `pyproject.toml`，并镜像到 `docs/03-工程规范与研发基础设施/tech-stack-server.md`。governance-lint 检测两边漂移并阻断 PR。
+
+## 常用命令
+
+```bash
+# 创建虚拟环境 + 装依赖
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# 本地开发（热加载）
+uvicorn app.main:app --reload --port 8000
+# 浏览自动生成的 OpenAPI UI：http://127.0.0.1:8000/docs
+
+# 测试 / lint / format / typecheck
+pytest -q
+ruff check .
+ruff format --check .
+mypy .
+
+# 安全扫描
+pip-audit
+```
+
+## 配置
+
+环境变量优先级：CLI / 容器注入 > `.env` 文件 > `app/config.py` 默认值。
+
+|  变量 | 默认 | 说明 |
+|---|---|---|
+| `APP_NAME` | `<projectName>-server` | 显示在 OpenAPI title |
+| `APP_VERSION` | `0.1.0` | 显示在 OpenAPI version |
+| `CORS_ALLOW_ORIGINS` | `["http://localhost:5173","http://localhost:3000"]` | 逗号分隔；生产环境收紧 |
+
+## 部署
+
+打包 / 镜像 / 流水线归 `deploy/` 与 `ops/`，详见 [`../docs/governance/deploy-ops.md`](../docs/governance/deploy-ops.md)。最小生产命令示例：
+
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
+```
+
+## 与契约的同步
+
+- API 端点：`contracts/openapi/api.yaml` → `app/main.py` 路由；改契约同 PR 改实现
+- 字典 / 枚举：`contracts/dictionaries/enums.yaml`（如启用）→ Pydantic Enum
+- 错误码：`contracts/errors/error-codes.yaml` → Exception → HTTP status 映射

package/src/templates/server-python/files/app-init.py

@@ -1 +1,11 @@
-"""Package marker. Implement per contracts/openapi/api.yaml."""
+"""<%= it.options.projectName %>-server.
+
+Application package. Entry point: app.main:app
+Run locally: `uvicorn app.main:app --reload`
+
+Contract First：路由实现见 contracts/openapi/api.yaml；新端点先改契约再写代码。
+"""
+
+from .main import app
+
+__all__ = ["app"]

package/src/templates/server-python/files/config.py

@@ -0,0 +1,40 @@
+"""Application configuration via pydantic-settings.
+
+环境变量映射规则：
+  - 全部大写、`_` 分隔
+  - 嵌套字段用 `__` 分隔（pydantic-settings 默认）
+  - 例：APP_NAME / APP_VERSION / CORS_ALLOW_ORIGINS=http://localhost:5173,http://localhost:3000
+
+`.env` 文件由 pydantic-settings 自动加载（项目根目录）。
+"""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Runtime settings.
+
+    新增字段必须：
+      - 给默认值（不要让生产环境因缺一个变量启动崩溃）
+      - 同步更新根 `.env.example`（如启用 contracts-base fragment）
+      - 敏感字段（密钥、token）只能从环境变量读，绝不写默认值
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    app_name: str = Field(default="<%= it.options.projectName %>-server")
+    app_version: str = Field(default="0.1.0")
+
+    # CORS：逗号分隔字符串解析为列表
+    cors_allow_origins: list[str] = Field(
+        default_factory=lambda: ["http://localhost:5173", "http://localhost:3000"]
+    )
+
+
+settings = Settings()

package/src/templates/server-python/files/main.py

@@ -0,0 +1,62 @@
+"""<%= it.options.projectName %>-server entry point.
+
+Contract First：路由 / 请求体 / 响应体应当与 contracts/openapi/api.yaml 对齐。
+新增端点的工作流见根 AGENTS.md §6（变更分级）+ docs/governance/change-tiers.md：
+端点新增 / 字段新增是 Tier 3，必须先冻结 contracts/openapi/api.yaml 再写实现。
+"""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from .config import settings
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
+    """启动 / 关闭钩子。
+
+    在这里做：
+      - 数据库连接池初始化（如启用 db）
+      - Elasticsearch 客户端初始化（如启用 db=elasticsearch）
+      - 后台任务启动
+    关闭时反向清理。
+    """
+    yield
+
+
+app = FastAPI(
+    title=settings.app_name,
+    version=settings.app_version,
+    description="Generated by @wneng/create-keel; implement per contracts/openapi/api.yaml.",
+    lifespan=lifespan,
+)
+
+# CORS — 默认放开本地前端开发常用端口；生产请通过环境变量收紧 allow_origins
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_allow_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/healthz", tags=["meta"])
+async def healthz() -> dict[str, str]:
+    """Liveness 探针。
+
+    部署时由 Kubernetes / Docker Compose 周期性调用；返回非 200 即视为不健康。
+    """
+    return {"status": "ok"}
+
+
+@app.get("/", tags=["meta"])
+async def root() -> dict[str, str]:
+    return {
+        "name": settings.app_name,
+        "version": settings.app_version,
+        "docs": "/docs",
+    }

package/src/templates/server-python/files/pyproject.toml

@@ -2,13 +2,20 @@
 name = "<%= it.options.projectName %>-server"
 version = "0.1.0"
 requires-python = ">=3.11"
-dependencies = []
+dependencies = [
+  "fastapi==0.115.5",
+  "uvicorn[standard]==0.32.0",
+  "pydantic==2.9.2",
+  "pydantic-settings==2.6.1",
+]
 
 [project.optional-dependencies]
 dev = [
   "ruff>=0.6.8",
   "mypy>=1.11.0",
   "pytest>=8.3.0",
+  "pytest-asyncio>=0.24.0",
+  "httpx>=0.27.0",
   "pip-audit>=2.7.0",
 ]
 
@@ -47,3 +54,9 @@ exclude = ["generated", ".venv"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+asyncio_mode = "auto"
+
+# 显式声明应用包，避免 setuptools 把 generated/ 误认为顶层包导致 build error
+[tool.setuptools.packages.find]
+include = ["app*"]
+exclude = ["tests*", "generated*"]

package/src/templates/server-python/files/test_healthz.py

@@ -0,0 +1,36 @@
+"""Smoke test for the healthz endpoint.
+
+CI 跑 `pytest -q` 时会运行；端到端验证：
+  - FastAPI app 能 import（语法、依赖、配置都对）
+  - lifespan 钩子能起、能落
+  - /healthz 返回 200 + {"status": "ok"}
+
+新加端点应在 tests/ 下补对应测试；契约级断言（响应 schema 一致性）由
+contracts/tests/contracts/ 下的契约测试覆盖，不在这里重复。
+"""
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+
+from app.main import app
+
+
+@pytest.mark.asyncio
+async def test_healthz_returns_ok() -> None:
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.get("/healthz")
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+
+
+@pytest.mark.asyncio
+async def test_root_returns_metadata() -> None:
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.get("/")
+    assert response.status_code == 200
+    body = response.json()
+    assert body["name"].endswith("-server")
+    assert body["version"] == "0.1.0"
+    assert body["docs"] == "/docs"

package/src/templates/server-python/fragment.yaml

@@ -1,5 +1,5 @@
 name: server-python
-version: 1.0.0
+version: 1.1.0
 appliesWhen:
   backend: python
 priority: 30
@@ -12,6 +12,15 @@ files:
     render: true
   - from: files/app-init.py
     to: server/app/__init__.py
+    render: true
+  - from: files/main.py
+    to: server/app/main.py
+    render: true
+  - from: files/config.py
+    to: server/app/config.py
+    render: true
+  - from: files/test_healthz.py
+    to: server/tests/test_healthz.py
     render: false
   - from: files/generated-gitkeep
     to: server/generated/.gitkeep

package/src/templates/web-react/files/_eslintrc.cjs

@@ -27,7 +27,11 @@ module.exports = {
     'react/react-in-jsx-scope': 'off',
     'react/prop-types': 'off',
     '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
-    '@typescript-eslint/no-explicit-any': 'warn',
+    // docs/03-工程规范与研发基础设施/coding-style-typescript.md forbids `any`.
+    // Use `unknown` + narrowing, or define the missing type. Escape hatch:
+    // a per-line `// eslint-disable-next-line @typescript-eslint/no-explicit-any`
+    // with a comment explaining why.
+    '@typescript-eslint/no-explicit-any': 'error',
     '@typescript-eslint/consistent-type-imports': 'warn',
   },
   ignorePatterns: ['dist', 'node_modules', 'generated'],

package/src/templates/web-vue/files/_eslintrc.cjs

@@ -21,7 +21,11 @@ module.exports = {
   ],
   rules: {
     '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
-    '@typescript-eslint/no-explicit-any': 'warn',
+    // docs/03-工程规范与研发基础设施/coding-style-typescript.md forbids `any`.
+    // Use `unknown` + narrowing, or define the missing type. Escape hatch:
+    // a per-line `// eslint-disable-next-line @typescript-eslint/no-explicit-any`
+    // with a comment explaining why.
+    '@typescript-eslint/no-explicit-any': 'error',
     'vue/multi-word-component-names': 'off',
   },
   ignorePatterns: ['dist', 'node_modules', 'generated'],