cowork-flow 0.0.1

package/template/.cowork-flow/spec/backend/database-guidelines.md

@@ -0,0 +1,26 @@
+# 后端数据库规范
+
+## 目标
+
+- 模型、迁移、查询方式一致
+- 数据变更可审计、可回滚、可复现
+
+## 基本要求
+
+- 表结构变更必须通过迁移文件管理
+- 查询优先使用项目统一的数据访问方式
+- 事务边界由业务动作定义，不要为“方便”扩大事务
+- 审计字段、逻辑删除、版本号等约定要全项目一致
+
+## 建议检查项
+
+- 新表是否补齐主键、索引、审计字段
+- 复杂查询是否可通过统一 API 或查询构造器表达
+- 是否存在拼接 SQL / 条件遗漏 / N+1 查询
+- 是否在错误层做了数据一致性补偿
+
+## 项目定制位
+
+- 迁移工具：`<按项目填写>`
+- ORM / 查询框架：`<按项目填写>`
+- 审计字段：`<按项目填写，例如 created_at / updated_at>`

package/template/.cowork-flow/spec/backend/directory-structure.md

@@ -0,0 +1,27 @@
+# 后端目录结构规范
+
+## 目标
+
+- 模块职责清晰
+- 包结构稳定
+- 新人和 AI 能快速定位代码
+
+## 推荐做法
+
+- 按业务能力或边界拆模块，不按“工具类型”滥拆
+- Controller / API 只做参数接收、鉴权入口和响应编排
+- Service / UseCase 承接业务规则
+- Repository / DAO 承接持久化访问
+- Domain Model / Entity / Aggregate 保持边界清晰
+
+## 命名建议
+
+- 模块名体现业务边界，不体现实现细节
+- 包名与目录名统一小写
+- 同一层命名保持后缀一致，例如 `Controller`、`Service`、`Repository`
+
+## 不建议
+
+- 一个模块同时承担多个无关业务
+- 在 Controller 中堆业务逻辑
+- 在公共模块中混入业务特化逻辑

package/template/.cowork-flow/spec/backend/error-handling.md

@@ -0,0 +1,20 @@
+# 后端异常处理规范
+
+## 目标
+
+- 调用方能稳定感知错误
+- 内部错误与外部错误边界清晰
+
+## 推荐做法
+
+- 统一定义错误码或错误类型
+- 参数校验错误、业务错误、系统错误分层处理
+- 对外返回稳定结构，对内保留足够上下文
+- 不把底层异常原样泄露给调用方
+
+## 典型检查项
+
+- 是否区分“可预期业务失败”和“系统异常”
+- 是否保留 traceId / requestId / correlationId
+- 是否有统一异常兜底
+- 是否记录了必要但不过量的日志

package/template/.cowork-flow/spec/backend/index.md

@@ -0,0 +1,36 @@
+# 后端开发规范
+
+> 通用模板：复制到新项目后，请替换为项目真实技术栈、模块结构和运行边界。
+
+---
+
+## 当前基线
+
+- 架构形态：`<按项目填写>`
+- 运行模块：`<按项目填写>`
+- 技术栈：`<按项目填写>`
+- 规范来源：以仓库内已落地代码、配置、测试和迁移脚本为准
+
+---
+
+## 阅读顺序
+
+| 文档 | 用途 |
+|------|------|
+| [目录结构](./directory-structure.md) | 模块划分、包结构、命名方式 |
+| [数据库规范](./database-guidelines.md) | 实体、迁移、查询、事务 |
+| [异常处理](./error-handling.md) | 错误码、异常边界、统一返回 |
+| [日志规范](./logging-guidelines.md) | 结构化日志、敏感信息、链路标识 |
+| [质量规范](./quality-guidelines.md) | 测试、lint、门禁、禁止模式 |
+
+---
+
+## 使用原则
+
+- 优先遵循仓库现有模式，不新增与现有风格冲突的写法
+- 先查已有公共模块、公共库或基础设施封装
+- 涉及跨模块、异步链路、权限边界时，同时阅读 `guides/` 下的思考指引
+
+---
+
+**文档语言**：默认中文，可按项目统一改为英文。

package/template/.cowork-flow/spec/backend/logging-guidelines.md

@@ -0,0 +1,20 @@
+# 后端日志规范
+
+## 目标
+
+- 便于排查
+- 便于追踪链路
+- 不泄露敏感信息
+
+## 推荐做法
+
+- 使用结构化日志
+- 统一记录请求标识、用户标识、任务标识或链路标识
+- 错误日志记录上下文，不重复打印同一异常
+- 对账号、令牌、密钥、身份证号、手机号等敏感字段脱敏
+
+## 不建议
+
+- 直接输出完整请求体或完整响应体
+- 使用临时 `print` / `console` 式调试输出长期留在主干
+- 同一错误在多层重复打印

package/template/.cowork-flow/spec/backend/quality-guidelines.md

@@ -0,0 +1,24 @@
+# 后端质量规范
+
+## 完成定义
+
+至少满足：
+
+- 编译 / 构建通过
+- 测试通过
+- 核心场景已验证
+- 新增约定已沉淀到 spec
+
+## 推荐门禁
+
+- 静态检查：`<按项目填写>`
+- 单元测试：`<按项目填写>`
+- 集成测试：`<按项目填写>`
+- 构建验证：`<按项目填写>`
+
+## 常见禁止模式
+
+- 未验证就宣称完成
+- 用硬编码绕过配置与契约
+- 用临时兼容逻辑代替真实修复
+- 变更接口或数据结构却不更新文档和调用方

package/template/.cowork-flow/spec/frontend/component-guidelines.md

@@ -0,0 +1,19 @@
+# 前端组件规范
+
+## 目标
+
+- 组件职责单一
+- 组合关系清晰
+- 交互边界稳定
+
+## 推荐做法
+
+- 容器组件负责数据与状态，展示组件负责呈现
+- 组件 API 保持简洁，避免“万能组件”
+- 把复杂交互拆成可复用但边界明确的小组件
+
+## 检查项
+
+- 组件是否承担了过多业务逻辑
+- Props 是否过多或命名不清
+- 组件是否依赖过多外部状态

package/template/.cowork-flow/spec/frontend/directory-structure.md

@@ -0,0 +1,18 @@
+# 前端目录结构规范
+
+## 目标
+
+- 页面、组件、状态和样式边界清晰
+- 新人和 AI 能快速定位入口与依赖
+
+## 推荐做法
+
+- 按功能模块组织，不按“通用 / 非通用”先拆
+- 页面入口、业务组件、通用组件、数据访问、状态管理分层清晰
+- 同一功能相关文件尽量邻近放置
+
+## 不建议
+
+- 页面文件承载大量业务逻辑
+- 组件目录中混入请求、状态、样式、工具函数但没有边界
+- 过早抽象通用组件

package/template/.cowork-flow/spec/frontend/hook-guidelines.md

@@ -0,0 +1,17 @@
+# 前端 Hook 规范
+
+## 目标
+
+- 复用副作用逻辑
+- 保持组件主体清晰
+
+## 推荐做法
+
+- 把数据获取、订阅、副作用、复杂状态流转抽到 Hook
+- Hook 返回值保持稳定且易理解
+- 让 Hook 名称体现行为，而不是实现
+
+## 不建议
+
+- 用 Hook 隐藏难以理解的副作用
+- 在 Hook 中混入多个无关职责

package/template/.cowork-flow/spec/frontend/index.md

@@ -0,0 +1,28 @@
+# 前端开发规范
+
+> 通用模板：如项目没有前端，可保留占位说明；如有前端，请替换成真实前端技术栈与规则。
+
+---
+
+## 当前基线
+
+- 前端形态：`<按项目填写>`
+- 技术栈：`<按项目填写>`
+- 契约来源：以后端接口、共享类型、设计系统和交互规范为准
+
+---
+
+## 文档索引
+
+| 文档 | 用途 |
+|------|------|
+| [目录结构](./directory-structure.md) | 说明模块划分和目录边界 |
+| [组件规范](./component-guidelines.md) | 说明组件职责、组合与交互边界 |
+| [Hook 规范](./hook-guidelines.md) | 说明复用逻辑与副作用边界 |
+| [状态管理](./state-management.md) | 说明服务端状态、客户端状态和权限状态 |
+| [质量规范](./quality-guidelines.md) | 说明前端门禁 |
+| [类型安全](./type-safety.md) | 说明共享类型与契约同步原则 |
+
+---
+
+**文档语言**：默认中文，可按项目统一改为英文。

package/template/.cowork-flow/spec/frontend/quality-guidelines.md

@@ -0,0 +1,23 @@
+# 前端质量规范
+
+## 完成定义
+
+至少满足：
+
+- 构建通过
+- 类型检查通过
+- lint / format 通过
+- 关键交互已手工验证
+
+## 推荐门禁
+
+- lint：`<按项目填写>`
+- type-check：`<按项目填写>`
+- test：`<按项目填写>`
+- build：`<按项目填写>`
+
+## 常见禁止模式
+
+- 用 `any` 或强制断言掩盖真实类型问题
+- 组件未处理加载、空态、错误态
+- 交互依赖隐式副作用

package/template/.cowork-flow/spec/frontend/state-management.md

@@ -0,0 +1,18 @@
+# 前端状态管理规范
+
+## 目标
+
+- 区分服务端状态与客户端状态
+- 权限、会话、草稿、筛选条件等状态边界清晰
+
+## 推荐做法
+
+- 服务端状态优先交给项目统一请求 / 缓存方案处理
+- 客户端临时状态尽量就近管理
+- 全局状态只保留真正跨模块共享的状态
+
+## 检查项
+
+- 是否把局部状态错误提升成全局状态
+- 是否把服务端状态与本地状态混在一起
+- 是否在权限状态上留有绕过入口

package/template/.cowork-flow/spec/frontend/type-safety.md

@@ -0,0 +1,18 @@
+# 前端类型安全规范
+
+## 目标
+
+- 前后端契约同步
+- 状态与组件 API 可推导
+
+## 推荐做法
+
+- 共享接口、枚举、错误码尽量来自统一契约源
+- 不手写重复的接口定义
+- 变更接口时同步更新调用方、校验和展示层
+
+## 检查项
+
+- 是否存在类型与真实响应结构不一致
+- 是否通过强转掩盖结构问题
+- 是否缺少空值、错误态、边界态定义

package/template/.cowork-flow/spec/guides/code-reuse-thinking-guide.md

@@ -0,0 +1,26 @@
+# 代码复用思考指引
+
+## 什么时候必须看
+
+- 你准备新增常量、错误码、工具函数、查询模板、DTO、校验逻辑
+- 你刚在多个文件做了类似修改
+- 你觉得“这个应该以后还会再用”
+
+## 检查问题
+
+- 项目里是否已经有同类实现？
+- 这个能力应该放在公共层、领域层还是模块内？
+- 现在抽象是否真的减少重复，还是提前设计？
+- 如果以后只会复用一次，是否值得抽取？
+
+## 最小动作
+
+```bash
+rg "相似关键字"
+```
+
+## 原则
+
+- 先搜索，后新增
+- 先复用，后抽象
+- 先最小可用，后稳定沉淀

package/template/.cowork-flow/spec/guides/cross-layer-thinking-guide.md

@@ -0,0 +1,21 @@
+# 跨层思考指引
+
+## 什么时候必须看
+
+- 变更穿过 3 层及以上
+- 接口、状态、权限、异步链路发生变化
+- 一个修改需要同步多个模块或多个进程
+
+## 检查问题
+
+- 输入从哪里来？经过哪些层？最终落到哪里？
+- 输出给谁？哪些层依赖它？
+- 错误在每一层如何表达和传播？
+- 权限、鉴权、业务授权是否被混淆？
+- 是否只改了主路径，漏掉异常路径和回滚路径？
+
+## 常见漏项
+
+- Controller 改了，但 service / repository / client 没改
+- 消息结构改了，但消费者没同步
+- 状态机规则改了，但校验和展示没同步

package/template/.cowork-flow/spec/guides/index.md

@@ -0,0 +1,31 @@
+# 思考指引
+
+> 本目录不讲实现细节，只提醒最容易出问题的思考点。
+
+---
+
+## 常见风险
+
+- 模块边界被打穿
+- 权限与业务授权混在一起
+- 跨层契约只改了一半
+- 新增一套重复常量、错误码、查询模式
+- 接口、数据结构、任务流转没有同步更新
+
+---
+
+## 使用方式
+
+- 写代码前先看 [编码前检查表](./pre-implementation-checklist.md)
+- 涉及跨模块、异步链路、权限或状态流转时，看 [跨层思考指引](./cross-layer-thinking-guide.md)
+- 涉及公共能力、常量、错误码、查询模板、校验逻辑时，看 [代码复用思考指引](./code-reuse-thinking-guide.md)
+
+---
+
+## 最小动作
+
+修改前先搜索：
+
+```bash
+rg "关键字"
+```

package/template/.cowork-flow/spec/guides/pre-implementation-checklist.md

@@ -0,0 +1,15 @@
+# 编码前检查表
+
+## 在动手前先确认
+
+- 这次改动属于 `L0`、`L1` 还是 `L2`？
+- 是否涉及 API、数据库、异步链路、权限或状态流转？
+- 是否需要先补 OpenSpec？
+- 是否已经明确成功标准和验证方式？
+- 是否已经搜索过相似实现与可复用能力？
+
+## 如果涉及行为变化
+
+- 是否已有 `proposal/spec/design/plan`？
+- 是否已经明确输入、输出、错误、边界场景？
+- 是否知道谁负责提交业务代码？

package/template/.cowork-flow/tasks/.gitkeep

@@ -0,0 +1 @@
+

package/template/.cowork-flow/tasks/archive/.gitkeep

@@ -0,0 +1 @@
+