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>
This commit is contained in:
jackyu66git
@@ -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`.
|
||||
Reference in New Issue
Block a user