@wneng/create-keel 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wneng/create-keel",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Scaffolder for Contract First + Vibe Coding projects (keel conventions)",
   "keywords": [
     "scaffold",
@@ -16,6 +16,8 @@
   "files": [
     "dist",
     "src/templates",
+    "src/feature/templates",
+    "src/standards/templates",
     "README.md",
     "LICENSE"
   ],

package/src/feature/templates/arch/adr.md.eta

@@ -0,0 +1,31 @@
+# ADR-<%= it.feature.nextAdrNumber %>：<%= it.feature.title %>
+
+> 状态：**Proposed**（<%= it.year %>）
+> 决策范围：<%= it.feature.title %>
+> 特性 slug：`<%= it.feature.slug %>`
+> 来源 PRD：[docs/01-背景与需求/prd-<%= it.feature.slug %>.md](../01-背景与需求/prd-<%= it.feature.slug %>.md)
+
+## 背景
+
+<!-- 为什么现在做出决定？什么约束或信号触发了这份 ADR？ -->
+
+## 决策
+
+<!-- 一段话说清决策结论，不含歧义。 -->
+
+## 备选方案
+
+- **方案 A** —— 优点 / 缺点 / 为何不采用
+- **方案 B** —— 优点 / 缺点 / 为何不采用
+
+## 影响
+
+### 正面
+- 列出正面影响
+
+### 负面 / 风险
+- 列出风险与缓解措施
+
+## 参考
+
+- 契约：[<%= it.feature.contractAnchor %>](../../<%= it.feature.contractAnchor %>)

package/src/feature/templates/backend/design.md.eta

@@ -0,0 +1,35 @@
+# 后端设计：<%= it.feature.title %>
+
+> 特性 slug：`<%= it.feature.slug %>`
+> PRD：[docs/01-背景与需求/prd-<%= it.feature.slug %>.md](../01-背景与需求/prd-<%= it.feature.slug %>.md)
+
+## 契约
+
+请求 / 响应形态的唯一真值源是 OpenAPI 文档。本设计文档与契约保持同步；
+两者不一致时以契约为准。
+
+- 路径：[<%= it.feature.contractAnchor %>](../../<%= it.feature.contractAnchor %>)
+
+## 模块边界
+
+<!-- 本特性涉及哪些模块？列出会变更的 controller / service / repository。 -->
+
+## 数据模型
+
+<!-- 新增表、字段、索引。引用 contracts/dictionaries/ 中的字典定义。 -->
+
+## 错误处理
+
+<!-- 错误码（DOMAIN.SUBDOMAIN.REASON）、HTTP 状态码映射、重试策略。 -->
+
+## 时序
+
+```
+client -> controller -> service -> repository -> db
+```
+
+## 测试计划
+
+- service 层单元测试
+- 与 `contracts/openapi/api.yaml` 的契约测试
+- 见：[docs/07-质量与测试/test-plans/<%= it.feature.slug %>.md](../07-质量与测试/test-plans/<%= it.feature.slug %>.md)

package/src/feature/templates/frontend/design.md.eta

@@ -0,0 +1,34 @@
+# 前端设计：<%= it.feature.title %>（web）
+
+> 特性 slug：`<%= it.feature.slug %>`
+> 后端设计：[docs/04-后端详细设计/<%= it.feature.slug %>.md](../04-后端详细设计/<%= it.feature.slug %>.md)
+
+## 用户流程
+
+<!-- 本特性在 web 端的逐步用户旅程。 -->
+
+## 页面 / 组件拆分
+
+| 组件 | 职责 |
+|------|------|
+| `<%= it.feature.slug %>Page` | 顶层路由组件 |
+| | |
+
+## 状态管理
+
+<!-- 本地状态、全局 store 切片、缓存失效规则。 -->
+
+## API 调用
+
+本特性通过 OpenAPI 契约调用后端。请由 `contracts/openapi/api.yaml` 生成
+客户端，避免手写 fetch 代码。
+
+- 契约：[<%= it.feature.contractAnchor %>](../../<%= it.feature.contractAnchor %>)
+
+## 校验
+
+<!-- 客户端校验规则；服务端是权威，但客户端校验能让错误 UX 更快。 -->
+
+## 无障碍
+
+<!-- 键盘导航、屏幕阅读器标签、对比度说明。 -->

package/src/feature/templates/pm/prd.md.eta

@@ -0,0 +1,37 @@
+# PRD：<%= it.feature.title %>
+
+> 特性 slug：`<%= it.feature.slug %>`
+> 由 `create-keel feature add` 在 <%= it.generatedAt %> 创建
+
+## 背景
+
+<!-- 描述用户问题与业务背景。替换本段。 -->
+
+## 目标
+
+- [ ] 主要目标
+- [ ] 次要目标
+
+## 非目标
+
+- 不在本次范围
+
+## 用户故事
+
+**作为** [角色]，**我希望** [能力]，**以便** [收益]。
+
+## 验收标准（EARS）
+
+下列标准使用 EARS 语法（WHEN / IF / WHILE / WHERE + THE \<system\> SHALL
+\<response\>）。请把占位描述替换为真实行为；保留 EARS 句型，让
+`governance-lint` 把这些条目识别为可测试规则。
+
+1. WHEN [触发事件发生时]，THE 系统 SHALL [可观察响应]。
+2. IF [出现意外情况]，THEN THE 系统 SHALL [错误处理 / 降级]。
+3. WHILE [处于某状态时]，THE 系统 SHALL [持续行为]。
+
+## 关联引用
+
+- 后端设计：[docs/04-后端详细设计/<%= it.feature.slug %>.md](../04-后端详细设计/<%= it.feature.slug %>.md)
+- 前端设计：[docs/05-前端客户端详细设计/<%= it.feature.slug %>-web.md](../05-前端客户端详细设计/<%= it.feature.slug %>-web.md)
+- 契约：[<%= it.feature.contractAnchor %>](../../<%= it.feature.contractAnchor %>)

package/src/feature/templates/sample/user-signup/arch/adr.md.eta

@@ -0,0 +1,48 @@
+# ADR-<%= it.feature.nextAdrNumber %>：<%= it.feature.title %>
+
+> 状态：**Proposed**（<%= it.year %>）
+> 决策范围：账户注册流程 + 验证模型
+> 特性 slug：`<%= it.feature.slug %>`
+> 来源 PRD：[docs/01-背景与需求/prd-<%= it.feature.slug %>.md](../01-背景与需求/prd-<%= it.feature.slug %>.md)
+
+## 背景
+
+PRD 要求自助注册账户并强制邮箱验证。本领域常见的实现模式有三种：应用内
+验证 token、邮件 magic link、邮件数字验证码。三者在安全与 UX 上各有权衡，
+选型会影响 `pending` 用户的存活时间以及鉴权模型的形态。
+
+## 决策
+
+采用 **基于服务端存储 token 的邮件 magic link**：
+
+- 注册时在 `users` 表创建 `pending` 行，并在 `verification_tokens` 表创建
+  一条 UUIDv4 token，TTL 24 小时
+- 验证邮件包含一条指向 `GET /auth/verify?token=...` 的链接
+- 成功时把用户切到 `active`，token 标记为已消费（一次性），并下发会话 cookie
+- 失败 / 过期时展示"重新申请链接"的 CTA
+
+## 备选方案
+
+- **数字验证码（6 位 OTP）**—— 在移动端输入更顺手，但桌面浏览器 UX 反而
+  更差，多了一步冗余输入。否决。
+- **不验证，只发邮件提示**—— 上线最快，但会让用户表充斥拼写错误与垃圾。
+  与 PRD 目标 #2 冲突。否决。
+- **仅联邦身份（Google / GitHub）**—— 适用场景下 UX 最佳，但会把没有这些
+  账户的用户挡在外面，且 PRD 把第三方登录明确列为 v1 非目标。否决。
+
+## 影响
+
+### 正面
+- 标准成熟方案，每种后端栈都有现成库支持
+- token 轮换策略简单（删除 + 新建一行）
+- `pending` → `active` 状态机清晰可审计
+
+### 负面 / 风险
+- 邮件送达率成为硬依赖，必须监控退信率
+- 24 小时 TTL 可能对一周才看一次邮箱的用户偏短；上线后根据转化遥测
+  数据再决定是否拉长
+
+## 参考
+
+- 契约：[<%= it.feature.contractAnchor %>](../../<%= it.feature.contractAnchor %>)
+- 关联：未来的 `password-reset` ADR 会复用同一张 token 表的 schema

package/src/feature/templates/sample/user-signup/backend/design.md.eta

@@ -0,0 +1,77 @@
+# 后端设计：<%= it.feature.title %>
+
+> 特性 slug：`<%= it.feature.slug %>`
+> PRD：[docs/01-背景与需求/prd-<%= it.feature.slug %>.md](../01-背景与需求/prd-<%= it.feature.slug %>.md)
+
+## 契约
+
+请求 / 响应形态的唯一真值源是 OpenAPI 文档。本设计文档描述**实现**；两者
+不一致时以契约为准。
+
+- 路径：[<%= it.feature.contractAnchor %>](../../<%= it.feature.contractAnchor %>)
+
+## 模块边界
+
+本特性涉及三个模块：
+
+- `auth/signup` —— 拥有 `POST /users/signup` 与 `GET /auth/verify`
+- `email` —— 拥有验证邮件的发送（模板 + 传输）
+- `users` —— 拥有 `users` 表与 `pending`/`active` 状态机
+
+## 数据模型
+
+```
+users
+  id            uuid PK
+  email         text UNIQUE NOT NULL
+  password_hash text NOT NULL          -- bcrypt cost 12
+  state         text NOT NULL          -- enum('pending','active','suspended')
+  created_at    timestamptz DEFAULT now()
+  activated_at  timestamptz NULL
+
+verification_tokens
+  token         uuid PK
+  user_id       uuid FK -> users.id NOT NULL
+  expires_at    timestamptz NOT NULL    -- created_at + 24h
+  consumed_at   timestamptz NULL
+```
+
+`users` 表上加索引 `users_email_lower_unique`（基于 `lower(email)`），
+保证大小写不敏感的唯一性。
+
+## 错误处理
+
+| 错误码 | HTTP | 触发场景 |
+|---|---|---|
+| `USER.AUTH.EMAIL_INVALID` | 400 | 邮箱不符合 RFC 5322 |
+| `USER.AUTH.PASSWORD_TOO_SHORT` | 400 | 密码不足 8 字符 |
+| `USER.AUTH.EMAIL_TAKEN` | 409 | 通用响应，不暴露邮箱是否存在 |
+| `USER.AUTH.RATE_LIMITED` | 429 | 对应 PRD 验收标准 4 |
+| `USER.AUTH.TOKEN_EXPIRED` | 410 | 验证链接超出 24 小时后被点击 |
+| `USER.AUTH.TOKEN_INVALID` | 400 | token 不存在或已被消费 |
+
+## 时序
+
+```
+POST /users/signup
+  controller 校验请求体
+    -> service.signup(email, password)
+        -> users.create(state='pending')
+        -> tokens.create(user_id, ttl=24h)
+        -> email.send_verification(user, token.token)
+    -> 201 Created { id, email, state }
+
+GET /auth/verify?token=...
+  controller -> service.verify(token)
+    -> tokens.consume(token)              # 拒绝过期 / 已用 token
+    -> users.activate(user_id)
+    -> session.create(user_id)
+  -> 302 重定向到 /welcome
+```
+
+## 测试计划
+
+- `service.signup` 的单元测试覆盖全部 6 种错误码
+- 针对 `contracts/openapi/api.yaml` 的契约测试
+- 属性测试：用同一 token 重复 verify 应当幂等
+- 见：[docs/07-质量与测试/test-plans/<%= it.feature.slug %>.md](../07-质量与测试/test-plans/<%= it.feature.slug %>.md)

package/src/feature/templates/sample/user-signup/frontend/design.md.eta

@@ -0,0 +1,54 @@
+# 前端设计：<%= it.feature.title %>（web）
+
+> 特性 slug：`<%= it.feature.slug %>`
+> 后端设计：[docs/04-后端详细设计/<%= it.feature.slug %>.md](../04-后端详细设计/<%= it.feature.slug %>.md)
+
+## 用户流程
+
+1. 访客从市场站点跳转到 `/signup`
+2. 填写邮箱 + 密码；客户端实时校验长度与格式
+3. 提交 → 按钮进入 loading → 成功或失败 toast
+4. 成功后页面切到"请查收邮件"，提供"重新发送"按钮
+5. 用户点击邮件中的链接 → 后端验证 → 302 跳到 `/welcome`
+
+## 页面 / 组件拆分
+
+| 组件 | 职责 |
+|------|------|
+| `SignupPage` | 顶层路由，持有表单状态与提交逻辑 |
+| `EmailField` | 提交前内联校验 RFC-5322 邮箱语法 |
+| `PasswordField` | 长度计 + 强度提示 |
+| `SubmitButton` | 两个字段都合法前禁用；请求中显示 loading 旋转图 |
+| `CheckEmailScreen` | 注册后确认页；带 60 秒冷却的"重新发送"按钮 |
+| `WelcomePage` | 验证后落地页 |
+
+## 状态管理
+
+- 表单字段使用组件本地 state，表单层无需全局 store
+- `useSignupMutation` 包装 API 调用，由 tanstack-query 处理重试策略
+- 鉴权会话在 `/welcome` 加载**之后**填充，使用 verify 重定向时下发的
+  cookie，永远不做乐观更新
+
+## API 调用
+
+本特性使用 OpenAPI 生成的客户端，不要手写 fetch 调用。
+
+- 契约：[<%= it.feature.contractAnchor %>](../../<%= it.feature.contractAnchor %>)
+- 操作：`POST /users/signup`（提交表单）、`GET /auth/verify`（验证落地）
+
+## 校验
+
+客户端校验与后端接受的形态保持一致；服务端仍然是 `EMAIL_TAKEN` 与限流
+响应的权威。
+
+| 字段 | 规则 | UI 反馈 |
+|------|------|---------|
+| email | RFC 5322 语法 | 内联提示"请输入合法邮箱" |
+| password | ≥ 8 字符 | 输入框下方显示强度计 + 字符计数 |
+
+## 无障碍
+
+- 表单可纯键盘操作；回车提交
+- 错误信息使用 `role="alert"`，让屏幕阅读器即时朗读
+- 校验状态绝不只用颜色表达，必须配图标 + 文字
+- 密码字段的"显示 / 隐藏"切换可被 Tab 触达并被屏幕阅读器朗读

package/src/feature/templates/sample/user-signup/pm/prd.md.eta

@@ -0,0 +1,46 @@
+# PRD：<%= it.feature.title %>
+
+> 特性 slug：`<%= it.feature.slug %>`
+> 这是 `create-keel --sample-feature` 附带的样例特性。把它当作可读的范例：
+> 看一遍后用你产品自己的 PRD 替换它。
+
+## 背景
+
+终端用户需要能在平台上自助创建账户。当前由销售团队手动开通账户，这种方式
+撑不过最初 50 个客户。自助注册表单去掉手动环节，把首次价值时间从数天
+缩短到数分钟。
+
+## 目标
+
+- [ ] 新用户能用邮箱 + 密码在 60 秒内完成账户创建
+- [ ] 验证邮箱前账户除了浏览公开文档外不能做任何事
+- [ ] 销售团队不再为自助层用户手动开账户
+
+## 非目标
+
+- 第三方登录（Google / GitHub）—— v1 不做，单独排期
+- SAML / SSO —— 企业层路线图
+- 密码重置流程 —— 由姊妹特性 `password-reset` 覆盖
+
+## 用户故事
+
+**作为** 潜在用户，**我希望** 能用邮箱与密码自助注册账户，**以便** 不必
+联系销售就能开始试用产品。
+
+**作为** 产品负责人，**我希望** 新账户必须验证邮箱，**以便** 垃圾邮件与
+拼写错误不会污染活跃用户指标。
+
+## 验收标准（EARS）
+
+1. WHEN 访客在注册表单中提交语法合法的邮箱与不少于 8 字符的密码，THE 系统 SHALL 在 30 秒内创建一条 `pending` 状态的用户记录并发送验证邮件。
+2. IF 访客提交的邮箱已被注册，THEN THE 系统 SHALL 返回 HTTP 409 与不暴露邮箱存在性的通用错误信息。
+3. WHILE 用户处于 `pending` 状态，THE 系统 SHALL 拒绝该用户发起的每一次已认证 API 调用，返回 HTTP 403 与错误码 `USER.AUTH.EMAIL_NOT_VERIFIED`。
+4. WHERE 启用了限流，THE 系统 SHALL 允许同一 IP 每 15 分钟最多 5 次注册尝试，超出后返回 HTTP 429。
+5. WHEN 用户在收到链接的 24 小时内点击验证链接，THE 系统 SHALL 把用户记录切换到 `active` 状态并重定向到注册后欢迎页。
+
+## 关联引用
+
+- 后端设计：[docs/04-后端详细设计/<%= it.feature.slug %>.md](../04-后端详细设计/<%= it.feature.slug %>.md)
+- 前端设计：[docs/05-前端客户端详细设计/<%= it.feature.slug %>-web.md](../05-前端客户端详细设计/<%= it.feature.slug %>-web.md)
+- 契约：[<%= it.feature.contractAnchor %>](../../<%= it.feature.contractAnchor %>)
+- 测试计划：[docs/07-质量与测试/test-plans/<%= it.feature.slug %>.md](../07-质量与测试/test-plans/<%= it.feature.slug %>.md)

package/src/feature/templates/sample/user-signup/test/test-plan.md.eta

@@ -0,0 +1,40 @@
+# 测试计划：<%= it.feature.title %>
+
+> 特性 slug：`<%= it.feature.slug %>`
+> PRD：[docs/01-背景与需求/prd-<%= it.feature.slug %>.md](../../01-背景与需求/prd-<%= it.feature.slug %>.md)
+
+## 覆盖矩阵
+
+下表把每条 PRD 验收标准映射到一个或多个测试产物。
+
+| PRD 标准 | 测试类型 | 位置 |
+|---------|---------|------|
+| 1. WHEN 合法注册 → 201 + 邮件已发送 | 单元 + 端到端 | `server/test/signup.test.ts` + `web/e2e/signup-happy.spec.ts` |
+| 2. IF 邮箱已被占 → 409 通用 | 单元 | `server/test/signup.duplicate.test.ts` |
+| 3. WHILE pending → 403 EMAIL_NOT_VERIFIED | 集成 | `contracts/tests/acceptance/<%= it.feature.slug %>.feature` |
+| 4. WHERE 启用限流 → 5 次 / 15 分钟 | 集成 | `server/test/signup.rate-limit.test.ts` |
+| 5. WHEN 24 小时内 verify → active + 重定向 | 单元 + 端到端 | `server/test/verify.test.ts` + `web/e2e/signup-verify.spec.ts` |
+
+## 边界用例
+
+- [ ] 邮箱 / 密码为空 → 400，两条错误同时返回
+- [ ] 邮箱含首尾空格 → 查询前裁剪
+- [ ] 密码恰好 8 字符 → 接受（边界）
+- [ ] 验证链接在第 24 小时 - 1 秒被点击 → 接受（边界）
+- [ ] 验证链接被点击两次 → 第二次返回 `TOKEN_INVALID`，不是 500
+- [ ] 同一邮箱并发注册 → 仅一笔成功，其余 409
+
+## 属性测试
+
+`signup → verify` 流程具有天然的 round-trip 性质：
+
+> 对任意合法的 (email, password)，注册之后用收到的 token 完成 verify，
+> 结果应当是一个状态为 `active` 且邮箱与输入相同的用户记录。
+
+用 fast-check 实现，放在 `server/test/signup.properties.test.ts`。
+
+## 缺陷追踪
+
+每次缺陷在 `docs/07-质量与测试/defects/<%= it.feature.slug %>-bug-NNN.md`
+立一份记录，关联回本测试计划。本特性提交后的第一个缺陷文件命名为
+`<%= it.feature.slug %>-bug-001.md`。

package/src/feature/templates/test/test-plan.md.eta

@@ -0,0 +1,23 @@
+# 测试计划：<%= it.feature.title %>
+
+> 特性 slug：`<%= it.feature.slug %>`
+> PRD：[docs/01-背景与需求/prd-<%= it.feature.slug %>.md](../../01-背景与需求/prd-<%= it.feature.slug %>.md)
+
+## 覆盖矩阵
+
+| 验收标准（PRD） | 测试类型 | 位置 |
+|----------------|---------|------|
+| 1. WHEN ... SHALL ... | 单元 | `server/test/<%= it.feature.slug %>.test.ts` |
+| 2. IF ... THEN SHALL ... | 契约 | `contracts/tests/acceptance/<%= it.feature.slug %>.feature` |
+| 3. WHILE ... SHALL ... | 端到端 | `web/e2e/<%= it.feature.slug %>.spec.ts` |
+
+## 边界用例
+
+- [ ] 空 / null 输入
+- [ ] 边界值
+- [ ] 并发 / 竞态（如适用）
+
+## 缺陷追踪
+
+每次缺陷在 `docs/07-质量与测试/defects/<%= it.feature.slug %>-bug-NNN.md`
+立一份记录，关联回本测试计划。

package/src/standards/templates/coding-style-dart.md.eta

@@ -0,0 +1,49 @@
+# Dart 编码规范
+
+> 真值是 `dart format` + `dart analyze`（包含 `analysis_options.yaml`）；本文件解释 *为什么* 与 *如何调整*。机器校验在 CI 中 `analyze` job 阻断违规。
+
+config: mobile/analysis_options.yaml
+
+## 命名规范
+
+- 类 / 枚举 / typedef：`PascalCase`
+- 方法 / 变量 / 字段：`camelCase`；常量 `lowerCamelCase` 或 `kPascalCase`（与项目内一种二选一锁死）
+- 库 / 文件名：`snake_case.dart`
+- 私有：下划线前缀 `_internal`
+
+## 格式化
+
+- `dart format` 单一权威；评审禁讨论缩进 / 行宽
+- 行宽 100；2 空格缩进；尾随逗号在多参 / 多元素结构上必加（dart format 行为依赖它）
+- import 顺序：`dart:*` → `package:*` → 相对路径，每段空行
+
+## 错误处理
+
+- `Exception` 子类描述业务错误；`Error` 仅用于不可恢复的 bug
+- 禁止 `catch` 不绑定变量；至少 `catch (e, st)` 并 log
+- 异步：`async/await` 是 happy path；`Future.wait` 时显式选择 `eagerError` 行为
+- 空值：用 sound null safety；禁止 `!` 解包除非有断言注释
+
+## Widget / 状态管理
+
+- StatelessWidget 优先；StatefulWidget 仅在必要时
+- 状态管理库（Provider / Riverpod / Bloc）：项目内统一一种，写在 ADR 中
+- build 方法保持 < 50 行；超过就拆子组件
+
+## 依赖与模块
+
+- `pubspec.yaml` 钉版本，与 `tech-stack-mobile.md` 对齐
+- 跨 `apps/*` 走 `packages/<shared>/` 或独立 pub package；禁止直接 path import 兄弟 app
+
+## 注释与文档
+
+- 公共 API 必须有 dartdoc（`///` 三斜杠）
+- 复杂逻辑加 `// Why:` 段
+- `// TODO` 必须带 issue 链接
+
+## lint 配置真值
+
+| 工具 | 配置文件 | CI job |
+|------|---------|--------|
+| dart format | （内置，无配置） | `format-check` |
+| dart analyze | `mobile/analysis_options.yaml` | `analyze` |

package/src/standards/templates/coding-style-go.md.eta

@@ -0,0 +1,52 @@
+# Go 编码规范
+
+> 真值是 `gofmt` + `golangci-lint` 配置；本文件解释 *为什么* 与 *如何调整*。机器校验在 CI 中 `lint` job 阻断违规。
+
+config: server/.golangci.yml
+
+## 命名规范
+
+- 包名：全小写单词，**无下划线 / 驼峰**；表达内容而非组织（`http` 而非 `httputil`）
+- 导出符号：`PascalCase`；非导出：`camelCase`
+- 错误变量：`Err<Reason>`（`ErrNotFound`）；接口：以 `-er` 结尾（`Reader`）
+- 测试：`Test<Func>`；fuzz：`Fuzz<Func>`；benchmark：`Benchmark<Func>`
+
+## 格式化
+
+- `gofmt -s` 单一权威；评审禁讨论缩进 / 行宽
+- 行宽建议 120 但不强制（gofmt 不限）；import 三段（标准库 → 第三方 → 本仓库），用空行隔开
+- `goimports` 自动处理；CI 中 `gofmt -l` 列出未格式化文件即阻断
+
+## 错误处理
+
+- 错误是返回值，不是异常；`if err != nil { return ... }` 是常态
+- 包裹错误用 `fmt.Errorf("...: %w", err)`；上层用 `errors.Is` / `errors.As` 解包
+- 禁止 `_ = err` 吞错；明确处理或加注释 `// best-effort, see issue #xxx`
+- panic 仅在不可恢复（程序 bug）时用；HTTP handler 不允许 panic 逃逸
+- sentinel error 在包级声明：`var ErrNotFound = errors.New("not found")`
+
+## 并发约束
+
+- 优先 channel；mutex 仅在 channel 不合适时用
+- 禁止 goroutine 泄露；启动 goroutine 必须有明确 cancel / done 机制
+- `context.Context` 是函数第一个参数；禁止存储在 struct field
+
+## 依赖与模块
+
+- 第三方依赖在 `go.mod` 钉版本，与 `tech-stack-server.md` 对齐
+- 主模块 `go.mod` 跟随仓库根；跨 `apps/*` 在 multi-app 模式下走 `internal/<shared>` 或独立 module
+
+## 注释与文档
+
+- 包级 doc comment：`// Package <name> ...`，必须存在
+- 导出符号 doc comment：`// <Name> ...` 开头（godoc 约定）
+- 不写 `// TODO` 而不带 issue 链接
+
+## lint 配置真值
+
+| 工具 | 配置文件 | CI job |
+|------|---------|--------|
+| gofmt | （内置，无配置） | `format-check` |
+| golangci-lint | `server/.golangci.yml` | `lint` |
+| go vet | （内置） | `vet` |
+| govulncheck | （命令行运行） | `security` |

package/src/standards/templates/coding-style-java.md.eta

@@ -0,0 +1,50 @@
+# Java 编码规范
+
+> 真值是 Checkstyle / Spotless 配置；本文件解释 *为什么* 与 *如何调整*。机器校验在 CI 中 `checkstyle` 与 `spotless:check` 阻断违规。
+
+config: server/checkstyle.xml
+
+## 命名规范
+
+- 类 / 接口 / 枚举：`PascalCase`；接口禁止 `I` 前缀
+- 方法 / 字段：`camelCase`；常量：`UPPER_SNAKE_CASE`
+- 包名：全小写 `com.<org>.<product>.<module>`，禁止下划线
+- 测试类：`<被测类>Test`；集成测试 `<场景>IT`
+
+## 格式化
+
+- Spotless（Google Java Format AOSP 风格）单一权威；评审禁讨论分号 / 大括号位置
+- 行宽 120；4 空格缩进；import 顺序：`java.*` → `javax.*` → 第三方 → `com.<org>.*`，每段空行
+- 删除未使用 import（Spotless 自动）
+
+## 错误处理
+
+- 检查异常仅在确实可恢复时使用；其余抛 `RuntimeException` 子类
+- 禁止 `catch (Exception e)` 吞错；至少 log + rethrow 或用 sentinel 返回值
+- 资源管理走 try-with-resources；禁止手写 `finally { close() }`
+- API 边界统一异常→`ProblemDetails`（RFC 7807）
+
+## 设计约束
+
+- POJO 走 record（Java 17+）或 Lombok `@Value`；二选一在 ADR 中记录
+- 禁止字段级公共可变状态；若必须用 `volatile` / `AtomicReference`
+- 依赖注入由 Spring 管理；构造函数注入，禁止字段注入
+
+## 依赖与模块
+
+- 第三方依赖在 `pom.xml` 钉版本，与 `tech-stack-server.md` frontmatter 对齐
+- 跨模块引用：`apps/*` 之间不允许直接 import（multi-app 模式下走 contract / 共享 packages）
+
+## 注释与文档
+
+- 公共类 / 公共方法必须有 JavaDoc，含 `@param` `@return` `@throws`
+- 复杂算法或决策点加 `// Why:` 段
+- 禁止 `// TODO` 不带 issue 链接
+
+## lint 配置真值
+
+| 工具 | 配置文件 | CI job |
+|------|---------|--------|
+| Checkstyle | `server/checkstyle.xml` | `checkstyle` |
+| Spotless | `server/pom.xml` 中 `<plugin>spotless</plugin>` 段 | `spotless-check` |
+| 编译警告 | `pom.xml` `-Werror` | `compile` |

package/src/standards/templates/coding-style-python.md.eta

@@ -0,0 +1,51 @@
+# Python 编码规范
+
+> 真值是 `ruff` + `mypy` 配置；本文件解释 *为什么* 与 *如何调整*。机器校验在 CI 中 `lint` 与 `typecheck` job 阻断违规。
+
+config: server/pyproject.toml
+
+## 命名规范
+
+- 模块 / 包：`snake_case`，全小写
+- 类：`PascalCase`；异常类：以 `Error` 结尾（`UserNotFoundError`）
+- 函数 / 变量：`snake_case`；常量：`UPPER_SNAKE_CASE`
+- 私有：单下划线前缀 `_helper`；name mangling 双下划线仅在确需时
+
+## 格式化
+
+- `ruff format` 单一权威（替代 black + isort）；评审禁讨论引号 / 行宽
+- 行宽 100；4 空格缩进；import 顺序：标准库 → 第三方 → 本地
+- 删除未使用 import（ruff 自动）
+
+## 类型注解
+
+- 全文件类型注解；函数签名禁止省略
+- 严格 mypy：`disallow_untyped_defs = true`，`strict_optional = true`
+- 优先 `pydantic.BaseModel` 描述 API 边界数据；`@dataclass(slots=True)` 描述内部值对象
+
+## 错误处理
+
+- 业务异常自定义 `XxxError(BaseAppError)`；禁止 `raise Exception(...)`
+- 禁止裸 `except:`；至少 `except Exception:` 并 log
+- 资源管理走 `with`；禁止手写 `try / finally: f.close()`
+- 异步：`asyncio.gather` 时显式选择 `return_exceptions` 行为
+
+## 依赖与导入
+
+- 第三方依赖在 `pyproject.toml` 钉版本，与 `tech-stack-server.md` 对齐
+- 跨 `apps/*` 引用走 `apps/_shared/` 或共享 distribution；禁止直接 `from apps.other import ...`
+- 循环 import：拆模块或用 TYPE_CHECKING 延迟
+
+## 注释与文档
+
+- 公共函数 / 类必须 docstring（Google 或 PEP 257 风格，仓库二选一锁死）
+- 复杂决策点加 `# Why:` 段
+- `# TODO` 必须带 issue 链接
+
+## lint 配置真值
+
+| 工具 | 配置文件 | CI job |
+|------|---------|--------|
+| ruff | `server/pyproject.toml` `[tool.ruff]` 段 | `lint` |
+| mypy | `server/pyproject.toml` `[tool.mypy]` 段 | `typecheck` |
+| pip-audit | （命令行） | `security` |