chore: seal Design Vision v1 and monorepo scaffold

Archive the differentiated YuXinGu product docs, AI engineering system, design contract, and Go/Vue scaffold. Next execution prioritizes Cece-parity over early innovation (see .ai/product/STRATEGY.md). Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-02 16:00:44 +08:00
parent 2686866376
commit 2fb1dfee14
193 changed files with 8854 additions and 1851 deletions
@@ -0,0 +1,27 @@
+# 愈心谷产品与业务文档
+
+工程规则以仓库根目录 [`.ai/`](../../.ai/) 为准；本目录放**产品 / 商业 / 竞品分析 / ADR（业务向）**。
+
+`apps/docs/standards/*` 已废弃，请改读 `.ai/`。
+
+---
+
+## 阅读顺序（产品重设计）
+
+1. [analysis/cece-teardown.md](analysis/cece-teardown.md) — 测测拆解 → 愈心谷映射  
+2. [`.ai/product/cece-feature-map.md`](../../.ai/product/cece-feature-map.md) — 测测 Feature Map（IA × 能力域）  
+3. [`.ai/product/feature-map.md`](../../.ai/product/feature-map.md) — 愈心谷 Feature Map + MVP  
+4. [prd-mvp.md](prd-mvp.md) — MVP 目标、IA、用户故事、API 切片、验收  
+5. [business-model.md](business-model.md) — 三层收入与飞轮  
+6. [product-roadmap.md](product-roadmap.md) — Phase A→D 竖切计划  
+
+域词汇：[`.ai/domain.md`](../../.ai/domain.md) · 领域图：[`.ai/domain/domain-map.md`](../../.ai/domain/domain-map.md)
+
+---
+
+## 其他
+
+| 文档 | 说明 |
+|---|---|
+| [adr/](adr/) | 架构/选型 ADR（与 `.ai/adr/` 分工：业务向可放此处） |
+| 根目录 `立项文档.md` | 早期立项材料；冲突时以本目录 + `.ai/` 为准 |
@@ -0,0 +1,23 @@
+# ADR 0001: Monorepo + Go API + Vue H5
+
+## 状态
+
+已采纳（2026-08-02）
+
+## 背景
+
+愈心谷需从静态 HTML 原型演进为可多端扩展的产品，并引入 AI 辅助开发；需统一规范与清晰边界。
+
+## 决策
+
+- 采用 npm workspaces Monorepo（`apps/*` + `packages/*`）。
+- 后端唯一实现：Go（gin）于 `apps/api`。
+- 当前主客户端：Vue3 + TS H5（`apps/user-h5`）；小程序仅脚手架。
+- 多端网络层：`packages/sdk` 适配器模式。
+- Git：Trunk-Based + Conventional Commits。
+
+## 后果
+
+- 新功能不得继续堆在根目录 legacy HTML。
+- 共享类型与 SDK 降低后续小程序迁移成本。
+- 需维护 workspace 与 Go module 两套依赖工具链。
@@ -0,0 +1,7 @@
+# ADR location moved
+
+Canonical Architecture Decision Records live in:
+
+**[../../../.ai/adr/](../../../.ai/adr/)**
+
+This folder keeps historical notes only if needed; do not add new ADRs here.
@@ -0,0 +1,79 @@
+# 竞品拆解：测测 → 愈心谷映射
+
+来源：[测测 App 深度体验报告（人人都是产品经理）](https://www.woshipm.com/evaluating/6391148.html)  
+下游：[PRD MVP](../prd-mvp.md) · [商业模式](../business-model.md) · [产品路线图](../product-roadmap.md) · [文档索引](../README.md)
+
+原则：学结构，不抄神秘学主叙事；愈心谷差异 = **数字性格 + 中医体质 + 关系档案 + 节气陪伴**（合规：无疗效、无吉凶）。
+
+域词汇以 [`.ai/domain.md`](../../../.ai/domain.md) 为准。
+
+---
+
+## 1. 测测做对了什么（可迁移）
+
+| 测测能力 | 本质 | 愈心谷对应 |
+|---|---|---|
+| 趣味测评拉新（MBTI 等） | 社交传播入口 | **Scale** + 分享卡片 |
+| 生日建档 /「了解 TA」 | 关系数据资产 | **Profile**（Self / Other） |
+| 五 Tab，中间「问」突出 | 战略入口可视化 | Home / Explore / **Ask** / Companion / Mine |
+| AI 挂档案，非通用闲聊 | 垂直差异化 | **Ask** 必须带 Profile 上下文 |
+| AI ‖ 真人 1v1 双轨 | 低摩擦升单 | Ask 内切换 **Consult**（后置） |
+| 会员订阅为主营收 | 可预测现金流 | **Subscription** → **Membership** / **VIP** |
+| 达人咨询高客单 | ARPU 拔高 | **Consult** |
+| 砍干扰广告 | 信任优先 | 不做干扰广告 |
+| 分享裂变 | 低 CAC | Decode / ScaleResult 分享 |
+
+## 2. 测测的坑（愈心谷要避开）
+
+| 风险 | 测测表现 | 愈心谷对策 |
+|---|---|---|
+| 定位拧巴 | 泛心理 vs 占星吸引力冲突 | 主叙事：文化测评 + 国标体质生活建议；重玄学模块降权 |
+| AI 像「算命」 | 引导问题偏运势 | Ask 按进入路径动态引导（性格/关系/养生） |
+| 视角切换难发现 | 「分析 TA」藏太深 | 首页解码后强引导建 Other Profile；Ask 顶部显式切换 Self/Other |
+| 跨会话记忆弱 | 电子闺蜜体验断裂 | MVP 先做 Profile 结构化记忆；长对话记忆 V1.2+ |
+| 多智能体认知负担 | 入口并列 | **只做一个 Ask**；不并行灵犀/小智式品牌矩阵 |
+
+## 3. 信息架构对照
+
+```
+测测:  首页 | 消息 | 问 | 在线 | 我的
+愈心谷: 首页 | 探索 | 问 | 陪伴 | 我的
+```
+
+- **探索** ≈ 测测首页宫格 + AI 玩法广场的「内容供给」（MVP 不做 UGC 广场，只做官方 Scale / Decode 入口）
+- **陪伴** ≈ 每日心情 + 节气（测测心情打卡的留存位，换成 SolarTerm + Mood）
+- **消息 / 在线** 后置；Consult 先做预约表单，不做达人双边平台
+
+## 4. 核心用户路径（对标测测三条场景）
+
+### P1 自我探索（拉新）
+
+Visitor → 首页 Decode 或 Scale → 简版结论 → 分享 → 注册为 User
+
+### P2 关系决策（差异化）
+
+User 建 Other Profile → Match 预览分数 → Unlock 解读 →（可选）Ask 切换 TA
+
+### P3 情绪 / 养生留存（夜间场景）
+
+Mood 打卡 / SolarTerm → Ask（档案上下文）→ 额度用尽 → Subscription
+
+## 5. 能力分层（对标测测「情感陪伴层」）
+
+```
+入口层（免费）     Decode 简版 / Scale 部分 / Share
+留存层（VIP）      Ask 额度 / SolarTerm 个性化 / Mood / 多 Profile
+转化层（高客单）   Report Unlock / Match / Consult
+```
+
+## 6. 不做清单（相对测测）
+
+- 不自研大模型备案叙事（可接外部 LLM）
+- 不做硬件（巴布类）
+- 不做达人双边平台冷启动
+- 不做 AI 心情小镇 / 3D 沙盘（成本高，非差异化必需）
+- Legacy 根目录 HTML 不承接新需求（见 `.ai/architecture.md`）
+
+## 7. 结论（一句话）
+
+测测验证了「测评入口 → 档案化 AI → 订阅 + 咨询」飞轮；愈心谷用 **体质与节气** 替换「运势主叙事」，用 **家庭/关系 Profile** 做裂变，用 **合规生活建议** 守住审核与信任。
@@ -0,0 +1,90 @@
+# 愈心谷商业模式
+
+关联：[PRD MVP](prd-mvp.md) · [测测拆解](analysis/cece-teardown.md) · [产品路线图](product-roadmap.md)
+
+---
+
+## 1. 一句话
+
+用「数字性格 + 中医体质」做**可复算、可对照**的自我认知入口，以**订阅为主、报告/契合为辅、咨询为远期高客单**，承接测测式漏斗，但避开算命与医疗承诺。
+
+---
+
+## 2. 价值主张
+
+| 对用户 | 对产品 |
+|---|---|
+| 知道「我是谁 / 我缺什么 / 怎么相处」 | 低摩擦获客（生日 / 量表） |
+| 比泛星座更「有结构」、比纯心理量表更「东方语境」 | 差异化：体质 × 性格 × 关系档案 |
+| 节气与日更内容形成回访理由 | 订阅续费钩子 |
+
+---
+
+## 3. 收入三层（对齐测测，本地化）
+
+```
+L1 免费获客     Decode 简版 / Scale / 分享卡
+       ↓
+L2 订阅留存     Membership：Ask 次数、完整报告、SolarTerm 深度、Mood 复盘
+       ↓
+L3 高 ARPU      Unlock 单次报告/Match ·（远期）Consult
+```
+
+| 层级 | 产品 | 定价方向（可调） | 备注 |
+|---|---|---|---|
+| L1 | 简版 Decode、热门 Scale | 0 | 结论可见 |
+| L2 | 月/季/年 VIP | 参考测测档位，偏下探试价 | 主收入 |
+| L2.5 | Unlock 完整报告 / Match 解读 | 单次低客单 | 不愿订也可转化 |
+| L3 | Consult | 远期 | 需履约与合规，非 MVP |
+
+**不做：** 侵入式广告、诱导抽奖、伪医疗售卖。
+
+---
+
+## 4. 飞轮
+
+```mermaid
+flowchart LR
+  Share[分享卡/社交] --> Free[免费测评]
+  Free --> Profile[档案沉淀]
+  Profile --> Paywall[原因与方案付费墙]
+  Paywall --> VIP[订阅]
+  VIP --> Ask[问 / 陪伴回访]
+  Ask --> Share
+  Profile --> Match[关系档案]
+  Match --> Unlock[单次解锁]
+  Unlock --> VIP
+```
+
+关键：Profile 越多 → Match/Ask 越有用 → 续费与解锁越高。
+
+---
+
+## 5. 单位经济（假设，待校验）
+
+| 指标 | MVP 观测 |
+|---|---|
+| 免费完成率 | Decode 简版 / Scale 完成率 |
+| 付费转化 | 简版→Unlock 或 VIP |
+| ARPU | 订阅为主，Unlock 为辅 |
+| 留存 | D1/D7；节气打开率 |
+| 合规成本 | 客服投诉 / 违规文案拦截率 |
+
+付费与权益**只信服务端**（见 `.ai/security.md`）。
+
+---
+
+## 6. B2B / 扩展（非 MVP）
+
+企业 EAP、线下门店引流、内容授权——在 C 端漏斗跑通后再开。平台扩展路径：H5 → 小程序（同一 `packages/sdk`）。
+
+---
+
+## 7. 与测测的差异化（商业）
+
+| 测测 | 愈心谷 |
+|---|---|
+| 星盘+心理+社交玩法宽 | 数字性格+体质窄而深 |
+| 强娱乐/玄学氛围 | 可复算、生活建议、免责声明 |
+| 咨询达人网络 | 先模板 Ask，后 Consult |
+| UGC 广场 | 暂不做，避免内容治理成本 |
@@ -0,0 +1,128 @@
+# 愈心谷 MVP PRD
+
+关联：[测测拆解映射](analysis/cece-teardown.md) · [商业模式](business-model.md) · [产品路线图](product-roadmap.md)  
+Feature Map：[`.ai/product/feature-map.md`](../../.ai/product/feature-map.md) · 竞品树：[`.ai/product/cece-feature-map.md`](../../.ai/product/cece-feature-map.md)  
+域词汇：[`.ai/domain.md`](../../.ai/domain.md) · 领域图：[`.ai/domain/domain-map.md`](../../.ai/domain/domain-map.md)  
+实现约束：[`.ai/architecture.md`](../../.ai/architecture.md) · playbooks: `add-api` / `new-page` / `payment`
+
+---
+
+## 1. 目标 / 非目标
+
+### 目标（MVP Done）
+
+在 **user-h5 + api** 上跑通：
+
+1. Visitor 输入生日 → 创建 **Self Profile** → 生成 **Decode** 简版（结论可见）
+2. 付费墙：Unlock 完整 Decode **或** 开通 **Subscription**（可模拟支付）
+3. 至少一个热门 **Scale**（如 MBTI）作答 → **ScaleResult** → 分享卡
+4. 可创建 **Other Profile**，生成 **Match** 预览（分数可见，解读锁定）
+5. 底栏 5 Tab 可用；Ask / Companion 允许规则模板占位，但入口与文案就位
+6. 服务端可复算报告；客户端不信任本地解锁
+
+### 非目标
+
+- Consult 履约 / 达人双边
+- mini-program 业务页
+- UGC「玩法广场」
+- 真实微信支付（用 `PAYMENT_MODE=mock`）
+- 长记忆多智能体 / 心情小镇级沉浸
+
+---
+
+## 2. 用户与场景
+
+| 画像 | 场景 | 成功指标 |
+|---|---|---|
+| P2 泛测评年轻女性 | 社交看到分享 → 测自己 | 完成 Decode 简版或 Scale |
+| P1 养生决策者 | 要「适合自己的调理参考」 | 查看完整 Decode 体质方案段 |
+| 关系困扰 | 帮 TA 测 / 看契合 | 创建 Other Profile + Match 预览 |
+
+---
+
+## 3. 信息架构（5 Tab）
+
+| Tab | 路由建议 | 内容 |
+|---|---|---|
+| 首页 | `/` | 品牌 + Decode 输入 + 热门 Feed + 宫格 |
+| 探索 | `/explore` | Scale 列表、Decode 入口；星镜/数字心理轻入口 |
+| 问 | `/ask` | Ask：基于当前 Profile；Tab 旁路「顾问预约」占位 |
+| 陪伴 | `/companion` | 今日 SolarTerm + Mood 打卡（可静态内容） |
+| 我的 | `/mine` | Profiles、Membership、Orders、设置 |
+
+二级：`/decode` `/scales/:slug` `/match` `/report/:id`
+
+---
+
+## 4. 关键用户故事
+
+### US1 Decode
+
+- 输入 year/month/day → API 校验 → 落 Profile + Report(Decode)
+- 简版：性格一句话 + 体质倾向一句话 + 1 条生活建议
+- 完整：原因拆解 + 方案列表；需 Unlock 或 VIP
+- 文案禁疗效 / 吉凶；页脚免责声明
+
+### US2 Scale
+
+- 列表来自 API；作答进度可本地缓存；提交服务端计分
+- 结果页：类型/分数 + 分享 + 引导 Decode/Ask
+
+### US3 Other + Match
+
+- 「帮 TA 测」创建 Other Profile
+- Match：展示契合分；解读段落锁定至 Unlock
+
+### US4 Membership（mock）
+
+- 套餐展示；下单 → mock 支付成功 → Membership active
+- Ask/完整报告次数按权益扣减（服务端）
+
+---
+
+## 5. 付费墙原则
+
+**免费给结论，付费给原因 + 方案。**  
+VIP 与单次 Unlock 二选一可达完整内容。
+
+---
+
+## 6. API 切片（MVP）
+
+统一信封见 `.ai/api.md`。最小集合：
+
+| Method | Path | 说明 |
+|---|---|---|
+| POST | `/api/v1/profiles` | 创建 Self/Other Profile |
+| GET | `/api/v1/profiles` | 列表 |
+| POST | `/api/v1/reports/decode` | 生成 Decode（简/全由权益决定） |
+| GET | `/api/v1/reports/:id` | 报告详情 |
+| GET | `/api/v1/scales` | 量表列表 |
+| GET | `/api/v1/scales/:slug` | 题目 |
+| POST | `/api/v1/scales/:slug/result` | 提交作答 |
+| POST | `/api/v1/match` | 契合度预览/完整 |
+| POST | `/api/v1/orders` | 创建订单 |
+| POST | `/api/v1/orders/:id/pay-mock` | 模拟支付 |
+| GET | `/api/v1/membership/me` | 当前权益 |
+| GET | `/api/v1/solar-terms/today` | 今日节气 |
+| POST | `/api/v1/moods` | 心情打卡（可后置） |
+
+Auth：Visitor 可用 device token；注册后升级 User（见 ADR-0004）。
+
+---
+
+## 7. 验收（QA）
+
+- [ ] 未付费看不到完整 Decode 原因段（抓包改本地也不生效）
+- [ ] 模拟支付后同一 Report 可完整查看
+- [ ] Other Profile + Match 预览分数、解读锁定
+- [ ] Scale 提交返回稳定计分
+- [ ] 文案无疗效/吉凶；有免责声明
+- [ ] `go test ./...` 与 `npm run build:h5` 通过
+- [ ] `/api/v1/healthz` OK
+
+---
+
+## 8. 实现顺序（竖切）
+
+按 [product-roadmap.md](product-roadmap.md) Phase A→B→C；每刀走 `.ai/playbooks/add-api.md` + `new-page.md`。
@@ -0,0 +1,78 @@
+# 产品分期路线图
+
+关联：[PRD MVP](prd-mvp.md) · [商业模式](business-model.md) · [`.ai/ROADMAP.md`](../../.ai/ROADMAP.md)（工程体系分期）
+
+实现一律竖切：API → types → H5；playbook：`add-api` / `new-page` / `payment`。
+
+---
+
+## Phase A — 解码闭环（当前下一刀）
+
+**目标：** Visitor 生日 → Profile → Decode 简/全权益 → mock Unlock/VIP
+
+| 交付 | Playbook | Done |
+|---|---|---|
+| Profile CRUD API | add-api | |
+| Decode 生成 + Report 读取（服务端裁剪字段） | add-api | |
+| H5 首页表单接真 API + 报告页 | new-page | |
+| Order + pay-mock + Membership | payment | |
+| 免责声明与文案禁区 | review checklist | |
+
+**退出标准：** PRD §7 中 Decode + Membership 相关项打勾。
+
+---
+
+## Phase B — 量表与关系
+
+| 交付 | Playbook |
+|---|---|
+| Scales 列表/题目/计分 API + 1 个热门量表 | add-api + new-page |
+| Other Profile + Match 预览/锁定 | add-api + new-page |
+| 分享卡（静态图或 canvas） | new-page |
+| 探索 Tab 接真数据 | new-page |
+
+**退出标准：** PRD US2/US3 验收通过。
+
+---
+
+## Phase C — 问与陪伴骨架
+
+| 交付 | 说明 |
+|---|---|
+| Ask：规则模板 + 权益次数 | 非 LLM 亦可；接口形状稳定 |
+| SolarTerm 今日内容 API + 陪伴页 | 可先静态 CMS JSON |
+| Mood 打卡最小写 | 可选 |
+| 「顾问预约」占位页 | 不履约 |
+
+**退出标准：** 5 Tab 均有真实或稳定占位数据；无死链。
+
+---
+
+## Phase D — 增长与平台（post-MVP）
+
+- 真实支付通道（微信支付等）
+- Auth 升级、多端登录
+- mini-program 适配（`packages/sdk`）
+- Consult 试点（合规评审后）
+- 内容运营后台（admin-h5）最小可用
+
+---
+
+## 不做清单（直到明确开闸）
+
+- UGC 玩法广场 / 达人市场
+- GraphQL / 微服务拆分
+- 长记忆多智能体陪伴
+- 根目录遗留 HTML 继续加功能（见 `LEGACY.md`）
+
+---
+
+## 与工程路线对齐
+
+| 产品 Phase | 工程侧重 |
+|---|---|
+| A–B | `apps/api` + `apps/user-h5` + Postgres |
+| C | Redis 仍可延迟；Ask 限流按需 |
+| D | 支付真通道、小程序、admin |
+
+工程体系 Phase 2/3（anti-patterns、metrics、mcp…）见 `.ai/ROADMAP.md`，不阻塞产品 A–C。
@@ -0,0 +1,37 @@
+# 01 Git 规范
+
+## 策略
+
+Trunk-Based Development：
+
+- 默认分支：`main`（可发布）。
+- 功能分支：`feature/<short-name>`，生命周期尽量 < 2 天。
+- 修复：`fix/<short-name>`。
+- 不设长期 `develop`。
+
+## Commit
+
+Conventional Commits：
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+```
+
+常用 type：`feat` `fix` `refactor` `perf` `style` `docs` `test` `chore`。
+
+scope 示例：`auth` `report` `sdk` `user-h5` `api`。
+
+subject 用英文或中文均可，但同一仓库保持一种；推荐英文短句，说明意图。
+
+## Release
+
+- 打 tag：`v0.1.0`（semver）。
+- Changelog 记录在 `apps/docs/CHANGELOG.md`（有正式发布时更新）。
+
+## 禁止
+
+- `git commit --no-verify`（除非负责人明确批准）。
+- 强制推送 `main`。
+- 提交密钥、`.env`、本地数据库文件。
@@ -0,0 +1,66 @@
+# 02 Go 编码规范
+
+参考：Effective Go、Uber Go Style Guide、Google Go Style Guide。
+
+## 目录
+
+```
+apps/api/
+  cmd/server/
+  internal/
+    handler/
+    service/<domain>/   # auth, profile, report, order…
+    repository/
+    model/
+    middleware/
+    config/
+  pkg/                  # 可复用小库，禁止膨胀
+  migrations/
+```
+
+## 包职责
+
+- 按 **业务域** 分包，不要 `package utils`。
+- 好：`order` `payment` `auth` `profile`。
+- `pkg/` 仅放与业务无关的通用能力（如 `response` 封装）。
+
+## Interface 放在调用方
+
+在 `handler`（或真正的调用包）定义 interface，service 实现之。  
+避免在 service 包里堆 `interface.go` 再反向依赖。
+
+## Context
+
+所有可能阻塞或下游调用的方法，首参必须是 `context.Context`：
+
+```go
+func (s *Service) Login(ctx context.Context, req LoginRequest) (*User, error)
+```
+
+## 错误
+
+```go
+if err != nil {
+    return fmt.Errorf("create user: %w", err)
+}
+```
+
+禁止裸 `return err` 且丢失上下文；禁止 `_ = err` 吞掉关键错误。
+
+## 日志
+
+结构化日志（zap 或统一 slog 封装）。禁止业务路径 `fmt.Println`。
+
+```go
+logger.Info("user login", zap.Int64("uid", uid), zap.String("ip", ip))
+```
+
+## 命名
+
+- 文件：`snake` 不强制，Go 惯用短名；导出标识符 PascalCase。
+- 避免 `Manager` `Helper` `Util` 空泛命名。
+
+## 测试
+
+- `*_test.go` 与实现同包或 `package foo_test`。
+- 表驱动测试优先；外部依赖用 interface mock。
@@ -0,0 +1,60 @@
+# 03 REST API 规范
+
+## URL
+
+- 前缀：`/api/v1`。
+- 资源名词复数、层级清晰：
+
+```
+GET    /api/v1/users
+GET    /api/v1/users/:id
+POST   /api/v1/users
+PUT    /api/v1/users/:id
+DELETE /api/v1/users/:id
+```
+
+动作型可用子路径：`POST /api/v1/reports/decode`。
+
+## 统一响应
+
+成功：
+
+```json
+{ "code": 0, "message": "success", "data": {} }
+```
+
+失败（HTTP 可用 4xx/5xx，body 仍带业务码）：
+
+```json
+{ "code": 10001, "message": "user not found" }
+```
+
+## 错误码段（约定）
+
+| 段 | 含义 |
+|---|---|
+| 0 | 成功 |
+| 1xxxx | 通用 / 参数 / 认证 |
+| 2xxxx | 用户与档案 |
+| 3xxxx | 报告与量表 |
+| 4xxxx | 订单与会员 |
+| 5xxxx | AI / 陪伴 |
+
+具体码表维护在 `apps/docs/api-errors.md`（随功能追加）。
+
+## 分页
+
+```
+GET /api/v1/scales?page=1&page_size=20
+```
+
+`data` 建议：
+
+```json
+{ "list": [], "total": 0, "page": 1, "page_size": 20 }
+```
+
+## 版本与文档
+
+- 破坏性变更升 `/api/v2` 或并行兼容期。
+- 同步更新 `proto/openapi.yaml`。
@@ -0,0 +1,38 @@
+# 04 数据库规范
+
+## 引擎
+
+PostgreSQL（主库）。本地可用 Docker Compose。
+
+## 命名
+
+- 表：`snake_case` 单数或清晰业务名，如 `user_profile`、`payment_order`、`user_session`。
+- **禁止** `tbl_` / `t_` 前缀。
+- 字段：`snake_case`。
+
+## 公共字段
+
+每张业务表默认包含：
+
+```
+id          BIGSERIAL PRIMARY KEY  -- 或 UUID，项目内统一一种
+created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+deleted_at  TIMESTAMPTZ NULL          -- 软删除
+```
+
+## 迁移
+
+- 使用 goose（或 golang-migrate），文件放 `apps/api/migrations/`。
+- 迁移必须可回滚（提供 `Down`）。
+- 禁止手改生产库结构而不留迁移文件。
+
+## 索引
+
+- 高频查询字段建索引；唯一业务键用 UNIQUE。
+- 写迁移时注明索引意图。
+
+## 敏感数据
+
+- 生日等：最小化存储；访问打审计日志（后置也可先文档约定）。
+- 密钥、支付信息不得明文进业务表。
@@ -0,0 +1,41 @@
+# 05 H5 / Vue 规范
+
+适用：`apps/user-h5`、`apps/admin-h5`。
+
+## 栈
+
+Vue 3 + TypeScript + Vite + Vue Router + Pinia。
+
+## 目录
+
+```
+src/
+  components/
+  pages/
+  layouts/
+  hooks/
+  api/          # 仅薄封装 → @yuxingu/sdk
+  stores/
+  utils/
+  router/
+  assets/
+```
+
+## 组件命名
+
+- 文件与组件名：`PascalCase`，如 `UserCard.vue`、`OrderTable.vue`。
+- 禁止：`usercard.vue`、`aaa.vue`。
+
+## 数据请求
+
+- 页面 / 组件内禁止直接 `fetch`/`axios` 拼完整 URL。
+- 经 `src/api/*` → `@yuxingu/sdk`。
+
+## 风格
+
+- 移动优先；品牌色见 `packages/ui` token。
+- 单文件建议 ≤ 300 行，复杂页拆子组件与 composable（`hooks/`）。
+
+## 路由
+
+- 与产品 5 Tab 对齐：`/` `explore` `ask` `companion` `mine`；二级页如 `/decode`、`/scales/:slug`。
@@ -0,0 +1,33 @@
+# 06 微信小程序规范
+
+适用：`apps/mini-program`（业务后置，先遵守结构）。
+
+## 目录建议
+
+```
+pages/
+  home/
+  profile/
+  login/
+  setting/
+components/
+  Avatar/
+  Button/
+services/          # 业务请求，内部用 sdk 适配器
+  user.ts
+  order.ts
+utils/
+app.js / app.json / app.wxss
+```
+
+## 规则
+
+- **不要在页面里直接写请求**；统一 `services/*`。
+- 登录、存储通过适配器注入 `packages/sdk`（`wx.request` / `wx.setStorage`）。
+- 组件目录 PascalCase 或微信惯用名，项目内统一一种。
+- 与 H5 共享类型：`@yuxingu/types`；不共享 Vue SFC。
+
+## 发布
+
+- 使用独立 appid 配置，密钥不进库。
+- 体验版 / 正式版环境变量与 API baseURL 分离。
@@ -0,0 +1,25 @@
+# 07 TypeScript 规范
+
+## 编译选项
+
+`strict: true`（含 `noImplicitAny`、`strictNullChecks` 等）。
+
+## 类型
+
+- 优先 `interface` / `type` 描述领域对象；放 `packages/types` 供多端复用。
+- 禁止滥用 `any`；临时逃逸用 `unknown` + 收窄。
+- 避免 `as any`；确需断言写清原因注释。
+
+## 示例
+
+```ts
+export interface User {
+  id: number
+  name: string
+}
+```
+
+## 与 API
+
+- 响应类型与 `code/message/data` 包装对齐 SDK 泛型。
+- 字段名与 JSON（snake_case）映射策略在 SDK 层统一（保持后端 snake，或统一 camel 转换，项目内二选一；**选定：前端 TS 用 camelCase，SDK 做转换**）。
@@ -0,0 +1,21 @@
+# 08 测试规范
+
+## Go（`apps/api`）
+
+- 领域纯函数（计分、解码规则）必须有单元测试。
+- Handler 可用 httptest 做集成测试；DB 用测试库或 docker。
+- CI 最少跑：`go test ./...`
+
+## H5
+
+- 关键工具函数单测（Vitest，后置可加）。
+- MVP 阶段：手动烟测清单写在 PR 描述（解码、量表、登录态）。
+
+## E2E
+
+- 正式流量前再引入 Playwright；不阻塞脚手架。
+
+## 原则
+
+- 测试与实现同 PR。
+- 不追求虚假覆盖率；优先测钱、测档案、测计分。
@@ -0,0 +1,29 @@
+# 09 Docker / CI/CD 规范
+
+## 本地
+
+```bash
+docker compose -f deploy/docker-compose.yml up -d
+```
+
+服务：`postgres`（必备）、可选 `api` 镜像。
+
+## 环境变量
+
+- `APP_ENV`：`dev` | `staging` | `prod`
+- `DATABASE_URL`
+- `HTTP_ADDR`（默认 `:8080`）
+- `JWT_SECRET` / 支付密钥等仅环境注入
+
+禁止把 `.env` 提交进 git（示例用 `.env.example`）。
+
+## CI 门禁（目标）
+
+1. `go test ./...`（api）
+2. `npm run build`（user-h5）
+3. lint（后置可加 golangci-lint / eslint）
+
+## 镜像
+
+- API 多阶段构建，最终镜像仅含二进制。
+- 标签：`yuxingu-api:<git-sha>`。
@@ -0,0 +1,25 @@
+# 10 AI 协作规范
+
+配合根目录 [AGENTS.md](../../../AGENTS.md)。
+
+## Prompt 约束（建议粘贴）
+
+- 先读 AGENTS.md 与 ARCHITECTURE.md。
+- 只改任务相关文件；单 PR 单功能。
+- 单文件 ≤300 行，函数 ≤50 行。
+- Go interface 放调用方；H5 请求走 SDK。
+- 不要改 legacy 根目录 HTML，除非迁移任务。
+
+## 评审清单
+
+- [ ] 是否破坏分层？
+- [ ] 是否出现巨型 utils？
+- [ ] 错误是否包装 `%w`？
+- [ ] 是否泄露密钥或不合规文案？
+- [ ] 类型是否进了 `packages/types`？
+
+## 禁止
+
+- 让 AI「顺便」重构无关模块。
+- 无人工阅读直接合并大段生成代码。
+- 用 AI 生成后删除所有注释与测试。
@@ -0,0 +1,25 @@
+# 11 安全规范
+
+## 认证与授权
+
+- API 使用 Bearer Token（JWT 或 session）；中间件校验。
+- 资源级校验：用户只能访问自己的档案/订单。
+
+## 密钥
+
+- 仅环境变量 / 密钥托管；禁止写进前端与仓库。
+- 轮换流程写入运维笔记（后置）。
+
+## 输入校验
+
+- 所有外部输入在 handler 层校验（生日范围、分页上限、字符串长度）。
+- SQL 一律参数化；禁止拼接。
+
+## 隐私与合规
+
+- 生日、测评结果属敏感个人信息：明示用途、支持删除（软删 + 注销流程后置）。
+- 对外文案：无医疗疗效、无吉凶祸福；报告页固定免责声明组件。
+
+## 支付
+
+- 验签、幂等、金额以服务端订单为准。
@@ -0,0 +1,26 @@
+# 12 文档规范
+
+> **工程协作规则已迁至** [`.ai/`](../../../.ai/)。本文件仅作产品文档索引补充；标准正文勿再扩写于此。
+
+## 类型
+
+| 类型 | 位置 |
+|---|---|
+| 索引 | `apps/docs/README.md` |
+| 竞品分析 | `apps/docs/analysis/*` |
+| PRD | `apps/docs/prd-mvp.md` |
+| 商业模式 | `apps/docs/business-model.md` |
+| 产品路线图 | `apps/docs/product-roadmap.md` |
+| ADR（架构决策） | `apps/docs/adr/` 与 `.ai/adr/` |
+| API | `proto/openapi.yaml` |
+| 工程标准 | `.ai/*`（勿继续写 `apps/docs/standards/*`） |
+| 变更 | `apps/docs/CHANGELOG.md`（可选） |
+
+## ADR
+
+重大选型（库、支付渠道、LLM 供应商）必须写 ADR：背景、决策、后果。
+
+## 文风
+
+- 中文产品文档；英文可出现在代码标识符与 Commit。
+- 避免过时截图；以路径与接口为准。
@@ -0,0 +1,22 @@
+# Deprecated as source of truth
+
+Engineering rules moved to the **AI Engineering System**:
+
+→ **[../../../.ai/](../../../.ai/)**
+
+| Old file | New location |
+|---|---|
+| 01-git | CONTRIBUTING.md + Trunk-Based note |
+| 02-go | `.ai/coding.md` + `.ai/tech-stack.md` |
+| 03-api | `.ai/api.md` |
+| 04-database | `.ai/database.md` |
+| 05-h5-vue | `.ai/ui.md` + `.ai/coding.md` |
+| 06-mini-program | `.ai/ui.md` + `.ai/architecture.md` |
+| 07-typescript | `.ai/coding.md` + `.ai/tech-stack.md` |
+| 08-testing | `.ai/testing.md` |
+| 09-cicd | `.ai/deployment.md` |
+| 10-ai-collab | `AGENTS.md` + `.ai/prompts/*` |
+| 11-security | `.ai/security.md` |
+| 12-docs | `.ai/definition-of-done.md` + `apps/docs` for PRD |
+
+Keep PRD / business docs: `apps/docs/prd-mvp.md`, `apps/docs/business-model.md`.